fix: prevent tunnel logs from corrupting TUI

Author: francis-du

.wcode/design/acceptance.yaml

@@ -359,7 +359,7 @@
 - schema_version: 1
   id: AC-UX-001
   title: Operator surfaces remain usable across terminal layouts
-  statement: The TUI stays readable in narrow layouts, uses the documentation palette and a compact connection/status hierarchy, actively loads Intelligence for the focused project, keeps the pairing code visible after connection, shows the complete supported-command catalog, distinguishes installed LSP availability from launch-ready trust and live-validated sessions, and exposes real warm LSP session/document/start/query telemetry. The TUI and WebUI label Executable access separately from Exact repository operation while preserving per-request approve/deny behavior. The WebUI renders a bounded project file tree and largest-file list with the repository line limit visible.
+  statement: The TUI stays readable in narrow layouts, uses the documentation palette and a compact connection/status hierarchy, actively loads Intelligence for the focused project, keeps the pairing code visible after connection, shows the complete supported-command catalog, distinguishes installed LSP availability from launch-ready trust and live-validated sessions, exposes real warm LSP session/document/start/query telemetry, and claims terminal output for the lifetime of the alternate-screen renderer so background operator diagnostics are retained as structured state without bypassing ratatui. The TUI and WebUI label Executable access separately from Exact repository operation while preserving per-request approve/deny behavior. The WebUI renders a bounded project file tree and largest-file list with the repository line limit visible.
   verification:
     - kind: test
       path: tests/unit/ui/monitor.rs
@@ -376,6 +376,9 @@
     - kind: test
       path: tests/unit/ui/monitor.rs
       symbol: semantic_session_status_updates_operator_intelligence_state
+    - kind: test
+      path: tests/unit/ui/monitor.rs
+      symbol: dashboard_terminal_claim_suppresses_background_operator_output
     - kind: test
       path: tests/unit/ui/monitor.rs
       symbol: opening_intelligence_loads_the_focused_workspace_without_prior_mcp_calls
@@ -527,8 +530,11 @@
 - schema_version: 1
   id: AC-TUNNEL-001
   title: Managed tunnel selection supports free provider fallback
-  statement: Every candidate tunnel is instance-health-verified, provider parsing rejects control hosts, and OAuth metadata plus existing sessions follow only the verified aliases owned by the running wcode process.
+  statement: Every candidate tunnel is instance-health-verified, provider parsing rejects control hosts, OAuth metadata plus existing sessions follow only the verified aliases owned by the running wcode process, and managed tunnel/provider dependency paths never write directly to stdout/stderr or inherit child terminal output; diagnostics flow through TaskMonitor so an active alternate-screen TUI cannot be corrupted.
   verification:
+    - kind: test
+      path: tests/unit/runtime/tunnel/mod.rs
+      symbol: tunnel_runtime_never_writes_directly_to_the_terminal
     - kind: test
       path: tests/unit/runtime/tunnel/mod.rs
       symbol: parses_quick_tunnel_url

.wcode/design/components.yaml

@@ -280,7 +280,7 @@
     - use revision-exact Evidence for current Proof and expose explicit stable/changing/needs_convergence/incomplete requirement states with blockers
     - compare the complete declared component architecture with code-derived dependency edges, distinguish strong observed drift from evidence gaps, and retain code statistics, mapped Git changes and structural revision history without reverting to an undifferentiated node-ball graph
     - keep English as the default UI language and expose explicit manual English / Simplified Chinese switching in both TUI and WebUI without locale auto-detection
