feat(cpp): interactive TUI — event loop, streaming render, modals

[kovtcharov]

gaia-bash's default interactive mode displayed nothing. ReplRunner installed TuiConsole — a headless FTXUI element builder that accumulated agent output in a vector nobody ever rendered (grep -rn "ScreenInteractive" cpp/ returned zero hits, and getChatElements() had no callers), so the only things on screen were the banner and the prompt. Single-query mode (gaia-bash "query") had the same fault. After this PR both modes show the agent: a fullscreen screen with a scrollable transcript, tokens appearing as they stream, a status bar carrying model/step/token count, an input line with history, and a tool-approval modal that keeps the confirmation security model intact instead of auto-allowing.

Three landmines had to be cleared for a fullscreen screen to work, each of which would have corrupted or deadlocked it:

• Tool confirmation — Agent auto-installs a stdin callback that writes over the screen and fights FTXUI's input thread. Every non-interactive mode sidesteps it with an auto-allow lambda; doing that here would have silently disabled confirmation. It is replaced with a modal-backed callback, and a decision is only accepted for the request the frame actually showed — a key typed before the modal opened cannot answer it, and teardown denies rather than allows.
• Ctrl-C — the REPL's SIGINT handler is not installed on the TUI path; Ctrl-C arrives as an FTXUI event. First press cancels the turn, second quits. Cancellation is only observed between agent steps, so the UI says cancel requested — the step already running finishes first instead of claiming the in-flight model call was aborted.
• Slash commands — all five built-ins printed with std::cout straight over the screen. They now go through an output sink that the TUI points at the transcript, and they run on the worker thread, so /run invoking a CONFIRM tool raises the modal instead of wedging the UI thread.

TuiConsole is replaced rather than extended (it had no change notification and re-parsed markdown for all 2000 entries per call). renderMarkdown() is reused, with paragraph wrapping added — long answers used to be clipped at the terminal edge — and its box-drawing borders swapped for ASCII rules, per the ASCII-by-default rule in docs/plans/tui-user-journey.md.

Closes #2812

Test plan

