pmacs/docs/vterm-framing.md

Vterm — framing (Arc 5 stage 2, three-PR delivery)

Revision 5 — 2026-07-21. Status: Stage 1 landed on main through PR #126 at merge 643d1e1. Stages 2 and 3 are not implemented.

Revision 5 establishes the renderer-facing cell invariant before Stage 2: terminal text discards C0/C1 controls rather than storing host-terminal control bytes in grapheme cells. SGR mouse release preserves the released button code; review cleanups remove dead screen paths and stale round-trip state; and the remaining VT-fidelity and allocation nits are explicit deferrals. Architecture is unchanged: C-c is the terminal editor escape (C-c C-c sends interrupt); main-screen resize reflows while alternate screen clips/pads; exited buffers remain with an Emacs-style process message; protocol v19 is additive with complete frames; shared Style stays unchanged; and one BufferId owns one shared process/screen whose most recently active frontend controls size.

This framing follows the compile-mode terminal substrate that landed in PR #113. src/process.rs already owns PTY creation, process groups, bounded readers, stdin writes, resize, exit/restart state, and final drain. src/ansi.rs already owns a streaming UTF-8/CSI/OSC parser, but deliberately emits only the line-oriented subset compile-mode needs. Vterm does not replace either subsystem. It extends their contracts and adds the missing terminal screen state machine.

Arc 5 stage 2 ships as three separately reviewed PRs:

1. terminal core — full-screen VT events, TerminalScreen, internal session ownership/contracts, and headless real-PTY acceptance;
2. TUI integration — terminal-window composition, input, resize, scrollback, selection, and copy;
3. GPU integration — protocol v19 terminal messages, semantic-daemon routing, and a native GPU terminal renderer.

There is no single mega-PR. Each stage is useful and testable by itself, and a later stage starts only after the preceding stage lands on main.

0. Revision 5 — Stage 1 implementation and review record

The first of the three vterm PRs is implemented, reviewed, fully gated, and landed on main as merge 643d1e1. Initial feature commit bbc1f33, first-review fixes through bf972a7, and second-review hardening 9797ada shipped through PR #126, https://github.com/levineuwirth/pmacs/pull/126. It is deliberately headless: there is no pmacs.terminal Lua module, interactive terminal command, TUI paint branch, or GPU/protocol surface yet.

0.1 Public seam and ownership

src/terminal/session.rs exports:

• owned TerminalSpec { command, args, cwd, env, name, rows, cols, scrollback_rows }, with new and strict pre-side-effect validate;
• TerminalProcessState::{Running, Exited(i32), Signaled(String), Crashed(String)};
• owned TerminalSnapshot { buffer_id, size, cells, cursor, title, screen_generation, selection, scroll_offset, at_bottom, pid, process };
• SharedTerminalManager = Rc<RefCell<TerminalManager>>;
• TerminalManager::{new, len, is_empty, open, is_terminal, process_id, snapshot, tick, send, resize, terminate, prune, shutdown}.

The Stage 1 snapshot(BufferId) is intentionally context-free: selection=[], scroll_offset=0, and at_bottom=true. Stage 2 adds per-(FrontendId, WindowId, BufferId) state and an owned snapshot_for_view(...); it must not add a second screen.

EditorState owns the one shared manager. Tick order is supervisor tick → terminal-owned PID drain/watchdog/prune → process.after-tick; LSP, MCP, and ordinary Lua process events retain their existing owners. ProcessSpec gained an AnsiParserProfile: ProcessSpec::new and Lua ansi=true stay LineOriented, while terminal sessions explicitly request FullScreen. Synchronous unpublished terminal spawn failure emits no orphan process event.

Terminal identity buffers are pathless, clean, empty, and buffer-read-only. The guard runs before direct edits, split Lua begin/skip-intercept edits, undo/redo, and local/remote CRDT content import. Attaching an immutable empty CRDT for semantic identity remains valid.

0.2 Stage 1 acceptance mapping

All fourteen Stage 1 criteria are implemented:

1. whole/split parser equivalence: screen::tests::parser_split_points_produce_identical_screen plus the ANSI split matrix;
2. malformed/truncated/over-cap recovery: the 44 ansi::tests, including split UTF-8, ignored CSI/OSC/DCS, and forward-progress cases;
3. cursor/region/edit exactness: cursor_erase_insert_delete_scroll_and_margins_mutate_exact_regions;
4. pending wrap/wide/combining invariants: wide overwrite, split ZWJ/RI/ modifier/variation, right-edge, and continuation tests;
5. alternate/synchronized publication: alternate_screen_preserves_main_and_has_no_history, synchronized_output_gates_snapshot_and_finish_releases, and watchdog;
6. DEC G0/G1 + SI/SO: acs_and_device_replies_are_exact;
7. SGR fidelity and ignored attributes: ANSI SGR/color/underline tests plus screen operation coverage;
8. resize semantics: soft-wrap reflow, wide-boundary/cursor/hard-break tests, alternate clipping, and atomic invalid resize;
9. dual history limits: history_obeys_row_and_cell_caps;
10. bounded DA/DSR/CPR and unsupported-output safety: acs_and_device_replies_are_exact plus parser ignore cases;
11. strict owned specifications: strict_owned_spec_rejects_before_spawn_and_is_mutation_independent;
12. real adversarial PTY/final drain: final_output_precedes_exact_nonzero_annotation_and_buffer_is_retained splits ESC/CSI writes, observes addressed alternate-screen output while running, unblocks raw stdin through send, restores the main screen, and proves final output precedes the exact PID/outcome annotation; zero, non-zero, signal, wrapped, and one-row annotations are separately pinned;
13. lifecycle cleanup: transactional failure, live buffer-kill prune/reap, and TERM-ignoring editor shutdown acceptance;
14. read-only/CRDT invariants: default + CRDT shared acceptance and focused buffer unit tests cover every mutation route and empty bootstrap.

