fix: make terminal scrollback reliable on Firefox Android

[eXPerience83]

Context

Real TrueNAS use of the Remote Dev Codex terminal exposed a mobile-only scrollback problem.

Observed on 2026-08-21 with Firefox on Android against the normal ttyd Codex endpoint (:7681):

• the terminal contains more output above the currently visible region;
• swiping upward can move through some recent output, but eventually stops before reaching older terminal history;
• the same session/output can be scrolled further back from the desktop browser;
• terminal input and the tmux session otherwise remain usable.

This was observed while reading a long Codex task report. The mobile viewport stopped at an intermediate line instead of allowing access to the beginning of the retained output.

Current terminal stack:

• pinned ttyd web terminal;
• xterm-based browser client;
• persistent tmux session;
• tmux mouse support intentionally enabled for scrolling/TUI interaction.

Related work:

• feat: add a touch-friendly terminal control bar for mobile clients #90 tracks a touch-friendly terminal control bar and already plans PgUp/PgDn plus a shared project-owned ttyd/xterm client extension point;
• fix: make terminal selection copying and clipboard feedback reliable #91 tracks selection/copy/clipboard behavior and must remain separate from scrollback semantics.

No existing open issue was found specifically for Android/Firefox scrollback.

Goal

Make retained terminal history reliably reachable by touch on supported Android browsers, without breaking desktop wheel scrolling, tmux mouse behavior, TUI pointer interaction, terminal selection, authentication, reconnect behavior, or the planned mobile controls in #90.

Investigation first

Do not assume the failing layer before reproducing it. Determine whether the lost/unreachable history is caused by one or more of:

1. Firefox Android touch/pointer/wheel event handling;
2. ttyd 1.7.7 client behavior;
3. xterm.js viewport/scrollback handling;
4. tmux mouse-mode translation or copy-mode behavior;
5. alternate-screen transitions from Codex/TUIs;
6. viewport resize / browser chrome / virtual-keyboard changes;
7. a mismatch between xterm scrollback and tmux history.

Record which layer owns the scrollback that remains reachable on desktop but not via Android touch.

Reproduction

Use one persistent tmux/Codex session with enough output to exceed several mobile screens.

Minimum reproduction:

1. Open the Codex terminal in Firefox Android.
2. Generate or display a long multiline output well beyond the viewport height.
3. Scroll upward using normal touch gestures until the terminal stops moving.
4. Record the oldest visible line reached on mobile.
5. Attach to the same session from desktop and verify whether older retained output is still reachable there.
6. Repeat after browser background/foreground and reconnect.

Do not use generated output containing secrets or credentials as the fixture.

Desired behavior

• A normal upward touch gesture can reach the oldest history still retained by the supported terminal/tmux configuration.
• Scrolling must not inject terminal input.
• Returning to the live bottom must remain straightforward.
• Tapping/dragging in TUIs must not be globally disabled merely to make history scrolling work.
• Desktop mouse-wheel behavior must remain unchanged.
• Mobile scrollback should work independently of whether Samsung Keyboard or Gboard is installed.

If browser limitations make native touch scrolling unreliable, evaluate a small explicit fallback such as dedicated scroll/page controls through the shared client structure from #90, but do not treat PgUp/PgDn buttons alone as equivalent to repairing broken touch scrollback unless investigation proves that is the best portable contract.

Coordination with #90

This issue is intentionally separate from #90 because it is a correctness problem in accessing retained terminal history, not just missing mobile keys.

However, both should share one project-owned ttyd/xterm client implementation if frontend changes are needed. Do not create a second independent generated client or duplicate websocket logic.

If #90 lands first, reuse its client packaging and touch-event infrastructure. If this issue lands first and requires client customization, establish an extension point suitable for #90 and #91.

Constraints

Preserve:

• ttyd authentication and --check-origin;
• existing websocket/session behavior;
• tmux persistence/reconnect semantics;
• desktop wheel scrolling;
• Codex/Antigravity TUI mouse interaction;
• current security boundaries and container capabilities.

Do not solve this by:

• disabling tmux mouse globally;
• replacing ttyd/tmux with another remote-terminal product;
• adding privileged containers, browser extensions, userscripts or proxy injection;
• increasing scrollback/history limits blindly before proving history is actually being discarded;
• coupling this fix to unrelated Codex runtime update work or security: harden outer containers and add cross-service isolation canaries #42 hardening.

Validation matrix

Test at least:

• Firefox Android, portrait;
• Firefox Android, landscape;
• Chrome Android, portrait/landscape;
• Firefox desktop on Windows;
• one Chromium desktop browser.

Exercise:

• normal shell output;
• long Codex output;
• wrapped lines and Unicode;
• tmux status line present;
• Codex/TUI alternate-screen entry and exit;
• browser background/foreground;
• reconnect to the same tmux session;
• soft keyboard open and closed where relevant.

For each case record whether the oldest retained history can be reached and whether scrolling causes selection, accidental input, or TUI interaction.

Acceptance criteria

• Firefox Android can reach the full retained terminal history that is reachable from desktop for the same live tmux session.
• Chrome Android behavior is either equivalent or any browser-specific limitation is explicitly documented with a working fallback.
• Desktop scroll behavior remains unchanged.
• tmux mouse/TUI interaction remains functional.
• Reconnect/background-foreground does not reset or corrupt scroll behavior unexpectedly.
• Automated tests cover any project-owned touch/scroll event translation introduced by the fix.
• Manual TrueNAS validation records the exact browser/device versions used.

Scope

Treat this as a focused investigation/fix issue. Do not combine it with #90 mobile key controls, #91 clipboard work, #42 hardening, or the Codex runtime updater PR #150 except where the shared frontend implementation requires coordination.

Proposed PR

fix: restore Android terminal scrollback