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.
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
| ScreenState | Detected TUI condition | Write & steer behavior |
|---|---|---|
empty_input_box | Agent 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_prompt | Tool execution confirmation menu with selectable options. | Prompts queue safely until resolved via oh-router action <id> approve or deny. |
folder_trust_dialog | Workspace directory trust prompt on initial launch. | Resolved via oh-router action <id> trust_folder (or automatically when auto_folder_trust policy is enabled). |
limit_dialog | Usage-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_prompt | Window reset countdown or ready-to-resume prompt. | Holds queued prompts until reset completes or the session switches tiers via oh-router switch. |
$ oh-router inspect term_01a2b3c4d5e6 --json
$ oh-router switch term_01a2b3c4d5e6 --tier sol --effort max