-    - keep the TUI visually compact with the documentation palette, actively load the focused Workspace when Intelligence opens, retain the pairing code after connection, expose the complete supported-command catalog, and distinguish LSP available / launch-ready / live-validated state alongside real warm semantic-session/document/start/query telemetry rather than a decorative LSP state
+    - keep the TUI visually compact with the documentation palette, actively load the focused Workspace when Intelligence opens, retain the pairing code after connection, expose the complete supported-command catalog, distinguish LSP available / launch-ready / live-validated state alongside real warm semantic-session/document/start/query telemetry rather than a decorative LSP state, and centrally claim terminal output while ratatui owns the alternate screen so background runtime diagnostics cannot punch through the dashboard
     - expose W as the discoverable TUI shortcut for the protected Project Observatory and provide TUI/WebUI controls for selectable pending authorization requests plus protected WebUI project and command-access management while keeping executable access distinct from exact repository-operation approval
     - derive a bounded project file tree and largest-file list from the same Software Graph snapshot, expose the 1000-line repository limit, and report truncation instead of starting an unbounded WebUI filesystem scan
   constraints:
@@ -664,6 +664,7 @@
     - start Cloudflare Quick Tunnel, localhost.run, Pinggy and Tailscale Funnel concurrently in the background so the dashboard never waits for a provider; retry unreachable providers on a fixed interval and keep every instance-health-verified tunnel live
     - respawn a single dead tunnel after an exponential backoff without restarting the process or disturbing live tunnels, promoting the next live tunnel when the primary endpoint dies
     - keep explicit provider selection and stable --public-url overrides available without weakening OAuth or local health verification
+    - route provider attempts, retries, dependency/install diagnostics, stale-process reclamation and connection events through TaskMonitor operator messages; never write directly to the terminal or inherit installer stdio while the runtime may be rendering the TUI
     - isolate provider lifecycle, dependency checks, URL parsing and health verification from the top-level process bootstrap
   depends_on:
     - component:mcp-runtime

.wcode/design/requirements.yaml

@@ -364,7 +364,7 @@
 - schema_version: 1
   id: REQ-UX-001
   title: Operator-visible Software Intelligence
-  intent: TUI and protected local WebUI surfaces must expose live software-intelligence state in a compact hierarchy that uses the documentation palette and remains usable in narrow terminals. The TUI actively loads the focused project, keeps the pairing code visible after connection, and exposes the complete command catalog. The WebUI shows a bounded project file tree and the largest files, including the repository line-limit signal. Executable access remains distinct from exact repository-operation approval, while language, appearance, refresh, project, precision, connection and per-request approval controls stay explicit.
+  intent: TUI and protected local WebUI surfaces must expose live software-intelligence state in a compact hierarchy that uses the documentation palette and remains usable in narrow terminals. The TUI actively loads the focused project, keeps the pairing code visible after connection, exposes the complete command catalog, and owns stdout/stderr while its alternate screen is active so background tunnel/setup diagnostics cannot corrupt the rendered terminal. The WebUI shows a bounded project file tree and the largest files, including the repository line-limit signal. Executable access remains distinct from exact repository-operation approval, while language, appearance, refresh, project, precision, connection and per-request approval controls stay explicit.
   priority: high
   implemented_by:
     - component:intelligence-ui
@@ -511,7 +511,7 @@
 - schema_version: 1
   id: REQ-TUNNEL-001
   title: Public tunnel availability is provider-resilient
-  intent: Remote MCP startup must not depend on one tunnel vendor. wcode keeps every instance-health-verified tunnel live, self-heals failures without restarting the process, directs OAuth to the hostname receiving the request, and preserves scoped persisted sessions when clients reconnect through another verified alias or restart the runtime.
+  intent: Remote MCP startup must not depend on one tunnel vendor. wcode keeps every instance-health-verified tunnel live, self-heals failures without restarting the process, directs OAuth to the hostname receiving the request, preserves scoped persisted sessions when clients reconnect through another verified alias or restart the runtime, and routes background provider diagnostics through structured monitor state rather than direct terminal writes while the TUI owns the terminal.
   priority: high
   implemented_by:
     - component:managed-tunnel

README.md

@@ -46,8 +46,10 @@ wcode --workspace "$PWD"
 
 The TUI opens immediately. In the normal configuration wcode also starts the
 local HTTP service, protected WebUI, OAuth server, and managed HTTPS tunnels.
