# 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.

Canonical URL: https://ohrouter.com/docs/vt-guard

## 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`. |

**Inspect live VT state and switch safely on a limit hold**

```sh
oh-router inspect term_01a2b3c4d5e6 --json
oh-router switch term_01a2b3c4d5e6 --tier sol --effort max
```