• cd cpp && cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j8 && cd build && ctest — 524/524 pass (80 of them TUI: 27 TuiApp, 18 TuiTranscript, 5 TuiConfirmBroker, 3 TerminalResetGuard, 27 markdown).
• Regression that would have caught the silent REPL: TuiApp.AgentOutputIsVisibleOnTheRenderedFrame submits a query, runs it through Agent::processQuery() against an in-process mock LLM, and asserts the answer text is present in Screen::ToString().
• TuiApp.StreamingTokensAppearIncrementallyInTheFrame / TuiTranscript.StreamingTokensRenderIncrementally — partial text is on the frame before the stream ends.
• TuiApp.ConfirmToolRaisesAModalAndApproveRunsTheTool, …DenyBlocksTheTool, …EscapeDenies, AlwaysAllowPersistsToTheAllowedToolsStore (reloaded from disk), KeysQueuedBeforeTheModalWasDrawnDoNotAnswerIt, SlashCommandInvokingAConfirmToolRaisesTheModal.
• TuiApp.CtrlCCancelsTheTurnWithoutExiting (process survives, terminal intact), SecondCtrlCDuringACancellingTurnExits, CtrlCWhenIdleRequestsExit.
• TerminalResetGuard.{EmitsResetSequenceWhenArmed,DisarmedGuardWritesNothing,RestoresOnExceptionUnwind}.
• TuiApp.RendersAt80x24 — 24 lines, none wider than 80 columns; FrameIsAsciiOnlyIncludingTheModal asserts no byte ≥ 0x80.
• Driven for real in a 24×80 pty against a live Lemonade server: query answered and rendered, /help and /model output inside the screen, /run raising the modal (allow-once did not persist, always-allow did land in ~/.gaia/security/allowed_tools.json), Ctrl-C cancelling a long turn without killing the process, and \033[?1049l + \033[?25h on exit in every case.
• cmake -B build-notui -DGAIA_BUILD_TUI=OFF builds and links (the whole TUI is #ifdef GAIA_HAS_TUI).
• gaia-bash --no-tui "query" and gaia-bash "query" on a real tty both print the answer (the second was silent before).

C++ Integration Tests (STX) may still fail with Could not find CMAKE_ROOT — that is the self-hosted runner's broken CMake cache tracked in #2817 / PR #2818, not this change.

[github-actions]

Verdict: Approve

This rewrites the gaia-bash TUI from a headless element-builder (which stored agent output in a vector nobody rendered) into a real fullscreen FTXUI event loop with streaming, a scrollable transcript, and a tool-approval modal. The old TuiConsole is replaced by three focused pieces — a thread-safe transcript, a fail-closed confirmation broker, and a terminal-restore guard — all driven through a headless handleEvent()/renderFrame() surface so behaviour is asserted against real rendered frames.

I found no blocking issues. The threading is handled with unusual care: the confirm broker denies (never deadlocks) when a decision is requested from the UI thread, denies on shutdown, and — notably — gates modal answers on an id that only counts once the modal has actually been drawn, so a keystroke queued before the modal opened can't silently always-allow a CONFIRM tool. The worker is joined before teardown, and the saveSession() path after the app is destroyed writes only to stderr, so the output-sink lambda capturing the app is never called dangling. Removed TuiConsole has no lingering references, and both docs (bash-agent.mdx, testing.mdx) were updated to match — the stale "split-pane layout" line is now the real modal behaviour.

Real-world evidence

N/A for this CI lane — the change is a C++ TUI under cpp/, not a Python Agent-UI/CLI/MCP/REST surface, so no evidence-bundle.md was produced and the strix-halo/Agent-UI lane doesn't cover it. That gap is well-covered here in a way text can substitute for: the new tests render the actual component tree via ftxui::Screen::Create() + Render() + ToString() and assert on visible frames (agent output reaches the screen, 80×24 fits, ASCII-only, modal appears/denies/persists, Ctrl-C cancels vs. quits, queued keys don't answer an unseen modal). Verdict rests on static review plus these headless render tests.

🔍 Technical details

Issues

🟢 Minor — headings and blockquotes still clip at 80 columns (cpp/src/tui_markdown.cpp:267,320). Paragraphs and list items were moved to parseInlineWrapped, but blockquote lines (parseInline(rawLine.substr(2))) and headings still use the non-wrapping parseInline, so a long quoted line or heading is cut at the terminal width rather than wrapped. Low value — quotes/headings are usually short and this is arguably outside the PR's stated scope (wrapping long answers) — but worth a follow-up sweep for consistency.

Strengths

• Genuinely testable design. Building the component tree in the constructor and exposing handleEvent()/renderFrame()/renderToString() lets the whole loop — streaming, modal, cancellation, scrolling — be exercised end-to-end through Agent::processQuery() on a real worker thread with a mock LLM, no terminal required. AgentOutputIsVisibleOnTheRenderedFrame directly pins the regression this PR fixes.
• Confirmation broker is correct under contention. UI-thread requests are refused instead of deadlocking (tui_app.cpp:1103), shutdown() fails closed, and resolve() is id-gated so a stale or double keypress can't answer the wrong request (tui_app.cpp:1160). KeysQueuedBeforeTheModalWasDrawnDoNotAnswerIt guards a real safety hole — a queued a auto-whitelisting a CONFIRM tool.
• Clean teardown ordering. ~TuiApp shuts the broker (waking a blocked worker with DENY), joins the worker, then clears the transcript callback; runTui()'s SinkGuard outlives the app scope so an exception out of the loop can't leave the sink pointing at a destroyed app.
• Docs kept in sync with the behaviour change, including the new --tui flag, the key table, and the honest "cancel requested" wording that matches the between-steps cancellation semantics.

[github-actions]

Verdict: Approve with suggestions ✅

This replaces the old headless TuiConsole (which quietly dropped agent output into a vector nobody rendered) with a real interactive FTXUI event loop for gaia-bash: a streaming transcript, an input line with history, scrollback, and a fail-closed tool-confirmation modal. The threading model is careful — the agent runs on a worker thread, the confirm broker hands decisions to the UI thread and denies on shutdown/teardown/UI-thread-reentry — and it ships with genuinely strong tests that assert against real rendered frames rather than internal state, which is exactly the regression class this rewrite is meant to kill.

One thing worth a look before merge: /clear no longer clears what the user sees. In the TUI, /clear wipes the model's history and prints "Conversation history cleared.", but the on-screen transcript keeps every old line — so the message and the screen disagree. The TuiTranscript::clear() method exists for exactly this but is never wired up (and its comment claims it's "used by /clear"). Either call it from the clear command or fix the comment.

Real-world evidence

N/A — this is the C++ gaia-bash terminal TUI (cpp/), not the Python Agent UI, so the Playwright/screenshot rule doesn't apply, and no evidence-bundle.md was produced in this lane. The review environment can't build/run the C++ target (no shell access here), so the verdict rests on static review plus the PR's own headless frame-render tests — which render ftxui::Screen frames and assert on visible text/ASCII/80×24, a solid substitute for driving a live terminal.

🔍 Technical details

🟡 /clear clears model history but not the visible transcript (cpp/src/repl.cpp:95-98, cpp/include/gaia/tui_transcript.h:755)
cmdClear calls agent.clearHistory() + emit("Conversation history cleared."), but nothing calls transcript_->clear(), so in the fullscreen path the transcript still shows the whole prior conversation while the message asserts it was cleared — a mislead. TuiTranscript::clear() is defined and documented as "Drop every entry (used by /clear)" yet has no caller in the diff (dead code + inaccurate comment). Wire it through the TUI clear path, or, if keeping visual scrollback across /clear is intentional, reword both the emitted message and the header comment so they stop claiming the entries are dropped. A test_tui_app case (/clear empties transcript().entryCount(), or explicitly asserts it does not) would lock in whichever behavior you pick.

🟢 Streamed inline code loses its background across word gaps (cpp/src/tui_markdown.cpp:1989)
parseInlineWrapped styles `code` per-word (dim | inverted), so a multi-word code span renders with un-styled gaps between words. Purely cosmetic and a reasonable trade for wrapping; noting only so it's a known consequence, not a surprise.

Strengths

• Confirm-broker security posture is correct and well-tested: DENY on shutdown, on teardown while pending, and on same-(UI)-thread reentry; the pendingId scheme stops a key queued before the modal was drawn from silently answering it (and thus from a-whitelisting a tool the user never saw). KeysQueuedBeforeTheModalWasDrawnDoNotAnswerIt is a great test to have.
• Tests assert on rendered frames (Screen::Create + Render + ToString, ASCII-only, ≤80 cols, 24 rows), not on "the handler stored it" — directly targeting the bug the old console had.
• Terminal restoration is layered (FTXUI's own restore + TerminalResetGuard covering exception unwind), and willUseTui() correctly requires a tty on both stdin and stdout, with a visible note + --tui escape hatch for MSYS/mintty instead of degrading silently.
• Docs (docs/cpp/bash-agent.mdx, docs/cpp/testing.mdx) updated in step with the code, including the new --tui flag and key table.

[kovtcharov-amd]

The STX red on this PR was a stale result, not a defect — I've re-triggered CI.

C++ Integration Tests (STX) failed here on the #2817 CMake-cache bug (CMake Error: Could not find CMAKE_ROOT, from a partially-swept cache that left bin\cmake.exe without share\cmake-*\Modules). Main fixed that in #2818 on 6 Aug, but this PR's last run predates the fix, so the X was left over rather than live.

Re-running against current main: the provisioning step now probes the cached CMake, re-downloads it when the modules directory is missing, and the suite passes 20/20 — including on sjlab-stx-3, one of the runners this used to fail on. No change to this branch was needed.