0.3 Final gates and bite

The initial delivery gate run fixed missing acceptance-crate documentation; PR CI then exposed Darwin's numeric strsignal suffix, fixed in 962944b. Review round 1's first Clippy pass found only identical LF/IND match arms, consolidated in bf972a7. Review round 2 added one screen unit and one shared acceptance case; the complete sequence restarted from gate 1:

• cargo fmt --check: clean;
• cargo clippy --workspace --all-targets -- -D warnings: clean;
• default library: 1,661 passed, 3 ignored;
• CRDT library: 1,837 passed, 3 ignored;
• Stage 1 acceptance: 9 default + 10 CRDT passed;
• M4 acceptance: 114 passed, 3 ignored, 1 basedpyright filtered;
• required GPU: 109 passed;
• workspace: 2,769 passed across 79 suites, 19 ignored, 1 filtered;
• git diff --check: clean.

scripts/bite main src/lib.rs --test vterm_stage1_acceptance returned bite: OK: the swapped pre-stage crate root cannot compile the new terminal API. This is explicitly the helper's weaker compile-time API bite, not a clean behavioral assertion failure.

scripts/bite HEAD^ src/ansi.rs --lib parser_split_points_produce_identical_screen returned bite: OK with a clean behavioral assertion failure: the pre-dispatch parser left the cursor at row zero/column four instead of applying NEL/RI/IND and landing at row one/column zero.

scripts/bite HEAD^ src/terminal/screen.rs --test vterm_stage1_acceptance terminal_cells_reject_child_control_characters returned bite: OK with a clean behavioral failure: the pre-hardening screen stored control bytes in a grapheme cluster rather than preserving the blank snapshot.

0.4 Downstream review findings (not implemented)

Stage 2 must derive PTY resize ownership from a durable accepted-input/focus owner before render fan-out, never transient EditorCore::active_frontend. Because KeyDispatcher pending state is global, a terminal C-c continuation must carry its owning FrontendId. Terminal copy should use the existing core kill-ring/clipboard setter, while the local run loop must drain/present clipboard signals; active-terminal BEL likewise uses the out-of-band frontend signal path.

Stage 3 additionally owns pmacs-gpu/src/attach.rs for gated terminal resize/pointer sending and coalescing. Daemon handlers must authenticate source frontend/buffer ownership before input, resize, or pointer routing. Wire-facing terminal state, selection, and limits must live in or be re-exported from pmacs-protocol. The current 16 MiB transport frame cap cannot hold the legal worst complete terminal frame (up to roughly 64 MiB of cluster bytes before encoding overhead): Stage 3 must either raise and test a measured cap at least as large as the legal worst case (review estimate at least 80 MiB), or add a shared aggregate payload bound. It must never silently chunk the locked complete-frame protocol.

0.5 Stage 1 review round 1

The first external review found no ownership, mutation-guard, parser-cap, or security regressions. This round resolves its three merge-adjacent findings:

• ESC D (IND), ESC E (NEL), and ESC M (RI) are typed full-screen operations. RI scrolls down only at the top margin; IND/NEL scroll up at the bottom margin, with NEL additionally returning to column zero. The parser's every-byte-split matrix and focused screen-margin test pin the complete path.
• Terminal children no longer inherit an arbitrary host TERM; absent a caller override, their process environment gets TERM=xterm-256color.
• The TERM-ignoring shutdown acceptance uses kill(pid, 0) through nix instead of Linux-only /proc, so macOS now exercises the assertion.
• Resize retains every surviving application tab stop and installs default stops only in newly added columns.

spawn_ansi_parser intentionally calls AnsiParser::finish() on channel disconnect for both profiles. For existing line-oriented compile/REPL consumers, EOF therefore delivers trailing partial text and required synthetic style/alternate-screen balancing that older code dropped. This is an intentional latent-bug fix and an observable compatibility contract.

The Stage 2 Lua open surface must uniquify colliding default buffer names (*terminal:sh*, *terminal:sh*<2>, and so on) before terminal creation becomes user-visible.

0.6 Stage 1 review round 2

The second external review found no ownership, lifecycle, mutation-guard, transactional-spawn, final-drain, parser-cap, or reflow defects and judged Stage 1 merge-ready. Its renderer-boundary hardening and cheap cleanups are resolved before Stage 2:

• TerminalScreen::write_text drops every char::is_control() value before grapheme segmentation, so parser-produced C1 and direct-event C0/C1 bytes cannot enter copyable or renderable cells. Unit and shared acceptance tests pin a byte-identical blank snapshot.
• SGR mouse release reports retain the released left/middle/right button code and use the lowercase m final.
• The dead line_feed mode parameter and contradictory wide-grapheme branch are removed; all logical-line ID allocation saturates consistently; and terminal prune clears stale round-trip input membership.

Out-of-range DECSTBM bottom clamping, CSI-intermediate clone removal, and a separately named configuration-time scrollback-row cap remain explicit deferrals in §11.

1. Problem and ownership boundary

Pmacs can supervise a PTY and can parse enough ANSI to turn command output into a line-oriented compilation buffer. It cannot host nvim, htop, a shell using cursor motion, or any other application whose output means “mutate a terminal screen” rather than “append text.” The current parser intentionally recognizes and discards cursor addressing, alternate-screen state, scrolling, and most terminal modes. The editor renderer only knows an ordinary rope and its views.

