Hidden stderr diagnostics duplicate mouse-enabled TUI frames

[code-yeongyu]

Summary

Regular-mode mouse capture appends a duplicate full TUI frame when a diagnostic is redirected to the debug log and never reaches the terminal.

Reproduction

1. Run the interactive source CLI in an isolated agent directory with terminal.mouse set to always.
2. Execute a read sequence followed by grep when the optional native grep prebuild is unavailable.
3. Grep emits its normal fallback diagnostic through console.warn; the interactive stderr guard stores that message in the debug log.
4. Observe the previous user prompt/tool group remaining above a second complete copy of the working frame.

Expected

Hidden diagnostics must not invalidate terminal geometry. Real visible stdout/stderr, including the redacted stderr fallback when the diagnostic log cannot be written, must still invalidate mouse hit targets until geometry is recalibrated.

Actual and evidence

Runtime instrumentation records this call chain:

grep/select-engine.ts → writeHiddenConsoleDiagnostic → ProcessTerminal.installExternalStderrObserver → hidden diagnostic log.

The same run then records a second fullRender: first render, and the output stream contains the CRLF followed by a fresh non-clearing frame from TuiMainScreen.doRender.

The defect remains when the terminal emulator is connected before the CLI starts. It is not a delayed terminal-query response.

Root cause

The stderr observer wraps an already-redirected process.stderr.write and calls noteExternalWrite before the redirect decides whether any bytes reach the terminal. TuiMainScreen responds to that false visibility signal by preserving the old frame and appending a new one.

Scope and acceptance

• Add a deterministic integration regression covering hidden diagnostics with mouse capture.
• Preserve real-output invalidation and redacted visible fallback behavior.
• Preserve stdout/stderr ownership and restoration through start/stop transitions.
• Re-run the actual 80/120-column interactive scenario and verify only one current exploration group.

Related

Found during #1870. Mouse capture was introduced in #1651; diagnostic hiding predates it in #677. #1704 describes a different resize/focus-triggered replay symptom. Private runtime evidence is held locally.

[code-yeongyu]

The stderr regression was reproduced through the real interactive TUI factory, terminal and output guard: hidden diagnostics produced two full redraws where the unchanged frame requires one. The visible redacted-fallback control passed on the original code.

Observation now subscribes below the diagnostic redirect. Fifteen focused tests passed, including both guard/observer installation and teardown orders, duplicate listener ownership, restart, callback/backpressure fidelity, visible fallback, and quit drain.

An additional direct-stdout control then exposed the same false invalidation in the stdout handler. It failed for the same two-versus-one redraw assertion before moving notification to the actually forwarded branches.

Actual 80- and 120-column runs now show one compact exploration group rather than two. Final static/domain gates and interactive mouse expansion are still being checked. A separate click-admission defect in the new #1870 group is being covered through real press/release dispatch rather than a direct call to its click handler.

[code-yeongyu]

Landing as its own PR (the fix was bundled in #1881, now closed as superseded).

[code-yeongyu]

Approach confirmed (port of the #1879 hunks from closed #1881).

Root cause: ProcessTerminal.installExternalStderrObserver wraps process.stderr.write above the interactive stderr guard. Hidden diagnostics still call noteExternalWrite, so mouse-enabled TuiMainScreen treats them as visible output and appends a second full frame.

Change:

• packages/tui/src/stderr-observer.ts observes the live stream without taking ownership of a later writer.
• packages/tui/src/terminal.ts accepts a host-owned observeExternalStderrWrites and only invalidates on actual terminal delivery (including stdout that is not swallowed).
• packages/coding-agent/src/core/output-guard.ts exposes observeVisibleStderrWrites on the visible sink below the diagnostic redirect, including the redacted fallback when the log write fails.
• packages/coding-agent/src/modes/interactive/tui-renderer.ts wires that observer into ProcessTerminal.

A message that only reaches the debug log leaves the frame alone. Output that reaches the terminal, including the redacted fallback when the log write fails, still invalidates mouse geometry.

[code-yeongyu]

PR opened: #2046 (fix/hidden-stderr-frame-1879, head f722316ea46dcb68249eea18c1add0e048b4c03f).

Gates:

• Redraw-count RED on origin/main: fullRedraws 1 → 2 (red-vitest.txt sha256 c62f74ad1a9f9a64ab03a6038fb2d31c5d128f647f6618dc767b44febc0892b7).
• GREEN on the branch: 13/13 focused tests, exit 0 (green-vitest.txt sha256 6770bdbd77d6cdaf44fda239b21dd783246bb7edfc2d32c9ddb31db50a877d17).
• bun run check exit 0 (typecheck-check.txt sha256 45b5c5dc5d9cda55157dfda76738ae045292bfdae4ed71cae97460a3ee4f4c69).
• Changelog gate PASS, both verdicts: changes.md coverage complete (3 production path(s) covered); changelog entry updated (packages/coding-agent/CHANGELOG.md, packages/tui/CHANGELOG.md) (changelog-gate.txt sha256 166184aa5a9b0b8bfd177128bce3ca8696233977d3096dd3bc340ae8ad58919b).

xterm.js boot capture shows one composer and one footer (tui-boot-xterm/terminal.png sha256 c4b31ff11564dfbb869d60fae7871a6e378d82483f2c65e018de669645dfddc1).

[code-yeongyu]

Merged in #2046 (merge commit 666f746).

Evidence (PR head f722316): the redraw-count regression (hidden-stderr-mouse-anchor.test.ts) failed on the base with expected 2 to be 1 and passes on the branch (13/13 in the focused Vitest run); typecheck exit 0; changelog gate PASS for both packages/coding-agent and packages/tui; CI green; an xterm.js boot capture shows one composer and one footer (no duplicated frame).