Documentation · Core concepts

2D VT Screen Guard

Terminal coding agents render interactive TUI menus using cursor positioning, alternate-screen buffers, and inverse-video SGR highlights. oh-vt emulates the real 2D screen so automated writes never confirm unintended paid-credit or upgrade prompts.

2D ECMA-48 VT screen guard blocking keystrokes while a usage-limit credit dialog is on screen.
oh-vt maintains a live 120x40 ECMA-48 grid with SGR cell attributes and screen_epoch checks so automated steering never confirms paid usage-credit prompts.

Real cols x rows ECMA-48 emulation

Substring matching on raw PTY byte streams breaks whenever an Ink or Ratatui interface redraws lines in place with CSI cursor movement (ESC [ H, ESC [ A..G), partial line erases (ESC [ K), or alternate screen buffers (ESC [ ? 1049 h).

Inside every oh-holder process, VtScreen feeds all PTY master output into primary and alternate GridBuffer matrices (default 120x40). Each VtCell records the Unicode scalar, display width (1 standard, 2 East Asian / emoji lead cell, 0 trailing cell), and CellAttrs (bold, inverse, 8-bit or approximated 24-bit foreground color). Secret patterns in visible lines and scrollback pass through oh_protocol::redact_secrets before leaving the holder.

Monotonic screen_epoch write protection

VtScreen maintains a 64-bit screen_epoch counter that increments on structural screen transitions: display erase (CSI J), line erase (CSI K), scroll up or down (CSI S / CSI T), terminal resize, and alternate-screen entry or exit (?47, ?1047, ?1049).

When ohd dispatches HolderRequest::Write { bytes, expected_screen_epoch }, oh-holder compares expected_screen_epoch against the live VtScreen epoch under the holder mutex. If a TUI dialog appeared micro-seconds before the write arrived, the holder rejects the write with screen_epoch_changed before a single byte touches the PTY master.

Recognized ScreenState classifications

ScreenStateDetected TUI conditionWrite & steer behavior
empty_input_boxAgent is idle at an empty prompt box ready for the next instruction.steer delivers immediately (mode: auto or now) and queue flush dispatches the next queued prompt.
permission_promptTool execution confirmation menu with selectable options.Prompts queue safely until resolved via oh-router action <id> approve or deny.
folder_trust_dialogWorkspace directory trust prompt on initial launch.Resolved via oh-router action <id> trust_folder (or automatically when auto_folder_trust policy is enabled).
limit_dialogUsage-limit reached menu offering paid usage credits, overage billing, or plan upgrades.Hard-blocked in both ohd and oh-holder (limit_dialog_blocked). Raw PTY input, steer, and approve cannot confirm paid credits.
client_reset_wait / reset_ready_promptWindow reset countdown or ready-to-resume prompt.Holds queued prompts until reset completes or the session switches tiers via oh-router switch.
Inspect live VT state and switch safely on a limit hold
$ oh-router inspect term_01a2b3c4d5e6 --json
$ oh-router switch term_01a2b3c4d5e6 --tier sol --effort max