The missing abstraction is a real terminal state machine:

PTY bytes -> AnsiParser -> terminal operations -> TerminalScreen
                                               -> response bytes -> PTY stdin
Frontend input -> terminal input encoder ------------------------^ 

TerminalScreen -> TUI cell composition
               -> protocol v19 TerminalFrame -> GPU cell layout

Ownership is explicit:

• ProcessSupervisor owns the child, PTY file descriptors, bounded worker pipeline, signal delivery, and final drain.
• AnsiParser owns byte-stream framing and escape-sequence decoding. It does not own a screen.
• TerminalScreen owns main/alternate grids, cursor and modes, scroll regions, tab stops, and scrollback.
• TerminalManager owns the mapping from a special editor BufferId to one PTY process plus one TerminalScreen, and owns per-window/per-frontend scroll/selection state.
• The ordinary buffer is an identity and lifecycle anchor only. Terminal screen contents are never mirrored into its rope.
• TUI and GPU frontends own final glyph drawing. They consume cells; they do not reinterpret ANSI or maintain a second VT state machine.

This keeps the existing semantics-down boundary intact. Document text remains a CRDT/rope semantic surface. A terminal is inherently a cell protocol, so its new wire family carries terminal cells, not daemon-formatted document text and not pixels.

2. Ground truth in the current tree

The implementation must preserve these existing contracts:

• ProcessMode::Pty, write_stdin, resize_pty, group-directed signals, bounded output channels, and the TERM/KILL final drain already exist in src/process.rs.
• ProcessSpec::ansi_events moves parsing onto a bounded worker and emits ProcessEventKind::Ansi; raw pipe/LSP consumers retain their byte contract.
• AnsiParser is stateful across arbitrary feed boundaries, has a per-state escape-sequence cap, safely recovers malformed sequences, carries truecolor and underline color, and resets after finish().
• The parser currently emits Text, SetStyle, line-oriented controls, Erase, SetTitle, and alternate-screen markers. Cursor motion and most CSI/DEC operations are parsed but discarded by design.
• Alternate-screen suppression is currently parser-global and load-bearing for compile/REPL consumers. Vterm therefore requires an explicit parser profile: LineOriented preserves today's suppression and event contract; FullScreen emits all screen/mode operations. ProcessSpec selects the profile when ansi_events is enabled; existing Lua process specs default to LineOriented, while terminal sessions construct FullScreen specs.
• EditorState::tick_processes is the main-thread process drain point. LSP/MCP and Lua packages drain events only for process IDs they own.
• EditorCore::round_trip_buffers already disables optimistic frontend edits for special buffer-local input surfaces.
• Grid frontends already receive generic CellDelta; a terminal window can be composed into that grid without a new grid protocol.
• Semantic frontends hold document text through CRDT snapshots and receive byte-anchored style/decorations. They require a new terminal-specific message because an empty terminal identity buffer contains no screen text.
• Desktop persistence saves file-backed buffers only. A pathless terminal buffer is already omitted; no special persistence exception is required.

3. Terminal core model

3.1 Types and files

Stage 1 adds a src/terminal/ module rather than growing editor.rs or ansi.rs into a second monolith:

• screen.rs: TerminalScreen, TerminalGrid, TerminalRow, cursor, modes, scrollback, resize, snapshots;
• input.rs: normalized key/mouse/paste to VT byte encoding;
• session.rs: TerminalManager, TerminalSession, process ownership and event application;
• view.rs (stage 2): per-context viewport/selection helpers and TUI composition.

src/ansi.rs remains the one escape parser. It gains terminal operations; it does not depend on editor state or TerminalScreen.

The public core shape is:

pub struct TerminalManager { /* BufferId -> TerminalSession */ }

pub struct TerminalSelectionSpan {
    pub row: u32,
    pub start_col: u32, // inclusive
    pub end_col: u32,   // exclusive
}

pub enum TerminalProcessState {
    Running,
    Exited(i32),
    Signaled(String),
    Crashed(String),
}

pub struct TerminalSnapshot {
    pub buffer_id: BufferId,
    pub size: CellSize,
    pub cells: Vec<Cell>,       // row-major visible slice
    pub cursor: Option<CellCoord>,
    pub title: Option<String>,
    pub screen_generation: u64,
    pub selection: Vec<TerminalSelectionSpan>,
    pub scroll_offset: u32,
    pub at_bottom: bool,
    pub pid: u32,
    pub process: TerminalProcessState,
}

A snapshot is owned data taken only after all parser events for the current main-thread tick are applied. Renderers never borrow the mutable screen across Lua, editor-core, or process-supervisor calls.

3.2 Parser extension

AnsiEvent gains enough operations to drive a VT-style screen:

• printable text, BEL, CR, LF/VT/FF, BS, HT, and tab-stop set/clear;
• relative and absolute cursor movement (CUU/CUD/CUF/CUB, CNL/CPL, CHA/HPA, VPA, CUP/HVP);
• erase display/line/characters;
• insert/delete characters and lines;
• scroll up/down and set/reset scrolling margins;
• save/restore cursor for both DEC and CSI spellings;
• main/alternate screen enter/exit (47, 1047, 1049);
• mode set/reset for insert, origin, autowrap, application cursor, application keypad, cursor visibility, bracketed paste, focus reporting, synchronized output (?2026), and supported mouse reporting modes;
• SGR and title changes;
• DEC G0/G1 character-set selection plus SI/SO, including the line-drawing characters full-screen TUIs depend on;
• device-status/device-attribute queries represented as typed requests. The session, not the parser, writes bounded response bytes to PTY stdin.