-Every tunnel is accepted only after its public `/healthz` response matches the
-current runtime instance.
+While the alternate-screen dashboard is active it owns terminal output:
+background tunnel/setup diagnostics are captured into `TaskMonitor` state
+instead of writing over the ratatui frame. Every tunnel is accepted only after
+its public `/healthz` response matches the current runtime instance.
 
 The selected root remains the security boundary. Project markers below it are
 discovered as subspaces, so a broad root such as `~/Code` can safely expose

docs/manual/releases/v0.5.0.md

@@ -85,6 +85,7 @@ v0.5.0 also changes when semantic work is recommended and how operators can tell
 - `agent_context` detects relationship-oriented tasks such as references, callers, implementations, rename impact, and cross-file semantic impact. It recommends `semantic_navigation` only when stronger relationship evidence is useful.
 - Ordinary “where is this symbol?” work stays on Tree-sitter/search instead of paying LSP startup or query cost.
 - The TUI Intelligence view exposes warm-session count, synchronized document count, provider starts, semantic query count, and fresh/stale semantic provider state.
+- The live dashboard now owns terminal output while its alternate screen is active. Tunnel/provider retries, dependency checks, reconnects, Setup-browser diagnostics, and other background operator messages are routed through `TaskMonitor` instead of writing directly to stdout/stderr; provider installers are captured rather than inheriting the terminal. This prevents background tunnel text from floating over or corrupting the ratatui frame.
 - Cached graph inputs can avoid graph reconstruction while still warming the provider session so later semantic requests do not pay process startup cost.
 - High-value Call Hierarchy and Implementation expansion remains bounded rather than querying every variable, field, and low-value symbol.
 - `semantic_provider_refresh` remains available as a force-refresh surface; automatic maintenance is the default for the hardened lane.

docs/manual/releases/v0.5.0.zh-CN.md

@@ -85,6 +85,7 @@ v0.5.0 也改变了何时推荐 Semantic Work，以及 Operator 怎么判断 War
 - `agent_context` 会识别 Reference、Caller、Implementation、Rename Impact、Cross-file Semantic Impact 等 Relationship-oriented Task，只有更强关系证据有价值时才推荐 `semantic_navigation`。
 - 普通“这个 Symbol 在哪里”继续走 Tree-sitter/Search，不承担 LSP Startup / Query Cost。
 - TUI Intelligence 会显示 Warm Session 数、已同步 Document 数、Provider Start 次数、Semantic Query 数以及 Fresh/Stale Provider State。
+- Live Dashboard 进入 Alternate Screen 后会独占 Terminal Output。Tunnel/Provider Retry、Dependency Check、Reconnect、Setup Browser Diagnostic 等后台 Operator Message 全部先进入 `TaskMonitor`，不再直接写 stdout/stderr；Provider Installer 也改为捕获输出而不是继承终端，避免隧道日志漂在 ratatui 画面上把 TUI 打花。
 - Graph Input 未变化时可以跳过 Graph Reconstruction，同时仍保持 Provider Session Warm，让后续 Semantic Request 不必再次支付 Process Startup Cost。
 - Call Hierarchy / Implementation 只扩展高价值 Symbol，并继续保持有界，不会为每个 Variable / Field 发大量请求。
 - `semantic_provider_refresh` 继续保留为 Force-refresh Surface；Hardened Lane 默认由 Runtime 自动维护。

src/app/mod.rs

@@ -1,7 +1,7 @@
 use crate::auth::AuthState;
 use crate::harness::ToolHarness;
 use crate::mcp::AppState;
