v0.8.66: Fix TUI modal and text overflow layout systemically

[Hmbown]

Problem

This is broader than one destructive approval modal. CodeWhale still has systemic TUI layout and text containment failures across modals and UI surfaces: text can overflow, bottom action rows can be clipped, important context can disappear below the visible frame, and long labels/commands/content can cross borders or push controls out of view.

The screenshot from June 29, 2026 shows one concrete symptom: the DESTRUCTIVE approval - exec_shell modal does not fully display its lower command/action area. Treat that screenshot as evidence of the broader class, not as the only failing surface.

The implementation agent needs to figure out the shared root causes and fix the UI/UX layout model once, instead of patching individual modal instances.

Scope

• All modal surfaces: destructive approvals, standard approvals, config/help/pickers, sub-agent views, command palettes, settings, confirmations, and list/detail modals.
• All text-heavy UI regions likely to overflow: command previews, policy explanations, intent text, labels, footers, action rows, status lines, sidebar rows, cards, tables, and wrapped paragraphs.
• All relevant terminal sizes, especially narrow and short viewports.

Required approach

• Audit the TUI layout/rendering primitives and identify where dimensions, wrapping, scrolling, and footer/action reservation are handled inconsistently.
• Establish shared layout contracts so containers reserve title/border/footer/action space first, constrain body content to the remaining area, and handle overflow explicitly.
• Replace ad hoc height guesses and one-off truncation with reusable helpers/components where possible.
• Make long text safe by default: wrap, truncate with clear affordance, or scroll depending on the surface.
• Ensure controls/actions remain visible and reachable even when body content is long.

Acceptance criteria

• No modal can hide its bottom action row or render content outside its border at supported terminal sizes.
• Long command text, policy/explanation text, labels, and footer/actions do not overflow their containers.
• Destructive approval, standard approval, config/help/picker, sub-agent/list-style, and command-palette-style modals have regression coverage at narrow, normal, and short terminal sizes.
• Representative non-modal UI text surfaces are audited and fixed where they share the same overflow/layout failure class.
• Tests or deterministic fixtures cover the shared primitives so future modal additions inherit the fix.
• The final PR documents the central layout contract and calls out any intentionally deferred edge cases.

Non-goals

• Do not patch only exec_shell or only the screenshot case.
• Do not solve this by making every modal larger. The fix should make overflow behavior correct at constrained sizes.

Repro signal

Observed in the TUI destructive approval modal for exec_shell with a multi-line command and long intent text: the modal bottom content/action area is not fully visible inside the frame. Similar failures should be assumed possible anywhere long text enters a modal or fixed-width UI region.

Notes for the implementation agent

This is a v0.8.66 release-blocking UI/UX reliability task. Start from the shared layout/rendering code and test fixtures, not from the single screenshot. The goal is a systemic fix for all modal/text overflow behavior.

[Hmbown]

Audit: shared root cause of modal/text overflow (current main 174405f)

Traced the TUI layout primitives. The overflow is vertical, and modals split into two families:

Family A — overflow-prone (build all lines → one top-aligned ParagraphwithWrapand NO.scroll()`, NO reserved footer band): action/footer rows are appended last, so Ratatui silently drops them first when content exceeds inner height.

• ApprovalWidget::render (crates/tui/src/tui/widgets/mod.rs:1200) — controls/options/footer appended at 1385–1476 into the same Vec, painted by one Paragraph at 1494–1497. This is the reported destructive-modal clip.
• ElevationWidget::render (widgets/mod.rs:1931) — fixed popup_height=22, options 2 lines each, no scroll → clips below ~26 rows.
• mode_picker (views/mode_picker.rs:92) — fixed height 9, no budget.
• ConfigView edit form (views/mod.rs:1644-1689) — the one Family-B view that still dumps lines with no reservation.

Family B — already correct (reserve chrome → compute visible-row budget → scroll): ConfigView list (views/mod.rs:1691), HelpView (help.rs:438), status_picker (status_picker.rs:215), SubAgentsView (views/mod.rs:2037), fleet_setup. Worth generalizing.

Root causes

1. Body and action rows share one top-aligned Paragraph with no reserved footer band → trailing actions clip.
2. No scroll / no fit-measurement — Wrap without .scroll(), never comparing wrapped height to inner rows.
3. Heights guessed via magic constants (compact_vertical = height<=20, APPROVAL_CARD_MIN_HEIGHT=18, popup_height=22/9) instead of derived.
4. Wrapping inflates row count unaccounted-for (long localized Policy/Cancel semantics + multiline commands).
5. Popup-rect math copy-pasted across 7 modals (N.min(area.sub(4)) + center) with inconsistent rules.

Proposed shared contract (one helper module)

modal_popup_area(area,max,min,pad) (the duplicated rect math) · render_card(area,buf,chrome) -> inner (title on top border, footer via title_bottom so neither costs a body row) · split_body_actions(inner, action_rows) -> (body, actions) (pinned bottom band, body keeps ≥1 row) · render_scrollable_body(body, lines, scroll) (clamped scroll + "… N more" affordance, reusing help.rs:187/status_picker.rs:278). Family-B refactors to call these; Family-A moves action rows out of the scrollable Vec into the reserved band → "actions always visible" becomes a structural invariant.

Safe first fix (release-sized)

Scoped to ApprovalWidget::render: build body_lines vs action_lines, carve a bottom band of action_lines.len() rows from inner, render body (scrollable) + actions (pinned) separately. No behavior change at comfortable sizes; directly fixes the destructive-modal clip; seeds split_body_actions.

Test strategy

Reuse render_approval_request/buffer_text (widgets/mod.rs:3295-3315): render a Destructive request (long description, >4 impacts, intent, multiline command) at narrow 44x24, short 80x16/80x14 (exercises compact_vertical + sub-18 clamp), normal 80x24; assert the action affordances ([y]/once/[d]/[Esc]/[s], or the four options + Enter footer) are present. They fail today at 80x14, pass after the fix. Add an ElevationWidget analog + a pure unit test for the new helpers.

Note: harvest/pr-3437-approval-modal is in flight on this area — flagging so this doesn't get double-implemented. Happy to take the shared-contract refactor or the safe ApprovalWidget slice if it's not already covered; say the word and I'll PR it.