Unknown, private, or malformed sequences stay non-fatal and bounded. Parser state always makes forward progress. DCS/APC/PM payloads remain ignored under the same per-sequence cap; they must not leak into visible text.

The parser-profile split is compatibility-critical. Full-screen support must not make compile-mode start appending alternate-screen text or receiving cursor events it does not understand. AnsiParser::new() and the existing Lua ansi = true process option retain the line-oriented profile; terminal session construction is the only initial full-screen caller. On finish(), LineOriented preserves today's synthetic alternate-screen/style balancing. FullScreen flushes pending text but does not invent an alternate-screen exit or clear cells. The session manager, after applying the actual final parser events, adds the process-exit annotation described in §4.1. Parser internals reset in both profiles.

The shared Cell::Style remains unchanged in this arc. Existing support covers indexed/truecolor foreground/background, bold, italic, underline variants, underline color, and reverse. Faint, conceal, blink, and strikethrough remain ignored rather than being mapped to an unrelated attribute. Extending the shared style would change every cell-carrying postcard encoding and is a separate protocol-wide decision, not hidden vterm scope.

3.3 Screen invariants

TerminalScreen maintains two grids:

• main screen with bounded scrollback;
• alternate screen with no scrollback and an independently saved cursor.

Every physical row records a monotonic logical-line ID, its cell offset within that logical line, and whether it ended in a soft autowrap. This is necessary for copy and resize: hard line breaks become \n; soft-wrapped physical rows are joined into one logical line. Per-view top/selection anchors use (line_id, cell_offset), not a physical row index, so reflow can remap them.

Core invariants:

• cells.len() == rows * cols; every row has exactly cols cells.
• Cursor and scrolling margins are always in bounds after every operation.
• A wide grapheme occupies a leading glyph plus Glyph::Continuation; an overwrite, erase, insert, delete, or resize never leaves an orphaned half.
• Combining codepoints extend the preceding grapheme when one exists; at the left edge they combine with a space cell. Cluster byte length is bounded.
• Autowrap uses the pending-wrap rule: writing the last column arms a wrap; the following printable grapheme performs it. Cursor motion/control clears the pending wrap where VT behavior requires.
• Origin mode interprets absolute row addressing relative to the active scrolling region.
• Insert/delete/scroll operations affect only their defined region and fill exposed cells with the current erase style.
• Entering 1049 saves the main cursor and clears the alternate grid; leaving it restores the main grid/cursor. Repeated set/reset is idempotent.
• Resizing the main screen reflows soft-wrapped logical lines, preserves hard breaks and logical-line IDs, and maps the cursor to the corresponding logical offset. The alternate screen is never reflowed: it is clipped/padded in place, matching a full-screen application's expectation that it will repaint after SIGWINCH.
• Scrollback eviction removes the oldest complete physical rows. It clamps a per-view anchor whose logical line was evicted to the oldest retained row. The default cap is 10,000 rows and an independent 4,000,000-cell budget; either limit may trigger eviction.

Synchronized output is a publication gate, not a second screen. Operations continue mutating TerminalScreen, but snapshots retain the last published generation until ?2026l. Exit/truncation releases the final state. A bounded one-second watchdog also releases and clears synchronization if a buggy child never resets it, preventing a permanently frozen editor surface.

Hard limits are shared constants, not frontend-local guesses:

• maximum rows: 512;
• maximum columns: 512;
• maximum visible cells: 262,144;
• maximum UTF-8 bytes in one grapheme cluster: 256;
• maximum retained history cells: 4,000,000;
• maximum parser control-string payload: the existing 1 KiB cap.

Invalid creation/resize arguments reject atomically. A rejected resize leaves the process and prior screen unchanged.

3.4 Device responses

The core responds to the small query set required by normal shells and TUIs:

• primary and secondary device attributes;
• operating-status report;
• cursor-position report, using current origin semantics.

Responses are fixed templates plus checked decimal coordinates and pass through the existing bounded write_stdin queue. OSC 52 clipboard writes, window manipulation, palette mutation, hyperlinks, sixel, and arbitrary DCS responses are not honored. Child output is untrusted; it cannot directly set the host clipboard or execute an editor command.

4. Session, buffer, and Lua contract

4.1 Session lifecycle

One terminal session owns exactly one process ID, one screen, and one identity buffer. A buffer may appear in several windows/frontends, but there is never a second parser or screen for it.

Creation order is transactional:

1. validate and copy the complete TerminalSpec;
2. create the read-only identity buffer;
3. spawn a raw PTY with ansi_events = FullScreen;
4. install the session in TerminalManager;
5. mark the buffer round-trip-only.

Stage 1 exposes that operation as a Rust manager contract for headless tests and future callers, but deliberately registers no interactive command: opening an unrenderable blank terminal buffer would be a broken partial feature. Stage 2's Lua binding calls the same operation and switches the caller's active window only after it succeeds. On synchronous spawn failure, the temporary buffer is removed and no session entry remains. The terminal process ID is not exposed through pmacs.process; only TerminalManager drains its events, so two consumers cannot steal batches from each other.

EditorState::tick_processes becomes:

1. supervisor tick();
2. terminal manager drains only its owned process IDs, applies all ANSI batches, queues device responses, and records terminal exit state;
3. the existing process.after-tick hook runs;
4. LSP/MCP retain their existing later ticks.