-use crate::monitor::{MonitorConfig, MonitorRenderer, TaskMonitor};
+use crate::monitor::{MonitorConfig, MonitorRenderer, OperatorMessageKind, TaskMonitor};
 use crate::tunnel::{
     normalize_public_url, public_endpoint_health_loop, spawn_tunnel_supervisor,
     wait_for_public_endpoint, ActiveTunnel, TunnelEvent, TunnelProvider,
@@ -459,7 +459,11 @@ pub async fn run() -> Result<()> {
         let _ = tunnel_settled_tx.send(true);
         local_url.clone()
     } else {
-        println!("  ↗ tunnel       requesting HTTPS endpoint in the background");
+        monitor.operator_message(
+            OperatorMessageKind::Info,
+            "tunnel",
+            "requesting HTTPS endpoint in the background",
+        );
         monitor.mark_public_endpoint("pending", None);
         {
             let forward_tx = tunnel_event_tx.clone();
@@ -546,14 +550,15 @@ pub async fn run() -> Result<()> {
     if open_setup {
         let mut settled = tunnel_settled_rx.clone();
         let url_slot = shared_public_url.clone();
+        let setup_monitor = monitor.clone();
         tokio::spawn(async move {
             if !*settled.borrow() {
                 // Providers keep retrying in the background; do not hold the
                 // opener hostage if none of them connects quickly.
                 let _ = timeout(Duration::from_secs(120), settled.changed()).await;
             }
             let base = url_slot.read().unwrap().clone();
-            open_setup_hub(&base, &format!("{base}/mcp"));
+            open_setup_hub(&base, &format!("{base}/mcp"), &setup_monitor);
         });
     }
     let renderer = monitor.spawn_renderer(monitor_config, args.monitor);
@@ -633,7 +638,11 @@ pub async fn run() -> Result<()> {
                                 auth.pairing_code()
                             );
                             if let Err(error) = send_imessage(recipient, &message) {
-                                eprintln!("  ! imessage      {error:#}");
+                                monitor.operator_message(
+                                    OperatorMessageKind::Warning,
+                                    "imessage",
+                                    format!("{error:#}"),
+                                );
                             }
                         }
                         tunnels.push(active);
@@ -693,7 +702,11 @@ pub async fn run() -> Result<()> {
                     let dead_provider = tunnels[index].provider();
                     let dead_url = tunnels[index].public_url().to_owned();
                     let was_primary = index == 0;
-                    eprintln!("  ! tunnel       {reason}; respawning {}", dead_provider.label());
+                    monitor.operator_message(
+                        OperatorMessageKind::Warning,
+                        "tunnel",
+                        format!("{reason}; respawning {}", dead_provider.label()),
+                    );
                     let mut dead = tunnels.remove(index);
                     dead.stop().await;
                     monitor.remove_tunnel(&dead_url);
@@ -723,9 +736,13 @@ pub async fn run() -> Result<()> {
                         .and_modify(|count| *count += 1)
                         .or_insert(1);
                     let backoff_secs = (15u64 << (*deaths - 1).min(4)).min(300);
-                    eprintln!(
-                        "  ! tunnel       {} respawns in {backoff_secs}s (death #{deaths})",
-                        dead_provider.label()
+                    monitor.operator_message(
+                        OperatorMessageKind::Warning,
+                        "tunnel",
+                        format!(
+                            "{} respawns in {backoff_secs}s (death #{deaths})",
+                            dead_provider.label()
+                        ),
                     );
                     pending_respawns.push((
                         dead_provider,
@@ -827,9 +844,13 @@ async fn wait_for_monitor_interrupt(receiver: Option<watch::Receiver<bool>>) {
     }
 }
 
-fn open_setup_hub(setup_url: &str, mcp_url: &str) {
-    println!("  ↗ setup        opening wcode setup hub");
-    println!("  · MCP URL      {mcp_url}");
+fn open_setup_hub(setup_url: &str, mcp_url: &str, monitor: &TaskMonitor) {
+    monitor.operator_message(
+        OperatorMessageKind::Info,
+        "setup",
+        "opening wcode setup hub",
+    );
+    monitor.operator_message(OperatorMessageKind::Info, "MCP URL", mcp_url);
     let mut command = if cfg!(target_os = "macos") {
         let mut command = StdCommand::new("open");
         command.arg(setup_url);
@@ -849,7 +870,11 @@ fn open_setup_hub(setup_url: &str, mcp_url: &str) {
         .stderr(StdStdio::null())
         .spawn()
     {
-        eprintln!("  ! setup        could not open the browser ({error}); visit {setup_url}");
+        monitor.operator_message(
+            OperatorMessageKind::Warning,
+            "setup",
+            format!("could not open the browser ({error}); visit {setup_url}"),
+        );
     }
 }