# Terminal capability contract

This package aims for the terminal-client workflows people rely on in iTerm2, not a claim that a
browser frame is macOS iTerm2. Every row is assigned to one of four owners so browser products can
compose the package without duplicating or pretending to own behavior.

- **UI** — reusable behavior supplied here.
- **tmux** — durable terminal behavior supplied by this package's shared substrate and tmux.
- **host** — browser/extension policy that must be supplied by the embedding product.
- **excluded** — platform-specific iTerm2 functionality that does not belong in a Volter Harness glue UI.

`verified` means the behavior executes today. `partial` names the remaining residue. `missing`
means it must not be presented as supported.

| Capability family | Owner | State | Contract / residue |
| --- | --- | --- | --- |
| Native Claude `/clear` identity rollover | host substrate | verified | Bounded transcript-edge evidence shared across iTerm and Terminal; ambiguous/claimed successors refused, chain history retained, stale mappings revoked. Controlled native-command tests; arbitrary interior transcript rewrites are not guaranteed. |
| VT screen, alternate screen, color, mouse reporting, IME | UI/xterm | verified | xterm.js is the emulator; the package does not reinterpret terminal bytes. |
| Unicode, emoji, CJK and IME input | UI/xterm | verified | Supplied by stable xterm.js behavior. Experimental grapheme clustering is not enabled by default. |
| Tabs and instant switching | UI | verified | Open viewers stay mounted; switching does not reconnect or replay output. |
| New, attach, detach, stop, open in local terminal | UI/tmux | verified | Detach never stops tmux. Stop remains explicit and ownership-gated. |
| Browser-safe shortcuts and discovery | UI | verified | Option/Alt+Shift namespace only; browser Command/Ctrl bindings are never claimed. |
| Scrollback, selection and copy | UI/xterm | verified | Bounded scrollback and native xterm selection. |
| Find in one terminal, next/previous match | UI | verified | Search covers the active xterm buffer. Cross-tab search is missing. |
| URL detection | UI | partial | The stable xterm web-link provider is active; host policy and end-to-end link opening still need a dedicated proof. |
| Paste and bracketed paste | UI | verified | Multiline or large pastes require confirmation; history is memory-only. Advanced transforms and slow paste are missing. |
| Save terminal contents | UI | partial | The normal buffer is projected to a bounded plain-text download; the browser download boundary and continuous logging still need dedicated proof. |
| Bell and background activity | UI | verified | A controlled tmux shell proved active visual bell plus inactive activity/bell tab state. System notifications are host policy. |
| Dynamic terminal title | UI/tmux | partial | Direct xterm title events are wired, but OSC titles do not currently survive the tmux attachment path. |
| Durable process survival and reconnect | tmux | verified | The tmux session outlives the viewer; a disconnected viewer can request a fresh grant. |
| New-session conversation recovery | host/tmux | verified | A bounded ten-minute ledger binds only one unambiguous new native descriptor by harness, workspace, first user prompt, and pre-launch catalog baseline. |
| Read-only mirroring without terminal reflow | tmux | verified | Observers inherit the pane's live dimensions and cannot send input. |
| Live PTY resize | UI/tmux | verified | Control attachments refit and send bounded resize frames; an isolated real tmux proof resized the PTY to 113×37. Observers never resize. |
| Split panes and draggable layout | UI/tmux | missing | tmux may contain panes, but this UI cannot create, address, or arrange them yet. |
| Window/pane dashboard and rename/reorder | UI/tmux | partial | Sessions are listed and tabs can be selected; windows, panes, rename, and drag reorder are missing. |
| Workspace/layout restoration | UI/host | missing | tmux preserves jobs, but open tabs, active tab, layout, and scrollback are not restored after the UI is destroyed. |
| Profiles, themes, fonts, cursor, scrollback settings | UI/host | missing | The default is tokenized, but there is no user profile model or settings surface yet. |
| Transparent embeddable surface | UI/host | verified | Shell and xterm layers preserve alpha; one tokenized backing layer prevents nested opacity from compounding. |
| Fit versus simulated viewport | UI/host | partial | The workspace exposes an explicit scale/fit policy and control attachments reflow in fit mode. Embedding hosts must supply the two presentation geometries and prove their boundary. |
| Font zoom, fullscreen and popout | host | missing | These alter host geometry or profile settings and require explicit embedding-host commands. |
| Search across tabs / terminal Exposé | UI | missing | Per-terminal search exists; no workspace-wide result navigator exists. |
| Command history, recent directories, prompt navigation | host/shell integration | missing | Requires a shell-integration event model rather than scraping rendered text. |
| Smart file/path selection and semantic history | UI/host | missing | URLs work. Files, line numbers, command URLs, and host open policy are not modeled. |
| Notifications for bell, activity, idle, exit, job completion | host | partial | UI events exist; browser notification permission and agent-status policy belong to the host. |
| Broadcast input | UI/tmux | missing | Must include an unmistakable armed state and explicit target scope before shipping. |
| Triggers, captured output, annotations, badges | host | missing | Requires a declarative event/action layer; never infer these from fragile DOM text. |
| Inline images / sixel / iTerm image protocol | UI/xterm | missing | xterm has an image addon, but it is not loaded or validated here. |
| Paste history persistence, password manager, secure keyboard entry | host/platform | partial | Paste history is deliberately memory-only. Secrets and secure input require native host policy. |
| Save/restore arrangements, undo close, instant replay | UI/host | missing | No layout journal or serialized screen timeline exists yet. |
| Dynamic profiles, Python/AppleScript API, coprocesses | excluded | excluded | These are iTerm2 automation/platform features, not Volter Harness's cross-harness glue role. |
| Touch Bar, native menu bar, macOS window transparency | excluded | excluded | A browser overlay uses browser/Widget Shell equivalents. |
| iTerm web browser and AI Chat | excluded | excluded | Vibewaiting already supplies browser context and semantic agent chat; duplicating them in the terminal package is out of scope. |

The next parity gates are ordered by user impact: live resize and pane addressing; restorable
workspace state; profiles/settings and explicit zoom/popout; cross-tab search and semantic shell
events; logging/replay and guarded broadcast input. A feature remains `missing` until its real
boundary is exercised—dependency presence or registry wiring is not proof.