At process exit, final drained output is applied first. The manager then writes one synthetic, default-style hard line into the active terminal screen: Process <PID> exited normally with code 0 for zero; Process <PID> exited abnormally with code <code> for a non-zero code; or Process <PID> exited abnormally with signal <signal> for signal termination. It emits CRLF first when needed so the annotation never overwrites child text. The annotation is terminal-owned (not parser output and not rope text), visible and copyable like the rest of the screen. The buffer remains until the user kills it. Killing the buffer terminates a still-live process/session. A periodic prune handles all buffer-removal paths, including Lua callers that bypass the friendly terminal close API. Editor shutdown uses the existing supervisor shutdown path and cannot restart a terminal.

The wire-visible process state has only the four variants above: synchronous spawn failure never publishes a session, and terminate remains Running until the supervisor reports its final outcome. Crash/signal strings are sanitized to one line and bounded before snapshots or Lua metadata are built.

4.2 Buffer semantics

A terminal buffer is pathless, unmodified, and read-only. Read-only is a buffer-owned invariant, not only an intercept view: Buffer gains a flag and typed error checked by ordinary edits, intercept-skipping host edits, undo/ redo, and local/remote CRDT content mutation. The terminal manager sets it before publishing the session. The rope stays empty for the session lifetime.

Consequences are deliberate:

• buffer lists and window switching see a normal named buffer;
• normal save/autosave/LSP/syntax/CRDT editing does not apply;
• desktop save omits it because it has no file path;
• terminal scrollback does not participate in ordinary document search;
• copy reads from terminal rows, never from a hidden mirror rope;
• killing the buffer is the single editor-lifecycle teardown signal.

Semantic bootstrap may attach an immutable empty CRDT state and send its BufferSnapshot so v18/v19 mirrors can track the buffer identity and CursorByte without decode/state failure. No terminal contents enter that CRDT, and local/remote CRDT edit validation rejects the read-only buffer. The stage-3 terminal frame is the authoritative visible semantic surface; a forged remote operation cannot mutate the empty identity rope.

No hidden “text projection” is maintained. Two representations would drift on cursor rewrites, erase operations, alternate-screen swaps, and resize.

4.3 Lua API

Stage 2 installs pmacs.terminal before user config, loads builtin/runtime/terminal.lua, and registers the interactive command:

local buffer = pmacs.terminal.open {
  command = os.getenv('SHELL') or '/bin/sh',
  args = {},
  cwd = nil,                 -- inherits instance cwd
  env = {},
  name = nil,                -- default: *terminal:<command>*
  rows = 24,
  cols = 80,
  scrollback_rows = 10000,
}

pmacs.terminal.is_terminal(buffer)       -- boolean
pmacs.terminal.state(buffer)             -- fresh plain metadata table
pmacs.terminal.send(buffer, bytes)       -- explicit raw bytes
pmacs.terminal.resize(buffer, rows, cols)
pmacs.terminal.terminate(buffer)         -- SIGTERM; buffer remains
pmacs.terminal.scroll(lines)             -- active terminal window
pmacs.terminal.scroll_to_bottom()
pmacs.terminal.copy_selection()          -- active terminal window

open validates exact raw table fields before side effects. Unknown fields, metatable-provided fields, holes in args, non-string env keys/values, embedded NUL, non-integer dimensions, and out-of-range scrollback reject with the field named. The copied spec is immune to caller mutation. Returned and accepted identity is BufferIdLua, following the rest of the editor API.

The built-in chunk registers terminal as an interactive command. It opens $SHELL without a shell-command interpolation layer. There is no command string split and no implicit sh -c. It also installs terminal-buffer-local commands used after the escape prefix: M-w copies the terminal selection, M-v/C-v page scrollback up/down, and M-</M-> move to the oldest retained row/bottom. These shadow ordinary document commands only during the one-key editor escape; normal terminal input still sends those keys to the child.

5. Stage 2 — TUI integration

5.1 Composition and cursor

For every window whose buffer_id belongs to TerminalManager, the window content rectangle is painted from a terminal snapshot instead of TextView::render. Modeline/statusline composition remains unchanged. Normal text overlays, line-number gutters, syntax, diagnostics, and wrapping are not run over terminal cells.

Each (frontend_id, window_id, buffer_id) owns a TerminalViewState. At bottom, the last screen row aligns with the content rectangle's last row. Scrolling records a stable logical-line top anchor rather than a numeric distance from a moving tail. New child output therefore does not move a scrolled-back viewport or selection. If retention evicts that anchor, it clamps once to the oldest retained row. A “not at bottom” marker is available to the built-in terminal statusline provider.

The active terminal cursor is translated from terminal-local coordinates into the window rectangle. It is hidden when the child hid it, the window is not active, the viewport is scrolled away from bottom, or the coordinate is clipped. Other terminal windows do not paint a cursor.

A smaller window clips; a larger window pads with default cells. Merely rendering a passive view never resizes the PTY.

BEL is forwarded only from the active terminal through the existing frontend signal path. OSC title is sanitized and exposed in terminal metadata/frame and the terminal statusline; it does not rename the identity buffer or directly set the host window title.

5.2 Input precedence

Modal editor surfaces remain authoritative. Input precedence is:

1. minibuffer, incremental search, completion/menu, query-replace, and other existing modal shadows;
2. terminal escape-prefix state;
3. terminal key/mouse/paste handling when the active buffer is terminal;
4. ordinary buffer-local/global keymaps and self-insert.

All terminal buffers remain in round_trip_buffers, so GPU/TUI input reaches this daemon-owned decision before any optimistic edit. Escape-prefix state is per frontend, so one attached user's pending escape never captures another user's next key.

When terminal input owns a normalized key, terminal/input.rs encodes:

• UTF-8 printable characters;
• Ctrl-character mappings, Alt ESC-prefixing, Enter/Tab/Backspace/Escape;
• arrows/Home/End according to application-cursor mode;
• Insert/Delete/Page and F1–F12 xterm sequences;
• Shift-Tab and supported modifier parameters.

Unknown/lock/media keys are ignored, never converted into text. Press is the only actionable event in the current normalized protocol; repeat arrives as repeated press and release is not forwarded. The normalized protocol does not distinguish number-row digits from numeric keypad digits, so application-keypad mode is tracked but cannot transform those ambiguous Key::Char events.

C-c is the fixed stage-2 terminal escape prefix. It is consumed and makes the next key run through the ordinary editor dispatcher, allowing C-c C-x ... for editor commands. C-c C-c sends the literal Ctrl-C byte required to interrupt the child. This is an intentional fixed stage-2 policy.

Paste sends exact bytes, wrapped in ESC[200~ / ESC[201~ only while the child enabled bracketed paste. It never passes through a command shell or Lua. When the child enabled focus reporting, authenticated frontend focus gain/loss sends ESC[I / ESC[O for the controlling terminal. With the mode off, focus changes send no PTY bytes.

5.3 Mouse, selection, copy, and scrollback

If the child enabled a supported mouse mode, pointer events inside the terminal content rectangle are encoded as SGR mouse reports, with coordinates translated to terminal-local 1-based cells. The active mode determines whether press, release, drag, move, and wheel are reported.

Otherwise the editor owns the gesture:

• wheel changes the per-window scrollback offset;
• primary drag creates a terminal-cell selection across history and screen;
• copy serializes selected rows as UTF-8, trims only trailing default blank cells, joins soft-wrapped rows without \n, and separates hard rows with \n;
• wide-cell continuations are never emitted twice;
• a new plain click clears the old selection;
• child output does not move a scrolled-back viewport or selection anchor.

pmacs.terminal.copy_selection() publishes through the existing kill-ring / clipboard path. Ordinary document selection fields remain untouched.

5.4 Resize ownership

One PTY has one kernel window size even when displayed in several views. The controlling view is the active window of core.active_frontend — the frontend that most recently supplied accepted input/focus. Only that view may resize the PTY. Passive views clip/pad.

For grid frontends, the daemon derives the terminal content rows × cols from the computed split rectangle and modeline reservation. Focus/split/frontend resize changes trigger one checked resize_pty; unchanged dimensions are suppressed. The screen model resizes before the child receives SIGWINCH, so its repaint lands into the new geometry. If the computed content rectangle has zero rows or columns, rendering skips it and the prior valid PTY size remains unchanged; zero is never sent to resize_pty.

6. Stage 3 — protocol v19 and GPU integration

6.1 Wire additions

Protocol v19 appends, never inserts, these final variants:

InstanceMessage::TerminalFrame {
    buffer_id: BufferId,
    size: CellSize,
    cells: Vec<Cell>,
    cursor: Option<CellCoord>,
    title: Option<String>,
    screen_generation: u64,
    selection: Vec<TerminalSelectionSpan>,
    scroll_offset: u32,
    at_bottom: bool,
    pid: u32,
    process: TerminalProcessState,
}

FrontendEvent::TerminalResize {
    frontend_id: FrontendId,
    buffer_id: BufferId,
    size: CellSize,
}

FrontendEvent::TerminalPointer {
    frontend_id: FrontendId,
    buffer_id: BufferId,
    coord: CellCoord,
    kind: MouseKind,
    mods: Modifiers,
}

TerminalFrame is a complete visible-grid replacement. Empty is not a clear sentinel: valid terminal sizes are non-zero and cells.len() must equal area. Complete replacement is chosen over a second diff/cache protocol for the first GPU stage. screen_generation advances on screen/process/title mutation; scroll/selection have their own per-context epochs. The producer caches and compares the complete context payload, so a view-only change still sends even when screen_generation is unchanged, while an identical payload is silent.

All terminal frame fields are untrusted at the GPU boundary. Validation checks shared row/column/area limits, exact area, cursor bounds, title length, selection ordering/non-overlap/bounds, cluster UTF-8 and cluster-byte limits, continuation structure, and attachment absence. Invalid input is rejected atomically and the last valid terminal frame remains painted.

The daemon routes terminal resize/pointer events by authenticated session source. Claimed frontend and buffer must match the source's active terminal window. A mismatch is dropped without resizing, selecting, or writing PTY input.

The protocol remains compatible with v18 where structurally possible:

• v18 grid peers need no new message and continue to receive composed CellDelta terminal windows;
• v18 semantic peers receive the immutable empty identity snapshot but no terminal variant. They cannot display the terminal screen; terminal use from those peers is unsupported, while normal document editing remains supported;
• v19 frontends gate the new outbound event variants on negotiated version;
• postcard byte pins cover the old final variants plus the newly appended discriminants.

6.2 Semantic producer

When a semantic frontend's active buffer is a terminal, its producer emits TerminalFrame plus the existing global theme/font/statusline facts that still apply. It suppresses document-only style spans, decorations, inlays, block adornments, folds, file summaries, line numbers, and document cursor layout for that buffer. On switching back to a document, existing caches are invalidated so the first document frame is a full authoritative resync.

The terminal frame is scoped to the authenticated frontend/window context, because scrollback offset and selection are per view. A frame for one split or frontend must never overwrite another context's baseline.

A GPU frontend reports its terminal viewport in cells, computed from its own font metrics and pixel allocation. No pixel dimensions, glyph advances, or DPI cross the daemon boundary. The daemon accepts a resize only from the controlling active frontend defined in §5.4.

6.3 GPU renderer

The GPU keeps a dedicated terminal render mode keyed by active buffer_id. It does not synthesize rope text from cells. Layout rules:

• one terminal column equals the active monospace cell advance;
• Glyph::Continuation consumes a column and draws nothing;
• clusters shape as one cell origin with the declared one/two-column footprint;
• terminal foreground/background/reverse/style resolve from the cell, not syntax or UI faces;
• selection spans resolve through ui.selection over child cells; cursor placement comes from terminal snapshot state;
• rows never wrap in the frontend; clipping is by terminal cell bounds;
• status band remains outside the terminal grid;
• theme/font changes invalidate terminal shaping and geometry caches;
• a font-size or window-size change recomputes the cell viewport and sends one TerminalResize after suppression of identical sizes.

Terminal mouse hit-testing is frontend-local pixel -> terminal cell. The GPU sends TerminalPointer, never a fake source byte offset.

7. Four-agent execution plan

The vterm roster is fixed at four agents for all three stages. Do not add review/scout agents; reuse these owners so state-machine decisions stay coherent.

Owner	Stable scope	Primary files
Lead/integrator	contracts first; TerminalManager, buffer/Lua/builtin wiring, cross-surface acceptance, gates, docs, branches/PRs	src/terminal/session.rs, src/lua_bindings/mod.rs, builtin/runtime/terminal.lua, tests/vterm_*_acceptance.rs, docs
VT core agent	streaming parser operations, screen state machine, input encoder, model units	src/ansi.rs, src/terminal/screen.rs, src/terminal/input.rs
TUI agent	terminal window composition, cursor, per-view scroll/selection/copy, grid input and resize	src/terminal/view.rs, owned sections of src/editor.rs, focused TUI tests
Protocol/GPU agent	v19 types/limits/gates, semantic terminal producer, authenticated daemon routing, GPU state/render/hit-test	pmacs-protocol, src/protocol.rs, src/semantic_render.rs, owned sections of src/daemon.rs, pmacs-gpu/src/main.rs

Coordination rules:

• Lead establishes types and method signatures before another lane edits a caller.
• Strict file ownership. src/editor.rs passes from lead to TUI only after stage-1 construction wiring is settled; src/daemon.rs belongs only to the protocol/GPU lane in stage 3.
• Workers do not update docs, ledgers, branches, or PRs and do not stash, checkout, rebase, or merge.
• Workers add focused tests in their owned modules. Lead alone owns shared acceptance files.
• Exact-path staging only; never git add ..
• Four agents are the total vterm team, not four implementation workers plus a lead.

Per-stage utilization:

• Stage 1: lead + VT core implement; TUI and protocol/GPU owners review the snapshot/input contracts against their future consumers.
• Stage 2: TUI implements; VT core owns encoder corrections; lead integrates lifecycle/acceptance; protocol/GPU owner checks that no TUI-only assumption enters the snapshot contract.
• Stage 3: protocol/GPU implements; TUI and VT core owners add parity cases in their existing surfaces; lead integrates and gates.

8. Branch and PR plan

Stage 1 landed on main through PR #126 at merge 643d1e1. Continue the approved sequential plan:

1. create pmacs-vterm-tui, branch vterm-tui, from post-#126 main; implement, gate, and open the second PR;
2. after Stage 2 merges, create pmacs-vterm-gpu, branch vterm-gpu, from the new main; implement, gate, and open the third PR.

The framing branch is vterm-framing in worktree pmacs-vterm-framing. Implementation branches are not stacked across an unmerged parent. This avoids base-branch deletion/auto-close risk and makes each PR's gate evidence honest.

9. Acceptance

Stage 1 — terminal core

1. Feed every supported CSI/OSC/DEC sequence, including IND/NEL/RI, at every byte split; whole-feed and split-feed screens are identical. RI and forward-index operations additionally pin exact scrolling-margin behavior.
2. Split UTF-8, malformed UTF-8, truncated escape, over-cap control string, and unknown private sequences recover without panic, unbounded growth, or visible escape leakage.
3. Cursor absolute/relative movement, save/restore, origin mode, margins, insert/delete character/line, erase, and scroll mutate only the specified cells.
4. Autowrap pending state, wide glyphs, combining clusters, overwrite, erase, and clipping never create orphan continuations.
5. Main/alternate screen swaps preserve the main grid and cursor; alternate output never enters scrollback. Synchronized output publishes no intermediate frame and releases on reset, EOF, and watchdog expiry.
6. DEC line drawing through G0/G1 + SI/SO renders the expected Unicode box glyphs across split feeds.
7. SGR indexed/truecolor/underline/reverse survives screen operations; ignored attributes leave supported fields unchanged.
8. Main-screen resize reflows only soft wraps, preserves cursor/logical-line identity and application tab stops, and adds defaults only in new columns; alternate-screen resize clips/pads without reflow.
9. Scrollback obeys both row and cell budgets, evicts oldest rows, and keeps the visible grid exact.
10. DA/DSR/CPR query events produce bounded exact response bytes; unsupported OSC/DCS cannot write stdin or clipboard.
11. Strict owned TerminalSpec values reject before spawn and are mutation-independent after spawn.
12. A real PTY child prints cursor-addressed/alternate-screen content in adversarial chunks; final output lands first, then exact normal/non-zero/ signal process annotations are visible and copyable before exit state.
13. Spawn failure leaves no buffer/session/process residue. Killing a live terminal buffer terminates it; editor shutdown leaves no child/reader.
14. Every rope mutation path (ordinary, intercept-skipping, undo/redo, local or remote CRDT edit/import) rejects the read-only terminal buffer and leaves its rope/revision/modified state unchanged; immutable empty CRDT bootstrap remains valid.

Stage 2 — TUI

15. Lua open performs the same strict raw-field validation, publishes no partial state on error, and switches the active window only after success.
16. A terminal window paints exact cells/styles inside its content rectangle; statusline, sibling splits, and outside cells are untouched.
17. Active cursor translation, child-hidden cursor, passive window, clipping, and scrolled-back hiding are exact.
18. Printable, Ctrl, Alt, arrows, Home/End, function keys, application cursor, focus reporting, and unknown keys produce the specified PTY bytes.
19. C-c dispatches one editor key; C-c C-c sends Ctrl-C; modal minibuffer, search, menu, and query-replace remain authoritative.
20. Paste is byte-exact with bracketed wrappers only when enabled.
21. Mouse-reporting modes receive translated SGR reports. With reporting off, the same gestures scroll/select/copy and write no PTY bytes.
22. Copy handles soft/hard wraps, trailing blanks, wide/combining glyphs, resize/reflow, eviction-clamped anchors, and selections crossing history/screen exactly once.
23. The controlling active view alone resizes the PTY; passive split/frontend renders never cause resize thrash.
24. A hermetic real TUI smoke opens /bin/sh, runs a cursor-addressed probe, resizes, scrolls/copies, exits, and restores the host terminal cleanly.

Stage 3 — GPU/protocol

25. Protocol v19 appends all new variants after v18 pins; v18 grid traffic round-trips unchanged and new outbound variants are version-gated.
26. Terminal frame validation accepts exact shared boundaries and atomically rejects over-area, bad area, out-of-bounds cursor, malformed cluster, orphan continuation, invalid selection spans, attachment, overlong title, and overlong process-state text while retaining the prior valid frame.
27. Semantic terminal activation suppresses document-only messages; switching back forces a complete document resync.
28. Two frontends/splits on one terminal keep independent scroll/selection snapshots; only the active controlling context resizes or writes input.
29. Forged frontend/buffer IDs in terminal resize/pointer events cannot affect another terminal or process.
30. Headless GPU rendering pins background rectangles, indexed/truecolor, reverse, wide/combining cells, clipping, cursor visibility, status-band separation, and no frontend wrapping.
31. Font/window resize emits cell dimensions, never pixels, and identical resize requests are suppressed.
32. Theme/font/terminal generation changes invalidate exactly the affected caches; an unchanged terminal frame produces no redraw message.
33. A real daemon + required-GPU smoke runs a full-screen alternate-screen probe, handles input and resize, exits, and returns to the preserved main screen.

10. Gates and bite verification

Every PR runs the standing full gates from AGENTS.md, sequentially, plus its stage acceptance suite. Stage 2 includes a real hermetic TUI PTY smoke; stage 3 includes PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu and the real-daemon GPU probe.

New behavioral acceptance must be bite-verified against the immediate pre-stage tree with scripts/bite where the swapped files compile. Protocol v19 tests additionally pin postcard bytes and verify the older-version daemon filter; a test that merely fails to decode on old code is not a useful bite.

11. Explicit deferrals

Not part of these three PRs:

• terminal image protocols (sixel, kitty graphics, iTerm images);
• OSC 52 host clipboard writes and OSC 8 hyperlink interaction;
• faint, blink, conceal, and strikethrough additions to shared Style;
• kitty keyboard protocol, key release events, media keys, and IME preedit;
• cursor-shape/blink rendering and numeric-keypad distinction absent from the current normalized input/cursor protocol;
• RIS (ESC c), DECALN (ESC # 8), and DEC cursor save/restore mode ?1048;
• CUU/CUD region clamping when the cursor starts inside scroll margins while origin mode is disabled;
• combining a character into the preceding cell across intervening SGR or cursor-control events;
• DECSTBM clamping when an explicit bottom margin exceeds the current screen height; the current core leaves the existing scrolling region unchanged;
• exact xterm ?1047 clear-on-exit and scroll-margin preservation across alternate-screen switches;
• legacy X10 mouse byte encoding when a child enables mouse tracking without SGR mode; Stage 2 sends no report for that unsupported combination;
• nonstandard CSI 3 K ignore semantics (the current core clears the line);
• the ASCII fast path that avoids grapheme-candidate allocation and segmentation for every printable character after another ASCII character, and avoiding the per-sequence intermediates clone in CSI dispatch;
• cleanup of the defensive impossible-state path where a terminal spawn returns a process without a running PID, and borrow-tolerant EditorState drop; normal spawn/rollback/prune/shutdown paths remain covered;
• a separately named configuration-time scrollback-row cap; the current validation conservatively reuses the history-cell cap before the runtime row and cell budgets enforce the effective limit;
• shell integration, prompt marks, command semantic zones, and cwd reporting;
• ordinary document search over terminal history;
• terminal session persistence/reconnect across editor restart;
• reparenting a live terminal process into a second daemon instance;
• user-configurable escape key and scrollback policy.

Deferral means graceful ignore or documented absence, never escape leakage, panic, unbounded allocation, or child leak.

12. Resolved decisions

The 2026-07-21 architecture discussion resolved every Revision 1 question:

1. Fixed terminal editor escape: C-c; C-c C-c sends literal Ctrl-C.
2. Resize: reflow main-screen soft wraps; clip/pad alternate screen.
3. Exit: retain the buffer and append the process PID/outcome line from §4.1.
4. Compatibility: additive v19; v18 grid remains supported, v18 semantic has no terminal surface.
5. GPU wire: complete visible frames with complete-payload suppression.
6. Style: preserve the shared encoding and defer unsupported attributes.
7. Identity: one process/screen per terminal BufferId; the most recently active frontend's active view controls PTY size.