From 3adac8c4cb977371a85422587ffffd13a478650c Mon Sep 17 00:00:00 2001
From: Levi Neuwirth <ln@levineuwirth.org>
Date: Wed, 22 Jul 2026 11:46:45 -0400
Subject: [PATCH 1/7] docs(vterm): carry approved stage 3 framing onto the
 implementation branch

Revision 8 of docs/vterm-framing.md was reviewed and approved on the
documentation branch vterm-stage3-framing. Stage 3 is implemented on this
branch, cut from canonical main, rather than stacked on that branch.

The framing locks additive protocol v19 (TerminalFrame, TerminalResize,
TerminalPointer), an 8 MiB aggregate glyph-byte bound under the unchanged
16 MiB transport cap, dual viewport declaration after every semantic
snapshot, authenticated per-view routing, and a fixed-cell native GPU
renderer. Criteria 28-37 are the scope of this branch.
---
 docs/active-work.md     |  62 ++---
 docs/agent-handoff.md   |  59 ++--
 docs/roadmap-2026-07.md |  17 +-
 docs/vterm-framing.md   | 596 ++++++++++++++++++++++++++++++----------
 4 files changed, 526 insertions(+), 208 deletions(-)

diff --git a/docs/active-work.md b/docs/active-work.md
index 49e000f..0d9ce3d 100644
--- a/docs/active-work.md
+++ b/docs/active-work.md
@@ -14,7 +14,8 @@ backlog.
   machine-local: `origin` may name this canonical URL, a release mirror,
   or something else, and therefore has no authority by name alone.
 - Canonical base at this snapshot:
-  `githubsucks/main` @ `86fc1bc` (Vterm Stage 2 #130 merged; protocol v18).
+  `githubsucks/main` @ `1dd47fc` (modeline detection #132 merged atop Vterm
+  Stage 2 #130; protocol v18).
 - On the transfer source, `origin/main` named a release mirror at
   `d3fa632` and lagged badly. On the current destination, `origin` names
   the canonical URL. This difference is why all recovery begins by
@@ -48,44 +49,43 @@ git worktree list
 git status --short --branch
 ```
 
-The first command must expose `86fc1bc` or a newer intentional main.
+The first command must expose `1dd47fc` or a newer intentional main.
 If it does not, stop and repair the remote/fetch configuration.
 
-## Modeline detection implementation lane
+## Vterm Stage 3 framing lane
 
-- Portable branch: `githubsucks/modeline-detection`
-- Approved framing head: `6b4f3c3`
-- Implementation head: `f8d05d2`
-- Base: originally canonical `main` @ `d5d9b9c`; current canonical `main`
-  @ `86fc1bc` (Vterm Stage 2 #130) is integrated before merge.
-- PR: #132, <https://github.com/levineuwirth/pmacs/pull/132>, open against
-  canonical `main` and explicitly authorized for merge.
-- State: Revision 2's bounded Emacs/Vim parser, explicit-over-inferred
-  precedence, alias normalization, shared fresh-load language pin, LSP path
-  guard, and all thirteen acceptance criteria are implemented. Protocol
-  remains v18.
-- Verification:
-  - focused modeline + shebang-pin acceptance before integration: 7 passed on
-    default LuaJIT and 7 passed on non-default Lua 5.4;
-  - post-integration `cargo fmt --check`;
-  - post-integration `cargo clippy --workspace --all-targets -- -D warnings`;
-  - post-integration `cargo test --lib`: 1,753 passed;
-  - post-integration `cargo test --lib --features crdt`: 1,929 passed;
-  - post-integration `cargo test --test m4_acceptance -- --skip basedpyright`:
-    120 passed, 3 ignored, 1 filtered;
-  - post-integration `PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu`: 109 passed;
-  - post-integration `cargo test --workspace -- --skip basedpyright`: 2,888
-    passed across 82 suites, 19 ignored, 1 filtered;
-  - `git diff --check`.
-- Next: push the current-main integration and merge PR #132 as authorized.
+- Portable branch: `githubsucks/vterm-stage3-framing`
+- Framing contract commit: `d7bb831`; Revision 8 review fixes: `c72dfea`;
+  both follow canonical-main integration.
+- Base: canonical `main` @ `1dd47fc` (modeline detection #132 atop Vterm
+  Stage 2 #130), protocol v18.
+- PR: none. This is framing only; no Stage 3 implementation branch exists.
+- State: `docs/vterm-framing.md` Revision 8 maps criteria 28–37, has passed
+  one external review, and awaits explicit user approval. It locks additive
+  protocol v19 `TerminalFrame`, `TerminalResize`, and `TerminalPointer`; an
+  8 MiB aggregate glyph-byte bound under the unchanged 16 MiB transport cap;
+  dual viewport declaration for the first terminal frame; authenticated
+  per-view semantic routing; and a fixed-cell native GPU renderer/input/cache
+  contract.
+- Stage 2 is landed as PR #130 at merge `86fc1bc`. Stage 3 starts from that
+  integrated substrate and does not reopen its TUI/Lua/controller contracts.
+- Review: no architectural defect. `c72dfea` makes the measured-size fixture
+  maximize style and cluster-prefix overhead, names the GPU clipboard signal
+  path without implying child OSC 52 support, and aligns Arc 5/internal-stage
+  naming.
+- Verification: documentation-only `git diff --check`; framing consistency
+  search. No runtime gates apply before implementation.
+- Next: explicit user approval. After approval, create `vterm-gpu` from the
+  then-current canonical main and implement criteria 28–37; do not stack the
+  feature on this documentation branch.
 
 Recovery worktree on a machine that does not already own the branch:
 
 ```sh
 git worktree add --track \
-  -b modeline-detection \
-  ../pmacs-modeline-detection \
-  githubsucks/modeline-detection
+  -b vterm-stage3-framing \
+  ../pmacs-vterm-stage3-framing \
+  githubsucks/vterm-stage3-framing
 ```
 
 ## Parked lane: kill-ring browser + persistence
diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md
index ef07948..52e6e9a 100644
--- a/docs/agent-handoff.md
+++ b/docs/agent-handoff.md
@@ -1,10 +1,10 @@
 # Agent handoff — cross-machine continuity
 
-**Last updated: 2026-07-22, after Vterm Stage 2 PR #130 review round 2
-was addressed and approved for merge; mode system wiring (#129) and its
-handoff (#131), config registry (#127), Vterm Stage 1 terminal core (#126),
-and completed Themes Arc 4 (#120/#124/#125) are landed on `main`. Vterm
-Stage 3 is not implemented.**
+**Last updated: 2026-07-22, after Vterm Stage 2 landed as PR #130 and
+modeline detection landed as #132. Mode system wiring (#129), config registry
+(#127), Vterm Stage 1 terminal core (#126), and completed Themes Arc 4
+(#120/#124/#125) are also on `main`. Vterm Stage 3 framing Revision 8 has
+passed one external review and is not implemented.**
 This file is the
 bridge between development machines. If you are an agent reading
 this on a fresh clone: this document plus the `docs/*-framing.md`
@@ -18,9 +18,9 @@ commands, read `docs/active-work.md` immediately after this file.
 
 ## 1. Where the project stands (2026-07-22)
 
-- `main` @ `d5d9b9c` (mode system handoff #131), protocol **v18**
-  (`SUPPORTED=[6..18]`; v16 = `ThemeFacts`, v17 = `FontFacts`, v18 =
-  `StatuslineSegments`).
+- `main` @ `1dd47fc` (modeline detection #132 atop Vterm Stage 2 #130),
+  protocol **v18** (`SUPPORTED=[6..18]`; v16 = `ThemeFacts`, v17 =
+  `FontFacts`, v18 = `StatuslineSegments`).
 - **Config registry LANDED — #127** (`docs/config-registry-framing.md`
   rev 3; merge `2e37c04`; two review rounds). `pmacs.config` is the
   typed, introspectable options registry the backlog ranked first, and
@@ -246,10 +246,11 @@ commands, read `docs/active-work.md` immediately after this file.
     behavioral bite; the original `main`/crate-root bite remains explicitly
     weaker compile-time API evidence.
   - Stage 3 owns `pmacs-gpu/src/attach.rs`, authenticated source routing,
-    protocol-owned wire types/limits, and a deliberate complete-frame limit
-    decision: 16 MiB is insufficient; use a measured legal-worst cap or
-    aggregate bound, never silent chunking.
-  - **Stage 2 TUI is implemented on `vterm-tui`** (`docs/vterm-framing.md`
+    protocol-owned wire types/limits, and complete-frame semantic projection.
+    Revision 8 chooses a shared 8 MiB aggregate glyph-byte bound whose measured
+    legal maximum stays below the unchanged 16 MiB transport cap; over-bound
+    snapshots are rejected, never truncated or silently chunked.
+  - **Stage 2 TUI LANDED ON `main` — #130** (`docs/vterm-framing.md`
     Revision 7, criteria 15–27). `TerminalViewKey` keys per-frontend/window
     projection state over one shared process/screen; logical row anchors retain
     scroll/selection through reflow. One authenticated frontend controls at
@@ -286,16 +287,26 @@ commands, read `docs/active-work.md` immediately after this file.
     removes owned cell snapshots from terminal mouse routing. The framing now
     records the transient v18 semantic-controller boundary and bracketed-paste
     injection deferral.
-  - Current-main integration (`3f0252f`) preserves per-frontend terminal
-    dispatch while applying the landed mode-scoped keymap, and exposes the
-    `mode`, `terminal`, and `lsp` statusline providers together.
-  - Post-integration gate: `cargo fmt --check`; strict workspace Clippy;
+  - Current-main integration (`3f0252f`) preserved per-frontend terminal
+    dispatch while applying the landed mode-scoped keymap, and exposed the
+    `mode`, `terminal`, and `lsp` statusline providers together. PR #130 merged
+    at `86fc1bc`.
+  - Final integrated gate: `cargo fmt --check`; strict workspace Clippy;
     1,753 default + 1,929 CRDT library tests (3 ignored each); mode-system
     acceptance 1 default + 1 CRDT; Stage 1 acceptance 9 default + 10 CRDT;
     Stage 2 acceptance 4 default + 4 CRDT; statusline acceptance 7 default +
     8 CRDT; M4 114 passed (3 ignored, 1 filtered); required GPU 109;
     workspace 2,882 passed across 82 suites (19 ignored, 1 filtered);
     `git diff --check` clean.
+  - **Stage 3 framing is Revision 8 on `vterm-stage3-framing`**: additive
+    protocol v19 complete frames/events, dual viewport bootstrap, common
+    validation/aggregate limits, authenticated semantic view adapters, and
+    fixed-cell GPU rendering/input/cache behavior. Criteria 28–37 are mapped.
+    First review found no architectural defect; `c72dfea` pins maximal style
+    and cluster-prefix overhead in the measured frame fixture, corrects the
+    GPU clipboard criterion, and distinguishes Arc 5 stage 2 from its internal
+    Stages 1–3. No implementation branch or PR exists pending explicit user
+    approval.
 - **PARKED: kill-ring browser + persistence.** Revision 2 framing is
   preserved on branch `kill-ring-browser`, but its `0efb5cd` scout is stale
   and must be repeated before implementation. No PR or implementation is
@@ -312,8 +323,9 @@ commands, read `docs/active-work.md` immediately after this file.
     fix (#101).
   - **Arc 4 (themes + extensibility) COMPLETE** — named UI faces (#120),
     live GPU font preferences (#124), statusline providers (#125).
-  - **Arc 5 terminal stage ACTIVE** — compile mode (#113) and Vterm terminal
-    core (#126) landed; Vterm TUI is the next formal stage.
+  - **Arc 5 terminal stage ACTIVE** — compile mode (#113), Vterm terminal
+    core (#126), and Vterm TUI (#130) landed; protocol/GPU Stage 3 is framed
+    and awaiting approval.
   - **Config registry COMPLETE (#127)** — not a numbered arc; it was the
     cross-cutting substrate ranked first on
     `docs/side-quest-backlog.md`'s north star, and it unblocks the
@@ -551,8 +563,12 @@ currently accepted for `autosave.interval-ms`, where a per-buffer
 value is meaningless.
 **Tab width is NOT a config gap** — see §5.
 Mode system (SHIPPED #129): minor modes, `buffer.after-mode-change`,
-mode-scoped settings, modeline detection, `describe-mode`, and persistence of
-explicit major-mode overrides/clears across sessions.
+mode-scoped settings, `describe-mode`, and persistence of explicit major-mode
+overrides/clears across sessions.
+Modeline detection (SHIPPED #132): bounded first/last-line Emacs `-*-`
+and Vim `ft=`/`filetype=` parsing, explicit-over-inferred precedence,
+alias normalization, and shared fresh-load language pinning for
+syntax/highlight/LSP startup.
 Highlight/detection (from the #114–#118 side-quest + injections #122):
 locals-query processing (run each grammar's LOCALS_QUERY so
 `#is?`/`#is-not? local` is honored instead of the current fail-closed
@@ -564,8 +580,7 @@ comment schemes), child-tree incrementality + range-scoped layer rebuild
 runtime/Lua-registered languages (v1 resolves only against
 `BUILTIN_LANGUAGES`), and the next injection *consumers* gated on new
 grammars — HTML/CSS/GraphQL/SQL (`<script>`/`<style>`, JS/TS template
-literals, doc-comment code); modeline detection as a 5th layer
-  (`-*- mode: … -*-` / `# vim: ft=…`);
+literals, doc-comment code);
 byte-accurate multibyte cursor placement in `move_active_cursor_to`
 (still steps one codepoint per LSP byte column). A full Jupyter `.ipynb`
 setup (reader → editable → kernel execution) now has its JSON grammar
diff --git a/docs/roadmap-2026-07.md b/docs/roadmap-2026-07.md
index 6c75a6f..9c1ef1c 100644
--- a/docs/roadmap-2026-07.md
+++ b/docs/roadmap-2026-07.md
@@ -80,7 +80,7 @@ preference at protocol v17; and composable per-window
 `pmacs.statusline` providers transported to semantic/GPU frontends by
 protocol-v18 `StatuslineSegments`.
 
-### Arc 5 — Terminal, staged — VTERM STAGE 2 ON FEATURE BRANCH
+### Arc 5 — Terminal, staged — VTERM STAGE 3 FRAMED
 
 - **Compile mode landed in #113**: line-oriented PTY/ANSI output,
   error-regex navigation, and `M-x compile`.
@@ -89,13 +89,14 @@ protocol-v18 `StatuslineSegments`.
   encoders, internal `TerminalManager`, read-only identity buffers, process
   lifecycle, control-free renderer-boundary cells, and headless real-PTY
   acceptance.
-- **Vterm Stage 2 TUI is implemented on `vterm-tui`**: terminal-window
-  composition, input/resize, per-context scroll/selection/copy, authenticated
-  frontend ownership, BEL/clipboard drainage, and the strict Lua surface.
-- **Vterm Stage 3 protocol/GPU follows Stage 2**: additive protocol v19
-  complete frames, authenticated daemon routing, and native GPU terminal
-  rendering. Its framing must resolve the 16 MiB transport cap's incompatibility
-  with the legal worst complete terminal frame; never silently chunk.
+- **Vterm Stage 2 TUI landed in #130**: terminal-window composition,
+  input/resize, per-context scroll/selection/copy, authenticated frontend
+  ownership, BEL/clipboard drainage, and the strict Lua surface.
+- **Vterm Stage 3 protocol/GPU is framed at Revision 8**: additive protocol
+  v19 complete frames/events, an aggregate glyph-byte bound under the
+  unchanged transport cap, dual viewport bootstrap, authenticated semantic
+  routing, and native fixed-cell GPU terminal rendering. Implementation waits
+  for explicit framing approval.
 
 ### Arc 6 — Folding (keystone gutter rider)
 
diff --git a/docs/vterm-framing.md b/docs/vterm-framing.md
index 84b50aa..5f0e6f0 100644
--- a/docs/vterm-framing.md
+++ b/docs/vterm-framing.md
@@ -1,22 +1,31 @@
 # Vterm — framing (Arc 5 stage 2, three-PR delivery)
 
-**Revision 7 — 2026-07-21. Status: Stage 1 landed on `main` as PR #126
-at merge `643d1e1`; Stage 2 is implemented on branch `vterm-tui` and Stage 3
-is not implemented.**
+**Revision 8 — 2026-07-22. Status: Stage 1 landed on `main` as PR #126
+at merge `643d1e1`; Stage 2 landed as PR #130 at merge `86fc1bc`; Stage 3
+is framed here and is not implemented.**
 
-Revision 7 closes the final three precision findings: `at_bottom` is geometric
-and distinct from live-tail following; the fixed `C-c` transport escape
-deliberately makes ordinary `C-c`-leading bindings unreachable in terminal
-windows; and context-implicit Lua view operations require an authenticated
-interactive origin with exact boolean/error results. Revision 6's durable
-controller and per-view identities, logical-cell anchors, frontend-explicit
-grid rendering, per-frontend dispatch, authenticated v18 input, local
-clipboard/BEL drainage, default-name uniquification, mouse override, and
-resize ordering remain unchanged. 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 accepted
-frontend/window context controls size.
+Revision 8 re-scouts the final stage against the integrated protocol-v18 tree
+and closes its remaining producer/frontend boundary decisions. Protocol v19
+uses one validated complete `TerminalFrame`; a shared 8 MiB aggregate glyph
+budget keeps the largest legal postcard message below the existing 16 MiB
+transport cap instead of broadening every connection's allocation ceiling.
+The first-frame bootstrap is explicit: after every `BufferSnapshot`, a v19 GPU
+sends the document viewport and, when the drawable terminal cell size is
+nonzero, terminal-cell geometry; the daemon accepts only the declaration
+appropriate to the authenticated active buffer.
+Semantic terminal rendering is per frontend/window. Passive views never resize
+the PTY, and terminal mode retains existing statusline, menu, minibuffer, and
+BEL/clipboard channels while suppressing document projection and presence.
+
+Revision 7's geometric `at_bottom`, fixed `C-c` transport escape,
+authenticated context-implicit Lua operations, durable controller and per-view
+identities, logical-cell anchors, frontend-explicit grid rendering,
+per-frontend dispatch, authenticated v18 input, local clipboard/BEL drainage,
+default-name uniquification, mouse override, and resize ordering remain
+unchanged. Main-screen resize reflows while alternate screen clips/pads;
+exited buffers remain with an Emacs-style process message; shared `Style`
+stays unchanged; and one `BufferId` owns one shared process/screen whose most
+recently accepted frontend/window context 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
@@ -26,7 +35,8 @@ 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:
+Arc 5 stage 2 (vterm) ships as three separately reviewed internal stages,
+one PR each:
 
 1. **terminal core** — full-screen VT events, `TerminalScreen`, internal
    session ownership/contracts, and headless real-PTY acceptance;
@@ -38,7 +48,7 @@ Arc 5 stage 2 ships as three separately reviewed PRs:
 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 7 — landed Stage 1 and reviewed Stage 2 contract
+## 0. Revision 8 — landed internal Stages 1–2 and framed Stage 3
 
 The first of the three vterm PRs landed on `main` at merge `643d1e1`.
 Implementation commits `bbc1f33` and `962944b`, first-review fixes through
@@ -189,14 +199,13 @@ The final framing review pinned three precision contracts:
   `active_frontend`.
 
 Stage 3 additionally owns `pmacs-gpu/src/attach.rs` for gated terminal
-resize/pointer sending and coalescing. New daemon event variants must apply the
+resize/pointer sending and coalescing. New daemon event variants apply the
 same authenticated-source rule. Wire-facing terminal state, selection, and
-limits live in or are 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.
+limits live in or are re-exported from `pmacs-protocol`. Revision 8 resolves
+the complete-frame size finding with a shared 8 MiB aggregate glyph-byte
+bound: the maximum legal encoded frame is measured below the unchanged
+16 MiB transport cap. The producer rejects rather than truncates or silently
+chunks an over-bound internal snapshot.
 
 ### 0.5 Stage 1 review round 1
 
@@ -245,6 +254,55 @@ Out-of-range DECSTBM bottom clamping, CSI-intermediate clone removal, and a
 separately named configuration-time scrollback-row cap remain explicit
 deferrals in §11.
 
+### 0.7 Stage 2 landing and Stage 3 re-scout
+
+Stage 2 landed on `main` as PR #130 at merge `86fc1bc` after two review
+rounds. Its integrated tree is the Stage 3 base: protocol v18, four terminal
+view-state acceptance cases in both default and CRDT builds, 109 required-GPU
+tests, and the authenticated daemon/TUI seams described in §§5 and 9. Stage 3
+does not reopen the landed escape, controller, selection, copy, resize, or Lua
+contracts.
+
+The current tree exposes five Stage 3 integration facts that are now locked:
+
+- A semantic frontend learns a buffer switch from `BufferSnapshot`, but an
+  empty terminal identity snapshot does not identify itself as terminal.
+  Therefore the GPU sends both its ordinary byte viewport and a
+  version-gated terminal-cell size after each snapshot; the daemon ignores the
+  inapplicable declaration. No buffer-kind flag or pixel geometry is added.
+- The existing TUI layout adapter subtracts modelines and handles splits from
+  a whole terminal size. Reusing it for the GPU would subtract chrome twice.
+  Stage 3 adds exact active-window semantic adapters whose `CellSize` already
+  describes the terminal content rectangle.
+- `screen_generation` does not cover selection, scroll, or process-state
+  changes. Silence is therefore based on equality of the complete ordered
+  wire payload, not on any one generation counter.
+- The legal Stage 1 cell bounds can exceed the 16 MiB transport cap when every
+  cell carries a maximal combining cluster. Rather than raising the allocation
+  ceiling for all pre-handshake and established messages, v19 adds an 8 MiB
+  aggregate glyph-byte limit and proves the largest legal encoded frame stays
+  below `MAX_FRAME_BYTES`.
+- The GPU's document shaper cannot define terminal column origins. Terminal
+  mode uses fixed cell geometry: explicit row/column rectangles own
+  background, underline, selection, cursor, clipping, and hit testing; text
+  runs are positioned at cell origins and never determine later cell
+  positions.
+
+### 0.8 Stage 3 framing review round 1
+
+The first external Stage 3 review verified the Revision 8 base, named seams,
+limits, Stage 1/2 compatibility, and continuity state and found no
+architectural defect. This round closes its three precision findings:
+
+- The measured maximum payload fixture now maximizes legal `Style` bytes on
+  every cell and distributes the exact glyph budget across legal clusters with
+  lengths chosen to maximize serialized length-prefix overhead.
+- GPU acceptance names terminal copy through `InstanceSignal::Clipboard` and
+  the existing OS clipboard path; it does not imply that child OSC 52 is
+  honored.
+- Arc 5 stage 2 is the vterm delivery; capitalized Stages 1–3 are its three
+  internal PR stages.
+
 ## 1. Problem and ownership boundary
 
 Pmacs can supervise a PTY and can parse enough ANSI to turn command output into
@@ -881,25 +939,29 @@ interval by adding the semantic terminal surface.
 
 ## 6. Stage 3 — protocol v19 and GPU integration
 
-### 6.1 Wire additions
+### 6.1 Protocol-owned wire contract
 
-Protocol v19 appends, never inserts, these final variants:
+Protocol v19 appends, never inserts, one instance message and two frontend
+events after the final v18 variants:
 
 ```rust
-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,
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+pub struct TerminalFrame {
+    pub buffer_id: BufferId,
+    pub size: CellSize,
+    pub cells: Vec<Cell>,
+    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,
 }
 
+InstanceMessage::TerminalFrame(TerminalFrame)
+
 FrontendEvent::TerminalResize {
     frontend_id: FrontendId,
     buffer_id: BufferId,
@@ -915,75 +977,247 @@ FrontendEvent::TerminalPointer {
 }
 ```
 
+`TerminalProcessState`, `TerminalSelectionSpan`, and every limit needed to
+validate these values move to or are re-exported from `pmacs-protocol`; core
+paths may re-export them so Stage 1/2 callers do not gain duplicate types.
+The shared limits are the landed row, column, visible-cell, grapheme, and
+metadata bounds plus:
+
+```rust
+pub const MAX_TERMINAL_FRAME_GLYPH_BYTES: usize = 8 * 1024 * 1024;
+```
+
+The aggregate counts each `Char`'s UTF-8 length, every `Cluster` byte, and zero
+for `Continuation`, with checked addition. `TerminalFrame::validate` is the
+single structural policy used before daemon emission and after GPU decode.
+`pmacs-protocol` takes the direct `unicode-width` dependency needed to validate
+one/two-column glyph and continuation topology; another frontend must not
+copy that policy.
+
+The existing `MAX_FRAME_BYTES = 16 MiB` remains unchanged. A protocol test
+constructs the maximum row/column frame with one maximal legal selection span
+per row and maximum title/process metadata. Every cell carries a legal
+one-column `Cluster` plus the maximal-encoding legal `Style`: RGB foreground,
+background, and underline color, a non-`None` underline, and all boolean flags
+set. The fixture distributes the exact aggregate budget across a legal cluster
+in every cell and chooses cluster lengths to maximize total serialized
+length-prefix overhead rather than packing bytes into a few maximal clusters.
+This maximizes cluster and per-cell style overhead together. It serializes
+the enclosing `InstanceMessage` with `postcard::to_allocvec` and asserts the
+measured length is below `MAX_FRAME_BYTES`. A one-byte-over aggregate is
+rejected before serialization.
+This is a wire-specific bound, not a mutation of the TUI screen: if a child
+constructs a larger internal snapshot, the semantic producer retains its last
+valid baseline, emits nothing malformed or truncated, and logs the first
+distinct bounded error until a valid frame clears the latch.
+
 `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.
+sentinel: valid terminal dimensions are nonzero and `cells.len()` equals the
+checked area exactly. `screen_generation` describes the published terminal
+screen/title generation; selection, scroll, viewport, and process state may
+change without it. The producer compares every ordered field against one
+retained baseline per semantic frontend context. A view-only change therefore
+sends; a byte-identical/equal payload is silent. Buffer snapshot, detach, and
+context replacement clear that baseline so the next valid terminal frame is
+authoritative.
 
-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.
+Validation is atomic and covers:
 
-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.
+- shared nonzero row/column/checked-area and aggregate-glyph limits;
+- exact cell area; each caller separately requires the expected current
+  `buffer_id`;
+- cursor bounds;
+- title and process-state metadata length/control-character rules;
+- valid nonempty cluster UTF-8 within the per-cluster limit;
+- printable one/two-column leading glyphs, required wide continuations, and no
+  orphan continuation; continuation style is ignored in favor of its lead;
+- no `Attachment` in any terminal cell;
+- strictly increasing, one-per-row, nonempty selection spans inside the frame;
+- `at_bottom == (scroll_offset == 0)`.
 
-The protocol remains compatible with v18 where structurally possible:
+Invalid daemon output is never written. Invalid GPU input retains the previous
+valid frame, requests no redraw, and reports one latched diagnostic rather than
+partially applying cells or metadata.
 
-- v18 grid peers need no new message and continue to receive composed
-  `CellDelta` terminal windows;
+Compatibility remains additive:
+
+- v18 grid peers keep receiving the Stage 2 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.
+  terminal message. Terminal use remains unsupported and invisible for those
+  peers; ordinary document editing remains supported;
+- v19 frontends send `TerminalResize`/`TerminalPointer` only to a negotiated
+  v19 daemon;
+- the v19 daemon filters `TerminalFrame` from every wire below v19;
+- postcard pins preserve every v18 discriminant and pin all three appended
+  v19 discriminants.
 
-### 6.2 Semantic producer
+### 6.2 First-frame bootstrap and authenticated routing
 
-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.
+`BufferSnapshot` remains the one semantic display-switch message. It carries
+the terminal identity buffer's valid empty CRDT state and adds no terminal
+flag. Immediately after applying any snapshot, a v19 GPU sends the existing
+`Viewport` for the new replica/generation and, when its derived terminal
+content rectangle has at least one row and column, `TerminalResize` with the
+new `buffer_id` and size in cells. A zero-area window sends no terminal
+declaration until a later geometry change yields a valid size.
 
-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.
+The daemon authenticates the connection source before reading any claimed
+`frontend_id`. A document buffer accepts only `Viewport`; an active terminal
+buffer accepts only `TerminalResize`. The inapplicable declaration is dropped
+without mutation or logging noise. This dual declaration occurs only after a
+snapshot or an actual geometry change, not every frame, and removes the
+otherwise circular dependency where the GPU would need a terminal frame before
+it knew to request one.
 
-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.
+For an authenticated active terminal window, a valid `TerminalResize` always
+records that exact `(frontend, window, buffer)` view size so passive frontends
+can receive their own clipped/padded projection. It resizes the PTY only when
+that exact view is the durable controller from §5.4; resize never claims
+control. The semantic adapter consumes a content `CellSize` directly and does
+not run the TUI placement helper or subtract a modeline again. Unchanged,
+zero/out-of-range, passive, and failed resizes retain existing geometry under
+the Stage 2 ordering contract.
 
-### 6.3 GPU renderer
+`TerminalPointer` must match the authenticated source, active terminal buffer,
+and last accepted terminal viewport, and its coordinate must be in bounds.
+Once accepted, it follows the same Stage 2 terminal pointer path: child SGR
+mouse reporting when eligible, otherwise per-view scroll/selection/context
+menu. Like other accepted pointer/input/focus events, it may claim control.
+A forged source, stale buffer, missing declaration, or out-of-bounds coordinate
+is dropped before view, controller, selection, menu, or PTY mutation.
 
-The GPU keeps a dedicated terminal render mode keyed by active `buffer_id`.
-It does not synthesize rope text from cells. Layout rules:
+Key, paste, focus, detach, BEL, and clipboard keep their landed event/message
+types. The daemon continues to overwrite client-claimed IDs with the
+authenticated source before terminal dispatch. Terminal mode adds no raw-byte
+input message and never sends child bytes through Lua or a shell.
 
-- 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.
+### 6.3 Semantic producer and editor adapters
 
-Terminal mouse hit-testing is frontend-local pixel -> terminal cell. The GPU
-sends `TerminalPointer`, never a fake source byte offset.
+`SemanticRenderState` stores the optional terminal viewport and last valid
+terminal-frame baseline for its one authenticated frontend. When the active
+buffer is terminal and a matching viewport exists, it requests an owned
+snapshot for the exact active `TerminalViewKey`, validates/converts it, and
+emits `TerminalFrame` only on complete-payload change.
+
+The editor-side contract is narrow:
+
+```rust
+prepare_semantic_terminal_view(
+    frontend_id: FrontendId,
+    buffer_id: BufferId,
+    size: CellSize,
+) -> Option<TerminalSnapshot>
+
+sync_semantic_terminal_layout(
+    frontend_id: FrontendId,
+    buffer_id: BufferId,
+    size: CellSize,
+) -> bool
+
+dispatch_semantic_terminal_pointer(
+    frontend_id: FrontendId,
+    buffer_id: BufferId,
+    size: CellSize,
+    coord: CellCoord,
+    kind: MouseKind,
+    mods: Modifiers,
+) -> bool
+```
+
+Each method derives the active `WindowId` from `frontend_id`, verifies that it
+still displays `buffer_id`, and delegates to the existing manager/view/input
+state machines. No method accepts a client-supplied window identity. Semantic
+layout sync runs after event coalescing, before `tick_processes`, exactly beside
+the landed grid sync; snapshot production occurs on the following render pass
+from the already-published screen.
+
+The terminal producer retains the buffer-independent/UI messages required by
+the native frontend: `StatusFacts`, `ThemeFacts`, `FontFacts`,
+`StatuslineSegments`, `MenuPrompt`, and `MinibufferPrompt`, plus daemon-owned
+`DispatchIdle`, `Signal`, and lifecycle messages. The built-in terminal
+statusline provider therefore remains the source of title/process/scroll text.
+It suppresses document-only style spans, decorations, inlays, block
+adornments, folds, file summaries, search/completion surfaces, line numbers,
+document `CursorByte`, and presence for the terminal identity buffer.
+
+On terminal activation the GPU clears/ignores every document-local visual
+cache before painting the first frame. On switching back, snapshot reset clears
+the producer's document baselines so the first matching document viewport
+receives the existing full authoritative style/decoration/summary resync.
+Terminal baselines are per frontend context; one split/frontend can never
+suppress or overwrite another's scroll/selection projection.
+
+### 6.4 GPU state and fixed-cell renderer
+
+The GPU state machine is explicit: `Document` or
+`Terminal { buffer_id, frame, derived paint caches }`. `BufferSnapshot`
+immediately leaves terminal mode, clears the prior terminal frame and
+terminal-only caches, and restores document defaults. A valid matching
+`TerminalFrame` enters terminal mode. A stale-buffer frame is ignored; an
+identical valid frame is retained without rebuild or redraw.
+
+Terminal geometry is the drawable code rectangle above the existing status
+band, with no document gutter or minimap. Rows and columns are
+`floor(pixel_extent / active_cell_metric)`, clamped through the shared
+nonzero protocol limits. Pixels, scale, DPI, and glyph advances never cross
+the wire. Rows never wrap; excess frame rows/columns clip to the declared cell
+rectangle and undersized content is padded with terminal defaults.
+
+Painting is cell-derived rather than rope-derived:
+
+- Every cell rectangle has a fixed origin from `(row, col)` and the active
+  monospace metrics. Backgrounds coalesce only adjacent equal resolved colors.
+- `Default` foreground/background map to the GPU's existing plain-text/window
+  defaults; indexed colors use the existing xterm palette; truecolor is exact.
+  `reverse` swaps the two resolved colors. A continuation draws no glyph and
+  inherits its lead cell's paint semantics.
+- Text shaping is split into explicitly positioned row runs. Contiguous
+  single-width ASCII may share one monospace buffer with rich attribute spans;
+  non-ASCII/cluster/wide leads start at an explicit cell origin and are clipped
+  to their declared one/two-cell footprint. A shaped advance never chooses the
+  next run's column.
+- Bold and italic use font attributes. Single/double/dotted/dashed underlines
+  use fixed-cell quads; curly uses the existing squiggle pipeline. Default
+  underline color follows the post-reverse foreground.
+- Terminal selection is a separate fixed-cell wash resolved through the
+  existing GPU `ui.selection` site; it never rewrites child cell styles.
+  Cursor visibility/position comes only from the frame and paints through the
+  existing caret primitive inside the terminal clip.
+- The status band and its provider runs remain outside/above terminal paint.
+  Document decoration, presence, caret, gutter, and minimap batches are not
+  prepared or drawn in terminal mode.
+
+### 6.5 GPU input, signals, and cache invalidation
+
+Keyboard, paste, focus, and detach reuse existing attach messages and daemon
+encoding. Inside the terminal clip, GPU mouse hit testing is
+pixel-to-`CellCoord`; press/release/drag/move/wheel sends `TerminalPointer`
+instead of a source-byte `Pointer`. The status band/outside clip is never a
+terminal hit. Move/drag events coalesce only while kind, coordinate, and
+modifiers are unchanged.
+
+Window resize, scale change, accepted `FontFacts`, and buffer snapshot
+recompute the cell viewport. One changed size sends one version-gated
+`TerminalResize`; an equal size is silent. A font change clears terminal shape
+and geometry caches until a matching-size authoritative frame arrives.
+
+Invalidation is deliberately narrow:
+
+- a changed terminal frame rebuilds cell text/background/underline/selection/
+  cursor data, but not statusline buffers;
+- `ThemeFacts` rebuilds the selection/status color sites, not child cell
+  shaping;
+- `FontFacts` rebuilds shape and geometry and emits a changed cell viewport;
+- status/statusline/menu/minibuffer messages touch only their existing caches;
+- a duplicate valid terminal frame and an unchanged geometry declaration do
+  no work.
+
+`InstanceSignal::Bell` requests one frontend attention event for each new
+active-terminal BEL; historical/passive suppression remains daemon-owned.
+`InstanceSignal::Clipboard` keeps the existing OS clipboard path. OSC title is
+sanitized frame/statusline metadata only and never becomes a raw window-title
+or terminal-control operation.
 
 ## 7. Four-agent execution plan
 
@@ -993,19 +1227,20 @@ coherent.
 
 | Owner | Stable scope | Primary files |
 | --- | --- | --- |
-| Lead/integrator | contracts first; `TerminalManager`, Lua/builtin wiring, lifecycle/signal integration, shared acceptance, gates, docs, branches/PRs | `src/terminal/session.rs`, `src/lua_bindings/mod.rs`, `builtin/runtime/terminal.lua`, narrow Stage 2 authenticated-dispatch sections of `src/daemon.rs`, `tests/vterm_*_acceptance.rs`, docs |
-| VT core agent | encoder corrections and screen query seams needed by view projection; no renderer ownership | `src/ansi.rs`, `src/terminal/screen.rs`, `src/terminal/input.rs` |
-| TUI agent | view projection, frontend-explicit grid composition/cursor, per-frontend dispatch, local events, scroll/selection/copy/resize | `src/terminal/view.rs`, `src/instance_render.rs`, `src/frontend.rs`, owned sections of `src/editor.rs`, focused TUI tests |
-| Protocol/GPU agent | Stage 2 contract review; Stage 3 v19 types/limits/gates, semantic producer, authenticated new-event routing, GPU state/render/hit-test | `pmacs-protocol`, `src/protocol.rs`, `src/semantic_render.rs`, Stage 3 sections of `src/daemon.rs`, `pmacs-gpu/src/{main,attach}.rs` |
+| Lead/integrator | contracts first; Stage 1/2 manager/Lua lifecycle; Stage 3 semantic producer, authenticated daemon routing, shared acceptance, gates, docs, branches/PRs | `src/terminal/session.rs`, `src/lua_bindings/mod.rs`, `builtin/runtime/terminal.lua`, `src/semantic_render.rs`, owned Stage 3 sections of `src/daemon.rs`, `tests/vterm_*_acceptance.rs`, docs |
+| VT core agent | encoder/screen seams; Stage 3 snapshot-to-wire conversion and shared terminal re-exports, no renderer ownership | `src/ansi.rs`, `src/terminal/{screen,input,session,view}.rs` in assigned non-overlapping sections |
+| TUI agent | landed TUI projection/input; Stage 3 exact active-window semantic adapters and parity tests, no GPU/protocol files | owned sections of `src/editor.rs`, focused TUI/adapter tests |
+| Protocol/GPU agent | protocol v19 types/limits/pins/gates and native GPU state/render/hit-test/attach sending | `pmacs-protocol`, `src/protocol.rs`, `pmacs-gpu/src/{main,attach}.rs` |
 
 Coordination rules:
 
-- Lead establishes types, invariants, and method signatures before another
-  lane edits callers.
-- Strict file ownership. `src/editor.rs` passes from lead to TUI only after
-  construction wiring; lead and TUI coordinate exact non-overlapping
-  `src/daemon.rs`/signal hunks. Stage 3 daemon work begins only after Stage 2
-  lands.
+- Lead establishes invariants and method signatures before another lane edits
+  callers; the protocol/GPU agent then implements the shared wire types.
+- Strict Stage 3 file ownership follows the table. VT-core and TUI edits in
+  `src/terminal/{session,view}.rs` / `src/editor.rs` are agreed as exact
+  non-overlapping symbols before work starts. Only the lead edits
+  `src/semantic_render.rs`, Stage 3 daemon routing, or shared acceptance.
+  Stage 3 begins only from landed Stage 2.
 - Workers do not update docs, ledgers, branches, or PRs and do not stash,
   checkout, rebase, or merge.
 - Workers add focused tests in owned modules. Lead alone owns shared
@@ -1021,25 +1256,33 @@ Per-stage utilization:
 - Stage 2: lead establishes manager/Lua contracts and authenticated adapters;
   TUI implements projection/input/rendering; VT core adds only required
   encoder/query corrections; protocol/GPU checks snapshot neutrality.
-- Stage 3: protocol/GPU implements; TUI and VT core add parity cases in their
-  existing surfaces; lead integrates and gates.
+- Stage 3: lead locks the protocol constants/types and editor method signatures,
+  then owns `src/semantic_render.rs`, authenticated `src/daemon.rs` routing,
+  shared acceptance, and integration. The protocol/GPU agent owns
+  `pmacs-protocol` plus `pmacs-gpu/src/{main,attach}.rs`; the VT-core agent owns
+  snapshot-to-wire conversion/shared terminal re-exports; the TUI agent owns
+  the exact semantic adapters in `src/editor.rs` and parity tests. All four run
+  in parallel only after the lead's contract checkpoint; no TUI rendering
+  behavior changes.
 
 ## 8. Branch and PR plan
 
-Stage 1 landed on `main` as PR #126 at merge `643d1e1`. Continue one clean PR
-at a time:
+Stage 1 landed as PR #126 at merge `643d1e1`. Stage 2 landed as PR #130 at
+merge `86fc1bc`. Revision 8 is preserved for approval on
+`vterm-stage3-framing`, based on the integrated current `main`.
 
-1. Revision 7 framing review is complete and the implementation contract is
-   approved; Stage 2 is implemented on `vterm-tui`, then gated and opened as
-   the second PR;
-2. merge Stage 2 only when the user says;
-3. create `pmacs-vterm-gpu`, branch `vterm-gpu`, from the then-current `main`;
-   implement, gate, and open the third PR.
+After explicit framing approval:
 
-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.
+1. create worktree `pmacs-vterm-gpu` and branch `vterm-gpu` from the then-current
+   canonical `githubsucks/main`;
+2. implement only Stage 3 / criteria 28–37;
+3. run the complete sequential gate and bite suite;
+4. open the third and final vterm PR for user review; never merge it without
+   explicit authorization.
 
+The historical framing branch `vterm-framing` remains the Revision 7 record.
+The Stage 3 implementation is not stacked on a documentation branch or an
+unmerged feature parent.
 
 ## 9. Acceptance
 
@@ -1184,47 +1427,97 @@ coverage remains beside the owning implementation. The criteria map as follows:
 
 ### Stage 3 — GPU/protocol
 
-28. Protocol v19 appends all new variants after v18 pins; v18 grid traffic
-    round-trips unchanged and new outbound variants are version-gated.
-29. 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.
-30. Semantic terminal activation suppresses document-only messages; switching
-    back forces a complete document resync.
-31. Two frontends/splits on one terminal keep independent scroll/selection
-    snapshots; only the active controlling context resizes or writes input.
-32. Forged frontend/buffer IDs in terminal resize/pointer events cannot affect
-    another terminal or process.
-33. Headless GPU rendering pins background rectangles, indexed/truecolor,
-    reverse, wide/combining cells, clipping, cursor visibility, status-band
-    separation, and no frontend wrapping.
-34. Font/window resize emits cell dimensions, never pixels, and identical
-    resize requests are suppressed.
-35. Theme/font/terminal generation changes invalidate exactly the affected
-    caches; an unchanged terminal frame produces no redraw message.
-36. 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.
+28. Protocol v19 appends all three new variants after the v18 pins; v18 grid
+    traffic round-trips byte-identically, v18 semantic document traffic still
+    works, and both outbound directions are independently version-gated.
+29. The measured maximum legal frame uses maximum dimensions, one maximum
+    selection span per row, maximum metadata, the exact aggregate glyph budget
+    present as one legal cluster per cell with lengths chosen to maximize
+    serialized length-prefix overhead, and the maximal-encoding legal style on
+    every cell. Its enclosing message encodes below the unchanged
+    16 MiB transport cap. Validation accepts exact shared boundaries and
+    atomically rejects one-byte-over aggregate, over-area, bad area,
+    out-of-bounds cursor, control/malformed/overlong clusters, orphan/missing
+    continuations, attachments, duplicate/out-of-order-row or otherwise
+    invalid selection spans, inconsistent bottom state, overlong title, and
+    overlong process text while retaining the prior valid frame.
+30. First terminal activation emits one authoritative complete frame after the
+    dual viewport declaration, then stays silent for a completely equal
+    payload. View-only and process-only changes emit despite an unchanged
+    screen generation. Terminal activation suppresses document projection,
+    cursor, presence, gutter, and completion; switching back forces one
+    complete document resync.
+31. Two semantic frontends over one terminal receive independent sizes,
+    scroll, selection, cursor visibility, and baselines while sharing one
+    process/screen. A passive declaration produces its clipped/padded frame but
+    does not resize; only the exact durable controller changes PTY geometry.
+32. Forged frontend/buffer IDs, stale buffers, undeclared viewports, and
+    out-of-bounds terminal pointer/resize events cannot affect another view,
+    controller, terminal selection, menu, PTY size, or child input.
+33. Headless GPU rendering pins default/indexed/truecolor foreground and
+    background, reverse, bold/italic, all supported underline forms, wide and
+    combining footprints, continuation inheritance, selection, cursor,
+    padding/clipping, status-band separation, and absence of frontend wrapping,
+    document gutter/minimap, and document overlays.
+34. GPU key, paste, focus, press/release/drag/move/wheel input reaches the same
+    Stage 2 terminal encoders and ownership paths. Pixel hit testing yields only
+    in-bounds cells, never source bytes or wire pixels, and unchanged move/drag
+    cells coalesce.
+35. Buffer/window/scale/font transitions emit exactly one changed cell
+    declaration and suppress identical sizes. Terminal, theme, font, and
+    statusline changes invalidate only their named caches; duplicate valid
+    frames request no redraw.
+36. Each new active BEL produces one GPU attention action. Terminal copy
+    publishes through `InstanceSignal::Clipboard` and the existing OS
+    clipboard path exactly once. Sanitized OSC title/process/scroll metadata
+    reaches the terminal provider/statusline without becoming a raw host-title
+    or control effect.
+37. A hermetic real daemon + required headless GPU smoke opens `/bin/sh`, runs
+    a full-screen alternate-screen probe, exercises key/paste/mouse/resize,
+    BEL/title metadata, scroll/select/copy through the clipboard signal, clean
+    exit, and buffer switch-back, then proves the preserved main screen and all
+    child/reader/session cleanup.
+
+#### Stage 3 verification map
+
+The cross-surface suite is `tests/vterm_stage3_acceptance.rs`; focused wire and
+GPU assertions remain in `pmacs-protocol` and `pmacs-gpu` respectively.
+
+- **28–29:** postcard discriminant/round-trip pins, common
+  `TerminalFrame::validate` boundary table, measured maximum legal payload, and
+  v18/v19 daemon/frontend send filters.
+- **30–32:** semantic producer baseline/reset tests, dual-declaration
+  bootstrap, real dispatcher source-forgery tests, and two-frontend
+  controller/passive-view acceptance.
+- **33:** pure fixed-cell paint-plan tests plus required headless offscreen
+  pixel probes for representative color/style/wide/selection/cursor/clipping
+  cases.
+- **34–36:** attach/event coalescing tests, authenticated daemon input tests,
+  and headless signal/statusline observations.
+- **37:** one real-daemon/real-PTY/headless-wgpu acceptance path; it is not
+  replaced by a decoded-message fixture.
 
 ## 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.
+stage acceptance suite. Stage 2 included a real hermetic TUI PTY smoke. Stage 3
+adds `cargo test --test vterm_stage3_acceptance`, its CRDT variant,
+`PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu`, the real-daemon/headless-GPU
+probe, and the ordinary workspace sweep.
 
 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.
+v19 tests additionally pin postcard bytes, prove the measured aggregate-bound
+maximum stays below the unchanged transport cap, and verify both
+older-version send filters; 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;
+- 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
@@ -1264,7 +1557,7 @@ panic, unbounded allocation, or child leak.
 
 ## 12. Resolved decisions
 
-The 2026-07-21 architecture, re-scout, and final framing review resolved every
+The 2026-07-22 architecture, re-scout, and final framing review resolved every
 current question:
 
 1. Fixed terminal editor escape: `C-c`; `C-c C-c` sends literal Ctrl-C.
@@ -1272,7 +1565,8 @@ current question:
 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.
+5. GPU wire: complete visible frames with complete-payload suppression under
+   one shared 8 MiB aggregate glyph-byte bound; the 16 MiB transport cap stays.
 6. Style: preserve the shared encoding and defer unsupported attributes.
 7. Identity: one process/screen per terminal `BufferId`.
 8. View state: logical-line/cell anchors per
@@ -1293,3 +1587,11 @@ current question:
     origin and otherwise error without mutation.
 14. Host effects: clipboard and BEL use explicit frontend signals; OSC title
     remains sanitized metadata.
+15. Bootstrap: after every semantic snapshot, v19 sends both byte viewport and
+    terminal cell size; the authenticated daemon accepts only the declaration
+    matching the active buffer kind.
+16. Semantic resize: the declaration records passive view geometry, but only
+    the exact durable controller changes the shared PTY/screen size.
+17. GPU layout: fixed cell rectangles own geometry and hit testing; shaped
+    glyph advances never determine subsequent columns, and OSC title remains
+    metadata rather than a host control effect.

From bdf2b6e4b4b231028170e91eb165dfd53fdd0919 Mon Sep 17 00:00:00 2001
From: Levi Neuwirth <ln@levineuwirth.org>
Date: Wed, 22 Jul 2026 13:28:35 -0400
Subject: [PATCH 2/7] feat(vterm): protocol v19 terminal frames and a native
 GPU terminal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Vterm Stage 3 — the final vterm stage. A semantic frontend can now host a
terminal: the daemon ships complete validated cell grids, and pmacs-gpu
renders them with fixed-cell geometry, its own input path, and no document
projection at all.

Protocol v19 appends three variants after their enums' final v18 members:
InstanceMessage::TerminalFrame (daemon-gated), and FrontendEvent::
TerminalResize / TerminalPointer (frontend-gated). It is the first bump to
gate in both directions, so criterion 28 pins each filter independently and
byte pins on StatuslineSegments and MenuPointer guard the placements.

pmacs-protocol gains src/terminal.rs: the shared row/column/visible-cell/
grapheme/metadata bounds, TerminalProcessState, TerminalSelectionSpan, and
TerminalFrame::validate — the ONE structural policy the daemon runs before
emission and the frontend runs after decode. src/terminal/* re-exports them
so no duplicate type exists, and unicode-width becomes a workspace dependency
so the screen and the validator measure glyph columns with one table. A new
8 MiB aggregate glyph bound keeps the largest legal frame (measured:
13,437,863 bytes) under the unchanged 16 MiB transport cap rather than
widening every connection's allocation ceiling.

The semantic producer suppresses the whole document family for a terminal
buffer while keeping the status band, theme, font, statusline, menu, and
minibuffer, and compares the complete ordered payload rather than
screen_generation — scroll, selection, and process state all change without
advancing it.

Two things the framing did not spell out, both found by the real-daemon
acceptance:

The Viewport gate keys on the authenticated source's ACTIVE buffer, not the
buffer the message names. Viewport also aligns the window to what it
declares, so a stale document viewport in flight when a command opened a
terminal dragged the frontend straight back off it: the window oscillated,
every terminal declaration was refused, and no frame ever arrived, with
nothing logged anywhere.

The producer clears terminal mode on every exit path. The daemon uses that
flag to suppress CursorByte and the presence sweep, so an early return that
left it set kept both suppressed after the frontend returned to a document.

pmacs-gpu/src/terminal.rs is a pure cell-space paint planner, unit-testable
without a GPU. The renderer builds one shaped buffer per text run, so a wide
or cluster glyph's advance can never choose the next column's origin.

Criterion 37 needed a seam rather than a fixture: pmacs-gpu depends only on
pmacs-protocol, so attach::connect's reader sink was generalized and a
--headless-probe mode added. The acceptance drives a real daemon, a real
/bin/sh child, the real attach client, and real composited pixels in one
path — which is how both defects above were found.

Gates: fmt; strict workspace clippy; 1,757 default + 1,933 CRDT library
tests; vterm Stage 1 9/10, Stage 2 4/4, Stage 3 4/5 acceptance
(default/CRDT); statusline 7/8; M4 120; required GPU 127; workspace sweep
2,919 across 83 suites; diff check clean.
---
 Cargo.lock                              |    1 +
 Cargo.toml                              |    6 +-
 docs/active-work.md                     |   74 +-
 docs/agent-handoff.md                   |   80 +-
 docs/vterm-framing.md                   |   82 +-
 pmacs-gpu/src/attach.rs                 |  153 ++-
 pmacs-gpu/src/main.rs                   | 1423 ++++++++++++++++++++++-
 pmacs-gpu/src/terminal.rs               |  753 ++++++++++++
 pmacs-protocol/Cargo.toml               |    6 +
 pmacs-protocol/src/lib.rs               |    6 +
 pmacs-protocol/src/message.rs           |   94 +-
 pmacs-protocol/src/terminal.rs          | 1010 ++++++++++++++++
 src/daemon.rs                           |  153 ++-
 src/editor.rs                           |  193 ++-
 src/frontend.rs                         |    7 +
 src/protocol.rs                         |  138 ++-
 src/semantic_render.rs                  |  199 +++-
 src/terminal/mod.rs                     |   30 +-
 src/terminal/session.rs                 |   55 +-
 src/terminal/view.rs                    |   47 +-
 tests/common/daemon.rs                  |   11 +
 tests/statusline_segments_acceptance.rs |   11 +-
 tests/vterm_stage3_acceptance.rs        |  809 +++++++++++++
 23 files changed, 5177 insertions(+), 164 deletions(-)
 create mode 100644 pmacs-gpu/src/terminal.rs
 create mode 100644 pmacs-protocol/src/terminal.rs
 create mode 100644 tests/vterm_stage3_acceptance.rs

diff --git a/Cargo.lock b/Cargo.lock
index 9ed454f..ba0880f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2594,6 +2594,7 @@ dependencies = [
  "postcard",
  "serde",
  "thiserror 2.0.18",
+ "unicode-width",
 ]
 
 [[package]]
diff --git a/Cargo.toml b/Cargo.toml
index 166751e..8bfb286 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -13,6 +13,10 @@ members = [".", "pmacs-protocol", "pmacs-gpu"]
 serde = { version = "1", features = ["derive"] }
 postcard = { version = "1", features = ["use-std"] }
 thiserror = "2"
+# Shared between `pmacs` (terminal screen) and `pmacs-protocol`
+# (`TerminalFrame::validate`). Pinned here so the producer and the
+# validator agree on every glyph's column width.
+unicode-width = "0.2"
 
 [package]
 name = "pmacs"
@@ -85,7 +89,7 @@ crdt = ["dep:loro", "pmacs-protocol/crdt"]
 [dependencies]
 crossterm = "0.28"
 thiserror = { workspace = true }
-unicode-width = "0.2"
+unicode-width = { workspace = true }
 unicode-segmentation = "1"
 # Regex engine for in-buffer regex search (Q#RX1). `regex::bytes::Regex`
 # matches over rope-snapshot bytes and yields byte offsets directly.
diff --git a/docs/active-work.md b/docs/active-work.md
index 0d9ce3d..4ca124b 100644
--- a/docs/active-work.md
+++ b/docs/active-work.md
@@ -52,42 +52,60 @@ git status --short --branch
 The first command must expose `1dd47fc` or a newer intentional main.
 If it does not, stop and repair the remote/fetch configuration.
 
-## Vterm Stage 3 framing lane
+## Vterm Stage 3 implementation lane
 
-- Portable branch: `githubsucks/vterm-stage3-framing`
-- Framing contract commit: `d7bb831`; Revision 8 review fixes: `c72dfea`;
-  both follow canonical-main integration.
+- Portable branch: `githubsucks/vterm-gpu`
+- Framing carried as the first commit; implementation follows it.
 - Base: canonical `main` @ `1dd47fc` (modeline detection #132 atop Vterm
-  Stage 2 #130), protocol v18.
-- PR: none. This is framing only; no Stage 3 implementation branch exists.
-- State: `docs/vterm-framing.md` Revision 8 maps criteria 28–37, has passed
-  one external review, and awaits explicit user approval. It locks additive
-  protocol v19 `TerminalFrame`, `TerminalResize`, and `TerminalPointer`; an
-  8 MiB aggregate glyph-byte bound under the unchanged 16 MiB transport cap;
-  dual viewport declaration for the first terminal frame; authenticated
-  per-view semantic routing; and a fixed-cell native GPU renderer/input/cache
-  contract.
-- Stage 2 is landed as PR #130 at merge `86fc1bc`. Stage 3 starts from that
-  integrated substrate and does not reopen its TUI/Lua/controller contracts.
-- Review: no architectural defect. `c72dfea` makes the measured-size fixture
-  maximize style and cluster-prefix overhead, names the GPU clipboard signal
-  path without implying child OSC 52 support, and aligns Arc 5/internal-stage
-  naming.
-- Verification: documentation-only `git diff --check`; framing consistency
-  search. No runtime gates apply before implementation.
-- Next: explicit user approval. After approval, create `vterm-gpu` from the
-  then-current canonical main and implement criteria 28–37; do not stack the
-  feature on this documentation branch.
+  Stage 2 #130). Cut from `main`, NOT stacked on `vterm-stage3-framing`,
+  per the framing's §8.
+- PR: open against canonical `main`; never merge without explicit
+  authorization.
+- State: criteria 28-37 implemented. Protocol v19 (`SUPPORTED=[6..=19]`):
+  `InstanceMessage::TerminalFrame` (discriminant 26, daemon-gated),
+  `FrontendEvent::TerminalResize` (11) and `TerminalPointer` (12)
+  (frontend-gated). `pmacs-protocol/src/terminal.rs` owns the shared
+  bounds and `TerminalFrame::validate`; `pmacs-gpu/src/terminal.rs` is the
+  pure cell-space paint planner; `pmacs-gpu --headless-probe` drives the
+  real attach client without winit for criterion 37.
+- Verification (clean tree, this machine):
+  - `cargo fmt --check`;
+  - `cargo clippy --workspace --all-targets -- -D warnings`;
+  - `cargo test --lib`: 1,757 passed (3 ignored);
+  - `cargo test --lib --features crdt`: 1,933 passed (3 ignored);
+  - vterm Stage 1 acceptance: 9 default / 10 CRDT;
+  - vterm Stage 2 acceptance: 4 default / 4 CRDT;
+  - vterm Stage 3 acceptance: 4 default / 5 CRDT (the CRDT-only case is
+    the real-daemon + real-PTY + headless-GPU path);
+  - statusline acceptance: 7 default / 8 CRDT;
+  - `cargo test --test m4_acceptance -- --skip basedpyright`: 120 passed
+    (3 ignored, 1 filtered);
+  - `PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu`: 127 passed;
+  - `cargo test --workspace -- --skip basedpyright`: 2,919 passed across
+    83 suites (19 ignored), one invocation;
+  - `git diff --check`.
+- Open caveat: the required-GPU suite failed ONCE mid-session and did not
+  reproduce across eight subsequent runs or the full sweep. The failing
+  test's identity was not captured. Re-run `PMACS_REQUIRE_GPU=1 cargo test
+  -p pmacs-gpu` a few times on review; if it recurs, capture the name.
+- Next: user review rounds on the PR.
 
-Recovery worktree on a machine that does not already own the branch:
+Recovery worktree:
 
 ```sh
 git worktree add --track \
-  -b vterm-stage3-framing \
-  ../pmacs-vterm-stage3-framing \
-  githubsucks/vterm-stage3-framing
+  -b vterm-gpu \
+  ../pmacs-vterm-gpu \
+  githubsucks/vterm-gpu
 ```
 
+## Vterm Stage 3 framing lane (superseded)
+
+- Portable branch: `githubsucks/vterm-stage3-framing`
+- Revision 8 framing, reviewed and approved. Its content is carried on
+  `vterm-gpu`; this branch is kept only as the approval record and has no
+  unmerged runtime work.
+
 ## Parked lane: kill-ring browser + persistence
 
 - Portable branch: `githubsucks/kill-ring-browser`
diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md
index 52e6e9a..9648dfe 100644
--- a/docs/agent-handoff.md
+++ b/docs/agent-handoff.md
@@ -1,10 +1,11 @@
 # Agent handoff — cross-machine continuity
 
-**Last updated: 2026-07-22, after Vterm Stage 2 landed as PR #130 and
+**Last updated: 2026-07-22, after Vterm Stage 3 (protocol v19, GPU
+terminal) was implemented on `vterm-gpu`. Vterm Stage 2 landed as PR #130 and
 modeline detection landed as #132. Mode system wiring (#129), config registry
 (#127), Vterm Stage 1 terminal core (#126), and completed Themes Arc 4
-(#120/#124/#125) are also on `main`. Vterm Stage 3 framing Revision 8 has
-passed one external review and is not implemented.**
+(#120/#124/#125) are also on `main`. Stage 3 is implemented on `vterm-gpu`
+and awaits review; see `docs/active-work.md`.**
 This file is the
 bridge between development machines. If you are an agent reading
 this on a fresh clone: this document plus the `docs/*-framing.md`
@@ -19,7 +20,8 @@ commands, read `docs/active-work.md` immediately after this file.
 ## 1. Where the project stands (2026-07-22)
 
 - `main` @ `1dd47fc` (modeline detection #132 atop Vterm Stage 2 #130),
-  protocol **v18** (`SUPPORTED=[6..18]`; v16 = `ThemeFacts`, v17 =
+  protocol **v18** on `main`, **v19** on `vterm-gpu`
+  (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`, v17 =
   `FontFacts`, v18 = `StatuslineSegments`).
 - **Config registry LANDED — #127** (`docs/config-registry-framing.md`
   rev 3; merge `2e37c04`; two review rounds). `pmacs.config` is the
@@ -245,11 +247,38 @@ commands, read `docs/active-work.md` immediately after this file.
     is a clean behavioral bite. The parser dispatch has its independent clean
     behavioral bite; the original `main`/crate-root bite remains explicitly
     weaker compile-time API evidence.
-  - Stage 3 owns `pmacs-gpu/src/attach.rs`, authenticated source routing,
-    protocol-owned wire types/limits, and complete-frame semantic projection.
-    Revision 8 chooses a shared 8 MiB aggregate glyph-byte bound whose measured
-    legal maximum stays below the unchanged 16 MiB transport cap; over-bound
-    snapshots are rejected, never truncated or silently chunked.
+  - **Stage 3 GPU/protocol is IMPLEMENTED on `vterm-gpu`** (framing
+    `docs/vterm-framing.md` Revision 9, criteria 28-37; awaiting review).
+    Protocol **v19**: `InstanceMessage::TerminalFrame` (discriminant 26,
+    daemon-gated) plus `FrontendEvent::TerminalResize` (11) and
+    `TerminalPointer` (12), both frontend-gated - the first bump gating in
+    BOTH directions. `SUPPORTED=[6..=19]`.
+  - `pmacs-protocol/src/terminal.rs` now owns the shared terminal bounds,
+    `TerminalProcessState`, `TerminalSelectionSpan`, and the single
+    structural policy `TerminalFrame::validate`; `src/terminal/*`
+    re-exports them so no duplicate type exists. `unicode-width` is a
+    workspace dependency so the screen and the validator measure glyph
+    columns identically. `MAX_TERMINAL_FRAME_GLYPH_BYTES = 8 MiB` bounds
+    the payload instead of widening the transport cap; the measured
+    maximum legal frame encodes to 13,437,863 bytes under the unchanged
+    16 MiB `MAX_FRAME_BYTES`. Over-bound snapshots are rejected, never
+    truncated or silently chunked.
+  - **The `Viewport` gate keys on the AUTHENTICATED SOURCE'S ACTIVE
+    BUFFER, not the buffer the message names.** `Viewport` also aligns the
+    window to the buffer it declares, so a stale document viewport in
+    flight when a command opens a terminal drags the frontend back off it
+    - the terminal then never paints, with no error anywhere. The weaker
+    "is the declared buffer a terminal" reading looks right and fails
+    exactly this way.
+  - Suppression compares the COMPLETE ordered payload, never
+    `screen_generation`: scroll, selection, viewport, and process state all
+    change without advancing it.
+  - GPU: `pmacs-gpu/src/terminal.rs` is a pure cell-space paint planner
+    (testable without a GPU); the renderer builds one shaped buffer per
+    text run so a wide/cluster advance can never choose the next column's
+    origin. `pmacs-gpu --headless-probe` drives the real attach client
+    without winit (`attach::connect_with_sink`), which is how criterion 37
+    gets one real daemon + real PTY + real wgpu path.
   - **Stage 2 TUI LANDED ON `main` — #130** (`docs/vterm-framing.md`
     Revision 7, criteria 15–27). `TerminalViewKey` keys per-frontend/window
     projection state over one shared process/screen; logical row anchors retain
@@ -443,10 +472,12 @@ buffer owns a path's recovery slot; only recover/discard release
 unclaimed crash data; adopt clears the old owner's skip cache.
 
 **Protocol** — encoding-breaking bumps are deliberate and versioned
-(`SUPPORTED=[6..18]`). v15 = `CompletionPopup` +
+(`SUPPORTED=[6..=19]`). v15 = `CompletionPopup` +
 `StatusFacts.message`; v16 = `ThemeFacts`; v17 = `FontFacts`; v18 =
-`StatuslineSegments`. New wire surface ⇒ bump + both-frontends support +
-acceptance.
+`StatuslineSegments`; v19 = the vterm terminal family. New wire surface ⇒
+bump + both-frontends support + acceptance. An APPENDED variant must be
+guarded by a byte pin on the PREVIOUS final variant — its own round-trip
+cannot detect a discriminant shift.
 
 **Fake LSP** (`src/bin/pmacs_fake_lsp.rs`) modes: `fullonly`,
 `rangeonly`, `rangeonly16` (UTF-16 + fail-closed bounds validation),
@@ -512,6 +543,31 @@ acceptance.
   and go through `pmacs.command.invoke("buffer.save")`. Caught only
   because the *other* case failed and the cause was chased instead of
   the assertion adjusted.
+- **A message that ALIGNS state cannot be gated on the state it names.**
+  `FrontendEvent::Viewport` both declares a byte range and switches the
+  frontend's window to the buffer it names. Gating the vterm v19 dual
+  declaration on "is the DECLARED buffer a terminal" therefore left a
+  stale in-flight document viewport free to drag a frontend straight back
+  off a terminal a command had just opened — the window oscillated, the
+  terminal declaration was refused every time, and no frame ever arrived.
+  Nothing errored. The gate has to key on the authenticated source's
+  ACTIVE buffer. Generalizes: when two messages declare competing views of
+  "what am I showing", the arbiter is the daemon's own state, never the
+  claim inside either message.
+- **A pass that sets a mode flag must clear it on EVERY exit.** The
+  semantic producer's terminal pass returned early via `?` when no
+  declaration existed, leaving `terminal_active` set — and the daemon uses
+  that flag to suppress `CursorByte` and the presence sweep, so a frontend
+  that went back to a document silently lost both. Caught by an acceptance
+  assertion, not by any type.
+- **Sub-crate acceptance needs a real seam, not a fixture.** `pmacs-gpu`
+  depends only on `pmacs-protocol`, so "real daemon + real PTY + real
+  wgpu in one path" could not be an in-crate test. Generalizing
+  `attach::connect`'s reader sink (`connect_with_sink`) and adding
+  `--headless-probe` gave the acceptance the REAL handshake, outbox,
+  writer, and `render_to_view` — which is the whole point; a
+  decoded-message fixture would have proved none of the three fit
+  together. The probe found two real defects the in-process tests did not.
 - **Real-grid acceptance must budget for macOS startup and path width.**
   A 100 ms first-Hello timeout failed under loaded macOS CI; use the normal
   five-second handshake window, then short polling reads. An 80-column split
diff --git a/docs/vterm-framing.md b/docs/vterm-framing.md
index 5f0e6f0..fcbd471 100644
--- a/docs/vterm-framing.md
+++ b/docs/vterm-framing.md
@@ -1,8 +1,11 @@
 # Vterm — framing (Arc 5 stage 2, three-PR delivery)
 
-**Revision 8 — 2026-07-22. Status: Stage 1 landed on `main` as PR #126
+**Revision 9 — 2026-07-22. Status: Stage 1 landed on `main` as PR #126
 at merge `643d1e1`; Stage 2 landed as PR #130 at merge `86fc1bc`; Stage 3
-is framed here and is not implemented.**
+is IMPLEMENTED on `vterm-gpu` and awaits review. Revision 8's framing text
+below is preserved verbatim as the approved contract; §0.9 records what the
+implementation actually did, including the two places it had to go beyond
+the letter of the framing.**
 
 Revision 8 re-scouts the final stage against the integrated protocol-v18 tree
 and closes its remaining producer/frontend boundary decisions. Protocol v19
@@ -303,6 +306,81 @@ architectural defect. This round closes its three precision findings:
 - Arc 5 stage 2 is the vterm delivery; capitalized Stages 1–3 are its three
   internal PR stages.
 
+### 0.9 Stage 3 as built
+
+Stage 3 is implemented on `vterm-gpu`, cut from canonical `main` @ `1dd47fc`
+rather than stacked on the documentation branch, with the approved Revision 8
+framing as its first commit. Criteria 28–37 are implemented.
+
+**Protocol.** `pmacs-protocol` gained `src/terminal.rs`, which now owns the
+shared row/column/visible-cell/grapheme/metadata bounds (re-exported from
+`crate::terminal::*` so every Stage 1/2 caller keeps its path and no duplicate
+type exists), `TerminalProcessState`, `TerminalSelectionSpan`, `TerminalFrame`,
+and `TerminalFrame::validate`. `unicode-width` was promoted to a workspace
+dependency so the terminal screen and the wire validator measure glyph columns
+with one table. Discriminants: `InstanceMessage::TerminalFrame` is 26,
+`FrontendEvent::TerminalResize` 11, `TerminalPointer` 12 — each appended after
+its enum's final v18 variant, with placement pins on `StatuslineSegments` and
+`MenuPointer` guarding them. `SUPPORTED_PROTOCOL_VERSIONS` is `[6..=19]`.
+
+The measured maximum legal frame — 512x512, one maximal selection span per row,
+maximum title and process metadata, the maximal-encoding `Style` on every cell,
+and the exact 8 MiB aggregate glyph budget distributed to maximize serialized
+length-prefix overhead — encodes to **13,437,863 bytes**, against the unchanged
+16,777,216-byte transport cap. A one-byte-over aggregate is rejected before
+serialization.
+
+**Two decisions the implementation had to make.**
+
+1. *The `Viewport` gate keys on the ACTIVE buffer, not the declared one.*
+   §6.2 says "a document buffer accepts only `Viewport`; an active terminal
+   buffer accepts only `TerminalResize`", and the first implementation read
+   that as a test on the buffer the message names. That is not sufficient:
+   `Viewport` also ALIGNS the frontend's window to the buffer it names, so a
+   stale document viewport still in flight when a command opened a terminal
+   dragged the frontend straight back off it — the real-daemon acceptance
+   showed the window oscillating and no frame ever arriving. The daemon now
+   drops `Viewport` when the authenticated source's active window shows a
+   terminal (and, defensively, when the declared buffer is itself a terminal).
+   This is the framing's own wording taken literally; it is recorded here
+   because the weaker reading looks correct and silently produces a terminal
+   that never paints.
+2. *The producer clears terminal mode on every exit path.* `in_terminal_mode`
+   is used daemon-side to suppress `CursorByte` and the presence sweep. An
+   early return from the terminal pass that left the flag set kept those
+   suppressed after the frontend went back to a document. Every path out of
+   the pass now clears it explicitly.
+
+**Renderer.** `pmacs-gpu/src/terminal.rs` is a pure, cell-space paint planner:
+it resolves a validated frame into background/underline/selection/cursor runs
+and explicitly positioned text runs, taking the frontend's two default colors
+as parameters so every paint rule is unit-testable without a GPU. `main.rs`
+holds a two-state machine (`Document` / `Terminal`), builds one shaped buffer
+per text run so a wide or cluster glyph's advance can never choose the next
+column's origin, and swaps the document quad/squiggle/caret/minimap/gutter
+batches for terminal ones while leaving the status band and popup layers alone.
+
+**Criterion 37.** The GPU is a separate binary that depends only on
+`pmacs-protocol`, so the single real path is driven as a process:
+`pmacs-gpu --headless-probe <socket> <report>` attaches through the REAL
+`attach` client (the reader sink was generalized so the winit path and the probe
+share one handshake, outbox, and writer), presses a real key that opens a real
+`/bin/sh` child, applies real `TerminalFrame`s, composites real pixels through
+`render_to_view`, sends real input and a real geometry change, and writes named
+observations the acceptance asserts on. `tests/vterm_stage3_acceptance.rs`
+`a37_…` is that test; it is CRDT-gated because the daemon advertises
+`crdt_replica` / `semantic_render` only on CRDT builds.
+
+**Verification (from a clean tree).** `cargo fmt --check`; strict workspace
+Clippy; 1,757 default + 1,933 CRDT library tests (3 ignored each); Stage 1
+acceptance 9 default + 10 CRDT; Stage 2 acceptance 4 default + 4 CRDT; Stage 3
+acceptance 4 default + 5 CRDT (the fifth is the CRDT-gated real-daemon path);
+statusline acceptance 7 default + 8 CRDT; M4 120 passed (3 ignored, 1 filtered);
+required GPU 127; one-invocation workspace sweep 2,919 passed across 83 suites
+(19 ignored); `git diff --check` clean. One unexplained single failure of the
+required-GPU suite occurred once mid-session and did not reproduce across eight
+subsequent runs including the full sweep; its identity was not captured.
+
 ## 1. Problem and ownership boundary
 
 Pmacs can supervise a PTY and can parse enough ANSI to turn command output into
diff --git a/pmacs-gpu/src/attach.rs b/pmacs-gpu/src/attach.rs
index ad4226d..7377ddb 100644
--- a/pmacs-gpu/src/attach.rs
+++ b/pmacs-gpu/src/attach.rs
@@ -23,10 +23,10 @@ use std::sync::{Arc, Condvar, Mutex};
 use std::thread;
 
 use pmacs_protocol::{
-    AttachRequest, BufferId, ByteRange, CrdtOp, FrontendCapabilities, FrontendEvent, FrontendId,
-    Hello, InstanceMessage, Key, KeyEvent, Modifiers, PROTOCOL_VERSION, PointerKind,
-    SUPPORTED_PROTOCOL_VERSIONS, TransportError, is_supported_protocol_version, read_message,
-    write_message,
+    AttachRequest, BufferId, ByteRange, CellCoord, CellSize, CrdtOp, FrontendCapabilities,
+    FrontendEvent, FrontendId, Hello, InstanceMessage, Key, KeyEvent, Modifiers, MouseKind,
+    PROTOCOL_VERSION, PointerKind, SUPPORTED_PROTOCOL_VERSIONS, TransportError,
+    is_supported_protocol_version, read_message, write_message,
 };
 use winit::event_loop::EventLoopProxy;
 
@@ -141,6 +141,19 @@ fn coalesce_kind(event: &FrontendEvent) -> Option<u8> {
             kind: PointerKind::Drag,
             ..
         } => Some(1),
+        // Vterm Stage 3 — terminal pointer MOVE and DRAG are the
+        // high-frequency terminal gestures and coalesce like their
+        // document twin. Press, release, and wheel stay lossless:
+        // collapsing a wheel run would silently lose scroll distance,
+        // and collapsing a press/release would break selection.
+        FrontendEvent::TerminalPointer {
+            kind: MouseKind::Move,
+            ..
+        } => Some(2),
+        FrontendEvent::TerminalPointer {
+            kind: MouseKind::Drag(_),
+            ..
+        } => Some(3),
         _ => None,
     }
 }
@@ -216,6 +229,24 @@ impl Outbox {
 pub fn connect(
     socket_path: &Path,
     proxy: EventLoopProxy<AppEvent>,
+) -> Result<AttachClient, AttachClientError> {
+    connect_with_sink(socket_path, move |event| {
+        proxy.send_event(AppEvent::Attach(event)).is_ok()
+    })
+}
+
+/// [`connect`], with the decoded-message destination left to the caller.
+///
+/// The winit path forwards to the event loop; the headless probe used by
+/// the Stage 3 acceptance forwards to a channel. Both drive the SAME
+/// handshake, capability gate, reader, writer, and outbox — a probe that
+/// reimplemented any of that would prove nothing about the real client.
+///
+/// `sink` returns `false` when its destination is gone, which stops the
+/// reader thread.
+pub fn connect_with_sink(
+    socket_path: &Path,
+    sink: impl Fn(AttachEvent) -> bool + Send + 'static,
 ) -> Result<AttachClient, AttachClientError> {
     let stream = UnixStream::connect(socket_path).map_err(AttachClientError::Connect)?;
 
@@ -300,17 +331,13 @@ pub fn connect(
             loop {
                 match read_message::<InstanceMessage>(&mut read_stream) {
                     Ok(msg) => {
-                        if proxy
-                            .send_event(AppEvent::Attach(AttachEvent::Message(Box::new(msg))))
-                            .is_err()
-                        {
-                            // Main loop torn down — quietly exit.
+                        if !sink(AttachEvent::Message(Box::new(msg))) {
+                            // Destination torn down — quietly exit.
                             return;
                         }
                     }
                     Err(e) => {
-                        let _ = proxy
-                            .send_event(AppEvent::Attach(AttachEvent::Disconnected(e.to_string())));
+                        sink(AttachEvent::Disconnected(e.to_string()));
                         return;
                     }
                 }
@@ -455,6 +482,44 @@ impl AttachClient {
         })
     }
 
+    /// Send a `FrontendEvent::TerminalResize` (Vterm Stage 3): the
+    /// terminal-cell geometry this frontend has on screen. Callers gate
+    /// on [`Self::server_protocol_version`] `>= 19`.
+    ///
+    /// Cells, never pixels — the frontend divides its own drawable
+    /// rectangle by its own metrics, keeping the no-pixels contract the
+    /// document `Viewport` established.
+    pub fn send_terminal_resize(
+        &self,
+        buffer_id: BufferId,
+        size: CellSize,
+    ) -> Result<(), TransportError> {
+        self.send_event(FrontendEvent::TerminalResize {
+            frontend_id: self.frontend_id,
+            buffer_id,
+            size,
+        })
+    }
+
+    /// Send a `FrontendEvent::TerminalPointer` (Vterm Stage 3): a
+    /// gesture hit-tested locally to a terminal cell. Callers gate on
+    /// [`Self::server_protocol_version`] `>= 19`.
+    pub fn send_terminal_pointer(
+        &self,
+        buffer_id: BufferId,
+        coord: CellCoord,
+        kind: MouseKind,
+        mods: Modifiers,
+    ) -> Result<(), TransportError> {
+        self.send_event(FrontendEvent::TerminalPointer {
+            frontend_id: self.frontend_id,
+            buffer_id,
+            coord,
+            kind,
+            mods,
+        })
+    }
+
     /// Send a `FrontendEvent::MenuPointer` (Q#CM1) — open-menu
     /// navigation hit-tested locally against the popup we drew. `index`
     /// is the row the pointer is over (`None` = off the menu); `invoke`
@@ -518,7 +583,7 @@ impl AttachClient {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use pmacs_protocol::InstanceCapabilities;
+    use pmacs_protocol::{InstanceCapabilities, MouseButton};
 
     fn caps(
         multi_frontend: bool,
@@ -652,6 +717,70 @@ mod tests {
         ));
     }
 
+    fn fe_terminal_pointer(kind: MouseKind, row: u32, col: u32) -> FrontendEvent {
+        FrontendEvent::TerminalPointer {
+            frontend_id: FrontendId(1),
+            buffer_id: BufferId::from_raw(1),
+            coord: CellCoord::new(row, col),
+            kind,
+            mods: Modifiers::NONE,
+        }
+    }
+
+    /// Acceptance 34: terminal move/drag runs coalesce to the latest
+    /// cell, while press, release, and wheel stay lossless and ordered.
+    #[test]
+    fn terminal_motion_coalesces_but_presses_and_wheels_stay_lossless() {
+        let mut ob = Outbox::new();
+        ob.enqueue(fe_terminal_pointer(
+            MouseKind::Down(MouseButton::Left),
+            0,
+            0,
+        ));
+        ob.enqueue(fe_terminal_pointer(
+            MouseKind::Drag(MouseButton::Left),
+            0,
+            1,
+        ));
+        ob.enqueue(fe_terminal_pointer(
+            MouseKind::Drag(MouseButton::Left),
+            0,
+            2,
+        ));
+        ob.enqueue(fe_terminal_pointer(
+            MouseKind::Drag(MouseButton::Left),
+            0,
+            3,
+        ));
+        ob.enqueue(fe_terminal_pointer(MouseKind::Up(MouseButton::Left), 0, 3));
+        assert_eq!(ob.queue.len(), 3, "the drag run collapsed to one");
+        assert!(matches!(
+            &ob.queue[1],
+            FrontendEvent::TerminalPointer {
+                kind: MouseKind::Drag(MouseButton::Left),
+                coord: CellCoord { row: 0, col: 3 },
+                ..
+            }
+        ));
+
+        // Wheel ticks carry scroll DISTANCE; collapsing a run would
+        // silently lose scrollback rows.
+        let mut wheel = Outbox::new();
+        wheel.enqueue(fe_terminal_pointer(MouseKind::ScrollUp, 1, 1));
+        wheel.enqueue(fe_terminal_pointer(MouseKind::ScrollUp, 1, 1));
+        wheel.enqueue(fe_terminal_pointer(MouseKind::ScrollUp, 1, 1));
+        assert_eq!(wheel.queue.len(), 3, "wheel ticks are lossless");
+
+        // Hover motion coalesces, but not across a different kind.
+        let mut moves = Outbox::new();
+        moves.enqueue(fe_terminal_pointer(MouseKind::Move, 2, 1));
+        moves.enqueue(fe_terminal_pointer(MouseKind::Move, 2, 2));
+        assert_eq!(moves.queue.len(), 1);
+        moves.enqueue(fe_terminal_pointer(MouseKind::ScrollDown, 2, 2));
+        moves.enqueue(fe_terminal_pointer(MouseKind::Move, 2, 3));
+        assert_eq!(moves.queue.len(), 3);
+    }
+
     #[test]
     fn coalescing_only_collapses_a_same_kind_tail() {
         let mut ob = Outbox::new();
diff --git a/pmacs-gpu/src/main.rs b/pmacs-gpu/src/main.rs
index 4da619e..e18ce27 100644
--- a/pmacs-gpu/src/main.rs
+++ b/pmacs-gpu/src/main.rs
@@ -23,9 +23,10 @@
 //! the SIL Open Font License 1.1 (see `fonts/OFL.txt`).
 
 mod attach;
+mod terminal;
 
 use std::collections::HashMap;
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex};
 
 use glyphon::cosmic_text::{Affinity, Cursor, Scroll, Wrap};
@@ -35,12 +36,13 @@ use glyphon::{
 };
 use loro::{ContainerTrait, ExportMode};
 use pmacs_protocol::{
-    AdornmentContent, AdornmentPlacement, BufferId, ByteRange, CompletionPopupRow, CrdtOp,
-    Decoration, DecorationKind, DecorationSegment, FrontendId, InlineAdornment, InstanceMessage,
-    InstanceSignal, Key as ProtocolKey, LineNumberMode, MAX_STATUSLINE_FACE_BYTES,
-    MAX_STATUSLINE_PROVIDERS, MAX_STATUSLINE_SEGMENT_BYTES, MAX_STATUSLINE_TOTAL_TEXT_BYTES,
-    MenuPromptRow, Modifiers, PointerKind, SelectionSnapshot, StatuslineSegment, StyleSegment,
-    StyleSpan,
+    AdornmentContent, AdornmentPlacement, BufferId, ByteRange, CellCoord, CellSize,
+    CompletionPopupRow, CrdtOp, Decoration, DecorationKind, DecorationSegment, FrontendId,
+    InlineAdornment, InstanceMessage, InstanceSignal, Key as ProtocolKey, LineNumberMode,
+    MAX_STATUSLINE_FACE_BYTES, MAX_STATUSLINE_PROVIDERS, MAX_STATUSLINE_SEGMENT_BYTES,
+    MAX_STATUSLINE_TOTAL_TEXT_BYTES, MenuPromptRow, Modifiers, MouseButton as ProtocolMouseButton,
+    MouseKind as ProtocolMouseKind, PointerKind, SelectionSnapshot, StatuslineSegment,
+    StyleSegment, StyleSpan, TerminalFrame, UnderlineStyle,
     cell::{Color as CellColor, Style as CellStyle},
     is_builtin_pair_char, is_modeline_face_name,
 };
@@ -52,6 +54,7 @@ use winit::keyboard::{Key, NamedKey};
 use winit::window::{Window, WindowId};
 
 use crate::attach::{AttachClient, AttachEvent};
+use crate::terminal::{TerminalPaintPlan, TerminalPalette};
 
 /// Bundled font (SIL Open Font License 1.1 — see `fonts/OFL.txt`).
 const JETBRAINS_MONO: &[u8] = include_bytes!("../fonts/JetBrainsMono-Regular.ttf");
@@ -72,6 +75,20 @@ const TEST_FONT_SOURCES: &[&[u8]] = &[
     TEST_FAMILY_BOLD,
 ];
 
+/// Extra font sources a headless `State` assembles with. Test builds add
+/// the fixture families the font-preference tests rely on; the Vterm
+/// Stage 3 attach probe, which is a release-mode binary, gets none.
+fn headless_extra_font_sources() -> &'static [&'static [u8]] {
+    #[cfg(test)]
+    {
+        TEST_FONT_SOURCES
+    }
+    #[cfg(not(test))]
+    {
+        &[]
+    }
+}
+
 /// The default font family — the query `family: None` (and every
 /// rejected requested family) resolves through (framing Q#F6). The
 /// bundle guarantees the query is never empty; a monospaced
@@ -305,6 +322,17 @@ const BG: wgpu::Color = wgpu::Color {
 
 const TEXT_LEFT: f32 = 16.0;
 const TEXT_TOP: f32 = 16.0;
+
+/// Stroke thickness for terminal straight-underline forms, in pixels.
+const TERMINAL_UNDERLINE_PX: f32 = 1.0;
+
+/// Fallback terminal selection wash when no `ui.selection` face is set.
+const TERMINAL_SELECTION_RGBA: [f32; 4] = [0.35, 0.45, 0.75, 0.35];
+
+/// The terminal cursor block. Translucent so the glyph beneath stays
+/// readable — a terminal cursor sits ON a character, unlike the
+/// document caret, which sits between two.
+const TERMINAL_CURSOR_RGBA: [f32; 4] = [0.85, 0.85, 0.9, 0.55];
 /// Caret bar width in px, and its color (bright, near-opaque — drawn
 /// over the text so it reads as the active insertion point). Session
 /// B1.
@@ -524,6 +552,16 @@ enum Mode {
     /// `pmacs-gpu --attach <socket>`: connect + render the daemon's
     /// rope.
     Attach { socket: PathBuf },
+    /// `pmacs-gpu --headless-probe <socket> <report>`: attach through
+    /// the real client, render real frames offscreen, and write a
+    /// machine-readable report.
+    ///
+    /// This exists for the Vterm Stage 3 acceptance, which must exercise
+    /// a real daemon, a real PTY, and real wgpu rendering in ONE path.
+    /// It drives the same `attach` handshake, the same
+    /// `apply_attach_message`, and the same `render_to_view` the windowed
+    /// mode does — only winit is absent, because CI has no display.
+    HeadlessProbe { socket: PathBuf, report: PathBuf },
 }
 
 /// Number of decimal digits in `n` (for `n >= 1`); allocation-free. Sizes
@@ -542,6 +580,9 @@ fn decimal_digits(mut n: usize) -> u32 {
 fn main() {
     env_logger::init();
     let mode = parse_args(std::env::args().skip(1).collect());
+    if let Mode::HeadlessProbe { socket, report } = &mode {
+        std::process::exit(run_headless_probe(socket, report));
+    }
     let event_loop = EventLoop::<AppEvent>::with_user_event()
         .build()
         .expect("create winit event loop");
@@ -558,6 +599,201 @@ fn main() {
         .expect("winit event loop run_app");
 }
 
+/// Drive a real attach session headlessly and write a probe report.
+///
+/// The Vterm Stage 3 acceptance needs one path that exercises a real
+/// daemon, a real PTY child, and real wgpu rendering together — a
+/// decoded-message fixture would prove none of the three fit. This is
+/// that path minus winit, which CI has no display for.
+///
+/// The report is one `key=value` line per fact so the acceptance test
+/// asserts on named observations rather than parsing prose. Exit code 0
+/// means the report was written; anything else means the probe could not
+/// run and the acceptance fails loudly rather than reading a stale file.
+#[allow(
+    clippy::too_many_lines,
+    reason = "one linear attach-render-observe probe session"
+)]
+fn run_headless_probe(socket: &Path, report: &Path) -> i32 {
+    use std::fmt::Write as _;
+    use std::sync::mpsc;
+
+    let Some(mut state) = State::new_headless(900, 600, "(connecting...)") else {
+        eprintln!("pmacs-gpu probe: no wgpu adapter available");
+        return 3;
+    };
+
+    let (tx, rx) = mpsc::channel::<AttachEvent>();
+    let client = match attach::connect_with_sink(socket, move |event| tx.send(event).is_ok()) {
+        Ok(client) => client,
+        Err(error) => {
+            eprintln!("pmacs-gpu probe: attach failed: {error}");
+            return 4;
+        }
+    };
+    state.set_frontend_id(client.frontend_id());
+
+    let mut facts = ProbeFacts {
+        server_protocol_version: client.server_protocol_version(),
+        ..ProbeFacts::default()
+    };
+
+    // Ask the daemon to open the acceptance terminal in THIS frontend's
+    // window. Going through a real key press is the point: the daemon's
+    // `terminal.open` targets the invoking frontend, so this is what
+    // puts the attached window on a terminal buffer.
+    if let Some(chord) = std::env::var_os("PMACS_GPU_PROBE_OPEN_KEY")
+        .and_then(|value| value.into_string().ok())
+        .and_then(|value| value.chars().next())
+    {
+        let _ = client.send_key(ProtocolKey::Char(chord), Modifiers::CTRL | Modifiers::ALT);
+    }
+
+    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(20);
+    let mut sent_input = false;
+    let mut sent_resize = false;
+    while std::time::Instant::now() < deadline {
+        let Ok(event) = rx.recv_timeout(std::time::Duration::from_millis(200)) else {
+            continue;
+        };
+        match event {
+            AttachEvent::Disconnected(reason) => {
+                facts.disconnect = Some(reason);
+                break;
+            }
+            AttachEvent::Message(msg) => {
+                let is_snapshot = matches!(*msg, InstanceMessage::BufferSnapshot { .. });
+                if let InstanceMessage::TerminalFrame(frame) = msg.as_ref() {
+                    facts.frames += 1;
+                    facts.last_frame_cols = frame.size.cols;
+                    facts.last_frame_rows = frame.size.rows;
+                    facts.last_frame_text = frame_probe_text(frame);
+                    facts.last_title.clone_from(&frame.title);
+                }
+                state.apply_attach_message(*msg);
+                if is_snapshot {
+                    // The dual declaration: a byte viewport for a
+                    // document, a cell size for a terminal. The daemon
+                    // keeps whichever matches.
+                    if let Some(buffer_id) = state.current_buffer_id {
+                        let (start, end) = state.view_range;
+                        let _ = client.send_viewport(
+                            buffer_id,
+                            pmacs_protocol::ByteRange { start, end },
+                            0,
+                        );
+                    }
+                    if let Some((buffer_id, size)) = state.terminal_declaration_if_changed() {
+                        facts.declarations += 1;
+                        let _ = client.send_terminal_resize(buffer_id, size);
+                    }
+                }
+                if state.terminal.is_some() {
+                    facts.entered_terminal_mode = true;
+                    // Render a REAL frame through the real composition
+                    // path, then record that it composited.
+                    let pixels = state.render_offscreen();
+                    let first = pixels.first().copied().unwrap_or_default();
+                    if pixels.iter().any(|&b| b != first) {
+                        facts.rendered_nonuniform_frames += 1;
+                    }
+                    if !sent_input && facts.frames >= 1 {
+                        sent_input = true;
+                        // Real child input over the real wire.
+                        let _ = client.send_key(ProtocolKey::Char('x'), Modifiers::NONE);
+                        let _ = client.send_key(ProtocolKey::Enter, Modifiers::NONE);
+                    }
+                    if !sent_resize && facts.frames >= 2 {
+                        sent_resize = true;
+                        state.resize(700, 500);
+                        if let Some((buffer_id, size)) = state.terminal_declaration_if_changed() {
+                            facts.declarations += 1;
+                            facts.resized_cols = size.cols;
+                            facts.resized_rows = size.rows;
+                            let _ = client.send_terminal_resize(buffer_id, size);
+                        }
+                    }
+                    if facts.resized_cols > 0 && facts.last_frame_cols == facts.resized_cols {
+                        facts.observed_resized_frame = true;
+                    }
+                }
+                if facts.observed_resized_frame && facts.rendered_nonuniform_frames >= 2 {
+                    break;
+                }
+            }
+        }
+    }
+
+    let mut out = String::new();
+    let _ = writeln!(
+        out,
+        "server_protocol_version={}",
+        facts.server_protocol_version
+    );
+    let _ = writeln!(out, "declarations={}", facts.declarations);
+    let _ = writeln!(out, "frames={}", facts.frames);
+    let _ = writeln!(
+        out,
+        "rendered_nonuniform_frames={}",
+        facts.rendered_nonuniform_frames
+    );
+    let _ = writeln!(out, "entered_terminal_mode={}", facts.entered_terminal_mode);
+    let _ = writeln!(
+        out,
+        "observed_resized_frame={}",
+        facts.observed_resized_frame
+    );
+    let _ = writeln!(out, "last_frame_rows={}", facts.last_frame_rows);
+    let _ = writeln!(out, "last_frame_cols={}", facts.last_frame_cols);
+    let _ = writeln!(out, "resized_rows={}", facts.resized_rows);
+    let _ = writeln!(out, "resized_cols={}", facts.resized_cols);
+    let _ = writeln!(out, "last_title={}", facts.last_title.unwrap_or_default());
+    let _ = writeln!(out, "last_frame_text={}", facts.last_frame_text);
+    let _ = writeln!(out, "disconnect={}", facts.disconnect.unwrap_or_default());
+    if let Err(error) = std::fs::write(report, out) {
+        eprintln!(
+            "pmacs-gpu probe: writing {} failed: {error}",
+            report.display()
+        );
+        return 5;
+    }
+    0
+}
+
+/// Named observations the headless probe reports back to the acceptance.
+#[derive(Default)]
+struct ProbeFacts {
+    server_protocol_version: u32,
+    declarations: u32,
+    frames: u32,
+    rendered_nonuniform_frames: u32,
+    entered_terminal_mode: bool,
+    observed_resized_frame: bool,
+    last_frame_rows: u32,
+    last_frame_cols: u32,
+    resized_rows: u32,
+    resized_cols: u32,
+    last_title: Option<String>,
+    last_frame_text: String,
+    disconnect: Option<String>,
+}
+
+/// One-line printable text of a terminal frame, for probe reporting.
+fn frame_probe_text(frame: &TerminalFrame) -> String {
+    let mut text = String::new();
+    for cell in &frame.cells {
+        match &cell.glyph {
+            pmacs_protocol::Glyph::Char(ch) => text.push(*ch),
+            pmacs_protocol::Glyph::Cluster(bytes) => {
+                text.push_str(&String::from_utf8_lossy(bytes));
+            }
+            pmacs_protocol::Glyph::Continuation => {}
+        }
+    }
+    text.retain(|ch| !ch.is_control());
+    text
+}
+
 /// Tiny argv parser. No `clap` because the surface is genuinely two
 /// shapes; full CLI parsing arrives when there's more to parse. The
 /// `for` ranges over a small set: at most one `--attach <socket>` or
@@ -577,6 +813,20 @@ fn parse_args(args: Vec<String>) -> Mode {
                 socket: PathBuf::from(socket),
             }
         }
+        "--headless-probe" => {
+            let socket = iter.next().unwrap_or_else(|| {
+                eprintln!("pmacs-gpu: --headless-probe requires a socket path");
+                std::process::exit(2);
+            });
+            let report = iter.next().unwrap_or_else(|| {
+                eprintln!("pmacs-gpu: --headless-probe requires a report path");
+                std::process::exit(2);
+            });
+            Mode::HeadlessProbe {
+                socket: PathBuf::from(socket),
+                report: PathBuf::from(report),
+            }
+        }
         "--help" | "-h" => {
             eprintln!(
                 "pmacs-gpu — GPU/GUI frontend for pmacs\n\nUSAGE:\n  pmacs-gpu                       \
@@ -955,6 +1205,36 @@ struct State {
     /// `face_fg_or` / `face_wash_or` / `modeline_face_colors` /
     /// `diag_face_rgba` resolvers (Q#TH5 mask + `Default` mapping).
     faces: HashMap<String, CellStyle>,
+    /// Vterm Stage 3 — the installed terminal frame and its derived
+    /// paint plan, or `None` in document mode. The two-state machine is
+    /// explicit: `BufferSnapshot` always leaves terminal mode, a valid
+    /// matching `TerminalFrame` always enters it.
+    terminal: Option<TerminalLocal>,
+    /// The terminal geometry last declared to the daemon, with the
+    /// buffer it described. Suppresses an unchanged re-declaration and
+    /// forces a fresh one after a buffer switch.
+    last_terminal_size_sent: Option<(BufferId, CellSize)>,
+    /// Whether an invalid terminal frame has already been reported.
+    /// Bounds the log while a bad producer keeps sending.
+    terminal_frame_error_latched: bool,
+    /// One shaped buffer per planned text run. Rebuilt only when the
+    /// plan changes, never per frame.
+    terminal_text_buffers: Vec<Buffer>,
+    /// Dedicated renderer for terminal glyphs, so they draw in their own
+    /// layer with terminal clipping rather than through the document
+    /// text pass.
+    terminal_text_renderer: TextRenderer,
+}
+
+/// Vterm Stage 3 — the GPU's terminal mode.
+struct TerminalLocal {
+    /// The terminal identity buffer this frame describes.
+    buffer_id: BufferId,
+    /// The last valid frame. Retained verbatim so an identical
+    /// re-send can be recognized and skipped without a rebuild.
+    frame: TerminalFrame,
+    /// Cell-space paint data derived from `frame`.
+    plan: TerminalPaintPlan,
 }
 
 /// Kind-glyph column for a completion row: the LSP
@@ -1176,6 +1456,71 @@ impl App {
         }
     }
 
+    /// Ship a terminal-cell gesture if the daemon speaks v19+.
+    ///
+    /// The terminal twin of [`Self::send_pointer`]: same frontend-side
+    /// version gate, cells instead of source bytes.
+    fn send_terminal_pointer(
+        &self,
+        buffer_id: BufferId,
+        coord: CellCoord,
+        kind: ProtocolMouseKind,
+        mods: Modifiers,
+    ) {
+        let Some(client) = self.attach_client.as_ref() else {
+            return;
+        };
+        if client.server_protocol_version() < 19 {
+            return;
+        }
+        if let Err(e) = client.send_terminal_pointer(buffer_id, coord, kind, mods) {
+            eprintln!("pmacs-gpu: send_terminal_pointer failed: {e}");
+        }
+    }
+
+    /// Declare the current terminal cell geometry when it has changed.
+    ///
+    /// Called after every applied message and after any real geometry
+    /// change. An unchanged size sends nothing, so a redraw storm
+    /// produces no wire traffic; a changed one sends exactly once.
+    fn flush_terminal_declaration(&mut self) {
+        let Some(client) = self.attach_client.as_ref() else {
+            return;
+        };
+        if client.server_protocol_version() < 19 {
+            return;
+        }
+        let Some(state) = self.state.as_mut() else {
+            return;
+        };
+        let Some((buffer_id, size)) = state.terminal_declaration_if_changed() else {
+            return;
+        };
+        if let Err(e) = client.send_terminal_resize(buffer_id, size) {
+            eprintln!("pmacs-gpu: send_terminal_resize failed: {e}");
+        }
+    }
+
+    /// Resolve a pixel to a terminal cell, or `None` when this window is
+    /// not in terminal mode or the pixel is outside the grid.
+    ///
+    /// The status band and the padding past the last whole column are
+    /// deliberately not terminal hits: a gesture there belongs to the
+    /// chrome, not the child.
+    fn terminal_pointer_hit(&self, x: f64, y: f64) -> Option<(BufferId, CellCoord)> {
+        let state = self.state.as_ref()?;
+        let terminal = state.terminal.as_ref()?;
+        let coord = crate::terminal::hit_test_cell(
+            x as f32,
+            y as f32,
+            (TEXT_LEFT, TEXT_TOP),
+            state.mono_advance(),
+            state.fm.code_line_height(),
+            terminal.plan.size,
+        )?;
+        Some((terminal.buffer_id, coord))
+    }
+
     /// Ship a [`pmacs_protocol::FrontendEvent::MenuPointer`] if the
     /// daemon speaks v11+ (Q#CM1). Navigates the open menu the daemon
     /// owns; pixels stay local, only the resolved row index crosses.
@@ -1199,7 +1544,7 @@ impl ApplicationHandler<AppEvent> for App {
         }
         let initial_text = match &self.mode {
             Mode::HelloWorld => HELLO_TEXT,
-            Mode::Attach { .. } => "(connecting...)",
+            Mode::Attach { .. } | Mode::HeadlessProbe { .. } => "(connecting...)",
         };
         self.state = Some(State::new(event_loop, initial_text));
 
@@ -1439,6 +1784,11 @@ impl ApplicationHandler<AppEvent> for App {
                 {
                     eprintln!("pmacs-gpu: resize send_viewport failed: {e}");
                 }
+                // Vterm Stage 3 — a resize is a real geometry change, so
+                // the cell grid is re-derived and declared here. The
+                // daemon resizes the shared PTY only if this frontend is
+                // the durable controller.
+                self.flush_terminal_declaration();
             }
             // Session M-2 — pointer input (docs/pmacs-gpu-mouse-framing.md).
             WindowEvent::CursorMoved { position, .. } => {
@@ -1459,6 +1809,25 @@ impl ApplicationHandler<AppEvent> for App {
                     }
                     return;
                 }
+                // Vterm Stage 3 — inside the terminal clip, motion is a
+                // terminal gesture. Consumed before minimap scrubbing
+                // and document hit testing: terminal mode paints no
+                // minimap and has no source bytes to resolve.
+                if state.terminal.is_some() {
+                    let dragging = state.pointer_drag_active;
+                    if let Some((buffer_id, coord)) =
+                        self.terminal_pointer_hit(position.x, position.y)
+                    {
+                        let mods = translate_mods(self.modifiers);
+                        let kind = if dragging {
+                            ProtocolMouseKind::Drag(ProtocolMouseButton::Left)
+                        } else {
+                            ProtocolMouseKind::Move
+                        };
+                        self.send_terminal_pointer(buffer_id, coord, kind, mods);
+                    }
+                    return;
+                }
                 if state.minimap_scrub_active {
                     // Scrubbing (Q#M6): the press began on the
                     // minimap; motion keeps jumping, even if the
@@ -1524,6 +1893,22 @@ impl ApplicationHandler<AppEvent> for App {
                     return;
                 }
                 let mods = translate_mods(self.modifiers);
+                if state.terminal.is_some() {
+                    let kind = match button_state {
+                        ElementState::Pressed => {
+                            state.pointer_drag_active = true;
+                            ProtocolMouseKind::Down(ProtocolMouseButton::Left)
+                        }
+                        ElementState::Released => {
+                            state.pointer_drag_active = false;
+                            ProtocolMouseKind::Up(ProtocolMouseButton::Left)
+                        }
+                    };
+                    if let Some((buffer_id, coord)) = self.terminal_pointer_hit(x, y) {
+                        self.send_terminal_pointer(buffer_id, coord, kind, mods);
+                    }
+                    return;
+                }
                 match button_state {
                     ElementState::Pressed => {
                         if state.in_minimap_band(x, y) {
@@ -1594,6 +1979,23 @@ impl ApplicationHandler<AppEvent> for App {
                     self.send_menu_pointer(None, true);
                     return;
                 }
+                // Vterm Stage 3 — a right-click in the terminal clip is
+                // a terminal gesture; the daemon decides between child
+                // reporting and the editor context menu, so the anchor
+                // is remembered here exactly as for a document click.
+                if state.terminal.is_some() {
+                    state.menu_anchor_px = (x, y);
+                    if let Some((buffer_id, coord)) = self.terminal_pointer_hit(x, y) {
+                        let mods = translate_mods(self.modifiers);
+                        self.send_terminal_pointer(
+                            buffer_id,
+                            coord,
+                            ProtocolMouseKind::Down(ProtocolMouseButton::Right),
+                            mods,
+                        );
+                    }
+                    return;
+                }
                 let Some(byte) = state.hit_test_source_byte(x, y) else {
                     return;
                 };
@@ -1622,6 +2024,24 @@ impl ApplicationHandler<AppEvent> for App {
                 if lines == 0 {
                     return;
                 }
+                // Vterm Stage 3 — the terminal's scrollback belongs to
+                // the daemon-side view, not to this frontend's local
+                // scroll, so a wheel tick crosses the wire as a
+                // terminal gesture instead of moving `scroll_top`.
+                if state.terminal.is_some() {
+                    if let Some((x, y)) = state.pointer_pos
+                        && let Some((buffer_id, coord)) = self.terminal_pointer_hit(x, y)
+                    {
+                        let mods = translate_mods(self.modifiers);
+                        let kind = if lines < 0 {
+                            ProtocolMouseKind::ScrollUp
+                        } else {
+                            ProtocolMouseKind::ScrollDown
+                        };
+                        self.send_terminal_pointer(buffer_id, coord, kind, mods);
+                    }
+                    return;
+                }
                 let vp = state.scroll_by_lines(lines);
                 if let Some(vp) = vp
                     && let Some(client) = self.attach_client.as_ref()
@@ -1747,6 +2167,18 @@ impl ApplicationHandler<AppEvent> for App {
                 {
                     eprintln!("pmacs-gpu: send Viewport failed: {e}");
                 }
+                // Vterm Stage 3 — the dual declaration. After every
+                // snapshot the frontend re-declares BOTH its byte
+                // viewport (above) and its terminal cell size, because
+                // an empty terminal identity snapshot does not announce
+                // itself as a terminal. The daemon keeps whichever one
+                // matches the buffer's kind, which is what breaks the
+                // otherwise circular "need a frame to know to ask for
+                // one" dependency.
+                self.flush_terminal_declaration();
+                let Some(state) = self.state.as_mut() else {
+                    return;
+                };
                 state.release_timed_out_floor();
                 let ready_keys = state.take_ready_round_trip_keys();
                 if let Some(client) = self.attach_client.as_ref() {
@@ -2106,10 +2538,10 @@ impl State {
     }
 
     /// Build a windowless `State` that renders to an offscreen texture, for
-    /// the headless render tests (F-014). Returns `None` when no GPU
-    /// adapter is available (a dev box with no working Vulkan, or CI
-    /// without lavapipe), so the caller skips rather than fails.
-    #[cfg(test)]
+    /// the headless render tests (F-014) and the Vterm Stage 3 headless
+    /// attach probe. Returns `None` when no GPU adapter is available (a
+    /// dev box with no working Vulkan, or CI without lavapipe), so the
+    /// caller skips rather than fails.
     fn new_headless(width: u32, height: u32, initial_text: &str) -> Option<Self> {
         let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle());
         let adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {
@@ -2143,7 +2575,9 @@ impl State {
             queue,
             config,
             initial_text,
-            TEST_FONT_SOURCES,
+            // Font fixtures exist only in test builds; the release-mode
+            // attach probe runs on the bundled face alone.
+            headless_extra_font_sources(),
         ))
     }
 
@@ -2198,6 +2632,11 @@ impl State {
         // UX gutter — a renderer for the line-number layer.
         let gutter_text_renderer =
             TextRenderer::new(&mut atlas, &device, MultisampleState::default(), None);
+        // Vterm Stage 3 — terminal glyphs draw in their own layer with
+        // their own clip; interleaving them with document text would
+        // subject them to the document's gutter offset and wrapping.
+        let terminal_text_renderer =
+            TextRenderer::new(&mut atlas, &device, MultisampleState::default(), None);
         let quad_renderer = QuadRenderer::new(&device, format);
         let squiggle_renderer = SquiggleRenderer::new(&device, format);
 
@@ -2371,6 +2810,11 @@ impl State {
             faces: HashMap::new(),
             gutter_buffer,
             gutter_text_renderer,
+            terminal: None,
+            last_terminal_size_sent: None,
+            terminal_frame_error_latched: false,
+            terminal_text_buffers: Vec::new(),
+            terminal_text_renderer,
         };
         // Real drawable dimensions from construction (framing Q#F6):
         // wrapping and `shape_until_cursor` must use the same clip the
@@ -2862,6 +3306,13 @@ impl State {
                 self.scroll_top = 0;
                 self.code_scroll_residual = 0.0;
                 self.last_viewport_sent = None;
+                // Vterm Stage 3 — a snapshot ALWAYS leaves terminal
+                // mode, including a terminal→terminal switch. The prior
+                // frame describes another session's screen, and the
+                // daemon has already dropped its own baseline, so the
+                // next valid frame is authoritative for whatever this
+                // buffer turns out to be.
+                self.exit_terminal_mode();
                 if !self.set_text(&text) {
                     // Even byte-identical A -> B snapshots can clear a
                     // prior minimap, so the new buffer's shaping clip
@@ -3354,13 +3805,364 @@ impl State {
                 size_centi_px,
             } => {
                 self.apply_font_facts(family.as_deref(), size_centi_px);
+                // Q#F6 + Vterm Stage 3: new metrics mean a new cell
+                // grid. The terminal shape/geometry caches are dropped
+                // here and stay dropped until an authoritative frame at
+                // the matching size arrives, so nothing paints at the
+                // old advance under the new font.
+                self.invalidate_terminal_shaping();
                 self.current_buffer_id
                     .and_then(|bid| self.viewport_send_if_changed(bid))
             }
+            InstanceMessage::TerminalFrame(frame) => {
+                self.apply_terminal_frame(frame);
+                None
+            }
             _ => None,
         }
     }
 
+    /// Install a decoded terminal frame, or reject it whole.
+    ///
+    /// Rejection is total by design: a partially applied frame would mix
+    /// cells from two screens. An invalid frame therefore keeps the
+    /// previous valid one, requests no redraw, and reports one latched
+    /// diagnostic instead of painting something the daemon never
+    /// authorized.
+    fn apply_terminal_frame(&mut self, frame: TerminalFrame) {
+        if self.current_buffer_id != Some(frame.buffer_id) {
+            // A frame for a buffer this window is no longer showing.
+            // The daemon clears its baseline on every snapshot, so the
+            // authoritative frame for the buffer we DO show is already
+            // on its way.
+            return;
+        }
+        if let Err(error) = frame.validate() {
+            if !self.terminal_frame_error_latched {
+                self.terminal_frame_error_latched = true;
+                eprintln!("pmacs-gpu: rejecting invalid TerminalFrame: {error}");
+            }
+            return;
+        }
+        self.terminal_frame_error_latched = false;
+        if self
+            .terminal
+            .as_ref()
+            .is_some_and(|terminal| terminal.frame == frame)
+        {
+            // A duplicate valid frame does no work at all: no plan
+            // rebuild, no reshape, no redraw.
+            return;
+        }
+        let plan = TerminalPaintPlan::build(&frame, Self::terminal_palette());
+        let buffer_id = frame.buffer_id;
+        self.terminal = Some(TerminalLocal {
+            buffer_id,
+            frame,
+            plan,
+        });
+        self.rebuild_terminal_text_buffers();
+        self.request_redraw();
+    }
+
+    /// The frontend defaults `Color::Default` resolves against.
+    fn terminal_palette() -> TerminalPalette {
+        let fg = plain_text_color();
+        TerminalPalette {
+            default_fg: [fg.r(), fg.g(), fg.b()],
+            default_bg: [
+                (WINDOW_BG_RGBA[0] * 255.0) as u8,
+                (WINDOW_BG_RGBA[1] * 255.0) as u8,
+                (WINDOW_BG_RGBA[2] * 255.0) as u8,
+            ],
+        }
+    }
+
+    /// Leave terminal mode and drop every terminal-only cache.
+    fn exit_terminal_mode(&mut self) {
+        self.terminal = None;
+        self.terminal_text_buffers.clear();
+        self.terminal_frame_error_latched = false;
+        self.last_terminal_size_sent = None;
+    }
+
+    /// Drop shaping and geometry caches without leaving terminal mode.
+    ///
+    /// Used when the font changes: the installed frame is still the
+    /// child's authoritative screen, but every cached shape was measured
+    /// at the old advance.
+    fn invalidate_terminal_shaping(&mut self) {
+        if self.terminal.is_some() {
+            self.rebuild_terminal_text_buffers();
+        }
+        self.last_terminal_size_sent = None;
+    }
+
+    /// Reshape one cosmic-text buffer per planned run.
+    ///
+    /// One buffer per RUN, not per row: a row-wide buffer would let a
+    /// wide or cluster glyph's shaped advance decide where the following
+    /// column starts, and terminal columns belong to the child.
+    fn rebuild_terminal_text_buffers(&mut self) {
+        let Some(terminal) = self.terminal.as_ref() else {
+            self.terminal_text_buffers.clear();
+            return;
+        };
+        let metrics = Metrics::new(self.fm.code_font_size(), self.fm.code_line_height());
+        let advance = self.mono_advance();
+        let family = self.resolved_family.clone();
+        let runs: Vec<_> = terminal
+            .plan
+            .runs
+            .iter()
+            .map(|run| {
+                (
+                    run.text.clone(),
+                    run.cells as f32 * advance,
+                    run.bold,
+                    run.italic,
+                )
+            })
+            .collect();
+        let mut buffers = Vec::with_capacity(runs.len());
+        for (text, width, bold, italic) in runs {
+            let mut buffer = Buffer::new(&mut self.font_system, metrics);
+            // No wrapping: a run occupies exactly the cells the child
+            // gave it, and overflow is a clip, never a second row.
+            buffer.set_wrap(&mut self.font_system, Wrap::None);
+            buffer.set_size(
+                &mut self.font_system,
+                Some(width.max(1.0)),
+                Some(metrics.line_height),
+            );
+            let attrs = Attrs::new()
+                .family(Family::Name(&family))
+                .weight(if bold {
+                    glyphon::cosmic_text::Weight::BOLD
+                } else {
+                    glyphon::cosmic_text::Weight::NORMAL
+                })
+                .style(if italic {
+                    glyphon::cosmic_text::Style::Italic
+                } else {
+                    glyphon::cosmic_text::Style::Normal
+                });
+            buffer.set_text(
+                &mut self.font_system,
+                &text,
+                &attrs,
+                Shaping::Advanced,
+                None,
+            );
+            buffer.shape_until_scroll(&mut self.font_system, false);
+            buffers.push(buffer);
+        }
+        self.terminal_text_buffers = buffers;
+    }
+
+    /// The terminal content rectangle's pixel origin.
+    ///
+    /// Deliberately not `text_left()`: terminal mode draws no document
+    /// gutter, so the grid starts at the plain text inset.
+    fn terminal_origin() -> (f32, f32) {
+        (TEXT_LEFT, TEXT_TOP)
+    }
+
+    /// The cell grid this window's drawable rectangle admits, or `None`
+    /// when it cannot fit one whole cell.
+    fn terminal_cell_viewport(&self) -> Option<CellSize> {
+        let (origin_x, origin_y) = Self::terminal_origin();
+        let width = self.config.width as f32 - origin_x;
+        let height = text_area_bottom(self.config.height, self.fm) - origin_y;
+        crate::terminal::cell_viewport(
+            width,
+            height,
+            self.mono_advance(),
+            self.fm.code_line_height(),
+        )
+    }
+
+    /// Pixel rectangle of a cell run in the terminal grid.
+    fn terminal_run_rect(&self, run: crate::terminal::CellRun) -> (f32, f32, f32, f32) {
+        let (ox, oy) = Self::terminal_origin();
+        let advance = self.mono_advance();
+        let line = self.fm.code_line_height();
+        (
+            ox + run.start_col as f32 * advance,
+            oy + run.row as f32 * line,
+            (run.end_col - run.start_col) as f32 * advance,
+            line,
+        )
+    }
+
+    /// Backgrounds, straight underlines, the selection wash, and the
+    /// terminal clip, as one quad batch drawn under the glyphs.
+    ///
+    /// Runs whose resolved background equals the window clear color are
+    /// dropped: the clear already painted them, and emitting a
+    /// full-screen quad per frame for the common case is pure waste.
+    fn terminal_quad_vertex_bytes(&self) -> Vec<u8> {
+        let Some(terminal) = self.terminal.as_ref() else {
+            return Vec::new();
+        };
+        let window_bg = Self::terminal_palette().default_bg;
+        let mut rects = Vec::new();
+        for bg in &terminal.plan.backgrounds {
+            if bg.color == window_bg {
+                continue;
+            }
+            let (x, y, w, h) = self.terminal_run_rect(bg.run);
+            rects.push(MinimapRect {
+                x,
+                y,
+                w,
+                h,
+                color: rgb_to_quad(bg.color, 1.0),
+            });
+        }
+        // Straight underline forms as fixed-cell quads; curly rides the
+        // squiggle pipeline, which owns the sine wave.
+        for underline in &terminal.plan.underlines {
+            if underline.style == UnderlineStyle::Curly {
+                continue;
+            }
+            let (x, y, w, h) = self.terminal_run_rect(underline.run);
+            let color = rgb_to_quad(underline.color, 1.0);
+            let thickness = TERMINAL_UNDERLINE_PX;
+            let baseline = y + h - thickness * 2.0;
+            match underline.style {
+                UnderlineStyle::Double => {
+                    rects.push(MinimapRect {
+                        x,
+                        y: baseline,
+                        w,
+                        h: thickness,
+                        color,
+                    });
+                    rects.push(MinimapRect {
+                        x,
+                        y: baseline + thickness * 2.0,
+                        w,
+                        h: thickness,
+                        color,
+                    });
+                }
+                UnderlineStyle::Dotted | UnderlineStyle::Dashed => {
+                    // Dotted and dashed differ only in duty cycle; both
+                    // are stepped along the run so a one-cell run still
+                    // shows at least one mark.
+                    let period = if underline.style == UnderlineStyle::Dotted {
+                        TERMINAL_UNDERLINE_PX * 3.0
+                    } else {
+                        TERMINAL_UNDERLINE_PX * 8.0
+                    };
+                    let duty = if underline.style == UnderlineStyle::Dotted {
+                        0.5
+                    } else {
+                        0.625
+                    };
+                    let mut at = x;
+                    while at < x + w {
+                        let seg = (period * duty).min(x + w - at);
+                        rects.push(MinimapRect {
+                            x: at,
+                            y: baseline,
+                            w: seg,
+                            h: thickness,
+                            color,
+                        });
+                        at += period;
+                    }
+                }
+                _ => rects.push(MinimapRect {
+                    x,
+                    y: baseline,
+                    w,
+                    h: thickness,
+                    color,
+                }),
+            }
+        }
+        // Terminal selection is the editor's, not the child's: it draws
+        // as a separate wash through the existing `ui.selection` site
+        // and never rewrites a cell's own style.
+        let selection_color = self.face_wash_or("ui.selection", TERMINAL_SELECTION_RGBA);
+        for run in &terminal.plan.selection {
+            let (x, y, w, h) = self.terminal_run_rect(*run);
+            rects.push(MinimapRect {
+                x,
+                y,
+                w,
+                h,
+                color: selection_color,
+            });
+        }
+        rects_to_vertex_bytes(&rects, self.config.width, self.config.height)
+    }
+
+    /// Curly terminal underlines through the existing squiggle pipeline.
+    fn terminal_squiggle_vertex_bytes(&self) -> Vec<u8> {
+        let Some(terminal) = self.terminal.as_ref() else {
+            return Vec::new();
+        };
+        let rects: Vec<MinimapRect> = terminal
+            .plan
+            .underlines
+            .iter()
+            .filter(|underline| underline.style == UnderlineStyle::Curly)
+            .map(|underline| {
+                let (x, y, w, h) = self.terminal_run_rect(underline.run);
+                MinimapRect {
+                    x,
+                    y: y + h - DIAG_SQUIGGLE_PX,
+                    w,
+                    h: DIAG_SQUIGGLE_PX,
+                    color: rgb_to_quad(underline.color, 1.0),
+                }
+            })
+            .collect();
+        squiggles_to_vertex_bytes(&rects, self.config.width, self.config.height)
+    }
+
+    /// The child cursor's quad, painted through the caret primitive so
+    /// it lands over the glyph it sits on.
+    fn terminal_cursor_vertex_bytes(&self) -> Vec<u8> {
+        let Some(terminal) = self.terminal.as_ref() else {
+            return Vec::new();
+        };
+        let Some(cursor) = terminal.plan.cursor else {
+            return Vec::new();
+        };
+        let (x, y, w, h) = self.terminal_run_rect(cursor);
+        rects_to_vertex_bytes(
+            &[MinimapRect {
+                x,
+                y,
+                w,
+                h,
+                color: TERMINAL_CURSOR_RGBA,
+            }],
+            self.config.width,
+            self.config.height,
+        )
+    }
+
+    /// A geometry declaration for the current buffer if it
+    /// changed, else `None`.
+    ///
+    /// Called after a snapshot and after any real geometry change
+    /// (window resize, scale, font). An equal size is silent, so a
+    /// redraw storm produces no wire traffic.
+    fn terminal_declaration_if_changed(&mut self) -> Option<(BufferId, CellSize)> {
+        let buffer_id = self.current_buffer_id?;
+        let size = self.terminal_cell_viewport()?;
+        if self.last_terminal_size_sent == Some((buffer_id, size)) {
+            return None;
+        }
+        self.last_terminal_size_sent = Some((buffer_id, size));
+        Some((buffer_id, size))
+    }
+
     /// True while the completion popup is open **for the buffer this
     /// window currently shows** — the predicate the key gates (Esc,
     /// RET/TAB) and the render path share, so a stale mirror can
@@ -5240,9 +6042,10 @@ impl State {
     }
 
     /// Render one frame to an offscreen texture and read it back as packed
-    /// RGBA8 (`width * height * 4` bytes, row padding removed). Test-only,
-    /// the entry point for the headless render harness (F-014).
-    #[cfg(test)]
+    /// RGBA8 (`width * height * 4` bytes, row padding removed). The entry
+    /// point for the headless render harness (F-014) and for the Vterm
+    /// Stage 3 attach probe, which needs real composited pixels rather
+    /// than a claim that it rendered.
     fn render_offscreen(&mut self) -> Vec<u8> {
         let width = self.config.width;
         let height = self.config.height;
@@ -5379,9 +6182,19 @@ impl State {
                 &completion_vertices,
             )
             .cloned();
+        // Vterm Stage 3 — terminal mode replaces every document paint
+        // batch. Document decoration washes, squiggles, caret, minimap,
+        // and gutter describe a rope this window is not showing; the
+        // status band and the popup layers above it stay, because they
+        // are buffer-independent chrome the daemon still drives.
+        let terminal_mode = self.terminal.is_some();
         // The band's strip rides the bg quad batch so it draws under
         // the band text (text renders after the first quad draw).
-        let mut bg_vertices = self.decoration_background_vertex_bytes();
+        let mut bg_vertices = if terminal_mode {
+            self.terminal_quad_vertex_bytes()
+        } else {
+            self.decoration_background_vertex_bytes()
+        };
         bg_vertices.extend(self.status_band_vertex_bytes());
         let bg_vertex_count = (bg_vertices.len() / QUAD_VERTEX_STRIDE as usize) as u32;
         let bg_buffer = self
@@ -5396,7 +6209,11 @@ impl State {
         // Diagnostic squiggles (Q#W1): own pipeline + buffer, drawn
         // between the wash quads and the text (under the glyphs, the
         // z-slot the straight bar held).
-        let squiggle_vertices = self.squiggle_vertex_bytes();
+        let squiggle_vertices = if terminal_mode {
+            self.terminal_squiggle_vertex_bytes()
+        } else {
+            self.squiggle_vertex_bytes()
+        };
         let squiggle_vertex_count =
             (squiggle_vertices.len() / SQUIGGLE_VERTEX_STRIDE as usize) as u32;
         let squiggle_buffer = self
@@ -5408,7 +6225,11 @@ impl State {
                 &squiggle_vertices,
             )
             .cloned();
-        let caret_vertices = self.caret_vertex_bytes();
+        let caret_vertices = if terminal_mode {
+            self.terminal_cursor_vertex_bytes()
+        } else {
+            self.caret_vertex_bytes()
+        };
         let caret_vertex_count = (caret_vertices.len() / QUAD_VERTEX_STRIDE as usize) as u32;
         let caret_buffer = self
             .caret_vertex_buffer
@@ -5436,7 +6257,12 @@ impl State {
         {
             self.minimap_cache = Some((minimap_key, self.minimap_vertex_bytes()));
         }
-        let minimap_vertices = &self.minimap_cache.as_ref().expect("just filled").1;
+        let empty_minimap: Vec<u8> = Vec::new();
+        let minimap_vertices = if terminal_mode {
+            &empty_minimap
+        } else {
+            &self.minimap_cache.as_ref().expect("just filled").1
+        };
         let minimap_vertex_count = (minimap_vertices.len() / QUAD_VERTEX_STRIDE as usize) as u32;
         let minimap_buffer = self
             .minimap_vertex_buffer
@@ -5465,6 +6291,9 @@ impl State {
         // main-text clip-left. Computed here as locals — calling `self.*`
         // inside the `prepare` args would conflict with its `&mut` borrows.
         let text_left = self.text_left();
+        // Hoisted for the same borrow reason as the colors below: the
+        // terminal areas are built inside a `&mut self.*` argument list.
+        let mono_advance = self.mono_advance();
         let gutter_clip_left = if self.line_numbers.is_on() {
             text_left.floor() as i32
         } else {
@@ -5478,6 +6307,30 @@ impl State {
             .map_or(Color::rgb(168, 168, 180), |(_, text)| text);
         let left_color = self.status_left_color();
         let gutter_color = self.face_fg_or("ui.gutter", Color::rgb(120, 120, 135));
+        // Vterm Stage 3 — the document code layer is dropped entirely
+        // in terminal mode; terminal glyphs draw from their own
+        // per-run layer below, positioned at cell origins.
+        let code_areas: Vec<TextArea> = if terminal_mode {
+            Vec::new()
+        } else {
+            vec![TextArea {
+                buffer: &self.buffer,
+                left: text_left,
+                top: TEXT_TOP,
+                scale: 1.0,
+                bounds: TextBounds {
+                    left: gutter_clip_left,
+                    top: 0,
+                    right: text_bounds_right,
+                    // Clip at the status band (Q#S3): a final
+                    // partially-visible line must not bleed
+                    // into the band.
+                    bottom: text_area_bottom(self.config.height, self.fm).round() as i32,
+                },
+                default_color: Color::rgb(230, 230, 235),
+                custom_glyphs: &[],
+            }]
+        };
         self.text_renderer
             .prepare(
                 &self.device,
@@ -5485,24 +6338,7 @@ impl State {
                 &mut self.font_system,
                 &mut self.atlas,
                 &self.viewport,
-                [
-                    TextArea {
-                        buffer: &self.buffer,
-                        left: text_left,
-                        top: TEXT_TOP,
-                        scale: 1.0,
-                        bounds: TextBounds {
-                            left: gutter_clip_left,
-                            top: 0,
-                            right: text_bounds_right,
-                            // Clip at the status band (Q#S3): a final
-                            // partially-visible line must not bleed
-                            // into the band.
-                            bottom: text_area_bottom(self.config.height, self.fm).round() as i32,
-                        },
-                        default_color: Color::rgb(230, 230, 235),
-                        custom_glyphs: &[],
-                    },
+                code_areas.into_iter().chain([
                     TextArea {
                         buffer: &self.status_buffer,
                         left: status_left,
@@ -5539,7 +6375,7 @@ impl State {
                         default_color: left_color,
                         custom_glyphs: &[],
                     },
-                ],
+                ]),
                 &mut self.swash_cache,
             )
             .expect("text_renderer prepare");
@@ -5547,7 +6383,7 @@ impl State {
         // UX gutter: prepare the line-number layer in the reserved left
         // strip (empty when off → renders nothing). Same `top` + line
         // height as the code, so numbers align row-for-row.
-        let gutter_areas: Vec<TextArea> = if self.line_numbers.is_on() {
+        let gutter_areas: Vec<TextArea> = if self.line_numbers.is_on() && !terminal_mode {
             vec![TextArea {
                 buffer: &self.gutter_buffer,
                 left: TEXT_LEFT,
@@ -5694,6 +6530,58 @@ impl State {
             )
             .expect("completion text_renderer prepare");
 
+        // Vterm Stage 3 — one TextArea per planned run, each pinned to
+        // its own cell origin and clipped to its declared footprint.
+        // Per-run areas are the point: a row-wide area would let one
+        // wide glyph's shaped advance shift every column after it.
+        let terminal_areas: Vec<TextArea> = self
+            .terminal
+            .as_ref()
+            .map(|terminal| {
+                let (ox, oy) = (TEXT_LEFT, TEXT_TOP);
+                let advance = mono_advance;
+                let line = self.fm.code_line_height();
+                let clip_bottom = text_area_bottom(self.config.height, self.fm).round() as i32;
+                let clip_right = self.config.width.cast_signed();
+                terminal
+                    .plan
+                    .runs
+                    .iter()
+                    .zip(self.terminal_text_buffers.iter())
+                    .map(|(run, buffer)| {
+                        let left = ox + run.col as f32 * advance;
+                        let top = oy + run.row as f32 * line;
+                        let right = (left + run.cells as f32 * advance).round() as i32;
+                        TextArea {
+                            buffer,
+                            left,
+                            top,
+                            scale: 1.0,
+                            bounds: TextBounds {
+                                left: left.floor() as i32,
+                                top: top.floor().max(0.0) as i32,
+                                right: right.min(clip_right),
+                                bottom: (top + line).round().min(clip_bottom as f32) as i32,
+                            },
+                            default_color: Color::rgb(230, 230, 235),
+                            custom_glyphs: &[],
+                        }
+                    })
+                    .collect()
+            })
+            .unwrap_or_default();
+        self.terminal_text_renderer
+            .prepare(
+                &self.device,
+                &self.queue,
+                &mut self.font_system,
+                &mut self.atlas,
+                &self.viewport,
+                terminal_areas,
+                &mut self.swash_cache,
+            )
+            .expect("terminal text_renderer prepare");
+
         let mut encoder = self
             .device
             .create_command_encoder(&wgpu::CommandEncoderDescriptor {
@@ -5733,6 +6621,12 @@ impl State {
             self.text_renderer
                 .render(&self.atlas, &self.viewport, &mut pass)
                 .expect("text_renderer render");
+            // Vterm Stage 3 — terminal glyphs sit in the code layer's
+            // z-slot: over the cell backgrounds and underlines, under
+            // the cursor block.
+            self.terminal_text_renderer
+                .render(&self.atlas, &self.viewport, &mut pass)
+                .expect("terminal text_renderer render");
             // UX gutter: line numbers in the reserved left strip (empty
             // layer when off).
             self.gutter_text_renderer
@@ -6815,6 +7709,7 @@ fn instance_message_label(msg: &InstanceMessage) -> &'static str {
         InstanceMessage::ThemeFacts { .. } => "ThemeFacts",
         InstanceMessage::FontFacts { .. } => "FontFacts",
         InstanceMessage::StatuslineSegments { .. } => "StatuslineSegments",
+        InstanceMessage::TerminalFrame(_) => "TerminalFrame",
     }
 }
 
@@ -7772,6 +8667,16 @@ fn plain_text_color() -> glyphon::Color {
 /// [`BG`].
 const WINDOW_BG_RGBA: [f32; 4] = [0.05, 0.05, 0.07, 1.0];
 
+/// Resolved terminal RGB → quad color, carrying `alpha`.
+fn rgb_to_quad(rgb: crate::terminal::Rgb, alpha: f32) -> [f32; 4] {
+    [
+        f32::from(rgb[0]) / 255.0,
+        f32::from(rgb[1]) / 255.0,
+        f32::from(rgb[2]) / 255.0,
+        alpha,
+    ]
+}
+
 /// glyphon (u8) → quad (f32) color, carrying `alpha`. Divides by 255
 /// — the same space every existing float constant uses (e.g. the
 /// error squiggle `[0.945, …]` is exactly `rgb(241, 76, 76) / 255`).
@@ -12060,4 +12965,442 @@ mod tests {
             "an unrelated proportional family is untouched"
         );
     }
+
+    // --- Vterm Stage 3: terminal mode -----------------------------------
+
+    fn terminal_cell(glyph: pmacs_protocol::Glyph, style: CellStyle) -> pmacs_protocol::Cell {
+        pmacs_protocol::Cell {
+            glyph,
+            style,
+            attachment: None,
+        }
+    }
+
+    fn terminal_frame_of(
+        buffer_id: BufferId,
+        rows: u32,
+        cols: u32,
+        cells: Vec<pmacs_protocol::Cell>,
+    ) -> TerminalFrame {
+        TerminalFrame {
+            buffer_id,
+            size: CellSize::new(rows, cols),
+            cells,
+            cursor: None,
+            title: Some("sh".into()),
+            screen_generation: 1,
+            selection: Vec::new(),
+            scroll_offset: 0,
+            at_bottom: true,
+            pid: 4242,
+            process: pmacs_protocol::TerminalProcessState::Running,
+        }
+    }
+
+    fn plain_terminal_frame(buffer_id: BufferId, text: &str, cols: u32) -> TerminalFrame {
+        let mut cells: Vec<pmacs_protocol::Cell> = text
+            .chars()
+            .map(|ch| terminal_cell(pmacs_protocol::Glyph::Char(ch), CellStyle::default()))
+            .collect();
+        while cells.len() < cols as usize {
+            cells.push(terminal_cell(
+                pmacs_protocol::Glyph::Char(' '),
+                CellStyle::default(),
+            ));
+        }
+        cells.truncate(cols as usize);
+        terminal_frame_of(buffer_id, 1, cols, cells)
+    }
+
+    /// Acceptance 35: a snapshot leaves terminal mode; a valid matching
+    /// frame enters it; a stale-buffer frame is ignored; a duplicate
+    /// valid frame rebuilds nothing.
+    #[test]
+    fn a35_terminal_mode_transitions_are_explicit_and_duplicates_do_no_work() {
+        let Some(mut state) = headless_or_skip(400, 300, "document text") else {
+            return;
+        };
+        let terminal_buffer = BufferId::next();
+        let other_buffer = BufferId::next();
+        state.current_buffer_id = Some(terminal_buffer);
+
+        // A frame for a buffer this window is not showing changes nothing.
+        state.apply_terminal_frame(plain_terminal_frame(other_buffer, "nope", 8));
+        assert!(
+            state.terminal.is_none(),
+            "a stale-buffer frame must not enter terminal mode"
+        );
+
+        let frame = plain_terminal_frame(terminal_buffer, "hello", 8);
+        state.apply_terminal_frame(frame.clone());
+        let terminal = state.terminal.as_ref().expect("terminal mode entered");
+        assert_eq!(terminal.buffer_id, terminal_buffer);
+        assert_eq!(terminal.plan.size, CellSize::new(1, 8));
+        let buffers_after_first = state.terminal_text_buffers.len();
+        assert!(buffers_after_first > 0, "runs were shaped");
+
+        // A byte-identical frame is retained without a rebuild.
+        state.terminal_text_buffers.clear();
+        state.apply_terminal_frame(frame);
+        assert!(
+            state.terminal_text_buffers.is_empty(),
+            "a duplicate valid frame must not rebuild shaping"
+        );
+
+        // A changed frame does rebuild.
+        state.apply_terminal_frame(plain_terminal_frame(terminal_buffer, "world", 8));
+        assert!(!state.terminal_text_buffers.is_empty());
+
+        // Leaving terminal mode drops every terminal-only cache.
+        state.exit_terminal_mode();
+        assert!(state.terminal.is_none());
+        assert!(state.terminal_text_buffers.is_empty());
+        assert!(state.last_terminal_size_sent.is_none());
+    }
+
+    /// Acceptance 29 (frontend half): an invalid frame is rejected whole
+    /// and the previous valid frame survives.
+    #[test]
+    fn a29_invalid_terminal_frame_retains_the_previous_valid_one() {
+        let Some(mut state) = headless_or_skip(400, 300, "document text") else {
+            return;
+        };
+        let terminal_buffer = BufferId::next();
+        state.current_buffer_id = Some(terminal_buffer);
+        let good = plain_terminal_frame(terminal_buffer, "good", 8);
+        state.apply_terminal_frame(good.clone());
+
+        // Cell count disagreeing with the declared area.
+        let mut short = plain_terminal_frame(terminal_buffer, "bad", 8);
+        short.cells.pop();
+        state.apply_terminal_frame(short);
+        assert_eq!(
+            state.terminal.as_ref().expect("still terminal").frame,
+            good,
+            "an invalid frame must not partially apply"
+        );
+
+        // An orphan continuation.
+        let mut orphan = plain_terminal_frame(terminal_buffer, "bad", 8);
+        orphan.cells[0] = terminal_cell(pmacs_protocol::Glyph::Continuation, CellStyle::default());
+        state.apply_terminal_frame(orphan);
+        assert_eq!(state.terminal.as_ref().expect("still terminal").frame, good);
+
+        // An attachment in a terminal cell.
+        let mut attached = plain_terminal_frame(terminal_buffer, "bad", 8);
+        attached.cells[1].attachment = Some(pmacs_protocol::Attachment::ImageCell {
+            image_id: 1,
+            sub_x: 0,
+            sub_y: 0,
+        });
+        state.apply_terminal_frame(attached);
+        assert_eq!(state.terminal.as_ref().expect("still terminal").frame, good);
+
+        // A later valid frame still lands, so the latch is not a wedge.
+        let next = plain_terminal_frame(terminal_buffer, "next", 8);
+        state.apply_terminal_frame(next.clone());
+        assert_eq!(state.terminal.as_ref().expect("terminal").frame, next);
+    }
+
+    /// Acceptance 35: geometry declaration emits exactly one changed
+    /// size and suppresses identical ones.
+    #[test]
+    fn a35_cell_declaration_emits_once_per_change() {
+        let Some(mut state) = headless_or_skip(400, 300, "document text") else {
+            return;
+        };
+        let buffer_id = BufferId::next();
+        state.current_buffer_id = Some(buffer_id);
+
+        let first = state
+            .terminal_declaration_if_changed()
+            .expect("a 400x300 window admits a cell grid");
+        assert_eq!(first.0, buffer_id);
+        assert!(first.1.rows >= 1 && first.1.cols >= 1);
+        assert!(
+            state.terminal_declaration_if_changed().is_none(),
+            "an unchanged size must be silent"
+        );
+
+        // A real geometry change re-declares exactly once.
+        state.resize(600, 300);
+        let widened = state
+            .terminal_declaration_if_changed()
+            .expect("a wider window is a new size");
+        assert!(widened.1.cols > first.1.cols);
+        assert!(state.terminal_declaration_if_changed().is_none());
+
+        // A buffer switch forces a fresh declaration even at the same size.
+        state.exit_terminal_mode();
+        let after_switch = state
+            .terminal_declaration_if_changed()
+            .expect("a snapshot forces re-declaration");
+        assert_eq!(after_switch.1, widened.1);
+    }
+
+    /// Acceptance 34: pixel hit testing yields only in-bounds cells and
+    /// never leaves the terminal rectangle.
+    #[test]
+    fn a34_terminal_hit_testing_stays_inside_the_declared_grid() {
+        let Some(mut state) = headless_or_skip(400, 300, "document text") else {
+            return;
+        };
+        let buffer_id = BufferId::next();
+        state.current_buffer_id = Some(buffer_id);
+        state.apply_terminal_frame(plain_terminal_frame(buffer_id, "abcd", 4));
+        let advance = f64::from(state.mono_advance());
+        let line = f64::from(state.fm.code_line_height());
+        let size = state.terminal.as_ref().expect("terminal").plan.size;
+
+        let origin = (f64::from(TEXT_LEFT), f64::from(TEXT_TOP));
+        let hit = |x: f64, y: f64| {
+            crate::terminal::hit_test_cell(
+                x as f32,
+                y as f32,
+                (TEXT_LEFT, TEXT_TOP),
+                state.mono_advance(),
+                state.fm.code_line_height(),
+                size,
+            )
+        };
+        assert_eq!(hit(origin.0, origin.1), Some(CellCoord::new(0, 0)));
+        assert_eq!(
+            hit(origin.0 + advance * 2.5, origin.1 + line * 0.5),
+            Some(CellCoord::new(0, 2))
+        );
+        // Past the last declared column, and above the grid origin (the
+        // window chrome), are not terminal hits.
+        assert_eq!(
+            hit(origin.0 + advance * f64::from(size.cols), origin.1),
+            None
+        );
+        assert_eq!(hit(origin.0, origin.1 - 1.0), None);
+        // The status band is below the grid and never hits.
+        assert_eq!(
+            hit(
+                origin.0,
+                f64::from(text_area_bottom(state.config.height, state.fm)) + 2.0
+            ),
+            None
+        );
+    }
+
+    /// Acceptance 33: a real headless frame paints terminal cells and
+    /// drops every document layer.
+    #[test]
+    fn a33_headless_terminal_frame_paints_cells_without_document_layers() {
+        let text = "alpha\nbeta\ngamma\ndelta\n";
+        let Some(mut document) = headless_or_skip(400, 300, text) else {
+            return;
+        };
+        let buffer_id = BufferId::next();
+        document.current_buffer_id = Some(buffer_id);
+        document.view_range = (0, text.len() as u64);
+        document.line_numbers = LineNumberMode::Absolute;
+        let document_px = document.render_offscreen();
+
+        let mut terminal = State::new_headless(400, 300, text).expect("adapter was just available");
+        terminal.current_buffer_id = Some(buffer_id);
+        terminal.view_range = (0, text.len() as u64);
+        terminal.line_numbers = LineNumberMode::Absolute;
+        // A red-on-blue row: both colors are far from the defaults, so
+        // their presence is unambiguous evidence the cells painted.
+        let styled = CellStyle {
+            fg: CellColor::Rgb(255, 0, 0),
+            bg: CellColor::Rgb(0, 0, 255),
+            ..CellStyle::default()
+        };
+        let cells: Vec<pmacs_protocol::Cell> = "TERMINAL"
+            .chars()
+            .map(|ch| terminal_cell(pmacs_protocol::Glyph::Char(ch), styled))
+            .collect();
+        let mut frame = terminal_frame_of(buffer_id, 1, cells.len() as u32, cells);
+        frame.cursor = Some(CellCoord::new(0, 0));
+        assert_eq!(frame.validate(), Ok(()));
+        terminal.apply_terminal_frame(frame);
+        let terminal_px = terminal.render_offscreen();
+
+        assert_eq!(document_px.len(), terminal_px.len());
+        let differing = document_px
+            .iter()
+            .zip(&terminal_px)
+            .filter(|(a, b)| a != b)
+            .count();
+        assert!(
+            differing > 1000,
+            "terminal mode must repaint the code area ({differing} bytes differ)"
+        );
+
+        // The blue cell background must actually be on screen.
+        let blue = terminal_px
+            .chunks_exact(4)
+            .filter(|px| px[2] > 100 && px[0] < 90 && px[1] < 90)
+            .count();
+        assert!(
+            blue > 100,
+            "the terminal cell background did not paint ({blue} blue pixels)"
+        );
+
+        // Document overlays are suppressed. The minimap is the
+        // unambiguous probe: it occupies a band no terminal cell can
+        // reach, and it paints only when a file summary is present.
+        // The comparison is DIFFERENTIAL rather than a brightness
+        // threshold — the window background is itself a nonzero sRGB
+        // value, so "is there ink here" is not a question absolute
+        // pixel levels can answer.
+        let summary = FileStyleSummaryState {
+            generation: 1,
+            lines: vec![
+                CellStyle {
+                    fg: CellColor::Rgb(255, 255, 255),
+                    ..CellStyle::default()
+                };
+                40
+            ],
+        };
+        let band_left = minimap_left(400).expect("a 400px window has a minimap band") as u32;
+        let code_bottom = text_area_bottom(300, document.fm) as u32;
+        let band_differs = |a: &[u8], b: &[u8]| {
+            let mut count = 0usize;
+            for row in 0..code_bottom {
+                for col in band_left..400 {
+                    let i = ((row * 400 + col) * 4) as usize;
+                    if a[i..i + 4] != b[i..i + 4] {
+                        count += 1;
+                    }
+                }
+            }
+            count
+        };
+
+        document.current_summary = Some(summary.clone());
+        document.current_line_shapes = minimap_line_shapes(text);
+        document.minimap_cache = None;
+        let document_minimap_px = document.render_offscreen();
+        assert!(
+            band_differs(&document_px, &document_minimap_px) > 0,
+            "the probe is vacuous unless a summary makes the document frame's \
+             minimap band change"
+        );
+
+        terminal.current_summary = Some(summary);
+        terminal.current_line_shapes = minimap_line_shapes(text);
+        terminal.minimap_cache = None;
+        let terminal_minimap_px = terminal.render_offscreen();
+        assert_eq!(
+            band_differs(&terminal_px, &terminal_minimap_px),
+            0,
+            "terminal mode must not paint the document minimap"
+        );
+    }
+
+    /// Acceptance 33: reverse video, selection, and the cursor each
+    /// change the rendered frame, and a continuation paints no glyph of
+    /// its own.
+    #[test]
+    fn a33_reverse_selection_and_cursor_each_change_the_frame() {
+        let Some(mut base) = headless_or_skip(400, 300, "x") else {
+            return;
+        };
+        let buffer_id = BufferId::next();
+        let build = |state: &mut State, mutate: &dyn Fn(&mut TerminalFrame)| -> Vec<u8> {
+            state.current_buffer_id = Some(buffer_id);
+            state.exit_terminal_mode();
+            state.current_buffer_id = Some(buffer_id);
+            let mut frame = plain_terminal_frame(buffer_id, "SAMPLE", 12);
+            mutate(&mut frame);
+            assert_eq!(frame.validate(), Ok(()));
+            state.apply_terminal_frame(frame);
+            state.render_offscreen()
+        };
+
+        let plain = build(&mut base, &|_| {});
+        let reversed = build(&mut base, &|frame| {
+            for cell in &mut frame.cells {
+                cell.style.reverse = true;
+            }
+        });
+        let selected = build(&mut base, &|frame| {
+            frame.selection = vec![pmacs_protocol::TerminalSelectionSpan {
+                row: 0,
+                start_col: 0,
+                end_col: 6,
+            }];
+        });
+        let with_cursor = build(&mut base, &|frame| {
+            frame.cursor = Some(CellCoord::new(0, 3));
+        });
+
+        let differs = |a: &[u8], b: &[u8]| a.iter().zip(b).filter(|(x, y)| x != y).count();
+        assert!(
+            differs(&plain, &reversed) > 500,
+            "reverse video must repaint the run"
+        );
+        assert!(
+            differs(&plain, &selected) > 200,
+            "a selection wash must reach the frame"
+        );
+        assert!(
+            differs(&plain, &with_cursor) > 50,
+            "the cursor block must reach the frame"
+        );
+
+        // A wide lead plus its continuation paints one glyph across two
+        // cells — the continuation contributes no run of its own.
+        base.exit_terminal_mode();
+        base.current_buffer_id = Some(buffer_id);
+        let mut cells = vec![
+            terminal_cell(
+                pmacs_protocol::Glyph::Char('\u{4e00}'),
+                CellStyle::default(),
+            ),
+            terminal_cell(pmacs_protocol::Glyph::Continuation, CellStyle::default()),
+        ];
+        cells.resize(
+            4,
+            terminal_cell(pmacs_protocol::Glyph::Char(' '), CellStyle::default()),
+        );
+        let frame = terminal_frame_of(buffer_id, 1, 4, cells);
+        assert_eq!(frame.validate(), Ok(()));
+        base.apply_terminal_frame(frame);
+        let plan = &base.terminal.as_ref().expect("terminal").plan;
+        let wide = plan.runs.first().expect("a wide run");
+        assert_eq!(wide.cells, 2, "the wide lead owns both columns");
+        assert!(
+            plan.runs.iter().all(|run| run.col != 1),
+            "the continuation contributes no run"
+        );
+    }
+
+    /// Acceptance 36: the terminal statusline metadata reaches the band
+    /// as text, never as a host-title or control effect.
+    #[test]
+    fn a36_terminal_title_stays_sanitized_statusline_metadata() {
+        let Some(mut state) = headless_or_skip(400, 300, "doc") else {
+            return;
+        };
+        let buffer_id = BufferId::next();
+        state.current_buffer_id = Some(buffer_id);
+        let mut frame = plain_terminal_frame(buffer_id, "sh", 8);
+        frame.title = Some("build: cargo test".into());
+        state.apply_terminal_frame(frame);
+        // The frame retains the title verbatim for the provider to
+        // render; nothing in the GPU turns it into a window-title or a
+        // terminal control sequence.
+        assert_eq!(
+            state
+                .terminal
+                .as_ref()
+                .expect("terminal")
+                .frame
+                .title
+                .as_deref(),
+            Some("build: cargo test")
+        );
+        // Control characters can never arrive here: validation rejects
+        // them before the frame is installed.
+        let mut hostile = plain_terminal_frame(buffer_id, "sh", 8);
+        hostile.title = Some("\u{1b}]0;pwned\u{7}".into());
+        assert!(hostile.validate().is_err());
+    }
 }
diff --git a/pmacs-gpu/src/terminal.rs b/pmacs-gpu/src/terminal.rs
new file mode 100644
index 0000000..8a1d794
--- /dev/null
+++ b/pmacs-gpu/src/terminal.rs
@@ -0,0 +1,753 @@
+//! Fixed-cell terminal paint planning (Vterm Stage 3).
+//!
+//! The document renderer derives geometry from shaped text: a glyph's
+//! advance decides where the next glyph starts. A terminal cannot work
+//! that way. Its column origins are defined by the CHILD, and the
+//! frontend's font has no say in them — a wide glyph the font renders
+//! 1.9 cells wide still occupies exactly two columns, and the cell after
+//! it still starts at exactly `col * advance`.
+//!
+//! So this module resolves a [`TerminalFrame`] into a plan expressed in
+//! CELLS, never pixels. Row/column rectangles own backgrounds,
+//! underlines, selection, the cursor, and clipping; the renderer
+//! multiplies by its own metrics at the end. That split is also what
+//! makes the paint rules testable without a GPU: everything here is a
+//! pure function of the frame plus two default colors.
+
+use pmacs_protocol::{Cell, CellSize, Color, Glyph, Style, TerminalFrame, UnderlineStyle};
+
+/// A resolved 24-bit color. The plan carries no `Default` sentinel:
+/// resolution happens once, up front, because `reverse` swaps the
+/// RESOLVED pair — a reversed default-on-default cell must come out as
+/// dark-on-light, which is impossible if `Default` survives into the
+/// swap.
+pub type Rgb = [u8; 3];
+
+/// The frontend defaults `Color::Default` resolves to.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct TerminalPalette {
+    /// The GPU's plain-text color.
+    pub default_fg: Rgb,
+    /// The GPU's window background.
+    pub default_bg: Rgb,
+}
+
+/// A half-open run of cells on one row: `[start_col, end_col)`.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct CellRun {
+    /// Row within the frame.
+    pub row: u32,
+    /// Inclusive first column.
+    pub start_col: u32,
+    /// Exclusive last column.
+    pub end_col: u32,
+}
+
+/// A background run with its resolved (post-`reverse`) color.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct BackgroundRun {
+    /// Cells covered.
+    pub run: CellRun,
+    /// Resolved fill.
+    pub color: Rgb,
+}
+
+/// An underline run with its resolved color and form.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct UnderlineRun {
+    /// Cells covered.
+    pub run: CellRun,
+    /// Resolved stroke color.
+    pub color: Rgb,
+    /// Which underline form to draw.
+    pub style: UnderlineStyle,
+}
+
+/// One shaped text run pinned to an explicit cell origin.
+///
+/// `cells` is the run's declared footprint. The renderer clips to it, so
+/// a font whose glyph is wider than the cells the child allocated
+/// overflows into a clip, never into the next column's origin.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct TextRun {
+    /// Row within the frame.
+    pub row: u32,
+    /// Origin column.
+    pub col: u32,
+    /// Declared width in cells.
+    pub cells: u32,
+    /// Text to shape.
+    pub text: String,
+    /// Resolved (post-`reverse`) foreground.
+    pub color: Rgb,
+    /// Bold via font attributes.
+    pub bold: bool,
+    /// Italic via font attributes.
+    pub italic: bool,
+}
+
+/// Everything one terminal frame paints, in cell coordinates.
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub struct TerminalPaintPlan {
+    /// The frame's declared grid.
+    pub size: CellSize,
+    /// Background fills, coalesced across adjacent equal colors.
+    pub backgrounds: Vec<BackgroundRun>,
+    /// Text runs in row-major order.
+    pub runs: Vec<TextRun>,
+    /// Underline strokes, coalesced across adjacent equal color+form.
+    pub underlines: Vec<UnderlineRun>,
+    /// Editor-owned selection wash, one run per selected row.
+    pub selection: Vec<CellRun>,
+    /// The child's cursor cell, when visible.
+    pub cursor: Option<CellRun>,
+}
+
+/// Resolve a cell's foreground and background, applying `reverse` after
+/// both defaults have been substituted.
+fn resolved_colors(style: &Style, palette: TerminalPalette) -> (Rgb, Rgb) {
+    let fg = resolve_color(style.fg, palette.default_fg);
+    let bg = resolve_color(style.bg, palette.default_bg);
+    if style.reverse { (bg, fg) } else { (fg, bg) }
+}
+
+/// Map one wire color through the frontend's defaults and palette.
+fn resolve_color(color: Color, default: Rgb) -> Rgb {
+    match color {
+        Color::Default => default,
+        Color::Rgb(r, g, b) => [r, g, b],
+        Color::Indexed(index) => indexed_rgb(index),
+    }
+}
+
+/// Standard xterm-style 256-color palette: 16 base colors, the 6×6×6
+/// cube (16..=231), then the 24-step grayscale ramp (232..=255).
+///
+/// Deliberately the same table the document path's `indexed_to_glyphon`
+/// uses. Two palettes in one frontend would make an indexed diagnostic
+/// and an indexed terminal cell disagree on what "red" is.
+pub fn indexed_rgb(index: u8) -> Rgb {
+    const ANSI16: [Rgb; 16] = [
+        [0, 0, 0],
+        [205, 49, 49],
+        [13, 188, 121],
+        [229, 229, 16],
+        [36, 114, 200],
+        [188, 63, 188],
+        [17, 168, 205],
+        [229, 229, 229],
+        [102, 102, 102],
+        [241, 76, 76],
+        [35, 209, 139],
+        [245, 245, 67],
+        [59, 142, 234],
+        [214, 112, 214],
+        [41, 184, 219],
+        [255, 255, 255],
+    ];
+    if index < 16 {
+        return ANSI16[index as usize];
+    }
+    if (16..=231).contains(&index) {
+        const STEPS: [u8; 6] = [0, 95, 135, 175, 215, 255];
+        let i = index - 16;
+        return [
+            STEPS[(i / 36) as usize],
+            STEPS[((i / 6) % 6) as usize],
+            STEPS[(i % 6) as usize],
+        ];
+    }
+    let level = 8 + 10 * (index - 232);
+    [level, level, level]
+}
+
+/// The style a cell paints with.
+///
+/// A continuation has no paint identity of its own: it is the second
+/// column of the preceding glyph, so it inherits that lead's style. A
+/// continuation that carried its own style would let the two halves of
+/// one wide character disagree on background or underline.
+fn paint_style(cells: &[Cell], index: usize, row_start: usize) -> &Style {
+    if matches!(cells[index].glyph, Glyph::Continuation) && index > row_start {
+        &cells[index - 1].style
+    } else {
+        &cells[index].style
+    }
+}
+
+/// The text a cell contributes, or `None` for a continuation.
+fn cell_text(cell: &Cell) -> Option<String> {
+    match &cell.glyph {
+        Glyph::Char(ch) => Some(ch.to_string()),
+        // Validation already proved the cluster is UTF-8; a defensive
+        // lossy decode keeps a future validator change from panicking
+        // the renderer.
+        Glyph::Cluster(bytes) => Some(String::from_utf8_lossy(bytes).into_owned()),
+        Glyph::Continuation => None,
+    }
+}
+
+/// Whether a cell can join an ASCII run.
+///
+/// Only single-column ASCII qualifies. Everything else — clusters, wide
+/// leads, non-ASCII — gets its own explicitly positioned run, because
+/// only for ASCII in a monospace face does the shaped advance reliably
+/// equal the cell advance.
+fn ascii_runnable(cell: &Cell) -> bool {
+    matches!(&cell.glyph, Glyph::Char(ch) if ch.is_ascii_graphic() || *ch == ' ')
+}
+
+/// Whether a cell is a wide lead (its continuation follows).
+fn is_wide_lead(cells: &[Cell], index: usize) -> bool {
+    cells
+        .get(index + 1)
+        .is_some_and(|next| matches!(next.glyph, Glyph::Continuation))
+}
+
+impl TerminalPaintPlan {
+    /// Resolve a validated frame into cell-space paint data.
+    ///
+    /// The frame must already have passed
+    /// [`TerminalFrame::validate`]; this assumes the cell count, the
+    /// wide-continuation topology, and the selection spans are sound.
+    #[must_use]
+    pub fn build(frame: &TerminalFrame, palette: TerminalPalette) -> Self {
+        let cols = frame.size.cols as usize;
+        let mut plan = Self {
+            size: frame.size,
+            ..Self::default()
+        };
+        if cols == 0 {
+            return plan;
+        }
+
+        for row in 0..frame.size.rows {
+            let row_start = row as usize * cols;
+            let row_cells = &frame.cells[row_start..row_start + cols];
+            plan.plan_row(row, row_cells, palette);
+        }
+
+        plan.selection = frame
+            .selection
+            .iter()
+            .map(|span| CellRun {
+                row: span.row,
+                start_col: span.start_col,
+                end_col: span.end_col,
+            })
+            .collect();
+
+        plan.cursor = frame.cursor.map(|cursor| CellRun {
+            row: cursor.row,
+            start_col: cursor.col,
+            end_col: cursor.col + 1,
+        });
+
+        plan
+    }
+
+    /// Plan one row's backgrounds, underlines, and text runs.
+    #[allow(clippy::too_many_lines, reason = "one row's paint state machine")]
+    fn plan_row(&mut self, row: u32, cells: &[Cell], palette: TerminalPalette) {
+        // Backgrounds and underlines coalesce across the whole row;
+        // text runs break on any attribute change AND on any glyph that
+        // cannot be positioned by shaping.
+        let mut bg_open: Option<(u32, Rgb)> = None;
+        let mut ul_open: Option<(u32, Rgb, UnderlineStyle)> = None;
+        let mut text_open: Option<(u32, String, Rgb, bool, bool)> = None;
+
+        for col in 0..cells.len() {
+            let style = paint_style(cells, col, 0);
+            let (fg, bg) = resolved_colors(style, palette);
+            let col_u32 = col as u32;
+
+            match bg_open {
+                Some((start, color)) if color != bg => {
+                    self.backgrounds.push(BackgroundRun {
+                        run: CellRun {
+                            row,
+                            start_col: start,
+                            end_col: col_u32,
+                        },
+                        color,
+                    });
+                    bg_open = Some((col_u32, bg));
+                }
+                Some(_) => {}
+                None => bg_open = Some((col_u32, bg)),
+            }
+
+            // A `Default` underline color follows the POST-reverse
+            // foreground: on a reversed cell the underline must track
+            // the color the glyph actually drew in, not the one the
+            // child nominally set.
+            let underline = (style.underline != UnderlineStyle::None).then(|| {
+                let color = match style.underline_color {
+                    Color::Default => fg,
+                    other => resolve_color(other, fg),
+                };
+                (color, style.underline)
+            });
+            match (ul_open, underline) {
+                (Some((start, color, form)), Some((next_color, next_form)))
+                    if color != next_color || form != next_form =>
+                {
+                    self.underlines.push(UnderlineRun {
+                        run: CellRun {
+                            row,
+                            start_col: start,
+                            end_col: col_u32,
+                        },
+                        color,
+                        style: form,
+                    });
+                    ul_open = Some((col_u32, next_color, next_form));
+                }
+                (Some((start, color, form)), None) => {
+                    self.underlines.push(UnderlineRun {
+                        run: CellRun {
+                            row,
+                            start_col: start,
+                            end_col: col_u32,
+                        },
+                        color,
+                        style: form,
+                    });
+                    ul_open = None;
+                }
+                (None, Some((color, form))) => ul_open = Some((col_u32, color, form)),
+                (Some(_), Some(_)) | (None, None) => {}
+            }
+
+            let cell = &cells[col];
+            let joinable = ascii_runnable(cell) && !is_wide_lead(cells, col);
+            if joinable {
+                match text_open.as_mut() {
+                    Some((_, text, color, bold, italic))
+                        if *color == fg && *bold == style.bold && *italic == style.italic =>
+                    {
+                        text.push_str(&cell_text(cell).unwrap_or_default());
+                    }
+                    _ => {
+                        self.flush_text_run(row, text_open.take());
+                        text_open = Some((
+                            col_u32,
+                            cell_text(cell).unwrap_or_default(),
+                            fg,
+                            style.bold,
+                            style.italic,
+                        ));
+                    }
+                }
+                continue;
+            }
+
+            self.flush_text_run(row, text_open.take());
+            let Some(text) = cell_text(cell) else {
+                // A continuation draws nothing: its lead already
+                // covers both columns.
+                continue;
+            };
+            let cells_wide = if is_wide_lead(cells, col) { 2 } else { 1 };
+            self.runs.push(TextRun {
+                row,
+                col: col_u32,
+                cells: cells_wide,
+                text,
+                color: fg,
+                bold: style.bold,
+                italic: style.italic,
+            });
+        }
+
+        let end = cells.len() as u32;
+        if let Some((start, color)) = bg_open {
+            self.backgrounds.push(BackgroundRun {
+                run: CellRun {
+                    row,
+                    start_col: start,
+                    end_col: end,
+                },
+                color,
+            });
+        }
+        if let Some((start, color, form)) = ul_open {
+            self.underlines.push(UnderlineRun {
+                run: CellRun {
+                    row,
+                    start_col: start,
+                    end_col: end,
+                },
+                color,
+                style: form,
+            });
+        }
+        self.flush_text_run(row, text_open);
+    }
+
+    fn flush_text_run(&mut self, row: u32, open: Option<(u32, String, Rgb, bool, bool)>) {
+        let Some((col, text, color, bold, italic)) = open else {
+            return;
+        };
+        let cells = text.chars().count() as u32;
+        self.runs.push(TextRun {
+            row,
+            col,
+            cells,
+            text,
+            color,
+            bold,
+            italic,
+        });
+    }
+}
+
+/// The terminal cell viewport a drawable rectangle admits.
+///
+/// Rows and columns are `floor(extent / metric)`, clamped through the
+/// shared protocol limits so an enormous window cannot declare a grid
+/// the daemon would reject. A rectangle too small for one whole cell
+/// yields `None`: a zero-area declaration is not sent at all, and the
+/// next geometry change that produces a valid size sends one.
+#[must_use]
+pub fn cell_viewport(
+    width_px: f32,
+    height_px: f32,
+    advance_px: f32,
+    line_px: f32,
+) -> Option<CellSize> {
+    if !(advance_px.is_finite() && line_px.is_finite()) || advance_px <= 0.0 || line_px <= 0.0 {
+        return None;
+    }
+    if !(width_px.is_finite() && height_px.is_finite()) || width_px <= 0.0 || height_px <= 0.0 {
+        return None;
+    }
+    let cols = (width_px / advance_px).floor();
+    let rows = (height_px / line_px).floor();
+    if cols < 1.0 || rows < 1.0 {
+        return None;
+    }
+    let cols = (cols as u32).min(u32::from(pmacs_protocol::MAX_TERMINAL_COLS));
+    let rows = (rows as u32).min(u32::from(pmacs_protocol::MAX_TERMINAL_ROWS));
+    // The area bound can still bite at the extremes (512x512 is exactly
+    // the cap, but a future limit change need not keep that true), so
+    // shed rows rather than emit a size the daemon must reject.
+    let max_rows = (pmacs_protocol::MAX_TERMINAL_VISIBLE_CELLS / cols as usize) as u32;
+    let rows = rows.min(max_rows);
+    if rows == 0 {
+        return None;
+    }
+    Some(CellSize::new(rows, cols))
+}
+
+/// Hit-test a pixel inside the terminal rectangle to a cell.
+///
+/// Returns `None` outside the declared grid, so the status band, the
+/// padding past the last full column, and any point above the terminal
+/// origin are never terminal hits.
+#[must_use]
+pub fn hit_test_cell(
+    x_px: f32,
+    y_px: f32,
+    origin: (f32, f32),
+    advance_px: f32,
+    line_px: f32,
+    size: CellSize,
+) -> Option<pmacs_protocol::CellCoord> {
+    if advance_px <= 0.0 || line_px <= 0.0 {
+        return None;
+    }
+    let dx = x_px - origin.0;
+    let dy = y_px - origin.1;
+    if dx < 0.0 || dy < 0.0 {
+        return None;
+    }
+    let col = (dx / advance_px).floor();
+    let row = (dy / line_px).floor();
+    if col < 0.0 || row < 0.0 {
+        return None;
+    }
+    let col = col as u32;
+    let row = row as u32;
+    if row >= size.rows || col >= size.cols {
+        return None;
+    }
+    Some(pmacs_protocol::CellCoord::new(row, col))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pmacs_protocol::{BufferId, CellCoord, TerminalProcessState, TerminalSelectionSpan};
+
+    const PALETTE: TerminalPalette = TerminalPalette {
+        default_fg: [230, 230, 235],
+        default_bg: [13, 13, 18],
+    };
+
+    fn styled(glyph: Glyph, style: Style) -> Cell {
+        Cell {
+            glyph,
+            style,
+            attachment: None,
+        }
+    }
+
+    fn plain(ch: char) -> Cell {
+        styled(Glyph::Char(ch), Style::default())
+    }
+
+    fn frame(rows: u32, cols: u32, cells: Vec<Cell>) -> TerminalFrame {
+        TerminalFrame {
+            buffer_id: BufferId::from_raw(1),
+            size: CellSize::new(rows, cols),
+            cells,
+            cursor: None,
+            title: None,
+            screen_generation: 1,
+            selection: Vec::new(),
+            scroll_offset: 0,
+            at_bottom: true,
+            pid: 1,
+            process: TerminalProcessState::Running,
+        }
+    }
+
+    #[test]
+    fn ascii_coalesces_by_attributes_and_keeps_explicit_origins() {
+        let red = Style {
+            fg: Color::Indexed(1),
+            ..Style::default()
+        };
+        let cells = vec![
+            plain('a'),
+            plain('b'),
+            styled(Glyph::Char('c'), red),
+            plain('d'),
+        ];
+        let plan = TerminalPaintPlan::build(&frame(1, 4, cells), PALETTE);
+        assert_eq!(plan.runs.len(), 3);
+        assert_eq!(plan.runs[0].text, "ab");
+        assert_eq!(plan.runs[0].col, 0);
+        assert_eq!(plan.runs[0].cells, 2);
+        assert_eq!(plan.runs[1].text, "c");
+        assert_eq!(plan.runs[1].col, 2);
+        assert_eq!(plan.runs[1].color, indexed_rgb(1));
+        // The run after the attribute change is positioned by its own
+        // column, not by where the previous run's glyphs happened to end.
+        assert_eq!(plan.runs[2].col, 3);
+    }
+
+    #[test]
+    fn wide_lead_owns_two_cells_and_its_continuation_draws_nothing() {
+        let cyan = Style {
+            bg: Color::Rgb(0, 40, 40),
+            ..Style::default()
+        };
+        let cells = vec![
+            styled(Glyph::Char('\u{4e00}'), cyan),
+            styled(Glyph::Continuation, Style::default()),
+            plain('x'),
+            plain('y'),
+        ];
+        let plan = TerminalPaintPlan::build(&frame(1, 4, cells), PALETTE);
+        let wide = &plan.runs[0];
+        assert_eq!(wide.text, "\u{4e00}");
+        assert_eq!(wide.col, 0);
+        assert_eq!(wide.cells, 2, "a wide lead declares a two-cell footprint");
+        assert_eq!(
+            plan.runs[1].col, 2,
+            "the run after a wide glyph starts at its own column"
+        );
+        assert!(
+            plan.runs.iter().all(|run| run.col != 1),
+            "a continuation contributes no text run"
+        );
+        // The continuation carries a DEFAULT style on the wire but must
+        // paint with its lead's background.
+        let covering = plan
+            .backgrounds
+            .iter()
+            .find(|bg| bg.run.start_col == 0)
+            .expect("lead background");
+        assert_eq!(covering.color, [0, 40, 40]);
+        assert_eq!(
+            covering.run.end_col, 2,
+            "the lead's background covers both of its columns"
+        );
+    }
+
+    #[test]
+    fn reverse_swaps_resolved_defaults_and_drives_the_underline_color() {
+        let style = Style {
+            reverse: true,
+            underline: UnderlineStyle::Single,
+            ..Style::default()
+        };
+        let plan =
+            TerminalPaintPlan::build(&frame(1, 1, vec![styled(Glyph::Char('z'), style)]), PALETTE);
+        assert_eq!(plan.backgrounds[0].color, PALETTE.default_fg);
+        assert_eq!(plan.runs[0].color, PALETTE.default_bg);
+        assert_eq!(
+            plan.underlines[0].color, PALETTE.default_bg,
+            "a default underline color follows the post-reverse foreground"
+        );
+    }
+
+    #[test]
+    fn explicit_underline_color_and_form_coalesce_then_break() {
+        let curly = Style {
+            underline: UnderlineStyle::Curly,
+            underline_color: Color::Rgb(200, 0, 0),
+            ..Style::default()
+        };
+        let mut dotted = curly;
+        dotted.underline = UnderlineStyle::Dotted;
+        let cells = vec![
+            styled(Glyph::Char('a'), curly),
+            styled(Glyph::Char('b'), curly),
+            styled(Glyph::Char('c'), dotted),
+            plain('d'),
+        ];
+        let plan = TerminalPaintPlan::build(&frame(1, 4, cells), PALETTE);
+        assert_eq!(plan.underlines.len(), 2);
+        assert_eq!(plan.underlines[0].run.start_col, 0);
+        assert_eq!(plan.underlines[0].run.end_col, 2);
+        assert_eq!(plan.underlines[0].style, UnderlineStyle::Curly);
+        assert_eq!(plan.underlines[0].color, [200, 0, 0]);
+        assert_eq!(plan.underlines[1].run.start_col, 2);
+        assert_eq!(plan.underlines[1].run.end_col, 3);
+        assert_eq!(plan.underlines[1].style, UnderlineStyle::Dotted);
+    }
+
+    #[test]
+    fn bold_italic_and_truecolor_reach_the_run() {
+        let style = Style {
+            bold: true,
+            italic: true,
+            fg: Color::Rgb(1, 2, 3),
+            ..Style::default()
+        };
+        let plan =
+            TerminalPaintPlan::build(&frame(1, 1, vec![styled(Glyph::Char('q'), style)]), PALETTE);
+        assert!(plan.runs[0].bold);
+        assert!(plan.runs[0].italic);
+        assert_eq!(plan.runs[0].color, [1, 2, 3]);
+    }
+
+    #[test]
+    fn selection_and_cursor_come_only_from_the_frame() {
+        let mut f = frame(2, 4, vec![plain('.'); 8]);
+        f.selection = vec![TerminalSelectionSpan {
+            row: 1,
+            start_col: 1,
+            end_col: 3,
+        }];
+        f.cursor = Some(CellCoord::new(0, 2));
+        let plan = TerminalPaintPlan::build(&f, PALETTE);
+        assert_eq!(
+            plan.selection,
+            vec![CellRun {
+                row: 1,
+                start_col: 1,
+                end_col: 3
+            }]
+        );
+        assert_eq!(
+            plan.cursor,
+            Some(CellRun {
+                row: 0,
+                start_col: 2,
+                end_col: 3
+            })
+        );
+
+        // A frame with no cursor paints none: visibility is the child's
+        // decision, never the frontend's.
+        f.cursor = None;
+        assert!(TerminalPaintPlan::build(&f, PALETTE).cursor.is_none());
+    }
+
+    #[test]
+    fn cluster_cells_get_their_own_positioned_run() {
+        let cells = vec![
+            plain('a'),
+            styled(
+                Glyph::Cluster("e\u{301}".as_bytes().to_vec().into_boxed_slice()),
+                Style::default(),
+            ),
+            plain('b'),
+        ];
+        let plan = TerminalPaintPlan::build(&frame(1, 3, cells), PALETTE);
+        assert_eq!(plan.runs.len(), 3);
+        assert_eq!(plan.runs[1].text, "e\u{301}");
+        assert_eq!(plan.runs[1].col, 1);
+        assert_eq!(plan.runs[1].cells, 1);
+        assert_eq!(plan.runs[2].col, 2);
+    }
+
+    #[test]
+    fn rows_never_share_runs_or_background_spans() {
+        let plan = TerminalPaintPlan::build(&frame(2, 2, vec![plain('x'); 4]), PALETTE);
+        assert_eq!(
+            plan.runs.len(),
+            2,
+            "one run per row, never wrapped together"
+        );
+        assert_eq!(plan.runs[0].row, 0);
+        assert_eq!(plan.runs[1].row, 1);
+        assert!(plan.backgrounds.iter().all(|bg| bg.run.end_col <= 2));
+    }
+
+    #[test]
+    fn cell_viewport_floors_clamps_and_refuses_a_degenerate_rectangle() {
+        assert_eq!(
+            cell_viewport(100.0, 50.0, 10.0, 20.0),
+            Some(CellSize::new(2, 10))
+        );
+        // Partial cells are dropped, never rounded up into a column the
+        // child would write past.
+        assert_eq!(
+            cell_viewport(109.0, 59.0, 10.0, 20.0),
+            Some(CellSize::new(2, 10))
+        );
+        assert_eq!(cell_viewport(9.0, 20.0, 10.0, 20.0), None);
+        assert_eq!(cell_viewport(100.0, 19.0, 10.0, 20.0), None);
+        assert_eq!(cell_viewport(100.0, 50.0, 0.0, 20.0), None);
+        assert_eq!(cell_viewport(f32::NAN, 50.0, 10.0, 20.0), None);
+        let huge = cell_viewport(1_000_000.0, 1_000_000.0, 1.0, 1.0).expect("clamped");
+        assert_eq!(huge.rows, u32::from(pmacs_protocol::MAX_TERMINAL_ROWS));
+        assert_eq!(huge.cols, u32::from(pmacs_protocol::MAX_TERMINAL_COLS));
+    }
+
+    #[test]
+    fn hit_test_yields_only_in_bounds_cells() {
+        let size = CellSize::new(3, 4);
+        assert_eq!(
+            hit_test_cell(16.0, 16.0, (16.0, 16.0), 10.0, 20.0, size),
+            Some(CellCoord::new(0, 0))
+        );
+        assert_eq!(
+            hit_test_cell(16.0 + 25.0, 16.0 + 41.0, (16.0, 16.0), 10.0, 20.0, size),
+            Some(CellCoord::new(2, 2))
+        );
+        // Above / left of the origin, and past the last declared cell —
+        // the status band and the trailing padding are not terminal hits.
+        assert_eq!(
+            hit_test_cell(15.0, 16.0, (16.0, 16.0), 10.0, 20.0, size),
+            None
+        );
+        assert_eq!(
+            hit_test_cell(16.0, 15.0, (16.0, 16.0), 10.0, 20.0, size),
+            None
+        );
+        assert_eq!(
+            hit_test_cell(16.0 + 40.0, 16.0, (16.0, 16.0), 10.0, 20.0, size),
+            None
+        );
+        assert_eq!(
+            hit_test_cell(16.0, 16.0 + 60.0, (16.0, 16.0), 10.0, 20.0, size),
+            None
+        );
+    }
+}
diff --git a/pmacs-protocol/Cargo.toml b/pmacs-protocol/Cargo.toml
index a1ced85..d84dcdb 100644
--- a/pmacs-protocol/Cargo.toml
+++ b/pmacs-protocol/Cargo.toml
@@ -46,3 +46,9 @@ crdt = []
 serde = { workspace = true }
 postcard = { workspace = true }
 thiserror = { workspace = true }
+# Vterm Stage 3: `TerminalFrame::validate` is the ONE structural policy
+# for terminal cells, so the column-width and wide-continuation rules
+# live here rather than being re-implemented per frontend. That needs a
+# direct width table; pinned through the workspace so this crate and
+# `pmacs`'s terminal screen measure glyphs identically.
+unicode-width = { workspace = true }
diff --git a/pmacs-protocol/src/lib.rs b/pmacs-protocol/src/lib.rs
index 70377f1..21b5f02 100644
--- a/pmacs-protocol/src/lib.rs
+++ b/pmacs-protocol/src/lib.rs
@@ -38,6 +38,7 @@ pub mod cell;
 pub mod crdt;
 pub mod ids;
 pub mod message;
+pub mod terminal;
 pub mod transport;
 
 pub use cell::{
@@ -57,4 +58,9 @@ pub use message::{
     StatuslineSegment, StyleSegment, StyleSpan, ThemeFace, is_builtin_pair_char,
     is_modeline_face_name, is_supported_protocol_version, is_ui_face_name, negotiate_capabilities,
 };
+pub use terminal::{
+    MAX_TERMINAL_COLS, MAX_TERMINAL_FRAME_GLYPH_BYTES, MAX_TERMINAL_GRAPHEME_BYTES,
+    MAX_TERMINAL_METADATA_BYTES, MAX_TERMINAL_ROWS, MAX_TERMINAL_VISIBLE_CELLS, TerminalFrame,
+    TerminalFrameError, TerminalProcessState, TerminalSelectionSpan,
+};
 pub use transport::{MAX_FRAME_BYTES, TransportError, read_message, write_message};
diff --git a/pmacs-protocol/src/message.rs b/pmacs-protocol/src/message.rs
index fe88144..79db7e7 100644
--- a/pmacs-protocol/src/message.rs
+++ b/pmacs-protocol/src/message.rs
@@ -393,6 +393,55 @@ pub enum FrontendEvent {
         /// moves the highlight.
         invoke: bool,
     },
+    /// Vterm Stage 3 (protocol v19): the terminal-cell geometry a
+    /// semantic frontend has on screen for `buffer_id`.
+    ///
+    /// This is the terminal twin of [`Self::Viewport`] and keeps the
+    /// same no-pixels contract: it carries a CELL size, never pixel
+    /// extent, DPI, or glyph advances. The frontend divides its own
+    /// drawable rectangle by its own metrics.
+    ///
+    /// A v19 frontend sends both this and `Viewport` after every
+    /// `BufferSnapshot`; the daemon accepts only the declaration
+    /// matching the authenticated active buffer's kind and drops the
+    /// other. That dual declaration is what removes the otherwise
+    /// circular dependency where a frontend would need a terminal frame
+    /// before it knew to ask for one.
+    ///
+    /// Recording the size is not claiming control: a passive view's
+    /// declaration produces its own clipped/padded projection, while
+    /// only the durable controller changes the shared PTY geometry.
+    /// Sent only to a `>= 19` daemon.
+    TerminalResize {
+        /// Which frontend declared the geometry (untrusted; the daemon
+        /// routes by the authenticated session, matching the
+        /// `CrdtOp` / `Viewport` / `Pointer` source-trust rule).
+        frontend_id: FrontendId,
+        /// Terminal identity buffer the frontend was displaying.
+        buffer_id: crate::BufferId,
+        /// Content rectangle size in terminal cells.
+        size: CellSize,
+    },
+    /// Vterm Stage 3 (protocol v19): a pointer gesture a semantic
+    /// frontend hit-tested to a terminal CELL.
+    ///
+    /// Terminal windows have no source bytes to hit-test against, so
+    /// this replaces [`Self::Pointer`] inside the terminal clip. Once
+    /// accepted it follows the landed Stage 2 pointer path: child SGR
+    /// mouse reporting when eligible, otherwise per-view scroll,
+    /// selection, or context menu. Sent only to a `>= 19` daemon.
+    TerminalPointer {
+        /// Which frontend produced the gesture (untrusted, as above).
+        frontend_id: FrontendId,
+        /// Terminal identity buffer the frontend was displaying.
+        buffer_id: crate::BufferId,
+        /// Cell the pointer is over, within the last declared viewport.
+        coord: CellCoord,
+        /// Which gesture step this is.
+        kind: MouseKind,
+        /// Modifiers held during the gesture.
+        mods: Modifiers,
+    },
 }
 
 /// Gesture step for [`FrontendEvent::Pointer`]. Double-click
@@ -437,7 +486,9 @@ impl FrontendEvent {
             | Self::CrdtOp { frontend_id, .. }
             | Self::Viewport { frontend_id, .. }
             | Self::Pointer { frontend_id, .. }
-            | Self::MenuPointer { frontend_id, .. } => *frontend_id,
+            | Self::MenuPointer { frontend_id, .. }
+            | Self::TerminalResize { frontend_id, .. }
+            | Self::TerminalPointer { frontend_id, .. } => *frontend_id,
         }
     }
 }
@@ -1067,6 +1118,25 @@ pub enum InstanceMessage {
         /// Right-side custom segments in display order.
         right: Vec<StatuslineSegment>,
     },
+    /// Vterm Stage 3 (protocol v19). The complete visible terminal grid
+    /// for the receiving frontend's active terminal window.
+    ///
+    /// A terminal identity buffer's `BufferSnapshot` is an empty CRDT
+    /// anchor, so a semantic frontend has no text to lay out; this
+    /// carries the cells instead. It is a whole-grid replacement, never
+    /// a delta, and it is validated by
+    /// [`crate::terminal::TerminalFrame::validate`] both before the
+    /// daemon emits it and after the frontend decodes it.
+    ///
+    /// Suppression compares the COMPLETE ordered payload, not
+    /// `screen_generation`: selection, scroll, viewport, and process
+    /// state all change without advancing that counter, and a
+    /// generation-keyed producer would go silent on exactly those
+    /// view-only updates. Daemon-gated `>= 19`.
+    ///
+    /// Appended after [`Self::StatuslineSegments`], the final v18
+    /// variant, so no existing postcard discriminant moves.
+    TerminalFrame(crate::terminal::TerminalFrame),
 }
 
 /// One resolved UI face for [`InstanceMessage::ThemeFacts`]: a full
@@ -1471,7 +1541,19 @@ pub enum ResourceBody {
 /// carrying custom modeline provider output. Daemon-gated `< 18`; a
 /// v17 peer keeps the built-in status band. Appended after `FontFacts`
 /// so the final v17 discriminant remains stable.
-pub const PROTOCOL_VERSION: u32 = 18;
+///
+/// Vterm Stage 3: bumped 18 → 19 for the terminal family —
+/// [`InstanceMessage::TerminalFrame`] (daemon-gated `< 19`) plus
+/// [`FrontendEvent::TerminalResize`] and
+/// [`FrontendEvent::TerminalPointer`] (frontend-gated, sent only to a
+/// `>= 19` instance). All three are appended after their enum's final
+/// v18 variant, so the ladder resumes on the v6 encoding floor: a v18
+/// grid peer keeps receiving Stage 2's composed `CellDelta` terminal
+/// windows, and a v18 semantic peer keeps ordinary document editing
+/// with no terminal surface at all. This is the first bump to gate in
+/// BOTH directions at once, which is why criterion 28 pins the two
+/// send filters independently.
+pub const PROTOCOL_VERSION: u32 = 19;
 
 /// T M10.5: the set of protocol versions a v1.0 binary accepts on
 /// the wire. v0.1 binaries only accepted `[1]`; v1.0 binaries accept
@@ -1540,7 +1622,13 @@ pub const PROTOCOL_VERSION: u32 = 18;
 ///
 /// Q#SL7: extended to `[6, ..., 18]`.
 /// [`InstanceMessage::StatuslineSegments`] is additive and daemon-gated.
-pub const SUPPORTED_PROTOCOL_VERSIONS: &[u32] = &[6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18];
+///
+/// Vterm Stage 3: extended to `[6, ..., 19]`. The terminal family is
+/// additive in both directions — `TerminalFrame` is daemon-gated,
+/// `TerminalResize` / `TerminalPointer` are frontend-gated — so v18 and
+/// v19 binaries interoperate with terminal traffic simply absent.
+pub const SUPPORTED_PROTOCOL_VERSIONS: &[u32] =
+    &[6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
 
 /// T M10.5: predicate for the handshake check. Returns `true` if
 /// `peer_version` is in [`SUPPORTED_PROTOCOL_VERSIONS`].
diff --git a/pmacs-protocol/src/terminal.rs b/pmacs-protocol/src/terminal.rs
new file mode 100644
index 0000000..8f094d7
--- /dev/null
+++ b/pmacs-protocol/src/terminal.rs
@@ -0,0 +1,1010 @@
+//! Terminal wire types (Vterm Stage 3, protocol v19).
+//!
+//! A terminal is inherently a cell protocol: its identity buffer is an
+//! empty CRDT anchor, so a semantic frontend that receives only
+//! `BufferSnapshot` has nothing to draw. [`TerminalFrame`] carries the
+//! complete visible grid instead — cells, cursor, per-view selection and
+//! scroll state, and sanitized process metadata.
+//!
+//! Every limit needed to validate a frame lives here rather than in the
+//! `pmacs` crate, so the daemon's pre-emission check and a frontend's
+//! post-decode check run the SAME policy. [`TerminalFrame::validate`] is
+//! that single structural policy. A second implementation of these rules
+//! in a frontend is a bug, not a convenience.
+//!
+//! This module owns the crate's only `unicode-width` use: glyph column
+//! width and wide-continuation topology cannot be checked without it.
+
+use crate::cell::{Cell, CellCoord, CellSize, Glyph};
+use crate::ids::BufferId;
+
+use unicode_width::{UnicodeWidthChar, UnicodeWidthStr};
+
+// ---------------------------------------------------------------------------
+// Shared limits
+// ---------------------------------------------------------------------------
+
+/// Maximum terminal rows accepted at creation, resize, or on the wire.
+pub const MAX_TERMINAL_ROWS: u16 = 512;
+
+/// Maximum terminal columns accepted at creation, resize, or on the wire.
+pub const MAX_TERMINAL_COLS: u16 = 512;
+
+/// Maximum visible terminal cells accepted at creation, resize, or on
+/// the wire.
+pub const MAX_TERMINAL_VISIBLE_CELLS: usize = 262_144;
+
+/// Maximum UTF-8 bytes retained in one terminal grapheme cluster.
+pub const MAX_TERMINAL_GRAPHEME_BYTES: usize = 256;
+
+/// Shared cap for terminal title and process-outcome metadata.
+pub const MAX_TERMINAL_METADATA_BYTES: usize = 1_024;
+
+/// Aggregate cap on glyph bytes carried by one [`TerminalFrame`].
+///
+/// The visible-cell bound alone does not bound a frame's encoded size:
+/// every cell may legally carry a [`MAX_TERMINAL_GRAPHEME_BYTES`]
+/// cluster, and `262_144 * 256` is 64 MiB — four times the transport's
+/// [`crate::MAX_FRAME_BYTES`]. Raising the transport cap would widen the
+/// allocation ceiling for every pre-handshake and established message on
+/// every connection, so v19 bounds the terminal payload instead. The
+/// protocol test `maximum_legal_terminal_frame_encodes_below_the_transport_cap`
+/// measures the largest legal frame this bound admits and pins it below
+/// the unchanged 16 MiB cap.
+pub const MAX_TERMINAL_FRAME_GLYPH_BYTES: usize = 8 * 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// Payload types
+// ---------------------------------------------------------------------------
+
+/// Process outcome published with a terminal frame.
+///
+/// `Signaled` and `Crashed` text is sanitized metadata subject to
+/// [`MAX_TERMINAL_METADATA_BYTES`] and the control-character rule; it is
+/// display text, never a host control effect.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize)]
+pub enum TerminalProcessState {
+    /// Child is running, or termination has only been requested.
+    Running,
+    /// Child exited with a status code.
+    Exited(i32),
+    /// Child was terminated by a sanitized symbolic signal.
+    Signaled(String),
+    /// Supervision failed after the session was published.
+    Crashed(String),
+}
+
+/// One selected span on one visible terminal row.
+///
+/// `start_col` is inclusive, `end_col` exclusive. A frame carries at most
+/// one span per row, in strictly increasing row order.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct TerminalSelectionSpan {
+    /// Visible row.
+    pub row: u32,
+    /// Inclusive starting column.
+    pub start_col: u32,
+    /// Exclusive ending column.
+    pub end_col: u32,
+}
+
+/// A complete visible terminal grid for one frontend/window view.
+///
+/// This is a whole-grid replacement, never a delta. Empty is NOT a clear
+/// sentinel: valid dimensions are nonzero and `cells.len()` equals the
+/// checked area exactly, so a receiver that decodes a valid frame always
+/// has a complete picture.
+///
+/// `screen_generation` describes the published screen/title generation
+/// only. Selection, scroll, viewport, and process state change WITHOUT
+/// advancing it, so a producer must compare the complete ordered payload
+/// — not that counter — when deciding whether to send.
+#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct TerminalFrame {
+    /// Identity buffer whose session this frame projects.
+    pub buffer_id: BufferId,
+    /// Visible grid dimensions in cells.
+    pub size: CellSize,
+    /// Row-major visible cells; exactly `size.area()` entries.
+    pub cells: Vec<Cell>,
+    /// Visible child cursor, or `None` when hidden.
+    pub cursor: Option<CellCoord>,
+    /// Sanitized child title.
+    pub title: Option<String>,
+    /// Published terminal screen/title generation.
+    pub screen_generation: u64,
+    /// Per-row selection spans, strictly increasing by row.
+    pub selection: Vec<TerminalSelectionSpan>,
+    /// Physical retained rows between this viewport and the live tail.
+    pub scroll_offset: u32,
+    /// Whether this view reaches the live tail; always `scroll_offset == 0`.
+    pub at_bottom: bool,
+    /// Operating-system process id for this session generation.
+    pub pid: u32,
+    /// Latest observed process state.
+    pub process: TerminalProcessState,
+}
+
+/// Why a [`TerminalFrame`] is not structurally valid.
+///
+/// Validation is atomic: the frame is rejected whole. A receiver retains
+/// its previous valid frame rather than applying any part of this one.
+#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
+pub enum TerminalFrameError {
+    /// Rows or columns are zero or above the shared bounds.
+    #[error("terminal size {rows}x{cols} is outside 1..={max_rows}x1..={max_cols}")]
+    Size {
+        /// Declared rows.
+        rows: u32,
+        /// Declared columns.
+        cols: u32,
+        /// Shared row bound.
+        max_rows: u32,
+        /// Shared column bound.
+        max_cols: u32,
+    },
+    /// The checked area exceeds the shared visible-cell bound.
+    #[error("terminal area {area} exceeds the visible-cell bound {max}")]
+    Area {
+        /// Checked `rows * cols`.
+        area: usize,
+        /// Shared visible-cell bound.
+        max: usize,
+    },
+    /// `cells.len()` disagrees with the declared area.
+    #[error("terminal frame carries {actual} cells for a {expected}-cell area")]
+    CellCount {
+        /// Declared area.
+        expected: usize,
+        /// Supplied cell count.
+        actual: usize,
+    },
+    /// The cursor lies outside the declared grid.
+    #[error("terminal cursor ({row},{col}) is outside the {rows}x{cols} grid")]
+    Cursor {
+        /// Cursor row.
+        row: u32,
+        /// Cursor column.
+        col: u32,
+        /// Declared rows.
+        rows: u32,
+        /// Declared columns.
+        cols: u32,
+    },
+    /// Title or process metadata is too long or carries control characters.
+    #[error("terminal {field} metadata is invalid: {reason}")]
+    Metadata {
+        /// Which metadata field failed.
+        field: &'static str,
+        /// Why it failed.
+        reason: &'static str,
+    },
+    /// A cell's glyph is not a legal terminal glyph.
+    #[error("terminal cell {index} has an invalid glyph: {reason}")]
+    Glyph {
+        /// Row-major cell index.
+        index: usize,
+        /// Why the glyph failed.
+        reason: &'static str,
+    },
+    /// A cell carries a frontend attachment, which terminals never use.
+    #[error("terminal cell {index} carries an attachment")]
+    Attachment {
+        /// Row-major cell index.
+        index: usize,
+    },
+    /// Aggregate glyph bytes exceed [`MAX_TERMINAL_FRAME_GLYPH_BYTES`].
+    #[error("terminal frame glyph bytes exceed the aggregate bound {max}")]
+    GlyphBudget {
+        /// Shared aggregate bound.
+        max: usize,
+    },
+    /// A selection span is empty, out of order, duplicated, or out of bounds.
+    #[error("terminal selection span {index} is invalid: {reason}")]
+    Selection {
+        /// Index into `selection`.
+        index: usize,
+        /// Why the span failed.
+        reason: &'static str,
+    },
+    /// `at_bottom` disagrees with `scroll_offset == 0`.
+    #[error("terminal at_bottom {at_bottom} disagrees with scroll_offset {scroll_offset}")]
+    BottomState {
+        /// Declared bottom state.
+        at_bottom: bool,
+        /// Declared scroll offset.
+        scroll_offset: u32,
+    },
+}
+
+impl TerminalFrame {
+    /// Check every structural rule a terminal frame must satisfy.
+    ///
+    /// This is the single policy used by the daemon before emission and
+    /// by a frontend after decode. It is pure: a rejected frame mutates
+    /// nothing, so callers get atomic rejection for free.
+    pub fn validate(&self) -> Result<(), TerminalFrameError> {
+        let area = self.checked_area()?;
+        if self.cells.len() != area {
+            return Err(TerminalFrameError::CellCount {
+                expected: area,
+                actual: self.cells.len(),
+            });
+        }
+        if let Some(cursor) = self.cursor
+            && (cursor.row >= self.size.rows || cursor.col >= self.size.cols)
+        {
+            return Err(TerminalFrameError::Cursor {
+                row: cursor.row,
+                col: cursor.col,
+                rows: self.size.rows,
+                cols: self.size.cols,
+            });
+        }
+        if let Some(title) = &self.title {
+            validate_metadata("title", title)?;
+        }
+        match &self.process {
+            TerminalProcessState::Signaled(text) => validate_metadata("signal", text)?,
+            TerminalProcessState::Crashed(text) => validate_metadata("crash", text)?,
+            TerminalProcessState::Running | TerminalProcessState::Exited(_) => {}
+        }
+        self.validate_cells()?;
+        self.validate_selection()?;
+        if self.at_bottom != (self.scroll_offset == 0) {
+            return Err(TerminalFrameError::BottomState {
+                at_bottom: self.at_bottom,
+                scroll_offset: self.scroll_offset,
+            });
+        }
+        Ok(())
+    }
+
+    /// Declared cell area, checked against both shared bounds.
+    fn checked_area(&self) -> Result<usize, TerminalFrameError> {
+        let rows = self.size.rows;
+        let cols = self.size.cols;
+        if rows == 0
+            || cols == 0
+            || rows > u32::from(MAX_TERMINAL_ROWS)
+            || cols > u32::from(MAX_TERMINAL_COLS)
+        {
+            return Err(TerminalFrameError::Size {
+                rows,
+                cols,
+                max_rows: u32::from(MAX_TERMINAL_ROWS),
+                max_cols: u32::from(MAX_TERMINAL_COLS),
+            });
+        }
+        // Both factors are bounded above by 512, so the product cannot
+        // overflow; `checked_mul` keeps that an assertion rather than an
+        // assumption a later bound change could quietly break.
+        let area = rows
+            .checked_mul(cols)
+            .and_then(|area| usize::try_from(area).ok())
+            .ok_or(TerminalFrameError::Area {
+                area: usize::MAX,
+                max: MAX_TERMINAL_VISIBLE_CELLS,
+            })?;
+        if area > MAX_TERMINAL_VISIBLE_CELLS {
+            return Err(TerminalFrameError::Area {
+                area,
+                max: MAX_TERMINAL_VISIBLE_CELLS,
+            });
+        }
+        Ok(area)
+    }
+
+    /// Glyph legality, wide-continuation topology, and the glyph budget.
+    fn validate_cells(&self) -> Result<(), TerminalFrameError> {
+        let cols = self.size.cols as usize;
+        let mut glyph_bytes = 0usize;
+        // Columns still owed to the preceding wide lead on this row.
+        let mut pending_continuation = false;
+        for (index, cell) in self.cells.iter().enumerate() {
+            if cell.attachment.is_some() {
+                return Err(TerminalFrameError::Attachment { index });
+            }
+            let col = index % cols;
+            if col == 0 && pending_continuation {
+                // A wide lead in the final column would have to be
+                // completed on the next row, which is not a footprint a
+                // terminal grid can express.
+                return Err(TerminalFrameError::Glyph {
+                    index: index - 1,
+                    reason: "wide glyph has no continuation column on its row",
+                });
+            }
+            match &cell.glyph {
+                Glyph::Continuation => {
+                    if !pending_continuation {
+                        return Err(TerminalFrameError::Glyph {
+                            index,
+                            reason: "continuation without a preceding wide glyph",
+                        });
+                    }
+                    pending_continuation = false;
+                }
+                Glyph::Char(ch) => {
+                    if pending_continuation {
+                        return Err(TerminalFrameError::Glyph {
+                            index,
+                            reason: "wide glyph is not followed by its continuation",
+                        });
+                    }
+                    let width = char_display_width(*ch).ok_or(TerminalFrameError::Glyph {
+                        index,
+                        reason: "glyph is a control or zero-width character",
+                    })?;
+                    glyph_bytes = add_glyph_bytes(glyph_bytes, ch.len_utf8())?;
+                    pending_continuation = width == 2;
+                }
+                Glyph::Cluster(bytes) => {
+                    if pending_continuation {
+                        return Err(TerminalFrameError::Glyph {
+                            index,
+                            reason: "wide glyph is not followed by its continuation",
+                        });
+                    }
+                    let width = cluster_display_width(bytes, index)?;
+                    glyph_bytes = add_glyph_bytes(glyph_bytes, bytes.len())?;
+                    pending_continuation = width == 2;
+                }
+            }
+        }
+        if pending_continuation {
+            return Err(TerminalFrameError::Glyph {
+                index: self.cells.len() - 1,
+                reason: "wide glyph has no continuation column on its row",
+            });
+        }
+        Ok(())
+    }
+
+    /// One nonempty in-bounds span per row, strictly increasing by row.
+    fn validate_selection(&self) -> Result<(), TerminalFrameError> {
+        let mut previous_row: Option<u32> = None;
+        for (index, span) in self.selection.iter().enumerate() {
+            if span.row >= self.size.rows {
+                return Err(TerminalFrameError::Selection {
+                    index,
+                    reason: "row is outside the frame",
+                });
+            }
+            if span.start_col >= span.end_col {
+                return Err(TerminalFrameError::Selection {
+                    index,
+                    reason: "span is empty or reversed",
+                });
+            }
+            if span.end_col > self.size.cols {
+                return Err(TerminalFrameError::Selection {
+                    index,
+                    reason: "span extends past the final column",
+                });
+            }
+            if previous_row.is_some_and(|previous| previous >= span.row) {
+                return Err(TerminalFrameError::Selection {
+                    index,
+                    reason: "rows are not strictly increasing",
+                });
+            }
+            previous_row = Some(span.row);
+        }
+        Ok(())
+    }
+}
+
+/// Column width of a leading `Char` glyph, or `None` when it cannot lead.
+fn char_display_width(ch: char) -> Option<usize> {
+    if ch.is_control() {
+        return None;
+    }
+    match UnicodeWidthChar::width(ch) {
+        Some(1) => Some(1),
+        Some(2) => Some(2),
+        _ => None,
+    }
+}
+
+/// Column width of a leading `Cluster` glyph.
+///
+/// Width is clamped into `1..=2` exactly as the terminal screen clamps it
+/// when it writes the cluster: a base plus combining marks may measure
+/// wider than two columns, and the screen occupies two. Clamping in one
+/// place and measuring in another is how a frame that renders correctly
+/// gets rejected on the wire.
+fn cluster_display_width(bytes: &[u8], index: usize) -> Result<usize, TerminalFrameError> {
+    if bytes.is_empty() {
+        return Err(TerminalFrameError::Glyph {
+            index,
+            reason: "cluster is empty",
+        });
+    }
+    if bytes.len() > MAX_TERMINAL_GRAPHEME_BYTES {
+        return Err(TerminalFrameError::Glyph {
+            index,
+            reason: "cluster exceeds the per-cluster byte limit",
+        });
+    }
+    let text = std::str::from_utf8(bytes).map_err(|_| TerminalFrameError::Glyph {
+        index,
+        reason: "cluster is not valid UTF-8",
+    })?;
+    if text.chars().any(char::is_control) {
+        return Err(TerminalFrameError::Glyph {
+            index,
+            reason: "cluster carries a control character",
+        });
+    }
+    let width = UnicodeWidthStr::width(text);
+    if width == 0 {
+        return Err(TerminalFrameError::Glyph {
+            index,
+            reason: "cluster occupies no columns",
+        });
+    }
+    Ok(width.min(2))
+}
+
+/// Accumulate glyph bytes under the aggregate bound with checked addition.
+fn add_glyph_bytes(total: usize, add: usize) -> Result<usize, TerminalFrameError> {
+    let next = total
+        .checked_add(add)
+        .ok_or(TerminalFrameError::GlyphBudget {
+            max: MAX_TERMINAL_FRAME_GLYPH_BYTES,
+        })?;
+    if next > MAX_TERMINAL_FRAME_GLYPH_BYTES {
+        return Err(TerminalFrameError::GlyphBudget {
+            max: MAX_TERMINAL_FRAME_GLYPH_BYTES,
+        });
+    }
+    Ok(next)
+}
+
+/// Length and control-character rules shared by title and process text.
+fn validate_metadata(field: &'static str, text: &str) -> Result<(), TerminalFrameError> {
+    if text.len() > MAX_TERMINAL_METADATA_BYTES {
+        return Err(TerminalFrameError::Metadata {
+            field,
+            reason: "exceeds the metadata byte limit",
+        });
+    }
+    if text.chars().any(char::is_control) {
+        return Err(TerminalFrameError::Metadata {
+            field,
+            reason: "carries a control character",
+        });
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cell::{Color, Style, UnderlineStyle};
+    use crate::message::InstanceMessage;
+    use crate::transport::MAX_FRAME_BYTES;
+
+    /// The style whose postcard encoding is as long as a legal `Style`
+    /// gets: three truecolor components, a non-`None` underline, and
+    /// every boolean set.
+    fn maximal_style() -> Style {
+        Style {
+            fg: Color::Rgb(0xff, 0xee, 0xdd),
+            bg: Color::Rgb(0x11, 0x22, 0x33),
+            bold: true,
+            italic: true,
+            underline: UnderlineStyle::Dashed,
+            reverse: true,
+            underline_color: Color::Rgb(0x44, 0x55, 0x66),
+        }
+    }
+
+    /// A legal one-column cluster of exactly `len` UTF-8 bytes.
+    ///
+    /// A combining mark is two bytes, so parity comes from the base:
+    /// a one-byte space for odd lengths, a two-byte `é` for even ones.
+    /// Width stays 1 no matter how many marks are appended.
+    fn cluster_of_len(len: usize) -> Vec<u8> {
+        assert!((1..=MAX_TERMINAL_GRAPHEME_BYTES).contains(&len));
+        let mut text = String::with_capacity(len);
+        if len % 2 == 1 {
+            text.push(' ');
+        } else {
+            text.push('\u{e9}');
+        }
+        while text.len() < len {
+            text.push('\u{301}');
+        }
+        assert_eq!(text.len(), len);
+        assert_eq!(UnicodeWidthStr::width(text.as_str()), 1);
+        text.into_bytes()
+    }
+
+    fn cell_with(glyph: Glyph) -> Cell {
+        Cell {
+            glyph,
+            style: maximal_style(),
+            attachment: None,
+        }
+    }
+
+    /// A minimal valid frame: `rows * cols` single-space cells.
+    fn frame(rows: u32, cols: u32) -> TerminalFrame {
+        let area = (rows * cols) as usize;
+        TerminalFrame {
+            buffer_id: BufferId::from_raw(7),
+            size: CellSize::new(rows, cols),
+            cells: vec![cell_with(Glyph::Char(' ')); area],
+            cursor: Some(CellCoord::new(0, 0)),
+            title: Some("sh".into()),
+            screen_generation: 3,
+            selection: Vec::new(),
+            scroll_offset: 0,
+            at_bottom: true,
+            pid: 4321,
+            process: TerminalProcessState::Running,
+        }
+    }
+
+    #[test]
+    fn exact_shared_boundaries_are_accepted() {
+        let mut f = frame(2, 4);
+        // A wide lead plus its continuation, a maximal-length cluster,
+        // and a maximal metadata string are all exactly legal.
+        f.cells[0] = cell_with(Glyph::Char('\u{4e00}'));
+        f.cells[1] = cell_with(Glyph::Continuation);
+        f.cells[2] = cell_with(Glyph::Cluster(
+            cluster_of_len(MAX_TERMINAL_GRAPHEME_BYTES).into_boxed_slice(),
+        ));
+        f.title = Some("t".repeat(MAX_TERMINAL_METADATA_BYTES));
+        f.process = TerminalProcessState::Signaled("s".repeat(MAX_TERMINAL_METADATA_BYTES));
+        f.cursor = Some(CellCoord::new(1, 3));
+        f.selection = vec![
+            TerminalSelectionSpan {
+                row: 0,
+                start_col: 0,
+                end_col: 4,
+            },
+            TerminalSelectionSpan {
+                row: 1,
+                start_col: 3,
+                end_col: 4,
+            },
+        ];
+        assert_eq!(f.validate(), Ok(()));
+    }
+
+    #[test]
+    #[allow(clippy::too_many_lines, reason = "one case per structural rule")]
+    fn every_structural_violation_is_rejected() {
+        // Each case mutates one axis of an otherwise valid frame, so a
+        // failure names exactly the rule that stopped enforcing.
+        let zero_rows = {
+            let mut f = frame(1, 1);
+            f.size = CellSize::new(0, 1);
+            f
+        };
+        assert!(matches!(
+            zero_rows.validate(),
+            Err(TerminalFrameError::Size { .. })
+        ));
+
+        let over_rows = {
+            let mut f = frame(1, 1);
+            f.size = CellSize::new(u32::from(MAX_TERMINAL_ROWS) + 1, 1);
+            f
+        };
+        assert!(matches!(
+            over_rows.validate(),
+            Err(TerminalFrameError::Size { .. })
+        ));
+
+        let over_area = {
+            let mut f = frame(1, 1);
+            f.size = CellSize::new(u32::from(MAX_TERMINAL_ROWS), u32::from(MAX_TERMINAL_COLS));
+            f
+        };
+        // 512 x 512 is exactly the visible-cell bound, so this frame
+        // fails on its cell count, not its area — the area bound is
+        // reached only if a later limit change makes them disagree.
+        assert!(matches!(
+            over_area.validate(),
+            Err(TerminalFrameError::CellCount { .. })
+        ));
+
+        let bad_count = {
+            let mut f = frame(2, 2);
+            f.cells.pop();
+            f
+        };
+        assert!(matches!(
+            bad_count.validate(),
+            Err(TerminalFrameError::CellCount {
+                expected: 4,
+                actual: 3
+            })
+        ));
+
+        let bad_cursor = {
+            let mut f = frame(2, 2);
+            f.cursor = Some(CellCoord::new(2, 0));
+            f
+        };
+        assert!(matches!(
+            bad_cursor.validate(),
+            Err(TerminalFrameError::Cursor { .. })
+        ));
+
+        let long_title = {
+            let mut f = frame(1, 1);
+            f.title = Some("t".repeat(MAX_TERMINAL_METADATA_BYTES + 1));
+            f
+        };
+        assert!(matches!(
+            long_title.validate(),
+            Err(TerminalFrameError::Metadata { field: "title", .. })
+        ));
+
+        let control_title = {
+            let mut f = frame(1, 1);
+            f.title = Some("ok\u{7}".into());
+            f
+        };
+        assert!(matches!(
+            control_title.validate(),
+            Err(TerminalFrameError::Metadata { field: "title", .. })
+        ));
+
+        let long_process = {
+            let mut f = frame(1, 1);
+            f.process = TerminalProcessState::Crashed("c".repeat(MAX_TERMINAL_METADATA_BYTES + 1));
+            f
+        };
+        assert!(matches!(
+            long_process.validate(),
+            Err(TerminalFrameError::Metadata { field: "crash", .. })
+        ));
+
+        let control_glyph = {
+            let mut f = frame(1, 1);
+            f.cells[0] = cell_with(Glyph::Char('\u{7}'));
+            f
+        };
+        assert!(matches!(
+            control_glyph.validate(),
+            Err(TerminalFrameError::Glyph { index: 0, .. })
+        ));
+
+        let malformed_cluster = {
+            let mut f = frame(1, 1);
+            f.cells[0] = cell_with(Glyph::Cluster(vec![0xff, 0xfe].into_boxed_slice()));
+            f
+        };
+        assert!(matches!(
+            malformed_cluster.validate(),
+            Err(TerminalFrameError::Glyph { index: 0, .. })
+        ));
+
+        let empty_cluster = {
+            let mut f = frame(1, 1);
+            f.cells[0] = cell_with(Glyph::Cluster(Vec::new().into_boxed_slice()));
+            f
+        };
+        assert!(matches!(
+            empty_cluster.validate(),
+            Err(TerminalFrameError::Glyph { index: 0, .. })
+        ));
+
+        let overlong_cluster = {
+            let mut f = frame(1, 1);
+            let mut bytes = cluster_of_len(MAX_TERMINAL_GRAPHEME_BYTES);
+            bytes.extend_from_slice("\u{301}".as_bytes());
+            f.cells[0] = cell_with(Glyph::Cluster(bytes.into_boxed_slice()));
+            f
+        };
+        assert!(matches!(
+            overlong_cluster.validate(),
+            Err(TerminalFrameError::Glyph { index: 0, .. })
+        ));
+
+        let orphan_continuation = {
+            let mut f = frame(1, 2);
+            f.cells[1] = cell_with(Glyph::Continuation);
+            f.cells[0] = cell_with(Glyph::Char('a'));
+            f
+        };
+        assert!(matches!(
+            orphan_continuation.validate(),
+            Err(TerminalFrameError::Glyph { index: 1, .. })
+        ));
+
+        let missing_continuation = {
+            let mut f = frame(1, 2);
+            f.cells[0] = cell_with(Glyph::Char('\u{4e00}'));
+            f
+        };
+        assert!(matches!(
+            missing_continuation.validate(),
+            Err(TerminalFrameError::Glyph { index: 1, .. })
+        ));
+
+        // A wide lead in the final column has nowhere to put its
+        // continuation: the next cell belongs to the next row.
+        let wide_at_row_end = {
+            let mut f = frame(2, 2);
+            f.cells[1] = cell_with(Glyph::Char('\u{4e00}'));
+            f
+        };
+        assert!(matches!(
+            wide_at_row_end.validate(),
+            Err(TerminalFrameError::Glyph { index: 1, .. })
+        ));
+
+        let attachment = {
+            let mut f = frame(1, 1);
+            f.cells[0].attachment = Some(crate::cell::Attachment::ImageCell {
+                image_id: 1,
+                sub_x: 0,
+                sub_y: 0,
+            });
+            f
+        };
+        assert!(matches!(
+            attachment.validate(),
+            Err(TerminalFrameError::Attachment { index: 0 })
+        ));
+
+        let reversed_span = {
+            let mut f = frame(1, 4);
+            f.selection = vec![TerminalSelectionSpan {
+                row: 0,
+                start_col: 3,
+                end_col: 1,
+            }];
+            f
+        };
+        assert!(matches!(
+            reversed_span.validate(),
+            Err(TerminalFrameError::Selection { index: 0, .. })
+        ));
+
+        let empty_span = {
+            let mut f = frame(1, 4);
+            f.selection = vec![TerminalSelectionSpan {
+                row: 0,
+                start_col: 2,
+                end_col: 2,
+            }];
+            f
+        };
+        assert!(matches!(
+            empty_span.validate(),
+            Err(TerminalFrameError::Selection { index: 0, .. })
+        ));
+
+        let duplicate_row = {
+            let mut f = frame(2, 4);
+            f.selection = vec![
+                TerminalSelectionSpan {
+                    row: 1,
+                    start_col: 0,
+                    end_col: 1,
+                },
+                TerminalSelectionSpan {
+                    row: 1,
+                    start_col: 1,
+                    end_col: 2,
+                },
+            ];
+            f
+        };
+        assert!(matches!(
+            duplicate_row.validate(),
+            Err(TerminalFrameError::Selection { index: 1, .. })
+        ));
+
+        let out_of_order = {
+            let mut f = frame(2, 4);
+            f.selection = vec![
+                TerminalSelectionSpan {
+                    row: 1,
+                    start_col: 0,
+                    end_col: 1,
+                },
+                TerminalSelectionSpan {
+                    row: 0,
+                    start_col: 0,
+                    end_col: 1,
+                },
+            ];
+            f
+        };
+        assert!(matches!(
+            out_of_order.validate(),
+            Err(TerminalFrameError::Selection { index: 1, .. })
+        ));
+
+        let span_past_end = {
+            let mut f = frame(1, 4);
+            f.selection = vec![TerminalSelectionSpan {
+                row: 0,
+                start_col: 0,
+                end_col: 5,
+            }];
+            f
+        };
+        assert!(matches!(
+            span_past_end.validate(),
+            Err(TerminalFrameError::Selection { index: 0, .. })
+        ));
+
+        let span_off_frame = {
+            let mut f = frame(1, 4);
+            f.selection = vec![TerminalSelectionSpan {
+                row: 1,
+                start_col: 0,
+                end_col: 1,
+            }];
+            f
+        };
+        assert!(matches!(
+            span_off_frame.validate(),
+            Err(TerminalFrameError::Selection { index: 0, .. })
+        ));
+
+        let inconsistent_bottom = {
+            let mut f = frame(1, 1);
+            f.scroll_offset = 4;
+            f.at_bottom = true;
+            f
+        };
+        assert!(matches!(
+            inconsistent_bottom.validate(),
+            Err(TerminalFrameError::BottomState { .. })
+        ));
+
+        let inconsistent_top = {
+            let mut f = frame(1, 1);
+            f.scroll_offset = 0;
+            f.at_bottom = false;
+            f
+        };
+        assert!(matches!(
+            inconsistent_top.validate(),
+            Err(TerminalFrameError::BottomState { .. })
+        ));
+    }
+
+    #[test]
+    fn aggregate_glyph_budget_accepts_the_exact_bound_and_rejects_one_byte_over() {
+        // Reaching the aggregate bound exactly requires the whole legal
+        // grid — no smaller frame can spend 8 MiB of glyph — so the
+        // boundary pair is built once and asserted in both directions.
+        let (exact, over) = budget_boundary_frames();
+        assert_eq!(exact.validate(), Ok(()));
+        assert_eq!(
+            over.validate(),
+            Err(TerminalFrameError::GlyphBudget {
+                max: MAX_TERMINAL_FRAME_GLYPH_BYTES
+            })
+        );
+    }
+
+    /// The exact-budget frame and its one-byte-over twin.
+    ///
+    /// Cluster lengths are chosen to maximize serialized length-prefix
+    /// overhead: postcard spends two bytes on any length `>= 128`, so as
+    /// many cells as the budget allows carry a 128-byte cluster and the
+    /// rest carry the one-byte minimum, rather than packing the budget
+    /// into a few maximal clusters that would each cost one prefix.
+    fn budget_boundary_frames() -> (TerminalFrame, TerminalFrame) {
+        /// Shortest cluster length postcard encodes with a two-byte
+        /// length prefix.
+        const WIDE_PREFIX_LEN: usize = 128;
+        let rows = u32::from(MAX_TERMINAL_ROWS);
+        let cols = u32::from(MAX_TERMINAL_COLS);
+        let area = (rows * cols) as usize;
+        assert_eq!(area, MAX_TERMINAL_VISIBLE_CELLS);
+
+        let spare = MAX_TERMINAL_FRAME_GLYPH_BYTES - area;
+        let wide_cells = spare / (WIDE_PREFIX_LEN - 1);
+        let remainder = spare % (WIDE_PREFIX_LEN - 1);
+        assert!(wide_cells + usize::from(remainder > 0) <= area);
+
+        let wide = cluster_of_len(WIDE_PREFIX_LEN).into_boxed_slice();
+        let single = cluster_of_len(1).into_boxed_slice();
+        let mut cells = Vec::with_capacity(area);
+        for index in 0..area {
+            let glyph = if index < wide_cells {
+                Glyph::Cluster(wide.clone())
+            } else if index == wide_cells && remainder > 0 {
+                Glyph::Cluster(cluster_of_len(remainder + 1).into_boxed_slice())
+            } else {
+                Glyph::Cluster(single.clone())
+            };
+            cells.push(cell_with(glyph));
+        }
+
+        let selection = (0..rows)
+            .map(|row| TerminalSelectionSpan {
+                row,
+                start_col: 0,
+                end_col: cols,
+            })
+            .collect();
+
+        let exact = TerminalFrame {
+            buffer_id: BufferId::from_raw(u64::MAX),
+            size: CellSize::new(rows, cols),
+            cells,
+            cursor: Some(CellCoord::new(rows - 1, cols - 1)),
+            title: Some("t".repeat(MAX_TERMINAL_METADATA_BYTES)),
+            screen_generation: u64::MAX,
+            selection,
+            scroll_offset: u32::MAX,
+            at_bottom: false,
+            pid: u32::MAX,
+            process: TerminalProcessState::Crashed("c".repeat(MAX_TERMINAL_METADATA_BYTES)),
+        };
+
+        let mut over = exact.clone();
+        // One more byte of glyph, nothing else changed.
+        let last = over.cells.len() - 1;
+        over.cells[last] = cell_with(Glyph::Cluster(cluster_of_len(3).into_boxed_slice()));
+
+        (exact, over)
+    }
+
+    #[test]
+    fn maximum_legal_terminal_frame_encodes_below_the_transport_cap() {
+        let (exact, _) = budget_boundary_frames();
+        assert_eq!(exact.validate(), Ok(()));
+
+        let mut glyph_bytes = 0usize;
+        for cell in &exact.cells {
+            glyph_bytes += match &cell.glyph {
+                Glyph::Char(ch) => ch.len_utf8(),
+                Glyph::Cluster(bytes) => bytes.len(),
+                Glyph::Continuation => 0,
+            };
+        }
+        assert_eq!(
+            glyph_bytes, MAX_TERMINAL_FRAME_GLYPH_BYTES,
+            "the measured fixture must spend the whole aggregate budget"
+        );
+
+        let msg = InstanceMessage::TerminalFrame(exact);
+        let bytes = postcard::to_allocvec(&msg).expect("encode");
+        assert!(
+            bytes.len() < MAX_FRAME_BYTES,
+            "largest legal terminal frame encodes to {} bytes, at or above the \
+             {MAX_FRAME_BYTES}-byte transport cap; the aggregate glyph bound no \
+             longer keeps terminal traffic inside the existing transport limit",
+            bytes.len()
+        );
+    }
+
+    #[test]
+    fn frames_round_trip_through_postcard() {
+        let mut f = frame(3, 5);
+        f.cells[0] = cell_with(Glyph::Char('\u{4e00}'));
+        f.cells[1] = cell_with(Glyph::Continuation);
+        f.cells[2] = cell_with(Glyph::Cluster(cluster_of_len(9).into_boxed_slice()));
+        f.selection = vec![TerminalSelectionSpan {
+            row: 2,
+            start_col: 1,
+            end_col: 4,
+        }];
+        f.scroll_offset = 6;
+        f.at_bottom = false;
+        f.process = TerminalProcessState::Exited(-1);
+        assert_eq!(f.validate(), Ok(()));
+
+        let msg = InstanceMessage::TerminalFrame(f);
+        let bytes = postcard::to_allocvec(&msg).expect("encode");
+        let decoded: InstanceMessage = postcard::from_bytes(&bytes).expect("decode");
+        assert_eq!(decoded, msg);
+    }
+}
diff --git a/src/daemon.rs b/src/daemon.rs
index f153625..8ae640f 100644
--- a/src/daemon.rs
+++ b/src/daemon.rs
@@ -799,6 +799,14 @@ fn peer_accepts_statusline_message(protocol_version: u32, message: &InstanceMess
     protocol_version >= 18 || !matches!(message, InstanceMessage::StatuslineSegments { .. })
 }
 
+/// The same belt-and-braces write-loop gate for the additive
+/// protocol-v19 terminal frame. The semantic producer skips construction
+/// for an older peer; this filter independently prevents an unknown
+/// discriminant reaching one, so neither gate alone is load-bearing.
+fn peer_accepts_terminal_message(protocol_version: u32, message: &InstanceMessage) -> bool {
+    protocol_version >= 19 || !matches!(message, InstanceMessage::TerminalFrame(_))
+}
+
 /// T M10.8 — dispatcher loop. The single thread that owns the editor.
 ///
 /// All attached frontends' inputs arrive via the `dispatcher_rx`
@@ -1078,11 +1086,24 @@ fn dispatcher_loop(
                 render_state.render_frame(editor, *fid, &terminal_snapshots, &other_presences)
             };
 
+            // Vterm Stage 3 — a semantic frontend showing a terminal has
+            // no document cursor: the identity buffer is empty, so both
+            // presence and `CursorByte` would describe byte 0 of a
+            // buffer with no text, painting a phantom peer caret over
+            // the cell grid.
+            let terminal_mode = semantic_states
+                .get(fid)
+                .is_some_and(crate::semantic_render::SemanticRenderState::in_terminal_mode);
+
             // T M10.6 per-frontend presence sweep. The snapshot is
             // computed from this frontend's view; the sweep then
             // produces broadcasts to OTHER multi-frontend recipients.
-            let snapshot = build_presence_snapshot(editor, *fid);
-            let broadcasts = session_registry.sweep(&[(*fid, snapshot)]);
+            let broadcasts = if terminal_mode {
+                Vec::new()
+            } else {
+                let snapshot = build_presence_snapshot(editor, *fid);
+                session_registry.sweep(&[(*fid, snapshot)])
+            };
 
             // T M11.6 — DispatchIdle signal. `crdt_replica` frontends
             // gate their optimistic-apply path on this; we ship it
@@ -1217,6 +1238,14 @@ fn dispatcher_loop(
                     if !peer_knows_font_facts && matches!(msg, InstanceMessage::FontFacts { .. }) {
                         continue;
                     }
+                    // Vterm Stage 3 — TerminalFrame gated at v19. A v18
+                    // semantic peer keeps the empty identity snapshot and
+                    // no terminal surface; a v18 grid peer is unaffected
+                    // because it composes terminal windows into its own
+                    // CellDelta.
+                    if !peer_accepts_terminal_message(negotiated_protocol_version, msg) {
+                        continue;
+                    }
                     if !peer_accepts_statusline_message(negotiated_protocol_version, msg) {
                         continue;
                     }
@@ -1266,6 +1295,7 @@ fn dispatcher_loop(
                 // optimistic-apply path consumes byte_pos; the legacy
                 // paint path consumes the grid coord.
                 if !write_failed
+                    && !terminal_mode
                     && session_registry
                         .session_state(*fid)
                         .is_some_and(|s| s.negotiated_capabilities.crdt_replica)
@@ -1380,6 +1410,18 @@ fn dispatcher_loop(
             if let Some(size) = term_sizes.get(frontend_id).copied() {
                 editor.sync_terminal_layout(*frontend_id, size);
             }
+            // Vterm Stage 3 — the semantic twin, right beside the grid
+            // sync so both frontend kinds resize the screen before the
+            // next child-output drain. The frontend declared a CONTENT
+            // rectangle, so this consumes the size directly instead of
+            // running the TUI placement helper, which would subtract a
+            // modeline the GPU never drew.
+            if let Some((buffer_id, size)) = semantic_states
+                .get(frontend_id)
+                .and_then(crate::semantic_render::SemanticRenderState::terminal_viewport)
+            {
+                editor.sync_semantic_terminal_layout(*frontend_id, buffer_id, size);
+            }
         }
 
         // `tick_async` last: the M4.5 async bridge settles awaiters
@@ -1621,7 +1663,30 @@ fn handle_dispatcher_event(
                     // session never sends this; if one does, there is
                     // no `SemanticRenderState` to update and it is a
                     // benign no-op.
-                    if semantic_states.contains_key(&source) {
+                    // Vterm Stage 3 — a v19 frontend declares BOTH a
+                    // byte viewport and a terminal cell size after every
+                    // snapshot, because an empty terminal identity
+                    // snapshot does not announce itself as a terminal.
+                    // The daemon keeps only the declaration appropriate
+                    // to the authenticated source's ACTIVE buffer.
+                    //
+                    // Keying on the active buffer rather than the
+                    // declared one is load-bearing: `Viewport` also
+                    // ALIGNS the window to the buffer it names, so a
+                    // stale document viewport still in flight when a
+                    // command opens a terminal would drag the frontend
+                    // straight back off it. The declared buffer is
+                    // checked too — a terminal has no byte viewport to
+                    // honor from any direction.
+                    let terminal_context = {
+                        let manager = editor.terminal_manager.borrow();
+                        let core = editor.core.borrow();
+                        let active = core
+                            .active_window_for(source)
+                            .is_some_and(|window| manager.is_terminal(window.buffer_id));
+                        active || manager.is_terminal(buffer_id)
+                    };
+                    if semantic_states.contains_key(&source) && !terminal_context {
                         // Phase B (B1) — the Viewport declares *which
                         // buffer this frontend is displaying*. Align its
                         // editor window to that buffer so keyboard input
@@ -1637,6 +1702,47 @@ fn handle_dispatcher_event(
                         }
                     }
                 }
+                FrontendEvent::TerminalResize {
+                    buffer_id, size, ..
+                } => {
+                    // Vterm Stage 3 — the terminal half of the dual
+                    // declaration. Routed by the authenticated `source`;
+                    // the payload's `frontend_id` is never read.
+                    //
+                    // Recording the geometry is what lets a PASSIVE view
+                    // receive its own clipped/padded projection, so the
+                    // record happens for any accepted declaration. Only
+                    // the durable controller's declaration reaches the
+                    // shared PTY — a declaration never claims control.
+                    if semantic_states.contains_key(&source)
+                        && editor.semantic_terminal_declaration_is_active(source, buffer_id)
+                    {
+                        if let Some(sem) = semantic_states.get_mut(&source) {
+                            sem.set_terminal_viewport(buffer_id, size);
+                        }
+                        editor.sync_semantic_terminal_layout(source, buffer_id, size);
+                    }
+                }
+                FrontendEvent::TerminalPointer {
+                    buffer_id,
+                    coord,
+                    kind,
+                    mods,
+                    ..
+                } => {
+                    // Vterm Stage 3 — a terminal-cell gesture. The
+                    // adapter re-derives the window from the
+                    // authenticated source and checks the coordinate
+                    // against the geometry that source declared, so a
+                    // forged id, a stale buffer, a missing declaration,
+                    // or an out-of-bounds cell all drop before any view,
+                    // controller, selection, menu, or PTY mutation.
+                    if semantic_states.contains_key(&source) {
+                        editor.dispatch_semantic_terminal_pointer(
+                            source, buffer_id, coord, kind, mods,
+                        );
+                    }
+                }
                 FrontendEvent::Pointer {
                     buffer_id,
                     byte,
@@ -2653,6 +2759,18 @@ fn apply_event(
                 "pmacs daemon: FrontendEvent::MenuPointer from a grid session; dropping"
             );
         }
+        FrontendEvent::TerminalResize { .. } | FrontendEvent::TerminalPointer { .. } => {
+            // Vterm Stage 3 — the terminal declarations belong to
+            // semantic sessions and are routed by the authenticated
+            // source in `handle_dispatcher_event`. A grid session
+            // resizes its terminal through the Stage 2 layout path, so
+            // one arriving here is a protocol violation; drop it
+            // rather than letting a payload-trusted id reach a view.
+            eprintln!(
+                "pmacs daemon: terminal declaration from a grid session; dropping \
+                 (grid terminals resize through the Stage 2 layout path)"
+            );
+        }
     }
 }
 
@@ -2687,6 +2805,35 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn terminal_frame_write_gate_rejects_v18_independently() {
+        let frame = InstanceMessage::TerminalFrame(crate::terminal::TerminalFrame {
+            buffer_id: crate::buffer::BufferId::from_raw(2),
+            size: crate::cell::CellSize::new(1, 1),
+            cells: vec![crate::cell::Cell::default()],
+            cursor: None,
+            title: None,
+            screen_generation: 0,
+            selection: Vec::new(),
+            scroll_offset: 0,
+            at_bottom: true,
+            pid: 1,
+            process: crate::terminal::TerminalProcessState::Running,
+        });
+        assert!(!peer_accepts_terminal_message(18, &frame));
+        assert!(peer_accepts_terminal_message(19, &frame));
+        // The gate is variant-scoped: it must not silence anything else
+        // on an older wire.
+        assert!(peer_accepts_terminal_message(
+            18,
+            &InstanceMessage::StatuslineSegments {
+                buffer_id: crate::buffer::BufferId::from_raw(2),
+                left: Vec::new(),
+                right: Vec::new(),
+            }
+        ));
+    }
+
     #[test]
     fn build_identity_includes_version_and_uptime() {
         let s = DaemonState::new(Some("research".into()));
diff --git a/src/editor.rs b/src/editor.rs
index 38a8003..8c844f9 100644
--- a/src/editor.rs
+++ b/src/editor.rs
@@ -1122,6 +1122,155 @@ impl EditorState {
         }
     }
 
+    /// Resolve the exact terminal view a semantic frontend is showing.
+    ///
+    /// The window identity is DERIVED from the authenticated frontend,
+    /// never accepted from the wire: a semantic peer names only a
+    /// buffer, so a forged or stale `buffer_id` fails this check and
+    /// reaches no view, controller, or PTY. A window that has since
+    /// switched away also fails, which is what makes a pointer racing a
+    /// buffer switch a no-op instead of a gesture on the wrong buffer.
+    fn semantic_terminal_key(
+        &self,
+        frontend_id: FrontendId,
+        buffer_id: crate::buffer::BufferId,
+    ) -> Option<TerminalViewKey> {
+        let core = self.core.borrow();
+        let view = core.views.get(&frontend_id)?;
+        let window = core.windows.get(&view.active)?;
+        if window.buffer_id != buffer_id {
+            return None;
+        }
+        let key = TerminalViewKey::new(frontend_id, window.id, buffer_id);
+        self.terminal_manager
+            .borrow()
+            .is_terminal(buffer_id)
+            .then_some(key)
+    }
+
+    /// Whether `buffer_id` is the terminal an authenticated semantic
+    /// frontend is currently displaying.
+    ///
+    /// The daemon calls this before recording a terminal declaration so
+    /// a stale or forged buffer never becomes a frontend's projection
+    /// target — a declaration is only meaningful for the window the
+    /// sender actually has on screen.
+    #[must_use]
+    pub fn semantic_terminal_declaration_is_active(
+        &self,
+        frontend_id: FrontendId,
+        buffer_id: crate::buffer::BufferId,
+    ) -> bool {
+        self.semantic_terminal_key(frontend_id, buffer_id).is_some()
+    }
+
+    /// Project one semantic frontend's active terminal view.
+    ///
+    /// Called from the render pass, after `sync_semantic_terminal_layout`
+    /// has already applied any geometry change, so the snapshot comes
+    /// from an already-published screen rather than one mid-resize.
+    pub fn prepare_semantic_terminal_view(
+        &self,
+        frontend_id: FrontendId,
+        buffer_id: crate::buffer::BufferId,
+        size: CellSize,
+    ) -> Option<TerminalSnapshot> {
+        let key = self.semantic_terminal_key(frontend_id, buffer_id)?;
+        self.terminal_manager
+            .borrow_mut()
+            .snapshot_for_view(key, size)
+    }
+
+    /// Record a semantic frontend's declared terminal geometry.
+    ///
+    /// Recording is unconditional for a valid declaration — that is what
+    /// gives a passive split its own clipped/padded projection — but the
+    /// PTY resizes only when this exact view is the durable controller.
+    /// Declaring geometry never CLAIMS control: a background frontend
+    /// repainting at a different size must not steal the shared screen
+    /// out from under the frontend the user is typing into.
+    ///
+    /// Returns whether the shared screen geometry actually changed.
+    pub fn sync_semantic_terminal_layout(
+        &mut self,
+        frontend_id: FrontendId,
+        buffer_id: crate::buffer::BufferId,
+        size: CellSize,
+    ) -> bool {
+        let Some(key) = self.semantic_terminal_key(frontend_id, buffer_id) else {
+            return false;
+        };
+        if !self
+            .terminal_manager
+            .borrow_mut()
+            .record_view_size(key, size)
+        {
+            return false;
+        }
+        let controls = self
+            .terminal_manager
+            .borrow()
+            .controller(buffer_id)
+            .is_some_and(|controller| controller.matches(key));
+        if !controls {
+            return false;
+        }
+        let old_size = self
+            .terminal_manager
+            .borrow()
+            .snapshot(buffer_id)
+            .map(|snapshot| snapshot.size);
+        if old_size == Some(size) {
+            return false;
+        }
+        let (Ok(rows), Ok(cols)) = (u16::try_from(size.rows), u16::try_from(size.cols)) else {
+            return false;
+        };
+        let result = self.terminal_manager.borrow_mut().resize(
+            buffer_id,
+            rows,
+            cols,
+            &mut self.process_supervisor.borrow_mut(),
+        );
+        if let Err(error) = result {
+            self.core.borrow_mut().status = error.to_string();
+            false
+        } else {
+            true
+        }
+    }
+
+    /// Apply a semantic frontend's terminal-cell pointer gesture.
+    ///
+    /// The gesture must name the authenticated frontend's active
+    /// terminal buffer, match the viewport that frontend last declared,
+    /// and land inside it. Anything else is dropped before any view,
+    /// controller, selection, menu, or PTY mutation — a coordinate is
+    /// only meaningful relative to the geometry the sender declared, so
+    /// accepting one against a stale or undeclared viewport would let a
+    /// peer select cells it never saw.
+    pub fn dispatch_semantic_terminal_pointer(
+        &mut self,
+        frontend_id: FrontendId,
+        buffer_id: crate::buffer::BufferId,
+        coord: CellCoord,
+        kind: TerminalMouseKind,
+        mods: TerminalModifiers,
+    ) -> bool {
+        let Some(key) = self.semantic_terminal_key(frontend_id, buffer_id) else {
+            return false;
+        };
+        let Some(size) = self.terminal_manager.borrow().declared_view_size(key) else {
+            return false;
+        };
+        if coord.row >= size.rows || coord.col >= size.cols {
+            return false;
+        }
+        self.core.borrow_mut().active_frontend = frontend_id;
+        self.apply_terminal_gesture(key, size, coord, kind, mods, (coord.row, coord.col));
+        true
+    }
+
     /// Precompute owned terminal view snapshots before entering paint borrows.
     pub fn prepare_terminal_views(
         &mut self,
@@ -1763,10 +1912,34 @@ impl EditorState {
         event: MouseEvent,
         global: (u32, u32),
     ) {
-        use crossterm::event::{MouseButton, MouseEventKind};
+        self.apply_terminal_gesture(
+            key,
+            viewport_size,
+            coord,
+            terminal_mouse_kind(event.kind),
+            terminal_modifiers(event.modifiers),
+            global,
+        );
+    }
 
-        let kind = terminal_mouse_kind(event.kind);
-        let modifiers = terminal_modifiers(event.modifiers);
+    /// The one terminal pointer path, shared by both frontend kinds.
+    ///
+    /// The TUI reaches it through crossterm translation and the semantic
+    /// frontend through `FrontendEvent::TerminalPointer`; both arrive as
+    /// the protocol-native kind/modifier pair, so child mouse reporting,
+    /// scroll, selection, and the context menu stay single-sourced.
+    /// A second copy of this precedence in the GPU lane is exactly how
+    /// Shift-drag or scrolled-back selection would silently diverge
+    /// between frontends.
+    fn apply_terminal_gesture(
+        &mut self,
+        key: TerminalViewKey,
+        viewport_size: CellSize,
+        coord: CellCoord,
+        kind: TerminalMouseKind,
+        modifiers: TerminalModifiers,
+        global: (u32, u32),
+    ) {
         let shift = modifiers.contains(TerminalModifiers::SHIFT);
         let (at_bottom, modes, screen_size) = {
             let mut manager = self.terminal_manager.borrow_mut();
@@ -1792,23 +1965,23 @@ impl EditorState {
 
         self.claim_terminal_controller(key);
         let mut manager = self.terminal_manager.borrow_mut();
-        match event.kind {
-            MouseEventKind::ScrollUp => {
+        match kind {
+            TerminalMouseKind::ScrollUp => {
                 let _ = manager.scroll_view(key, viewport_size, SCROLL_LINES);
             }
-            MouseEventKind::ScrollDown => {
+            TerminalMouseKind::ScrollDown => {
                 let _ = manager.scroll_view(key, viewport_size, -SCROLL_LINES);
             }
-            MouseEventKind::Down(MouseButton::Left) => {
+            TerminalMouseKind::Down(TerminalMouseButton::Left) => {
                 let _ = manager.begin_selection(key, viewport_size, coord);
             }
-            MouseEventKind::Drag(MouseButton::Left) => {
+            TerminalMouseKind::Drag(TerminalMouseButton::Left) => {
                 let _ = manager.update_selection(key, viewport_size, coord);
             }
-            MouseEventKind::Up(MouseButton::Left) => {
+            TerminalMouseKind::Up(TerminalMouseButton::Left) => {
                 let _ = manager.finish_selection(key, viewport_size, coord);
             }
-            MouseEventKind::Down(MouseButton::Right) => {
+            TerminalMouseKind::Down(TerminalMouseButton::Right) => {
                 drop(manager);
                 self.core.borrow_mut().break_command_chain(key.frontend_id);
                 let rows = self.build_menu_rows();
diff --git a/src/frontend.rs b/src/frontend.rs
index 6c1ca45..81e5a0f 100644
--- a/src/frontend.rs
+++ b/src/frontend.rs
@@ -429,6 +429,13 @@ impl Frontend {
             // the grid TUI paints provider output directly from the
             // registry and silently drops an unexpected wire copy.
             | InstanceMessage::StatuslineSegments { .. }
+            // Vterm Stage 3 — TerminalFrame is the semantic frontend's
+            // terminal surface. A grid TUI composes terminal windows
+            // into its own CellDelta (Stage 2) and advertises no
+            // semantic render, so the daemon never sends it here; an
+            // unexpected copy drops silently like the rest of the
+            // family rather than being re-interpreted as cells.
+            | InstanceMessage::TerminalFrame(_)
             | InstanceMessage::ResourceOffer { .. }
             // T M11.6 — DispatchIdle is consumed by `attach.rs`'s
             // optimistic-apply gate; if any reaches this render path
diff --git a/src/protocol.rs b/src/protocol.rs
index ac2a632..a86a9d1 100644
--- a/src/protocol.rs
+++ b/src/protocol.rs
@@ -1683,7 +1683,7 @@ mod tests {
     // --- M5.5a handshake & postcard round-trips ---
 
     #[test]
-    fn protocol_version_is_eighteen_for_statusline_segments() {
+    fn protocol_version_is_nineteen_for_the_terminal_family() {
         // Pin the value: T M10.5 bumped 1→2 (v1.0 wire: CrdtOp /
         // PresenceUpdate). T M11.1 bumped 2→3 (v1.1 wire: the
         // SemanticFrame family + FrontendEvent::Viewport). T M11.6
@@ -1714,8 +1714,13 @@ mod tests {
         // variant — see the ThemeFacts placement pin).
         // Statusline segments Q#SL7 bumped 17→18 (`InstanceMessage::
         // StatuslineSegments`, additive + daemon-gated, appended after
-        // FontFacts — see the v17 placement pin).
-        assert_eq!(PROTOCOL_VERSION, 18);
+        // FontFacts — see the v17 placement pin). Vterm Stage 3 bumped
+        // 18→19 (`InstanceMessage::TerminalFrame`, daemon-gated, plus
+        // `FrontendEvent::TerminalResize` / `TerminalPointer`,
+        // frontend-gated — the first bump that gates in BOTH
+        // directions; all three appended after their enum's final v18
+        // variant, see the placement pins).
+        assert_eq!(PROTOCOL_VERSION, 19);
     }
 
     #[test]
@@ -1790,17 +1795,18 @@ mod tests {
         // regex/invalid), v11 (the context menu), v12 (the GUI
         // minibuffer), v13 (`LineNumbers`), v14 (`LineNumberMode`), v15
         // (`CompletionPopup`), v16 (`ThemeFacts`), v17 (`FontFacts`),
-        // and v18 (`StatuslineSegments`) all interoperate.
-        for accepted in 6..=18 {
+        // v18 (`StatuslineSegments`), and v19 (the vterm terminal
+        // family) all interoperate.
+        for accepted in 6..=19 {
             assert!(
                 is_supported_protocol_version(accepted),
                 "v{accepted} must be accepted"
             );
         }
-        for rejected in [0, 1, 2, 3, 4, 5, 19, u32::MAX] {
+        for rejected in [0, 1, 2, 3, 4, 5, 20, u32::MAX] {
             assert!(
                 !is_supported_protocol_version(rejected),
-                "v{rejected} must be rejected by a v18 binary"
+                "v{rejected} must be rejected by a v19 binary"
             );
         }
     }
@@ -1891,6 +1897,124 @@ mod tests {
         }
     }
 
+    #[test]
+    fn statusline_segments_encoding_is_unchanged_by_the_v19_build() {
+        // Vterm Stage 3 placement pin: `TerminalFrame` must be APPENDED
+        // after `StatuslineSegments` — the final v18 variant, whose
+        // ordinal moves if anything is inserted before any v18 variant.
+        // These are the exact bytes a v18 binary produced for this
+        // value (discriminant 25 as a postcard varint, then the buffer
+        // id and two empty vectors); the new variant's own round-trip
+        // cannot detect a shift.
+        let msg = InstanceMessage::StatuslineSegments {
+            buffer_id: pmacs_protocol::BufferId::from_raw(4),
+            left: Vec::new(),
+            right: Vec::new(),
+        };
+        let bytes = postcard::to_allocvec(&msg).expect("encode");
+        assert_eq!(
+            bytes,
+            [25, 4, 0, 0],
+            "StatuslineSegments' v18 wire bytes changed — a variant was \
+             inserted before it; append new InstanceMessage variants \
+             at the end"
+        );
+    }
+
+    #[test]
+    fn menu_pointer_encoding_is_unchanged_by_the_v19_build() {
+        // The same placement pin for the frontend→instance enum:
+        // `TerminalResize` / `TerminalPointer` are appended after
+        // `MenuPointer`, the final v18 `FrontendEvent` variant. A
+        // frontend-gated variant inserted earlier would shift the
+        // discriminants of `Viewport` and `Pointer`, which older
+        // daemons decode on every session.
+        let ev = FrontendEvent::MenuPointer {
+            frontend_id: FrontendId(2),
+            index: Some(1),
+            invoke: true,
+        };
+        let bytes = postcard::to_allocvec(&ev).expect("encode");
+        assert_eq!(
+            bytes,
+            [10, 2, 1, 1, 1],
+            "MenuPointer's v18 wire bytes changed — a variant was \
+             inserted before it; append new FrontendEvent variants \
+             at the end"
+        );
+    }
+
+    #[test]
+    fn terminal_family_round_trips_and_pins_its_discriminants() {
+        let bid = pmacs_protocol::BufferId::from_raw(9);
+        let frame = pmacs_protocol::TerminalFrame {
+            buffer_id: bid,
+            size: CellSize::new(1, 2),
+            cells: vec![
+                Cell {
+                    glyph: pmacs_protocol::Glyph::Char('h'),
+                    style: Style::default(),
+                    attachment: None,
+                },
+                Cell {
+                    glyph: pmacs_protocol::Glyph::Char('i'),
+                    style: Style::default(),
+                    attachment: None,
+                },
+            ],
+            cursor: Some(CellCoord::new(0, 1)),
+            title: None,
+            screen_generation: 2,
+            selection: Vec::new(),
+            scroll_offset: 0,
+            at_bottom: true,
+            pid: 77,
+            process: pmacs_protocol::TerminalProcessState::Running,
+        };
+        assert_eq!(frame.validate(), Ok(()));
+
+        let msg = InstanceMessage::TerminalFrame(frame);
+        let bytes = postcard::to_allocvec(&msg).expect("encode");
+        assert_eq!(
+            bytes.first(),
+            Some(&26),
+            "TerminalFrame must be the 27th InstanceMessage variant \
+             (appended after StatuslineSegments)"
+        );
+        let decoded: InstanceMessage = postcard::from_bytes(&bytes).expect("decode");
+        assert_eq!(decoded, msg);
+
+        for (ev, discriminant) in [
+            (
+                FrontendEvent::TerminalResize {
+                    frontend_id: FrontendId(3),
+                    buffer_id: bid,
+                    size: CellSize::new(24, 80),
+                },
+                11u8,
+            ),
+            (
+                FrontendEvent::TerminalPointer {
+                    frontend_id: FrontendId(3),
+                    buffer_id: bid,
+                    coord: CellCoord::new(4, 5),
+                    kind: MouseKind::Down(MouseButton::Left),
+                    mods: Modifiers::SHIFT,
+                },
+                12,
+            ),
+        ] {
+            let bytes = postcard::to_allocvec(&ev).expect("encode");
+            assert_eq!(
+                bytes.first(),
+                Some(&discriminant),
+                "terminal FrontendEvent variants must be appended after MenuPointer"
+            );
+            let decoded: FrontendEvent = postcard::from_bytes(&bytes).expect("decode");
+            assert_eq!(decoded, ev);
+        }
+    }
+
     #[test]
     fn font_facts_encoding_is_unchanged_by_the_v18_build() {
         let msg = InstanceMessage::FontFacts {
diff --git a/src/semantic_render.rs b/src/semantic_render.rs
index 2d3ec0a..2ba2f56 100644
--- a/src/semantic_render.rs
+++ b/src/semantic_render.rs
@@ -33,7 +33,7 @@
 use std::collections::HashMap;
 
 use crate::buffer::BufferId;
-use crate::cell::Style;
+use crate::cell::{CellSize, Style};
 use crate::editor::EditorState;
 use crate::protocol::{
     AdornmentContent, AdornmentPlacement, ByteRange, Decoration, DecorationKind, DecorationSegment,
@@ -44,6 +44,7 @@ use crate::statusline::{
     StatuslineEvaluation, StatuslineEvaluationOutcome, StatuslineEvaluationTarget,
     evaluate_statusline,
 };
+use crate::terminal::TerminalFrame;
 
 /// The viewport a `semantic_render` frontend last declared.
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -131,6 +132,10 @@ fn minibuffer_window(candidates: &[String], selected: Option<usize>) -> (Vec<Str
 /// Owns one `semantic_render` session's projection state: the last
 /// viewport the frontend declared, and the diff baseline per buffer
 /// for the `StyleSpans` and `Decorations` families.
+#[allow(
+    clippy::struct_excessive_bools,
+    reason = "independent per-peer capability and latch flags"
+)]
 pub struct SemanticRenderState {
     /// The session this projection serves. Selection is per-window
     /// (per-frontend) state, so the decoration projection needs the
@@ -276,6 +281,31 @@ pub struct SemanticRenderState {
     /// when the store is non-stale and non-empty) — a steady-state
     /// CPU burn for a value that changes only when the buffer does.
     diag_line_cache: HashMap<BufferId, DiagLineCache>,
+    /// Whether the peer negotiated protocol >= 19 (Vterm Stage 3). A
+    /// v18 semantic peer receives the terminal identity buffer's empty
+    /// snapshot and nothing else: terminal use is unsupported and
+    /// invisible there, while ordinary document editing is unchanged.
+    peer_knows_terminal_frames: bool,
+    /// The terminal-cell geometry this frontend last declared, or
+    /// `None` before its first accepted `TerminalResize`. One value,
+    /// not a map: a frontend displays at most one terminal at a time
+    /// (its active window), and the buffer travels with the size so a
+    /// declaration outliving a switch cannot project the wrong session.
+    terminal_viewport: Option<(BufferId, CellSize)>,
+    /// The last terminal frame this peer received, compared in FULL.
+    ///
+    /// Not keyed on `screen_generation`: selection, scroll, viewport,
+    /// and process state all change without advancing that counter, so
+    /// a generation-keyed baseline goes silent on exactly the view-only
+    /// updates the frontend needs. `None` means the peer has received
+    /// no frame, so the next valid one is authoritative.
+    last_terminal_frame: Option<TerminalFrame>,
+    /// Whether an invalid terminal snapshot was already reported since
+    /// the last valid frame. Bounds the log to one line per distinct
+    /// failure rather than one per tick while the condition persists.
+    terminal_error_latched: bool,
+    /// Whether the most recent render pass projected a terminal.
+    terminal_active: bool,
 }
 
 /// One [`SemanticRenderState::diag_line_cache`] entry: the line-start
@@ -371,6 +401,7 @@ impl SemanticRenderState {
         s.peer_knows_theme_facts = negotiated_protocol_version >= 16;
         s.peer_knows_font_facts = negotiated_protocol_version >= 17;
         s.peer_knows_statusline_segments = negotiated_protocol_version >= 18;
+        s.peer_knows_terminal_frames = negotiated_protocol_version >= 19;
         s
     }
 
@@ -416,6 +447,11 @@ impl SemanticRenderState {
             peer_knows_statusline_segments: true,
             last_statusline: HashMap::new(),
             diag_line_cache: HashMap::new(),
+            peer_knows_terminal_frames: true,
+            terminal_viewport: None,
+            last_terminal_frame: None,
+            terminal_error_latched: false,
+            terminal_active: false,
         }
     }
 
@@ -431,6 +467,59 @@ impl SemanticRenderState {
         });
     }
 
+    /// Record the terminal-cell geometry this frontend declared
+    /// (`FrontendEvent::TerminalResize`, accepted by the daemon only
+    /// when it names the authenticated source's active terminal).
+    ///
+    /// Replacing the declaration for a DIFFERENT buffer drops the frame
+    /// baseline: the next frame describes another session entirely, and
+    /// comparing it against the old one could suppress it.
+    pub fn set_terminal_viewport(&mut self, buffer_id: BufferId, size: CellSize) {
+        if self
+            .terminal_viewport
+            .is_some_and(|(previous, _)| previous != buffer_id)
+        {
+            self.clear_terminal_baseline();
+        }
+        self.terminal_viewport = Some((buffer_id, size));
+    }
+
+    /// The terminal geometry this frontend last declared.
+    ///
+    /// The daemon reads this to apply the semantic layout sync beside
+    /// the landed grid sync, before the next child-output drain.
+    #[must_use]
+    pub fn terminal_viewport(&self) -> Option<(BufferId, CellSize)> {
+        self.terminal_viewport
+    }
+
+    /// Whether the last render pass projected a terminal.
+    ///
+    /// The daemon consults this to suppress the document `CursorByte`
+    /// and the presence sweep: a terminal identity buffer is empty, so
+    /// both would describe a cursor at byte 0 of a buffer with no text.
+    /// It tracks the PASS, not the baseline — a first frame rejected by
+    /// validation still means this frontend is displaying a terminal,
+    /// and falling back to the document path there would paint an empty
+    /// buffer over a live session.
+    #[must_use]
+    pub fn in_terminal_mode(&self) -> bool {
+        self.terminal_active
+    }
+
+    /// Forget the terminal frame baseline so the next valid frame is
+    /// authoritative, and re-arm the invalid-frame log.
+    fn clear_terminal_baseline(&mut self) {
+        self.last_terminal_frame = None;
+        self.terminal_error_latched = false;
+    }
+
+    /// Drop terminal projection state on detach or context replacement.
+    pub fn on_terminal_context_released(&mut self) {
+        self.terminal_viewport = None;
+        self.clear_terminal_baseline();
+    }
+
     /// Snapshot/baseline reset contract (PR #120 round 2 finding 1).
     ///
     /// A `BufferSnapshot` resets the receiving frontend's
@@ -464,6 +553,14 @@ impl SemanticRenderState {
     /// buffer, and any buffer the frontend navigates to receives its
     /// own snapshot first.
     pub fn on_buffer_snapshot_sent(&mut self, buffer_id: BufferId) {
+        // Vterm Stage 3: a snapshot takes the GPU out of terminal mode
+        // unconditionally — it clears the prior frame and every
+        // terminal-only cache before painting. Both sides must forget
+        // together, and the frontend re-declares its geometry
+        // immediately after applying the snapshot, so dropping the
+        // declaration here costs one message, not a stuck terminal.
+        self.terminal_viewport = None;
+        self.clear_terminal_baseline();
         self.last_sent.remove(&buffer_id);
         self.last_style_gate.remove(&buffer_id);
         self.last_decorations.remove(&buffer_id);
@@ -496,6 +593,14 @@ impl SemanticRenderState {
     /// to say (no hints, no prior non-empty send).
     #[allow(clippy::too_many_lines)]
     pub fn render_frame(&mut self, state: &EditorState) -> Vec<InstanceMessage> {
+        // Vterm Stage 3: a terminal window suppresses the whole document
+        // projection. It is checked FIRST because the terminal identity
+        // buffer is a valid (empty) document — running the document path
+        // over it would ship an authoritative empty styling/summary
+        // resync on top of the live cell grid.
+        if let Some(messages) = self.terminal_frame_pass(state) {
+            return messages;
+        }
         let Some(vp) = self.viewport.clone() else {
             // Emit nothing before the frontend declares a viewport.
             return Vec::new();
@@ -694,6 +799,98 @@ impl SemanticRenderState {
         out
     }
 
+    /// Project this frontend's active terminal, or `None` when it is
+    /// not displaying one (so the document path runs instead).
+    ///
+    /// Returning `Some` means terminal mode: the caller emits exactly
+    /// these messages and no document family at all. What survives is
+    /// the buffer-independent chrome the native frontend still needs —
+    /// status band, theme, font, statusline, menu, and minibuffer — plus
+    /// the frame itself.
+    fn terminal_frame_pass(&mut self, state: &EditorState) -> Option<Vec<InstanceMessage>> {
+        // A v18 peer has no terminal surface at all: it keeps the
+        // document path over the empty identity buffer, exactly as it
+        // did before this protocol version existed.
+        //
+        // Every path out of terminal mode clears `terminal_active`
+        // explicitly. An early `?` that left it set would keep the
+        // daemon suppressing this frontend's `CursorByte` and presence
+        // long after it went back to editing a document.
+        let declaration = self
+            .peer_knows_terminal_frames
+            .then_some(self.terminal_viewport)
+            .flatten();
+        let Some((buffer_id, size)) = declaration else {
+            self.terminal_active = false;
+            return None;
+        };
+        let Some(snapshot) =
+            state.prepare_semantic_terminal_view(self.frontend_id, buffer_id, size)
+        else {
+            // The window switched away, the session died, or the
+            // declared size went out of range. Leave terminal mode and
+            // let the document path resume.
+            self.terminal_active = false;
+            self.clear_terminal_baseline();
+            return None;
+        };
+        self.terminal_active = true;
+
+        // Evaluate callbacks before `ThemeFacts` for the same reason the
+        // document path does: a callback may register a face, and the
+        // face inventory must precede the segment text that names it.
+        let statusline_evaluation = self.peer_knows_statusline_segments.then(|| {
+            evaluate_statusline(
+                state.lua_host.lua(),
+                &state.core,
+                &state.statusline_registry,
+                StatuslineEvaluationTarget::Semantic {
+                    frontend_id: self.frontend_id,
+                    declared_buffer: buffer_id,
+                },
+            )
+        });
+
+        let mut out = Vec::new();
+        let frame = snapshot.into_terminal_frame();
+        match frame.validate() {
+            Ok(()) => {
+                self.terminal_error_latched = false;
+                // Complete-payload comparison, not `screen_generation`:
+                // a scroll, a selection change, or a process exit must
+                // reach the frontend even though the screen itself is
+                // byte-identical.
+                if self.last_terminal_frame.as_ref() != Some(&frame) {
+                    self.last_terminal_frame = Some(frame.clone());
+                    out.push(InstanceMessage::TerminalFrame(frame));
+                }
+            }
+            Err(error) => {
+                // Never emit a malformed or truncated frame. The peer
+                // keeps the last valid one; one bounded log line marks
+                // the condition until a valid frame clears the latch.
+                if !self.terminal_error_latched {
+                    self.terminal_error_latched = true;
+                    eprintln!(
+                        "pmacs: terminal frame for {:?} on {:?} failed validation, \
+                         retaining the last valid frame: {error}",
+                        buffer_id, self.frontend_id
+                    );
+                }
+            }
+        }
+
+        out.extend(self.status_facts_msg(state, buffer_id));
+        out.extend(self.menu_prompt_msg(state, buffer_id));
+        out.extend(self.minibuffer_prompt_msg(state, buffer_id));
+        out.extend(self.theme_facts_msg(state));
+        out.extend(self.font_facts_msg(state));
+        if let Some(evaluation) = statusline_evaluation {
+            self.emit_statusline_segments(evaluation, &mut out);
+        }
+        Some(out)
+    }
+
     /// Apply the lead evaluator's publication outcome to the v18 wire
     /// baseline. Invalidated evaluations discard all callback text and
     /// publish authoritative empty replacements for the captured old
diff --git a/src/terminal/mod.rs b/src/terminal/mod.rs
index 267ff32..27ee96c 100644
--- a/src/terminal/mod.rs
+++ b/src/terminal/mod.rs
@@ -12,24 +12,28 @@ pub mod session;
 pub mod view;
 
 pub use session::{
-    SharedTerminalManager, TerminalError, TerminalManager, TerminalProcessState,
-    TerminalSelectionSpan, TerminalSnapshot, TerminalSpec,
+    SharedTerminalManager, TerminalError, TerminalManager, TerminalSnapshot, TerminalSpec,
 };
 pub use view::{
     LogicalCellAnchor, TerminalController, TerminalSelection, TerminalViewKey, TerminalViewState,
 };
 
-/// Maximum terminal rows accepted at creation or resize.
-pub const MAX_TERMINAL_ROWS: u16 = 512;
-/// Maximum terminal columns accepted at creation or resize.
-pub const MAX_TERMINAL_COLS: u16 = 512;
-/// Maximum visible terminal cells accepted at creation or resize.
-pub const MAX_TERMINAL_VISIBLE_CELLS: usize = 262_144;
-/// Maximum UTF-8 bytes retained in one terminal grapheme cluster.
-pub const MAX_TERMINAL_GRAPHEME_BYTES: usize = 256;
+// Vterm Stage 3: the screen bounds and the process/selection payload
+// types moved to `pmacs-protocol` so the daemon's pre-emission check and
+// a frontend's post-decode check run the SAME policy. Re-exported here
+// so Stage 1/2 callers keep their `crate::terminal::…` paths and no
+// duplicate type appears in the tree.
+pub use pmacs_protocol::terminal::{
+    MAX_TERMINAL_COLS, MAX_TERMINAL_FRAME_GLYPH_BYTES, MAX_TERMINAL_GRAPHEME_BYTES,
+    MAX_TERMINAL_METADATA_BYTES, MAX_TERMINAL_ROWS, MAX_TERMINAL_VISIBLE_CELLS, TerminalFrame,
+    TerminalFrameError, TerminalProcessState, TerminalSelectionSpan,
+};
+
 /// Default retained main-screen scrollback rows.
+///
+/// Configuration-time, not a wire bound: history never crosses the
+/// protocol, so this stays core-owned.
 pub const DEFAULT_TERMINAL_SCROLLBACK_ROWS: usize = 10_000;
-/// Maximum retained main-screen history cells.
+/// Maximum retained main-screen history cells. Core-owned for the same
+/// reason as [`DEFAULT_TERMINAL_SCROLLBACK_ROWS`].
 pub const MAX_TERMINAL_HISTORY_CELLS: usize = 4_000_000;
-/// Shared cap for terminal title and process-outcome metadata.
-pub const MAX_TERMINAL_METADATA_BYTES: usize = 1_024;
diff --git a/src/terminal/session.rs b/src/terminal/session.rs
index 686214b..ee96923 100644
--- a/src/terminal/session.rs
+++ b/src/terminal/session.rs
@@ -20,7 +20,7 @@ use crate::terminal::screen::TerminalScreen;
 use crate::terminal::view::{TerminalController, TerminalViewKey, TerminalViewState};
 use crate::terminal::{
     MAX_TERMINAL_COLS, MAX_TERMINAL_HISTORY_CELLS, MAX_TERMINAL_METADATA_BYTES, MAX_TERMINAL_ROWS,
-    MAX_TERMINAL_VISIBLE_CELLS,
+    MAX_TERMINAL_VISIBLE_CELLS, TerminalFrame, TerminalProcessState, TerminalSelectionSpan,
 };
 
 /// Shared single-owner terminal registry used by editor and future Lua bindings.
@@ -133,30 +133,6 @@ impl TerminalSpec {
     }
 }
 
-/// Process outcome published with an owned terminal snapshot.
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub enum TerminalProcessState {
-    /// Child is running or termination has only been requested.
-    Running,
-    /// Child exited with a status code.
-    Exited(i32),
-    /// Child was terminated by a sanitized symbolic signal.
-    Signaled(String),
-    /// Supervision failed after the session was published.
-    Crashed(String),
-}
-
-/// One selected terminal-row span. Stage 1 snapshots leave selection empty.
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub struct TerminalSelectionSpan {
-    /// Visible row.
-    pub row: u32,
-    /// Inclusive starting column.
-    pub start_col: u32,
-    /// Exclusive ending column.
-    pub end_col: u32,
-}
-
 /// Owned, renderer-safe terminal state captured after a manager tick.
 #[derive(Clone, Debug, PartialEq)]
 pub struct TerminalSnapshot {
@@ -184,6 +160,35 @@ pub struct TerminalSnapshot {
     pub process: TerminalProcessState,
 }
 
+impl TerminalSnapshot {
+    /// Convert an owned snapshot into its protocol-v19 wire form.
+    ///
+    /// The two shapes are deliberately distinct types even though their
+    /// fields line up: the snapshot is core-owned state the TUI also
+    /// consumes, while [`TerminalFrame`] is wire input a peer may forge.
+    /// The conversion is total, but the CALLER must still
+    /// [`TerminalFrame::validate`] before emitting — the aggregate glyph
+    /// bound is a wire limit the screen does not enforce, so a child
+    /// that builds a legal-but-huge internal snapshot must be caught
+    /// here rather than sent truncated.
+    #[must_use]
+    pub fn into_terminal_frame(self) -> TerminalFrame {
+        TerminalFrame {
+            buffer_id: self.buffer_id,
+            size: self.size,
+            cells: self.cells,
+            cursor: self.cursor,
+            title: self.title,
+            screen_generation: self.screen_generation,
+            selection: self.selection,
+            scroll_offset: self.scroll_offset,
+            at_bottom: self.at_bottom,
+            pid: self.pid,
+            process: self.process,
+        }
+    }
+}
+
 /// Terminal session/registry failures.
 #[derive(Debug, Error)]
 pub enum TerminalError {
diff --git a/src/terminal/view.rs b/src/terminal/view.rs
index b8cd2ad..d79d8b6 100644
--- a/src/terminal/view.rs
+++ b/src/terminal/view.rs
@@ -7,8 +7,11 @@ use crate::buffer::BufferId;
 use crate::cell::{Cell, CellCoord, CellSize, Glyph, Style};
 use crate::protocol::FrontendId;
 use crate::terminal::screen::{BorrowedScreenProjection, TerminalModes, TerminalRow};
-use crate::terminal::session::{TerminalManager, TerminalSelectionSpan, TerminalSnapshot};
-use crate::terminal::{MAX_TERMINAL_COLS, MAX_TERMINAL_ROWS, MAX_TERMINAL_VISIBLE_CELLS};
+use crate::terminal::session::{TerminalManager, TerminalSnapshot};
+use crate::terminal::{
+    MAX_TERMINAL_COLS, MAX_TERMINAL_ROWS, MAX_TERMINAL_VISIBLE_CELLS, TerminalProcessState,
+    TerminalSelectionSpan,
+};
 use crate::window::WindowId;
 
 /// One frontend/window projection of a terminal session.
@@ -250,6 +253,42 @@ impl TerminalManager {
             .map(|session| session.screen.projection_ref().size)
     }
 
+    /// Record an exact view's declared viewport size without projecting.
+    ///
+    /// Vterm Stage 3: a semantic frontend declares terminal geometry
+    /// through its own message rather than through a layout pass, and a
+    /// PASSIVE view must still record its size — that is what lets it
+    /// receive its own clipped/padded projection instead of the
+    /// controller's. Recording a size is deliberately not claiming
+    /// control; the caller decides whether to resize the PTY.
+    ///
+    /// Returns `false` for an unknown session or an out-of-range size,
+    /// leaving prior geometry untouched.
+    pub fn record_view_size(&mut self, key: TerminalViewKey, viewport_size: CellSize) -> bool {
+        if !valid_viewport(viewport_size) {
+            return false;
+        }
+        let Some(session) = self.sessions.get(&key.buffer_id) else {
+            return false;
+        };
+        let projection = session.screen.projection_ref();
+        let bell_count = session.screen.bell_count();
+        let state = self.views.entry(key).or_insert_with(|| TerminalViewState {
+            alternate_active: Some(projection.alternate_active),
+            last_bell_count: bell_count,
+            ..TerminalViewState::default()
+        });
+        normalize_state(state, projection);
+        state.viewport_size = Some(viewport_size);
+        true
+    }
+
+    /// The viewport size an exact view last declared or rendered at.
+    #[must_use]
+    pub fn declared_view_size(&self, key: TerminalViewKey) -> Option<CellSize> {
+        self.views.get(&key).and_then(|state| state.viewport_size)
+    }
+
     /// Return fresh geometric status for one registered view.
     #[must_use]
     pub fn view_status(&mut self, key: TerminalViewKey) -> Option<TerminalViewStatus> {
@@ -670,7 +709,7 @@ fn project_snapshot(
     projection: BorrowedScreenProjection<'_>,
     state: &TerminalViewState,
     pid: u32,
-    process: crate::terminal::session::TerminalProcessState,
+    process: TerminalProcessState,
 ) -> TerminalSnapshot {
     let rows = retained_rows(projection);
     let geometry = view_geometry(&rows, state, viewport_size.rows);
@@ -782,8 +821,8 @@ fn copy_selection_bytes(rows: &RetainedRows<'_>, selection: TerminalSelection) -
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::terminal::TerminalProcessState;
     use crate::terminal::screen::ScreenProjection;
-    use crate::terminal::session::TerminalProcessState;
 
     fn row(id: u64, offset: u32, text: &str, soft_wrapped: bool) -> TerminalRow {
         TerminalRow {
diff --git a/tests/common/daemon.rs b/tests/common/daemon.rs
index 8a1aed2..6cb087a 100644
--- a/tests/common/daemon.rs
+++ b/tests/common/daemon.rs
@@ -63,6 +63,17 @@ impl TestDaemon {
         Self::spawn_with_env_and_config(&[], Some(init_lua))
     }
 
+    /// Spawn with BOTH env overrides and a user `init.lua`.
+    ///
+    /// Vterm Stage 3 needs this pair together: `init.lua` opens the
+    /// terminal the frontend will attach to, and
+    /// `PMACS_INSTANCE_SEMANTIC_RENDER` is what makes the daemon
+    /// advertise the capability a semantic frontend requires.
+    #[allow(dead_code)] // consumed per-suite; not every test crate uses it
+    pub fn spawn_with_env_and_init(env_vars: &[(&str, &str)], init_lua: &str) -> Self {
+        Self::spawn_with_env_and_config(env_vars, Some(init_lua))
+    }
+
     fn spawn_with_env_and_config(env_vars: &[(&str, &str)], init_lua: Option<&str>) -> Self {
         let tempdir = TempDir::new().expect("tempdir");
         // tempfile::TempDir creates 0755-mode directories; the daemon
diff --git a/tests/statusline_segments_acceptance.rs b/tests/statusline_segments_acceptance.rs
index 120c71f..8d6f1d2 100644
--- a/tests/statusline_segments_acceptance.rs
+++ b/tests/statusline_segments_acceptance.rs
@@ -781,11 +781,16 @@ fn a12_builtin_lsp_provider_tracks_real_attachment_and_unknown_label() {
 // (the drop arm itself is pinned beside Frontend::apply_message).
 #[test]
 fn a13_17_26_protocol_semantic_init_late_join_and_version_cost() {
-    assert_eq!(PROTOCOL_VERSION, 18);
-    for version in 6..=18 {
+    // Vterm Stage 3 appended the terminal family as v19. This
+    // acceptance owns the STATUSLINE variant's placement and gate, so
+    // it tracks the current wire version rather than pinning 18: the
+    // v18 floor it actually cares about is asserted below and in
+    // `peer_accepts_statusline_message`.
+    assert_eq!(PROTOCOL_VERSION, 19);
+    for version in 6..=19 {
         assert!(is_supported_protocol_version(version));
     }
-    assert!(!is_supported_protocol_version(19));
+    assert!(!is_supported_protocol_version(20));
     let sample = InstanceMessage::StatuslineSegments {
         buffer_id: BufferId::from_raw(9),
         left: vec![StatuslineSegment {
diff --git a/tests/vterm_stage3_acceptance.rs b/tests/vterm_stage3_acceptance.rs
new file mode 100644
index 0000000..80ef188
--- /dev/null
+++ b/tests/vterm_stage3_acceptance.rs
@@ -0,0 +1,809 @@
+//! Stage 3 terminal/GPU protocol acceptance (criteria 28–37).
+//!
+//! Focused wire and paint assertions live in `pmacs-protocol` and
+//! `pmacs-gpu`; this suite owns the cross-surface behavior — the
+//! semantic producer's baselines, the authenticated per-view routing,
+//! and the real-daemon path.
+
+mod common;
+
+use std::thread;
+use std::time::{Duration, Instant};
+
+use pmacs::cell::{CellCoord, CellSize, Glyph};
+use pmacs::editor::EditorState;
+use pmacs::protocol::{
+    FrontendId, InstanceMessage, Modifiers, MouseButton, MouseKind, TerminalFrame,
+};
+use pmacs::semantic_render::SemanticRenderState;
+use pmacs::terminal::{TerminalProcessState, TerminalSpec, TerminalViewKey};
+use pmacs::window::{FrontendView, Layout, Window, WindowId};
+
+fn tick_until(
+    state: &mut EditorState,
+    timeout: Duration,
+    mut done: impl FnMut(&EditorState) -> bool,
+) {
+    let deadline = Instant::now() + timeout;
+    loop {
+        state.tick_processes();
+        if done(state) {
+            return;
+        }
+        assert!(Instant::now() < deadline, "terminal condition timed out");
+        thread::sleep(Duration::from_millis(10));
+    }
+}
+
+fn snapshot_text(snapshot: &pmacs::terminal::TerminalSnapshot) -> String {
+    let mut text = String::new();
+    for cell in &snapshot.cells {
+        match &cell.glyph {
+            Glyph::Char(ch) => text.push(*ch),
+            Glyph::Cluster(bytes) => text.push_str(&String::from_utf8_lossy(bytes)),
+            Glyph::Continuation => {}
+        }
+    }
+    text
+}
+
+fn frame_text(frame: &TerminalFrame) -> String {
+    let mut text = String::new();
+    for cell in &frame.cells {
+        match &cell.glyph {
+            Glyph::Char(ch) => text.push(*ch),
+            Glyph::Cluster(bytes) => text.push_str(&String::from_utf8_lossy(bytes)),
+            Glyph::Continuation => {}
+        }
+    }
+    text
+}
+
+/// Give `frontend_id` its own window showing `buffer_id`, the way the
+/// daemon's session bootstrap and buffer-follow do.
+fn attach_view(
+    state: &EditorState,
+    frontend_id: FrontendId,
+    buffer_id: pmacs::buffer::BufferId,
+) -> WindowId {
+    let mut core = state.core.borrow_mut();
+    let text_view = {
+        let registry = core.registry.clone();
+        let registry = registry.borrow();
+        let buffer = registry.get(buffer_id).expect("buffer present");
+        pmacs::text_view::TextView::new(buffer)
+    };
+    let window_id = WindowId::next();
+    let window = Window::new(window_id, buffer_id, text_view);
+    core.windows.insert(window_id, window);
+    core.register_frontend_view(
+        frontend_id,
+        FrontendView {
+            layout: Layout::single(window_id),
+            active: window_id,
+        },
+    );
+    window_id
+}
+
+/// Point an already-registered view at another buffer, the way a
+/// daemon-side buffer switch does.
+fn switch_view(state: &EditorState, frontend_id: FrontendId, buffer_id: pmacs::buffer::BufferId) {
+    let mut core = state.core.borrow_mut();
+    let window_id = core.views.get(&frontend_id).expect("view present").active;
+    let text_view = {
+        let registry = core.registry.clone();
+        let registry = registry.borrow();
+        let buffer = registry.get(buffer_id).expect("buffer present");
+        pmacs::text_view::TextView::new(buffer)
+    };
+    let window = core.windows.get_mut(&window_id).expect("window present");
+    window.buffer_id = buffer_id;
+    window.text_view = text_view;
+    window.cursor = 0;
+    window.selection = None;
+}
+
+fn open_terminal(
+    state: &mut EditorState,
+    args: &str,
+    rows: u16,
+    cols: u16,
+) -> pmacs::buffer::BufferId {
+    let mut spec = TerminalSpec::new("/bin/sh");
+    spec.args = vec!["-c".into(), args.into()];
+    spec.rows = rows;
+    spec.cols = cols;
+    state
+        .terminal_manager
+        .borrow_mut()
+        .open(
+            spec,
+            &mut state.core.borrow_mut(),
+            &mut state.process_supervisor.borrow_mut(),
+        )
+        .expect("open terminal")
+}
+
+fn terminal_frames(messages: &[InstanceMessage]) -> Vec<TerminalFrame> {
+    messages
+        .iter()
+        .filter_map(|msg| match msg {
+            InstanceMessage::TerminalFrame(frame) => Some(frame.clone()),
+            _ => None,
+        })
+        .collect()
+}
+
+fn one_frame(messages: &[InstanceMessage]) -> TerminalFrame {
+    let frames = terminal_frames(messages);
+    assert_eq!(frames.len(), 1, "expected exactly one terminal frame");
+    frames.into_iter().next().expect("checked length")
+}
+
+/// Acceptance 30: the first activation emits one authoritative complete
+/// frame, an equal payload is silent, view-only and process-only changes
+/// emit despite an unchanged screen generation, the document projection
+/// is suppressed while terminal, and switching back resyncs the
+/// document in full.
+#[test]
+#[allow(
+    clippy::too_many_lines,
+    reason = "one producer-baseline lifecycle scenario"
+)]
+fn a30_first_frame_is_authoritative_then_only_real_changes_emit() {
+    let mut state = EditorState::new();
+    let frontend_id = FrontendId(31);
+    let terminal_buffer = open_terminal(
+        &mut state,
+        "printf 'alpha\\nbeta\\n'; i=0; while [ $i -lt 20 ]; do printf 'row%02d\\n' \"$i\"; \
+         i=$((i+1)); done; sleep 30",
+        6,
+        24,
+    );
+    tick_until(&mut state, Duration::from_secs(5), |state| {
+        state
+            .terminal_manager
+            .borrow()
+            .snapshot(terminal_buffer)
+            .is_some_and(|snapshot| snapshot_text(&snapshot).contains("row19"))
+    });
+    attach_view(&state, frontend_id, terminal_buffer);
+
+    let mut producer = SemanticRenderState::for_peer(frontend_id, 19);
+    let size = CellSize::new(6, 24);
+    producer.set_terminal_viewport(terminal_buffer, size);
+
+    // First activation: exactly one complete frame, and no document
+    // family at all.
+    let first = producer.render_frame(&state);
+    let frame = one_frame(&first);
+    assert_eq!(frame.buffer_id, terminal_buffer);
+    assert_eq!(frame.size, size);
+    assert_eq!(frame.cells.len(), (size.rows * size.cols) as usize);
+    assert_eq!(frame.validate(), Ok(()));
+    assert!(frame_text(&frame).contains("row19"));
+    assert!(
+        producer.in_terminal_mode(),
+        "a projected terminal puts the producer in terminal mode"
+    );
+    for msg in &first {
+        assert!(
+            !matches!(
+                msg,
+                InstanceMessage::StyleSpans { .. }
+                    | InstanceMessage::Decorations { .. }
+                    | InstanceMessage::InlineAdornments { .. }
+                    | InstanceMessage::FileStyleSummary { .. }
+                    | InstanceMessage::LineNumbers { .. }
+                    | InstanceMessage::SearchPrompt { .. }
+                    | InstanceMessage::CompletionPopup { .. }
+            ),
+            "terminal mode must suppress the document projection, saw {msg:?}"
+        );
+    }
+
+    // Nothing changed: a completely equal payload is silent.
+    let second = producer.render_frame(&state);
+    assert!(
+        terminal_frames(&second).is_empty(),
+        "an unchanged terminal payload must not re-send"
+    );
+
+    // A view-only change — scrolling this frontend's own view — leaves
+    // `screen_generation` alone but must still reach the frontend.
+    let key = {
+        let core = state.core.borrow();
+        let window_id = core.views.get(&frontend_id).expect("view").active;
+        TerminalViewKey::new(frontend_id, window_id, terminal_buffer)
+    };
+    let generation_before = frame.screen_generation;
+    assert!(
+        state
+            .terminal_manager
+            .borrow_mut()
+            .scroll_view(key, size, 3),
+        "scrolling the view back into history"
+    );
+    let scrolled = one_frame(&producer.render_frame(&state));
+    assert_eq!(
+        scrolled.screen_generation, generation_before,
+        "scrolling does not advance the screen generation"
+    );
+    assert_eq!(scrolled.scroll_offset, 3);
+    assert!(!scrolled.at_bottom);
+
+    // A selection is also view-only.
+    assert!(
+        state
+            .terminal_manager
+            .borrow_mut()
+            .begin_selection(key, size, CellCoord::new(0, 0))
+    );
+    assert!(
+        state
+            .terminal_manager
+            .borrow_mut()
+            .finish_selection(key, size, CellCoord::new(0, 4))
+    );
+    let selected = one_frame(&producer.render_frame(&state));
+    assert!(
+        !selected.selection.is_empty(),
+        "a selection change must reach the frontend"
+    );
+    assert_eq!(selected.screen_generation, generation_before);
+
+    // A process-only change: the child exits. The frame carries the new
+    // outcome even though the frontend has not scrolled or typed.
+    state
+        .terminal_manager
+        .borrow_mut()
+        .terminate(terminal_buffer, &mut state.process_supervisor.borrow_mut())
+        .expect("terminate child");
+    let mut exited = None;
+    let deadline = Instant::now() + Duration::from_secs(5);
+    while Instant::now() < deadline {
+        state.tick_processes();
+        for frame in terminal_frames(&producer.render_frame(&state)) {
+            if !matches!(frame.process, TerminalProcessState::Running) {
+                exited = Some(frame);
+                break;
+            }
+        }
+        if exited.is_some() {
+            break;
+        }
+        thread::sleep(Duration::from_millis(10));
+    }
+    let exited = exited.expect("a process-state change must produce a frame");
+    assert_ne!(exited.process, TerminalProcessState::Running);
+
+    // Switching back to a document: the snapshot reset drops the
+    // terminal declaration and baseline, and the producer leaves
+    // terminal mode so the document resync can happen.
+    let document = state.core.borrow().active_buffer_id();
+    switch_view(&state, frontend_id, document);
+    producer.on_buffer_snapshot_sent(document);
+    assert!(
+        producer.terminal_viewport().is_none(),
+        "a snapshot clears the terminal declaration"
+    );
+    producer.set_viewport(document, pmacs::protocol::ByteRange { start: 0, end: 0 }, 0);
+    let back = producer.render_frame(&state);
+    assert!(
+        terminal_frames(&back).is_empty(),
+        "a document buffer produces no terminal frames"
+    );
+    assert!(
+        !producer.in_terminal_mode(),
+        "the producer leaves terminal mode when the window switches away"
+    );
+}
+
+/// Acceptance 31: two semantic frontends over one terminal keep
+/// independent sizes, scroll, selection, and baselines while sharing one
+/// process and screen; a passive declaration produces its own
+/// clipped/padded frame but only the durable controller resizes the PTY.
+#[test]
+#[allow(
+    clippy::too_many_lines,
+    reason = "one shared-session two-frontend scenario"
+)]
+fn a31_two_semantic_frontends_share_one_session_with_independent_views() {
+    let mut state = EditorState::new();
+    let first_id = FrontendId(41);
+    let second_id = FrontendId(42);
+    let terminal_buffer = open_terminal(
+        &mut state,
+        "i=0; while [ $i -lt 30 ]; do printf 'row%02d\\n' \"$i\"; i=$((i+1)); done; sleep 30",
+        8,
+        40,
+    );
+    tick_until(&mut state, Duration::from_secs(5), |state| {
+        state
+            .terminal_manager
+            .borrow()
+            .snapshot(terminal_buffer)
+            .is_some_and(|snapshot| snapshot_text(&snapshot).contains("row29"))
+    });
+    let first_window = attach_view(&state, first_id, terminal_buffer);
+    let second_window = attach_view(&state, second_id, terminal_buffer);
+
+    let first_size = CellSize::new(6, 30);
+    let second_size = CellSize::new(4, 20);
+    let mut first = SemanticRenderState::for_peer(first_id, 19);
+    let mut second = SemanticRenderState::for_peer(second_id, 19);
+
+    // The first frontend declares and becomes the controller by acting
+    // on its view; the second declares only.
+    assert!(state.semantic_terminal_declaration_is_active(first_id, terminal_buffer));
+    first.set_terminal_viewport(terminal_buffer, first_size);
+    second.set_terminal_viewport(terminal_buffer, second_size);
+
+    let first_key = TerminalViewKey::new(first_id, first_window, terminal_buffer);
+    state.terminal_manager.borrow_mut().register_view(first_key);
+    assert!(
+        state
+            .terminal_manager
+            .borrow_mut()
+            .claim_controller(first_key)
+    );
+
+    let screen_before = state
+        .terminal_manager
+        .borrow()
+        .snapshot(terminal_buffer)
+        .expect("snapshot")
+        .size;
+
+    // A PASSIVE declaration records geometry and produces the passive
+    // frontend's own projection, but never touches the shared screen.
+    assert!(!state.sync_semantic_terminal_layout(second_id, terminal_buffer, second_size));
+    assert_eq!(
+        state
+            .terminal_manager
+            .borrow()
+            .snapshot(terminal_buffer)
+            .expect("snapshot")
+            .size,
+        screen_before,
+        "a passive declaration must not resize the shared PTY"
+    );
+
+    // The CONTROLLER's declaration does resize it.
+    assert!(state.sync_semantic_terminal_layout(first_id, terminal_buffer, first_size));
+    assert_eq!(
+        state
+            .terminal_manager
+            .borrow()
+            .snapshot(terminal_buffer)
+            .expect("snapshot")
+            .size,
+        first_size,
+        "the durable controller owns the shared geometry"
+    );
+
+    let first_frame = one_frame(&first.render_frame(&state));
+    let second_frame = one_frame(&second.render_frame(&state));
+    assert_eq!(first_frame.size, first_size);
+    assert_eq!(second_frame.size, second_size);
+    assert_eq!(
+        first_frame.pid, second_frame.pid,
+        "both views project one process"
+    );
+    assert_eq!(first_frame.process, second_frame.process);
+    assert_eq!(
+        first_frame.screen_generation,
+        second_frame.screen_generation
+    );
+
+    // Scroll and select on the first view only.
+    assert!(
+        state
+            .terminal_manager
+            .borrow_mut()
+            .scroll_view(first_key, first_size, 4)
+    );
+    let second_key = TerminalViewKey::new(second_id, second_window, terminal_buffer);
+    assert!(state.terminal_manager.borrow_mut().begin_selection(
+        first_key,
+        first_size,
+        CellCoord::new(0, 0)
+    ));
+    assert!(state.terminal_manager.borrow_mut().finish_selection(
+        first_key,
+        first_size,
+        CellCoord::new(0, 5)
+    ));
+
+    let first_after = one_frame(&first.render_frame(&state));
+    assert_eq!(first_after.scroll_offset, 4);
+    assert!(!first_after.at_bottom);
+    assert!(!first_after.selection.is_empty());
+
+    // The second frontend's baseline is its own: its projection is
+    // unchanged, so it emits nothing — and when it does emit, it carries
+    // its own scroll and no selection.
+    let second_after = second.render_frame(&state);
+    for frame in terminal_frames(&second_after) {
+        assert_eq!(frame.scroll_offset, 0, "scroll is per view");
+        assert!(frame.selection.is_empty(), "selection is per view");
+    }
+    assert!(
+        state
+            .terminal_manager
+            .borrow()
+            .view_state(second_key)
+            .is_some(),
+        "the passive view remains registered"
+    );
+
+    state
+        .terminal_manager
+        .borrow_mut()
+        .terminate(terminal_buffer, &mut state.process_supervisor.borrow_mut())
+        .expect("terminate child");
+}
+
+/// Acceptance 32: forged frontend/buffer identities, stale buffers,
+/// undeclared viewports, and out-of-bounds coordinates cannot affect
+/// another view, the controller, terminal selection, the menu, the PTY
+/// size, or child input.
+#[test]
+#[allow(
+    clippy::too_many_lines,
+    reason = "one case per rejected identity or bound"
+)]
+fn a32_forged_stale_and_out_of_bounds_terminal_events_change_nothing() {
+    let mut state = EditorState::new();
+    let owner = FrontendId(51);
+    let attacker = FrontendId(52);
+    let terminal_buffer = open_terminal(&mut state, "sleep 30", 6, 20);
+    let other_terminal = open_terminal(&mut state, "sleep 30", 6, 20);
+    tick_until(&mut state, Duration::from_secs(5), |state| {
+        state
+            .terminal_manager
+            .borrow()
+            .snapshot(terminal_buffer)
+            .is_some()
+    });
+    let owner_window = attach_view(&state, owner, terminal_buffer);
+    let document = state.core.borrow().active_buffer_id();
+    attach_view(&state, attacker, document);
+
+    // Declare a size that differs from the spec's 6x20, so the
+    // controller's resize is observable rather than suppressed as
+    // unchanged.
+    let size = CellSize::new(5, 18);
+    let owner_key = TerminalViewKey::new(owner, owner_window, terminal_buffer);
+    state.terminal_manager.borrow_mut().register_view(owner_key);
+    assert!(
+        state
+            .terminal_manager
+            .borrow_mut()
+            .claim_controller(owner_key)
+    );
+    assert!(state.sync_semantic_terminal_layout(owner, terminal_buffer, size));
+    let geometry_before = state
+        .terminal_manager
+        .borrow()
+        .snapshot(terminal_buffer)
+        .expect("snapshot")
+        .size;
+    assert_eq!(
+        geometry_before, size,
+        "the controller's declaration applied"
+    );
+
+    // The attacker's window shows a DOCUMENT, so naming the owner's
+    // terminal buffer is a forgery: the declaration is refused outright.
+    assert!(!state.semantic_terminal_declaration_is_active(attacker, terminal_buffer));
+    assert!(!state.sync_semantic_terminal_layout(attacker, terminal_buffer, CellSize::new(2, 4)));
+    assert_eq!(
+        state
+            .terminal_manager
+            .borrow()
+            .snapshot(terminal_buffer)
+            .expect("snapshot")
+            .size,
+        geometry_before,
+        "a forged declaration must not resize another frontend's session"
+    );
+    assert_eq!(
+        state.terminal_manager.borrow().controller(terminal_buffer),
+        Some(pmacs::terminal::TerminalController::from_view(owner_key)),
+        "a forged declaration must not steal control"
+    );
+
+    // A pointer naming a buffer the sender is not displaying, and one
+    // naming a terminal that exists but is not its active window, are
+    // both dropped before any view mutation.
+    assert!(!state.dispatch_semantic_terminal_pointer(
+        attacker,
+        terminal_buffer,
+        CellCoord::new(0, 0),
+        MouseKind::Down(MouseButton::Left),
+        Modifiers::NONE,
+    ));
+    assert!(!state.dispatch_semantic_terminal_pointer(
+        owner,
+        other_terminal,
+        CellCoord::new(0, 0),
+        MouseKind::Down(MouseButton::Left),
+        Modifiers::NONE,
+    ));
+
+    // An out-of-bounds coordinate against a DECLARED viewport is
+    // dropped too — a cell the sender never saw is not a hit.
+    assert!(!state.dispatch_semantic_terminal_pointer(
+        owner,
+        terminal_buffer,
+        CellCoord::new(size.rows, 0),
+        MouseKind::Down(MouseButton::Left),
+        Modifiers::NONE,
+    ));
+    assert!(!state.dispatch_semantic_terminal_pointer(
+        owner,
+        terminal_buffer,
+        CellCoord::new(0, size.cols),
+        MouseKind::Down(MouseButton::Left),
+        Modifiers::NONE,
+    ));
+    assert!(
+        state
+            .terminal_manager
+            .borrow()
+            .view_state(owner_key)
+            .expect("owner view")
+            .selection
+            .is_none(),
+        "a rejected pointer must not begin a selection"
+    );
+    assert!(
+        !state.core.borrow().menu_is_open(),
+        "a rejected pointer must not open the context menu"
+    );
+
+    // A frontend with no declared viewport cannot hit-test at all: the
+    // coordinate has no geometry to be relative to.
+    let fresh = FrontendId(53);
+    attach_view(&state, fresh, terminal_buffer);
+    assert!(!state.dispatch_semantic_terminal_pointer(
+        fresh,
+        terminal_buffer,
+        CellCoord::new(0, 0),
+        MouseKind::Down(MouseButton::Left),
+        Modifiers::NONE,
+    ));
+
+    // The owner's own in-bounds gesture is accepted, proving the
+    // rejections above are about identity and bounds, not a dead path.
+    assert!(state.dispatch_semantic_terminal_pointer(
+        owner,
+        terminal_buffer,
+        CellCoord::new(0, 0),
+        MouseKind::Down(MouseButton::Left),
+        Modifiers::NONE,
+    ));
+
+    for buffer in [terminal_buffer, other_terminal] {
+        state
+            .terminal_manager
+            .borrow_mut()
+            .terminate(buffer, &mut state.process_supervisor.borrow_mut())
+            .expect("terminate child");
+    }
+}
+
+/// The daemon config the Stage 3 real-path acceptance runs against: a
+/// command that opens a controlled terminal child, bound to a key the
+/// probe can press.
+#[cfg(feature = "crdt")]
+const PROBE_INIT_LUA: &str = r#"
+pmacs.command.define {
+  name = "vterm-probe.open",
+  description = "Open the Stage 3 acceptance terminal child.",
+  fn = function()
+    return pmacs.terminal.open {
+      command = "/bin/sh",
+      args = { "-c",
+        "i=0; while [ $i -lt 400 ]; do printf 'VTERMROW%02d\n' \"$i\"; i=$((i+1)); sleep 0.05; done" },
+    }
+  end,
+}
+-- C-M-t is deliberately an unbound chord: `bind` is strict and
+-- refuses to shadow an existing binding, so a bound one (C-t is
+-- transpose-chars) would fail init and leave the probe on a scratch.
+pmacs.keymap.bind { scope = "global", sequence = "C-M-t", command = "vterm-probe.open" }
+"#;
+
+/// Acceptance 37: one path through a real daemon, a real PTY child, and
+/// real headless wgpu rendering.
+///
+/// The GPU is a separate binary that deliberately depends only on
+/// `pmacs-protocol`, so this drives it as a process: the daemon opens a
+/// `/bin/sh` terminal from its own `init.lua`, and `pmacs-gpu
+/// --headless-probe` attaches through the REAL attach client, applies
+/// real `TerminalFrame`s, composites real pixels offscreen, sends real
+/// input and a real geometry change, and reports named observations.
+/// A decoded-message fixture is deliberately not a substitute — it would
+/// prove nothing about the three fitting together.
+#[cfg(feature = "crdt")]
+#[test]
+fn a37_real_daemon_real_pty_and_headless_gpu_render_one_terminal_session() {
+    use std::path::{Path, PathBuf};
+
+    /// The `pmacs-gpu` binary sits beside the `pmacs` one in the same
+    /// target directory. Cargo exposes `CARGO_BIN_EXE_*` only for the
+    /// package under test, so the sibling is derived rather than named.
+    fn gpu_binary() -> PathBuf {
+        Path::new(env!("CARGO_BIN_EXE_pmacs"))
+            .parent()
+            .expect("test binary directory")
+            .join("pmacs-gpu")
+    }
+
+    let required = std::env::var_os("PMACS_REQUIRE_GPU").is_some();
+    let binary = gpu_binary();
+    if !binary.exists() {
+        assert!(
+            !required,
+            "PMACS_REQUIRE_GPU is set but {} is not built; run the workspace build first",
+            binary.display()
+        );
+        eprintln!(
+            "skipping a37: {} is not built (build the workspace to include it)",
+            binary.display()
+        );
+        return;
+    }
+
+    let daemon = common::daemon::TestDaemon::spawn_with_env_and_init(
+        &[
+            ("PMACS_INSTANCE_SEMANTIC_RENDER", "1"),
+            ("PMACS_INSTANCE_MULTI_FRONTEND", "1"),
+        ],
+        // The terminal is opened BY THE FRONTEND, through a real key
+        // binding: `terminal.open` targets the invoking frontend's
+        // window, so this is what actually puts the GPU's own window on
+        // a terminal buffer. Opening it from init.lua instead would
+        // switch the daemon's local window and leave the attached
+        // frontend on a scratch — which is a real behavior, just not
+        // the one this acceptance is about.
+        //
+        // The child keeps writing so the rendered frame carries live
+        // cursor-addressed content and outlives the resize.
+        PROBE_INIT_LUA,
+    );
+
+    let report = daemon
+        .socket_path()
+        .parent()
+        .expect("socket parent")
+        .join("gpu-probe.txt");
+    let output = std::process::Command::new(&binary)
+        .arg("--headless-probe")
+        .arg(daemon.socket_path())
+        .arg(&report)
+        // The chord the probe presses to run `vterm-probe.open`.
+        .env("PMACS_GPU_PROBE_OPEN_KEY", "t")
+        .output()
+        .expect("run the headless GPU probe");
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        // Exit 3 is "no wgpu adapter" — the same skip contract the
+        // in-crate headless render tests use.
+        let no_adapter = output.status.code() == Some(3);
+        assert!(
+            no_adapter && !required,
+            "headless GPU probe failed (status {:?}):\n{stderr}",
+            output.status.code()
+        );
+        eprintln!("skipping a37: no wgpu adapter available");
+        return;
+    }
+
+    let text = std::fs::read_to_string(&report).expect("probe report");
+    let facts: std::collections::HashMap<&str, &str> = text
+        .lines()
+        .filter_map(|line| line.split_once('='))
+        .collect();
+
+    assert_eq!(
+        facts.get("server_protocol_version").copied(),
+        Some("19"),
+        "the real daemon negotiated v19 with the real client: {text}"
+    );
+    assert_eq!(
+        facts.get("entered_terminal_mode").copied(),
+        Some("true"),
+        "the GPU entered terminal mode from a real frame: {text}"
+    );
+    let frames: u32 = facts
+        .get("frames")
+        .and_then(|v| v.parse().ok())
+        .unwrap_or_default();
+    assert!(
+        frames >= 2,
+        "expected live terminal frames, got {frames}: {text}"
+    );
+    let rendered: u32 = facts
+        .get("rendered_nonuniform_frames")
+        .and_then(|v| v.parse().ok())
+        .unwrap_or_default();
+    assert!(
+        rendered >= 2,
+        "expected real composited frames, got {rendered}: {text}"
+    );
+    assert!(
+        facts
+            .get("last_frame_text")
+            .is_some_and(|t| t.contains("VTERMROW")),
+        "the child's cursor-addressed output must reach the rendered frame: {text}"
+    );
+    let declarations: u32 = facts
+        .get("declarations")
+        .and_then(|v| v.parse().ok())
+        .unwrap_or_default();
+    assert!(
+        declarations >= 2,
+        "expected a bootstrap declaration and a resize declaration, got \
+         {declarations}: {text}"
+    );
+    assert_eq!(
+        facts.get("observed_resized_frame").copied(),
+        Some("true"),
+        "the controller's resize must reach the shared PTY and come back \
+         as a frame at the new width: {text}"
+    );
+    assert!(
+        facts
+            .get("disconnect")
+            .copied()
+            .unwrap_or_default()
+            .is_empty(),
+        "the probe must finish without a transport failure: {text}"
+    );
+}
+
+/// Acceptance 30 (v18 half) and 28: a peer that negotiated v18 receives
+/// no terminal message at all and keeps the ordinary document path over
+/// the empty identity buffer.
+#[test]
+fn a28_a30_a_v18_semantic_peer_has_no_terminal_surface() {
+    let mut state = EditorState::new();
+    let frontend_id = FrontendId(61);
+    let terminal_buffer = open_terminal(&mut state, "sleep 30", 4, 20);
+    tick_until(&mut state, Duration::from_secs(5), |state| {
+        state
+            .terminal_manager
+            .borrow()
+            .snapshot(terminal_buffer)
+            .is_some()
+    });
+    attach_view(&state, frontend_id, terminal_buffer);
+
+    let mut producer = SemanticRenderState::for_peer(frontend_id, 18);
+    producer.set_terminal_viewport(terminal_buffer, CellSize::new(4, 20));
+    producer.set_viewport(
+        terminal_buffer,
+        pmacs::protocol::ByteRange { start: 0, end: 0 },
+        0,
+    );
+    let messages = producer.render_frame(&state);
+    assert!(
+        terminal_frames(&messages).is_empty(),
+        "a v18 peer must never receive a terminal frame"
+    );
+    assert!(
+        !producer.in_terminal_mode(),
+        "a v18 peer stays on the document path"
+    );
+
+    state
+        .terminal_manager
+        .borrow_mut()
+        .terminate(terminal_buffer, &mut state.process_supervisor.borrow_mut())
+        .expect("terminate child");
+}

From 1d0b46f0237fe8b0f91ea6f47611cf5334690df6 Mon Sep 17 00:00:00 2001
From: Levi Neuwirth <ln@levineuwirth.org>
Date: Wed, 22 Jul 2026 13:29:29 -0400
Subject: [PATCH 3/7] docs(vterm): record the stage 3 pull request

---
 docs/active-work.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/active-work.md b/docs/active-work.md
index 4ca124b..9697065 100644
--- a/docs/active-work.md
+++ b/docs/active-work.md
@@ -59,8 +59,8 @@ If it does not, stop and repair the remote/fetch configuration.
 - Base: canonical `main` @ `1dd47fc` (modeline detection #132 atop Vterm
   Stage 2 #130). Cut from `main`, NOT stacked on `vterm-stage3-framing`,
   per the framing's §8.
-- PR: open against canonical `main`; never merge without explicit
-  authorization.
+- PR: #135, <https://github.com/levineuwirth/pmacs/pull/135>, open against
+  canonical `main`. Never merge without explicit authorization.
 - State: criteria 28-37 implemented. Protocol v19 (`SUPPORTED=[6..=19]`):
   `InstanceMessage::TerminalFrame` (discriminant 26, daemon-gated),
   `FrontendEvent::TerminalResize` (11) and `TerminalPointer` (12)

From 50fd9a08e4c723976cf4d7f8e97c6955cf004f1a Mon Sep 17 00:00:00 2001
From: Levi Neuwirth <ln@levineuwirth.org>
Date: Wed, 22 Jul 2026 14:49:23 -0400
Subject: [PATCH 4/7] fix(vterm): address stage 3 review round 1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five findings, all addressed. One was a real defect; one prediction did not
reproduce and is documented as such rather than papered over.

Hover no longer claims durable terminal control (finding 2, the real one).
apply_terminal_gesture claimed the controller before dispatching, including
for Move, which does nothing. A semantic frontend reports motion at pixel
rate, so sweeping the mouse across a passive split's terminal took durable
control, and the next layout sync resized the shared PTY to that background
view's geometry — precisely the theft the controller rule exists to prevent.
Bare motion no longer claims; every deliberate gesture still does.
scripts/bite HEAD src/editor.rs on the new test is a clean behavioral bite.

The terminal-mode presence-sweep skip is removed (finding 1), but the
predicted failure did NOT reproduce. The review reasoned that skipping the
sweep freezes last_broadcast at the abandoned document position. It does
not: the buffer-follow clears the terminal declaration when it ships the
snapshot, so terminal_active is false on the tick a window first shows a
terminal, and the declaration cannot arrive until a later tick — the
frontend learns the buffer id from that very snapshot. One truthful sweep
always lands first. The real-daemon two-frontend test written to catch the
freeze passes against the pre-fix tree; the bite is vacuous and the test is
labelled a regression guard, not fix evidence. The skip goes anyway: it was
load-bearing on tick ordering and bought nothing, and removing it makes
"presence follows the frontend" structural.

Terminal motion is deduplicated by cell (finding 3). Sub-cell motion
resolved to the same coordinate and still crossed the wire, where every
event is a daemon-side gesture. Press and release re-arm the memo so the
first drag after a press still reports. Its unit test cannot bite — the
seam did not exist pre-fix — and says so.

Declarations record only once sent (finding 4).
terminal_declaration_if_changed is now a pure query;
note_terminal_declaration_sent records. A failed write is retried instead of
suppressed as already-declared. The existing a35 test caught the contract
change and now pins both halves.

Unchanged frames skip revalidation (finding 5). The complete-payload
comparison runs before validate; only validated frames are ever stored, so a
frame equal to the baseline has already passed. The chrome tail is factored
into terminal_chrome so both exits emit it identically.

Gates: fmt; strict workspace clippy; 1,757 default + 1,933 CRDT library
tests; Stage 1 9/10, Stage 2 4/4, Stage 3 5/7, statusline 7/8
(default/CRDT); M4 120; required GPU 128; workspace sweep 2,921 across 83
suites; diff check clean.
---
 docs/active-work.md              |  18 +-
 docs/vterm-framing.md            |  48 ++++++
 pmacs-gpu/src/main.rs            | 135 +++++++++++++--
 src/daemon.rs                    |  40 +++--
 src/editor.rs                    |  20 ++-
 src/semantic_render.rs           |  45 ++++-
 tests/vterm_stage3_acceptance.rs | 272 +++++++++++++++++++++++++++++++
 7 files changed, 537 insertions(+), 41 deletions(-)

diff --git a/docs/active-work.md b/docs/active-work.md
index 9697065..eed0dcf 100644
--- a/docs/active-work.md
+++ b/docs/active-work.md
@@ -84,11 +84,19 @@ If it does not, stop and repair the remote/fetch configuration.
   - `cargo test --workspace -- --skip basedpyright`: 2,919 passed across
     83 suites (19 ignored), one invocation;
   - `git diff --check`.
-- Open caveat: the required-GPU suite failed ONCE mid-session and did not
-  reproduce across eight subsequent runs or the full sweep. The failing
-  test's identity was not captured. Re-run `PMACS_REQUIRE_GPU=1 cargo test
-  -p pmacs-gpu` a few times on review; if it recurs, capture the name.
-- Next: user review rounds on the PR.
+- Review round 1 addressed (framing §0.10): hover no longer claims durable
+  terminal control (real defect, bite-verified); terminal motion dedupes by
+  cell; declarations record only once sent; unchanged frames skip
+  revalidation; the terminal-mode presence-sweep skip is removed. The
+  review's predicted presence FREEZE did not reproduce — the buffer-follow
+  clears the declaration before `render_frame`, so a truthful sweep always
+  precedes terminal mode; that test is a labelled regression guard, not
+  fix evidence.
+- Post-review gates: required GPU 128; workspace sweep 2,921 across 83
+  suites; Stage 3 acceptance 5 default / 7 CRDT; everything else as above.
+- Closed caveat: the once-seen required-GPU failure did not reproduce in
+  eight author runs plus four reviewer runs. Treated as environmental.
+- Next: further user review rounds on the PR.
 
 Recovery worktree:
 
diff --git a/docs/vterm-framing.md b/docs/vterm-framing.md
index fcbd471..ee0b59d 100644
--- a/docs/vterm-framing.md
+++ b/docs/vterm-framing.md
@@ -381,6 +381,54 @@ required GPU 127; one-invocation workspace sweep 2,919 passed across 83 suites
 required-GPU suite occurred once mid-session and did not reproduce across eight
 subsequent runs including the full sweep; its identity was not captured.
 
+### 0.10 Stage 3 review round 1
+
+PR #135's first review found no correctness blocker, confirmed the required-GPU
+suite clean across four runs (twelve total with the author's), and raised two
+design questions plus three minor notes. All five are addressed.
+
+- **Presence while in terminal mode (finding 1) — fix kept, prediction not
+  reproduced.** The review predicted that skipping the presence sweep freezes
+  `last_broadcast` at the abandoned document position, leaving peers painting a
+  stale caret. It does not: the buffer-follow clears the terminal declaration
+  when it ships the snapshot, so `terminal_active` is false on the tick a window
+  first shows a terminal, and the declaration cannot arrive until a later tick
+  (the frontend learns the buffer id FROM that snapshot). One truthful sweep
+  always lands first. A real-daemon two-frontend test written to catch the
+  freeze passes against the pre-fix tree — the bite is VACUOUS, and it is
+  labelled a regression guard rather than fix evidence. The skip is removed
+  anyway: it was load-bearing on tick ordering and bought nothing, and its
+  removal makes "presence follows the frontend" structural.
+- **Hover claimed durable control (finding 2) — real, fixed, bite-verified.**
+  `apply_terminal_gesture` claimed the controller before dispatching, including
+  for `Move`, which does nothing. A semantic frontend reports motion at pixel
+  rate, so sweeping the mouse across a PASSIVE split's terminal took durable
+  control and the next layout sync resized the shared PTY to that background
+  view's geometry — exactly the theft the controller rule exists to prevent.
+  Bare motion no longer claims; every deliberate gesture still does.
+  `scripts/bite HEAD src/editor.rs` on
+  `hover_does_not_steal_terminal_control_from_the_active_frontend` is a clean
+  behavioral bite (assertion failure, not a compile error).
+- **Terminal motion is deduplicated by cell (finding 3).** Sub-cell motion
+  resolved to the same coordinate and still crossed the wire, where each event
+  is a daemon-side gesture. `State::terminal_motion_is_new` now gates it, and
+  press/release re-arm the memo so the first drag after a press still reports.
+  Its unit test cannot bite — the seam did not exist pre-fix — and says so.
+- **Declarations record only once sent (finding 4).**
+  `terminal_declaration_if_changed` is now a pure query and
+  `note_terminal_declaration_sent` records, so a failed write is retried instead
+  of suppressed as already-declared. The existing `a35` test caught the contract
+  change and now pins both halves.
+- **Unchanged frames are no longer re-validated (finding 5).** The complete
+  payload comparison runs before `validate`; only validated frames are ever
+  stored, so a frame equal to the baseline has already passed. The chrome tail
+  is factored into `terminal_chrome` so both exits emit it identically.
+
+Post-review gates: `cargo fmt --check`; strict workspace Clippy; 1,757 default +
+1,933 CRDT library tests; Stage 1 acceptance 9/10, Stage 2 4/4, Stage 3 5/7,
+statusline 7/8 (default/CRDT); M4 120; required GPU 128; workspace sweep 2,921
+across 83 suites (19 ignored); `git diff --check` clean.
+
 ## 1. Problem and ownership boundary
 
 Pmacs can supervise a PTY and can parse enough ANSI to turn command output into
diff --git a/pmacs-gpu/src/main.rs b/pmacs-gpu/src/main.rs
index e18ce27..b6ef17d 100644
--- a/pmacs-gpu/src/main.rs
+++ b/pmacs-gpu/src/main.rs
@@ -683,9 +683,11 @@ fn run_headless_probe(socket: &Path, report: &Path) -> i32 {
                             0,
                         );
                     }
-                    if let Some((buffer_id, size)) = state.terminal_declaration_if_changed() {
+                    if let Some((buffer_id, size)) = state.terminal_declaration_if_changed()
+                        && client.send_terminal_resize(buffer_id, size).is_ok()
+                    {
                         facts.declarations += 1;
-                        let _ = client.send_terminal_resize(buffer_id, size);
+                        state.note_terminal_declaration_sent(buffer_id, size);
                     }
                 }
                 if state.terminal.is_some() {
@@ -706,11 +708,13 @@ fn run_headless_probe(socket: &Path, report: &Path) -> i32 {
                     if !sent_resize && facts.frames >= 2 {
                         sent_resize = true;
                         state.resize(700, 500);
-                        if let Some((buffer_id, size)) = state.terminal_declaration_if_changed() {
+                        if let Some((buffer_id, size)) = state.terminal_declaration_if_changed()
+                            && client.send_terminal_resize(buffer_id, size).is_ok()
+                        {
                             facts.declarations += 1;
                             facts.resized_cols = size.cols;
                             facts.resized_rows = size.rows;
-                            let _ = client.send_terminal_resize(buffer_id, size);
+                            state.note_terminal_declaration_sent(buffer_id, size);
                         }
                     }
                     if facts.resized_cols > 0 && facts.last_frame_cols == facts.resized_cols {
@@ -1217,6 +1221,12 @@ struct State {
     /// Whether an invalid terminal frame has already been reported.
     /// Bounds the log while a bad producer keeps sending.
     terminal_frame_error_latched: bool,
+    /// Last terminal cell a motion or drag was reported at. Pixel-rate
+    /// motion inside ONE cell is not new information for the daemon —
+    /// the document drag path dedupes by hit byte for the same reason.
+    /// Cleared on press, release, and every exit from terminal mode, so
+    /// a gesture that returns to the same cell still reports.
+    last_terminal_pointer_cell: Option<CellCoord>,
     /// One shaped buffer per planned text run. Rebuilt only when the
     /// plan changes, never per frame.
     terminal_text_buffers: Vec<Buffer>,
@@ -1496,8 +1506,9 @@ impl App {
         let Some((buffer_id, size)) = state.terminal_declaration_if_changed() else {
             return;
         };
-        if let Err(e) = client.send_terminal_resize(buffer_id, size) {
-            eprintln!("pmacs-gpu: send_terminal_resize failed: {e}");
+        match client.send_terminal_resize(buffer_id, size) {
+            Ok(()) => state.note_terminal_declaration_sent(buffer_id, size),
+            Err(e) => eprintln!("pmacs-gpu: send_terminal_resize failed: {e}"),
         }
     }
 
@@ -1818,13 +1829,22 @@ impl ApplicationHandler<AppEvent> for App {
                     if let Some((buffer_id, coord)) =
                         self.terminal_pointer_hit(position.x, position.y)
                     {
-                        let mods = translate_mods(self.modifiers);
-                        let kind = if dragging {
-                            ProtocolMouseKind::Drag(ProtocolMouseButton::Left)
-                        } else {
-                            ProtocolMouseKind::Move
-                        };
-                        self.send_terminal_pointer(buffer_id, coord, kind, mods);
+                        // Sub-cell motion resolves to the same cell and
+                        // carries nothing new. Report only on a cell
+                        // change, matching the document drag path's
+                        // hit-byte dedupe — otherwise pixel-rate motion
+                        // becomes pixel-rate wire traffic, and every one
+                        // of those is a daemon-side gesture.
+                        let state = self.state.as_mut().expect("checked above");
+                        if state.terminal_motion_is_new(coord) {
+                            let mods = translate_mods(self.modifiers);
+                            let kind = if dragging {
+                                ProtocolMouseKind::Drag(ProtocolMouseButton::Left)
+                            } else {
+                                ProtocolMouseKind::Move
+                            };
+                            self.send_terminal_pointer(buffer_id, coord, kind, mods);
+                        }
                     }
                     return;
                 }
@@ -1904,6 +1924,11 @@ impl ApplicationHandler<AppEvent> for App {
                             ProtocolMouseKind::Up(ProtocolMouseButton::Left)
                         }
                     };
+                    // A press or release always reports, and it re-arms
+                    // the motion dedupe: the first drag after a press
+                    // must reach the daemon even at the cell the press
+                    // landed on.
+                    state.last_terminal_pointer_cell = None;
                     if let Some((buffer_id, coord)) = self.terminal_pointer_hit(x, y) {
                         self.send_terminal_pointer(buffer_id, coord, kind, mods);
                     }
@@ -2813,6 +2838,7 @@ impl State {
             terminal: None,
             last_terminal_size_sent: None,
             terminal_frame_error_latched: false,
+            last_terminal_pointer_cell: None,
             terminal_text_buffers: Vec::new(),
             terminal_text_renderer,
         };
@@ -3884,6 +3910,7 @@ impl State {
         self.terminal_text_buffers.clear();
         self.terminal_frame_error_latched = false;
         self.last_terminal_size_sent = None;
+        self.last_terminal_pointer_cell = None;
     }
 
     /// Drop shaping and geometry caches without leaving terminal mode.
@@ -4159,10 +4186,32 @@ impl State {
         if self.last_terminal_size_sent == Some((buffer_id, size)) {
             return None;
         }
-        self.last_terminal_size_sent = Some((buffer_id, size));
         Some((buffer_id, size))
     }
 
+    /// Whether terminal motion at `coord` is new information.
+    ///
+    /// Records the cell as reported either way, so a caller that skips
+    /// the send still advances the memo. Press and release reset it
+    /// (`last_terminal_pointer_cell = None`), which is what lets the
+    /// first drag after a press reach the daemon even at the cell the
+    /// press landed on.
+    fn terminal_motion_is_new(&mut self, coord: CellCoord) -> bool {
+        let changed = self.last_terminal_pointer_cell != Some(coord);
+        self.last_terminal_pointer_cell = Some(coord);
+        changed
+    }
+
+    /// Record a declaration the caller actually put on the wire.
+    ///
+    /// Separate from [`Self::terminal_declaration_if_changed`] so a
+    /// FAILED send does not leave a size believed-declared: the daemon
+    /// would still hold the old geometry while this frontend suppressed
+    /// every retry as unchanged.
+    fn note_terminal_declaration_sent(&mut self, buffer_id: BufferId, size: CellSize) {
+        self.last_terminal_size_sent = Some((buffer_id, size));
+    }
+
     /// True while the completion popup is open **for the buffer this
     /// window currently shows** — the predicate the key gates (Esc,
     /// RET/TAB) and the render path share, so a stale mirror can
@@ -13117,9 +13166,20 @@ mod tests {
             .expect("a 400x300 window admits a cell grid");
         assert_eq!(first.0, buffer_id);
         assert!(first.1.rows >= 1 && first.1.cols >= 1);
+
+        // Review round 1, finding 4: the query does not record. Until
+        // the caller confirms the send, the declaration stays PENDING,
+        // so a failed write is retried rather than suppressed as
+        // already-declared.
+        assert_eq!(
+            state.terminal_declaration_if_changed(),
+            Some(first),
+            "an unsent declaration must still be offered"
+        );
+        state.note_terminal_declaration_sent(first.0, first.1);
         assert!(
             state.terminal_declaration_if_changed().is_none(),
-            "an unchanged size must be silent"
+            "an unchanged size must be silent once it has been sent"
         );
 
         // A real geometry change re-declares exactly once.
@@ -13128,6 +13188,7 @@ mod tests {
             .terminal_declaration_if_changed()
             .expect("a wider window is a new size");
         assert!(widened.1.cols > first.1.cols);
+        state.note_terminal_declaration_sent(widened.0, widened.1);
         assert!(state.terminal_declaration_if_changed().is_none());
 
         // A buffer switch forces a fresh declaration even at the same size.
@@ -13372,6 +13433,50 @@ mod tests {
         );
     }
 
+    /// Review round 1, finding 3: terminal motion reports only on a cell
+    /// change.
+    ///
+    /// A unit test on the memo rather than on the wire: the send site
+    /// lives in `window_event`, which needs a real winit event and a
+    /// live attach client. This cannot bite against the pre-fix tree —
+    /// the seam it calls did not exist there — so it is a contract pin,
+    /// not fix evidence.
+    #[test]
+    fn terminal_motion_reports_once_per_cell_and_rearms_on_press() {
+        let Some(mut state) = headless_or_skip(400, 300, "doc") else {
+            return;
+        };
+        let buffer_id = BufferId::next();
+        state.current_buffer_id = Some(buffer_id);
+        state.apply_terminal_frame(plain_terminal_frame(buffer_id, "abcd", 8));
+
+        let cell = CellCoord::new(0, 2);
+        assert!(state.terminal_motion_is_new(cell), "first sight of a cell");
+        assert!(
+            !state.terminal_motion_is_new(cell),
+            "sub-cell motion inside one cell is not new information"
+        );
+        assert!(
+            state.terminal_motion_is_new(CellCoord::new(0, 3)),
+            "crossing into another cell reports"
+        );
+
+        // A press/release re-arms the memo, so the first drag after a
+        // press reaches the daemon even at the press cell.
+        let press_cell = CellCoord::new(1, 1);
+        assert!(state.terminal_motion_is_new(press_cell));
+        state.last_terminal_pointer_cell = None;
+        assert!(
+            state.terminal_motion_is_new(press_cell),
+            "a press re-arms the memo at its own cell"
+        );
+
+        // Leaving terminal mode drops it too: the next terminal's cells
+        // are a different grid entirely.
+        state.exit_terminal_mode();
+        assert!(state.last_terminal_pointer_cell.is_none());
+    }
+
     /// Acceptance 36: the terminal statusline metadata reaches the band
     /// as text, never as a host-title or control effect.
     #[test]
diff --git a/src/daemon.rs b/src/daemon.rs
index 8ae640f..46ed1d1 100644
--- a/src/daemon.rs
+++ b/src/daemon.rs
@@ -1087,10 +1087,9 @@ fn dispatcher_loop(
             };
 
             // Vterm Stage 3 — a semantic frontend showing a terminal has
-            // no document cursor: the identity buffer is empty, so both
-            // presence and `CursorByte` would describe byte 0 of a
-            // buffer with no text, painting a phantom peer caret over
-            // the cell grid.
+            // no document cursor: the identity buffer is empty, so a
+            // `CursorByte` would describe byte 0 of a buffer with no
+            // text and scroll the frontend's document view against it.
             let terminal_mode = semantic_states
                 .get(fid)
                 .is_some_and(crate::semantic_render::SemanticRenderState::in_terminal_mode);
@@ -1098,12 +1097,33 @@ fn dispatcher_loop(
             // T M10.6 per-frontend presence sweep. The snapshot is
             // computed from this frontend's view; the sweep then
             // produces broadcasts to OTHER multi-frontend recipients.
-            let broadcasts = if terminal_mode {
-                Vec::new()
-            } else {
-                let snapshot = build_presence_snapshot(editor, *fid);
-                session_registry.sweep(&[(*fid, snapshot)])
-            };
+            //
+            // Terminal mode does NOT skip this (PR #135 review finding 1).
+            // `sweep` is diff-keyed on `last_broadcast`, so a skip can
+            // only ever FREEZE a frontend's presence — it can never
+            // retract it. Sweeping truthfully moves the presence into
+            // the terminal identity buffer, which is what takes this
+            // frontend's caret off every peer showing the document.
+            //
+            // Honest note on why the skip was not a live bug: the
+            // buffer-follow above clears the terminal declaration when
+            // it ships the snapshot, so `render_frame` reports
+            // `terminal_active == false` on the tick a window first
+            // shows a terminal, and the declaration cannot arrive until
+            // a later tick (the frontend learns the buffer id FROM that
+            // snapshot). Every entry into terminal mode is therefore
+            // already preceded by one truthful sweep. The skip was
+            // load-bearing on that ordering and bought nothing; removing
+            // it makes "presence follows the frontend" structural
+            // instead of a property of tick sequencing.
+            //
+            // The framing's "suppress presence for the terminal identity
+            // buffer" is a RENDER rule — no peer overlay is painted
+            // inside a terminal — which the GPU honors by not preparing
+            // the decoration batch in terminal mode. It was never a
+            // reason to stop telling peers where this frontend went.
+            let snapshot = build_presence_snapshot(editor, *fid);
+            let broadcasts = session_registry.sweep(&[(*fid, snapshot)]);
 
             // T M11.6 — DispatchIdle signal. `crdt_replica` frontends
             // gate their optimistic-apply path on this; we ship it
diff --git a/src/editor.rs b/src/editor.rs
index 8c844f9..bcba37c 100644
--- a/src/editor.rs
+++ b/src/editor.rs
@@ -1951,6 +1951,18 @@ impl EditorState {
             (status.at_bottom, modes, screen_size)
         };
 
+        // Hover is not an act of taking over a terminal (PR #135 review
+        // finding 2). Every other gesture is deliberate — a press, a
+        // release, a drag, a wheel tick, a right-click — but bare motion
+        // happens whenever a pointer crosses a window. A semantic
+        // frontend reports motion at pixel rate, so claiming on `Move`
+        // let merely sweeping the mouse across a PASSIVE split's
+        // terminal take durable control, and the next layout sync then
+        // resized the shared PTY to that background view's geometry.
+        // That is precisely the theft the controller rule exists to
+        // prevent.
+        let claims_control = !matches!(kind, TerminalMouseKind::Move);
+
         if !shift
             && at_bottom
             && modes.mouse_sgr
@@ -1958,12 +1970,16 @@ impl EditorState {
             && coord.col < screen_size.cols
             && let Some(bytes) = crate::terminal::input::encode_mouse(kind, coord, modifiers, modes)
         {
-            self.claim_terminal_controller(key);
+            if claims_control {
+                self.claim_terminal_controller(key);
+            }
             self.send_terminal_bytes(key.buffer_id, &bytes);
             return;
         }
 
-        self.claim_terminal_controller(key);
+        if claims_control {
+            self.claim_terminal_controller(key);
+        }
         let mut manager = self.terminal_manager.borrow_mut();
         match kind {
             TerminalMouseKind::ScrollUp => {
diff --git a/src/semantic_render.rs b/src/semantic_render.rs
index 2ba2f56..85b9753 100644
--- a/src/semantic_render.rs
+++ b/src/semantic_render.rs
@@ -853,17 +853,26 @@ impl SemanticRenderState {
 
         let mut out = Vec::new();
         let frame = snapshot.into_terminal_frame();
+        // Complete-payload comparison FIRST, and not on
+        // `screen_generation`: a scroll, a selection change, or a
+        // process exit must reach the frontend even though the screen
+        // itself is byte-identical.
+        //
+        // Comparing before validating is also what keeps the steady
+        // state cheap. Only validated frames are ever stored, so a frame
+        // equal to the baseline has already passed — re-running the
+        // per-cell width and topology checks every tick would recompute
+        // a verdict we hold.
+        if self.last_terminal_frame.as_ref() == Some(&frame) {
+            self.terminal_error_latched = false;
+            out.extend(self.terminal_chrome(state, buffer_id, statusline_evaluation));
+            return Some(out);
+        }
         match frame.validate() {
             Ok(()) => {
                 self.terminal_error_latched = false;
-                // Complete-payload comparison, not `screen_generation`:
-                // a scroll, a selection change, or a process exit must
-                // reach the frontend even though the screen itself is
-                // byte-identical.
-                if self.last_terminal_frame.as_ref() != Some(&frame) {
-                    self.last_terminal_frame = Some(frame.clone());
-                    out.push(InstanceMessage::TerminalFrame(frame));
-                }
+                self.last_terminal_frame = Some(frame.clone());
+                out.push(InstanceMessage::TerminalFrame(frame));
             }
             Err(error) => {
                 // Never emit a malformed or truncated frame. The peer
@@ -880,15 +889,33 @@ impl SemanticRenderState {
             }
         }
 
+        out.extend(self.terminal_chrome(state, buffer_id, statusline_evaluation));
+        Some(out)
+    }
+
+    /// The buffer-independent chrome a terminal-mode frontend still
+    /// needs, in the order the document path emits it.
+    ///
+    /// Shared by both terminal-pass exits so an unchanged frame and a
+    /// changed one ship exactly the same chrome — the suppression is
+    /// about the FRAME, never about the status band going quiet.
+    fn terminal_chrome(
+        &mut self,
+        state: &EditorState,
+        buffer_id: BufferId,
+        statusline_evaluation: Option<StatuslineEvaluation>,
+    ) -> Vec<InstanceMessage> {
+        let mut out = Vec::new();
         out.extend(self.status_facts_msg(state, buffer_id));
         out.extend(self.menu_prompt_msg(state, buffer_id));
         out.extend(self.minibuffer_prompt_msg(state, buffer_id));
         out.extend(self.theme_facts_msg(state));
         out.extend(self.font_facts_msg(state));
+        // Q#SL6/Q#SL8: face inventory must precede segment text.
         if let Some(evaluation) = statusline_evaluation {
             self.emit_statusline_segments(evaluation, &mut out);
         }
-        Some(out)
+        out
     }
 
     /// Apply the lead evaluator's publication outcome to the v18 wire
diff --git a/tests/vterm_stage3_acceptance.rs b/tests/vterm_stage3_acceptance.rs
index 80ef188..4a170af 100644
--- a/tests/vterm_stage3_acceptance.rs
+++ b/tests/vterm_stage3_acceptance.rs
@@ -767,6 +767,278 @@ fn a37_real_daemon_real_pty_and_headless_gpu_render_one_terminal_session() {
     );
 }
 
+/// Review round 1, finding 1: a frontend that enters terminal mode must
+/// still tell its peers it left the document.
+///
+/// **This is a regression guard, not a bite-verified fix.** The review
+/// predicted that skipping the presence sweep in terminal mode freezes
+/// `last_broadcast` at the abandoned document position. It does not, and
+/// this test passes against the pre-fix tree: the buffer-follow clears
+/// the terminal declaration when it ships the snapshot, so
+/// `terminal_active` is false on the tick a window first shows a
+/// terminal, and the declaration cannot arrive until a later tick — one
+/// truthful sweep always lands first. The skip was load-bearing on that
+/// ordering and bought nothing, so it is gone; this test pins the
+/// resulting invariant against a future reordering that would make the
+/// predicted freeze real.
+///
+/// Real daemon, real wire, two real frontends: presence delivery is a
+/// property of the dispatcher loop, not of any function it calls.
+#[cfg(feature = "crdt")]
+#[test]
+fn terminal_mode_keeps_reporting_presence_so_peers_drop_the_stale_caret() {
+    use pmacs::protocol::{
+        AttachRequest, FrontendCapabilities, Hello, Key, KeyEvent, PROTOCOL_VERSION, read_message,
+        write_message,
+    };
+    use std::os::unix::net::UnixStream;
+
+    fn attach(daemon: &common::daemon::TestDaemon, semantic: bool) -> (Hello, UnixStream) {
+        let mut stream = daemon.connect();
+        stream
+            .set_read_timeout(Some(Duration::from_secs(2)))
+            .expect("read timeout");
+        let hello: Hello = read_message(&mut stream).expect("read Hello");
+        let req = AttachRequest {
+            protocol_version: hello.protocol_version,
+            frontend_capabilities: FrontendCapabilities {
+                synchronized_output: false,
+                unicode_smp: true,
+                true_color: true,
+                mouse: false,
+                bracketed_paste: false,
+                terminal_kind: Some("acceptance".into()),
+                multi_frontend: true,
+                crdt_replica: true,
+                semantic_render: semantic,
+            },
+            initial_size: CellSize::new(24, 80),
+        };
+        write_message(&mut stream, &req).expect("write AttachRequest");
+        (hello, stream)
+    }
+
+    /// Pump one stream until `want` returns a value, or time out.
+    fn pump<T>(
+        stream: &mut UnixStream,
+        what: &str,
+        mut want: impl FnMut(&InstanceMessage) -> Option<T>,
+    ) -> T {
+        let deadline = Instant::now() + Duration::from_secs(20);
+        while Instant::now() < deadline {
+            match read_message::<InstanceMessage>(stream) {
+                Ok(msg) => {
+                    if let Some(found) = want(&msg) {
+                        return found;
+                    }
+                }
+                Err(_) => continue,
+            }
+        }
+        panic!("timed out waiting for {what}");
+    }
+
+    assert_eq!(PROTOCOL_VERSION, 19);
+    let daemon = common::daemon::TestDaemon::spawn_with_env_and_init(
+        &[
+            ("PMACS_INSTANCE_SEMANTIC_RENDER", "1"),
+            ("PMACS_INSTANCE_MULTI_FRONTEND", "1"),
+        ],
+        PROBE_INIT_LUA,
+    );
+
+    // B attaches FIRST. The presence sweep is diff-keyed, so A's very
+    // first snapshot is its only guaranteed broadcast — if B were not
+    // yet a registered recipient, that broadcast would reach nobody and
+    // A's presence would sit unchanged (and unsent) forever after.
+    let (_hello_b, mut b) = attach(&daemon, false);
+    // A is the semantic frontend that will open a terminal; B is the
+    // peer whose document view would keep painting A's stale caret.
+    let (hello_a, mut a) = attach(&daemon, true);
+    let a_id = hello_a.assigned_frontend_id;
+
+    // A declares a byte viewport so it is a live semantic session.
+    let document = pump(&mut a, "A's first BufferSnapshot", |msg| match msg {
+        InstanceMessage::BufferSnapshot { buffer_id, .. } => Some(*buffer_id),
+        _ => None,
+    });
+    write_message(
+        &mut a,
+        &pmacs::protocol::FrontendEvent::Viewport {
+            frontend_id: a_id,
+            buffer_id: document,
+            visible: pmacs::protocol::ByteRange { start: 0, end: 0 },
+            generation: 0,
+        },
+    )
+    .expect("A declares a viewport");
+
+    // B sees A in the document. Without this the later assertion could
+    // pass vacuously against a peer that never had presence at all.
+    let seen_in_document = pump(&mut b, "A's presence in the document", |msg| match msg {
+        InstanceMessage::PresenceUpdate {
+            frontend_id,
+            buffer_id,
+            ..
+        } if *frontend_id == a_id => Some(*buffer_id),
+        _ => None,
+    });
+    assert_eq!(seen_in_document, document);
+
+    // A opens a terminal through the bound chord and declares its cells.
+    write_message(
+        &mut a,
+        &pmacs::protocol::FrontendEvent::Key(KeyEvent {
+            frontend_id: a_id,
+            key: Key::Char('t'),
+            mods: Modifiers::CTRL | Modifiers::ALT,
+            timestamp_ns: 0,
+        }),
+    )
+    .expect("A opens a terminal");
+    let terminal = pump(&mut a, "A's terminal BufferSnapshot", |msg| match msg {
+        InstanceMessage::BufferSnapshot { buffer_id, .. } if *buffer_id != document => {
+            Some(*buffer_id)
+        }
+        _ => None,
+    });
+    write_message(
+        &mut a,
+        &pmacs::protocol::FrontendEvent::TerminalResize {
+            frontend_id: a_id,
+            buffer_id: terminal,
+            size: CellSize::new(12, 40),
+        },
+    )
+    .expect("A declares terminal cells");
+    // A really is in terminal mode once a frame arrives.
+    let framed = pump(&mut a, "A's first TerminalFrame", |msg| match msg {
+        InstanceMessage::TerminalFrame(frame) => Some(frame.buffer_id),
+        _ => None,
+    });
+    assert_eq!(framed, terminal);
+
+    // The finding: B must learn that A left the document.
+    let seen_after = pump(
+        &mut b,
+        "A's presence leaving the document",
+        |msg| match msg {
+            InstanceMessage::PresenceUpdate {
+                frontend_id,
+                buffer_id,
+                ..
+            } if *frontend_id == a_id && *buffer_id != document => Some(*buffer_id),
+            _ => None,
+        },
+    );
+    assert_eq!(
+        seen_after, terminal,
+        "A's presence must move into the terminal identity buffer, not freeze \
+         at the document position it abandoned"
+    );
+}
+
+/// Review round 1, finding 2: hover must not claim durable control.
+///
+/// A semantic frontend reports motion at pixel rate, so if bare `Move`
+/// claimed the controller, sweeping the mouse across a PASSIVE split's
+/// terminal would take it — and the next layout sync would resize the
+/// shared PTY to that background view's geometry. Every deliberate
+/// gesture still claims; only motion does not.
+#[test]
+fn hover_does_not_steal_terminal_control_from_the_active_frontend() {
+    let mut state = EditorState::new();
+    let owner = FrontendId(71);
+    let bystander = FrontendId(72);
+    let terminal_buffer = open_terminal(&mut state, "sleep 30", 6, 20);
+    tick_until(&mut state, Duration::from_secs(5), |state| {
+        state
+            .terminal_manager
+            .borrow()
+            .snapshot(terminal_buffer)
+            .is_some()
+    });
+    let owner_window = attach_view(&state, owner, terminal_buffer);
+    let bystander_window = attach_view(&state, bystander, terminal_buffer);
+
+    let owner_size = CellSize::new(6, 20);
+    let bystander_size = CellSize::new(4, 12);
+    let owner_key = TerminalViewKey::new(owner, owner_window, terminal_buffer);
+    let bystander_key = TerminalViewKey::new(bystander, bystander_window, terminal_buffer);
+    {
+        let mut manager = state.terminal_manager.borrow_mut();
+        assert!(manager.record_view_size(owner_key, owner_size));
+        assert!(manager.record_view_size(bystander_key, bystander_size));
+    }
+
+    // The owner takes control with a real press.
+    assert!(state.dispatch_semantic_terminal_pointer(
+        owner,
+        terminal_buffer,
+        CellCoord::new(0, 0),
+        MouseKind::Down(MouseButton::Left),
+        Modifiers::NONE,
+    ));
+    assert_eq!(
+        state.terminal_manager.borrow().controller(terminal_buffer),
+        Some(pmacs::terminal::TerminalController::from_view(owner_key)),
+        "a press claims control"
+    );
+
+    // The bystander merely hovers, repeatedly. Control must not move.
+    for col in 0..4 {
+        assert!(state.dispatch_semantic_terminal_pointer(
+            bystander,
+            terminal_buffer,
+            CellCoord::new(0, col),
+            MouseKind::Move,
+            Modifiers::NONE,
+        ));
+    }
+    assert_eq!(
+        state.terminal_manager.borrow().controller(terminal_buffer),
+        Some(pmacs::terminal::TerminalController::from_view(owner_key)),
+        "hovering a passive view must not take durable control"
+    );
+
+    // And the shared PTY keeps the controller's geometry: a stolen
+    // controller would resize it to the bystander's smaller view.
+    assert!(!state.sync_semantic_terminal_layout(bystander, terminal_buffer, bystander_size));
+    assert_eq!(
+        state
+            .terminal_manager
+            .borrow()
+            .snapshot(terminal_buffer)
+            .expect("snapshot")
+            .size,
+        owner_size,
+        "a hovered-over passive view must not resize the shared screen"
+    );
+
+    // A deliberate gesture from the bystander still claims, so the
+    // hover exemption is narrow rather than a dead controller path.
+    assert!(state.dispatch_semantic_terminal_pointer(
+        bystander,
+        terminal_buffer,
+        CellCoord::new(0, 1),
+        MouseKind::Down(MouseButton::Left),
+        Modifiers::NONE,
+    ));
+    assert_eq!(
+        state.terminal_manager.borrow().controller(terminal_buffer),
+        Some(pmacs::terminal::TerminalController::from_view(
+            bystander_key
+        )),
+        "a press still claims control"
+    );
+
+    state
+        .terminal_manager
+        .borrow_mut()
+        .terminate(terminal_buffer, &mut state.process_supervisor.borrow_mut())
+        .expect("terminate child");
+}
+
 /// Acceptance 30 (v18 half) and 28: a peer that negotiated v18 receives
 /// no terminal message at all and keeps the ordinary document path over
 /// the empty identity buffer.

From 9ff6a626238b97cf5e227cd0cf175950c5285119 Mon Sep 17 00:00:00 2001
From: Levi Neuwirth <ln@levineuwirth.org>
Date: Wed, 22 Jul 2026 15:33:26 -0400
Subject: [PATCH 5/7] fix(vterm): address stage 3 review round 2
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One real defect, three cleanups, and a named deferral.

A daemon disconnect in terminal mode hid the disconnect notice. The
Disconnected arm set the placeholder text but never left terminal mode,
where the document code layer is not prepared at all and the terminal glyph
layer keeps painting its last frame — so the user was left looking at a
frozen, live-looking terminal that silently ignored input. GPU auto-reconnect
is a named deferral, so that state persisted until relaunch. State::
on_daemon_disconnected now leaves terminal mode, forces a repaint even when
the notice text is byte-identical, and requests a redraw.

The fix and its test share a file, so scripts/bite's file granularity cannot
bite it; the equivalent was done by hand. Neutralizing only the
exit_terminal_mode() call makes the test fail on the "must leave terminal
mode" assertion; restoring it makes it pass.

sync_semantic_terminal_layout no longer clones the whole visible cell grid to
read one size. It ran every dispatcher tick for any semantic frontend with a
declared terminal; TerminalManager::screen_size reads the value from the
borrowed projection instead.

Inbound terminal events now require a negotiated v19 session. The outbound
TerminalFrame was gated twice while TerminalResize/TerminalPointer relied on
the frontend's send gate alone. A pre-v19 peer cannot construct those
variants, so this only refuses a hand-rolled client — and the a32 forgery
tests already prove such an event reaches nothing but the sender's own
authenticated active view — but the asymmetry was not deliberate.

A terminal-mode press that misses the grid no longer arms a drag, so a later
in-grid motion cannot send a Drag with no preceding Down. Daemon-side impact
was nil; the state is now honest. A release still always ends the drag.

The roadmap and handoff Arc 5 lines still said Stage 3 was framed and
awaiting approval, contradicting this PR's own ledger. Both corrected.

Named deferral: terminal wheel gestures discard scroll magnitude. One winit
wheel event becomes one gesture regardless of the lines it accumulated, while
the document path scrolls by lines. Closing it means either N gestures
(chattier) or a magnitude field on the pointer event — a protocol change.
Neither belongs in this stage.

Gates: fmt; strict workspace clippy; 1,758 default + 1,934 CRDT library
tests; Stage 1 9/10, Stage 2 4/4, Stage 3 5/7, statusline 7/8
(default/CRDT); M4 120; required GPU 129; workspace sweep 2,923 across 83
suites; diff check clean.
---
 docs/active-work.md     | 14 +++++--
 docs/agent-handoff.md   |  4 +-
 docs/roadmap-2026-07.md | 12 +++---
 docs/vterm-framing.md   | 51 +++++++++++++++++++++++++
 pmacs-gpu/src/main.rs   | 83 +++++++++++++++++++++++++++++++++++++++--
 src/daemon.rs           | 57 +++++++++++++++++++++++++++-
 src/editor.rs           | 10 ++---
 src/terminal/view.rs    | 13 ++++++-
 8 files changed, 223 insertions(+), 21 deletions(-)

diff --git a/docs/active-work.md b/docs/active-work.md
index eed0dcf..f3396d1 100644
--- a/docs/active-work.md
+++ b/docs/active-work.md
@@ -92,10 +92,18 @@ If it does not, stop and repair the remote/fetch configuration.
   clears the declaration before `render_frame`, so a truthful sweep always
   precedes terminal mode; that test is a labelled regression guard, not
   fix evidence.
-- Post-review gates: required GPU 128; workspace sweep 2,921 across 83
-  suites; Stage 3 acceptance 5 default / 7 CRDT; everything else as above.
+- Review round 2 addressed (framing §0.11): a daemon disconnect now leaves
+  terminal mode so the notice is visible (real defect, hand-verified
+  because fix and test share a file); the per-tick full-grid clone is
+  gone; inbound terminal events require a negotiated v19 session; a
+  grid-missing press no longer arms a drag; roadmap/handoff Arc 5 lines
+  corrected. Named deferral: terminal wheel gestures discard scroll
+  magnitude.
+- Post-round-2 gates: 1,758 default + 1,934 CRDT library tests; required
+  GPU 129; workspace sweep 2,923 across 83 suites; Stage 3 acceptance 5
+  default / 7 CRDT; M4 120; fmt, clippy, diff check clean.
 - Closed caveat: the once-seen required-GPU failure did not reproduce in
-  eight author runs plus four reviewer runs. Treated as environmental.
+  eight author runs plus five reviewer runs. Treated as environmental.
 - Next: further user review rounds on the PR.
 
 Recovery worktree:
diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md
index 9648dfe..a4a857f 100644
--- a/docs/agent-handoff.md
+++ b/docs/agent-handoff.md
@@ -353,8 +353,8 @@ commands, read `docs/active-work.md` immediately after this file.
   - **Arc 4 (themes + extensibility) COMPLETE** — named UI faces (#120),
     live GPU font preferences (#124), statusline providers (#125).
   - **Arc 5 terminal stage ACTIVE** — compile mode (#113), Vterm terminal
-    core (#126), and Vterm TUI (#130) landed; protocol/GPU Stage 3 is framed
-    and awaiting approval.
+    core (#126), and Vterm TUI (#130) landed; protocol/GPU Stage 3 is
+    implemented and in review as PR #135.
   - **Config registry COMPLETE (#127)** — not a numbered arc; it was the
     cross-cutting substrate ranked first on
     `docs/side-quest-backlog.md`'s north star, and it unblocks the
diff --git a/docs/roadmap-2026-07.md b/docs/roadmap-2026-07.md
index 9c1ef1c..e93f4f7 100644
--- a/docs/roadmap-2026-07.md
+++ b/docs/roadmap-2026-07.md
@@ -80,7 +80,7 @@ preference at protocol v17; and composable per-window
 `pmacs.statusline` providers transported to semantic/GPU frontends by
 protocol-v18 `StatuslineSegments`.
 
-### Arc 5 — Terminal, staged — VTERM STAGE 3 FRAMED
+### Arc 5 — Terminal, staged — VTERM STAGE 3 IN REVIEW
 
 - **Compile mode landed in #113**: line-oriented PTY/ANSI output,
   error-regex navigation, and `M-x compile`.
@@ -92,11 +92,11 @@ protocol-v18 `StatuslineSegments`.
 - **Vterm Stage 2 TUI landed in #130**: terminal-window composition,
   input/resize, per-context scroll/selection/copy, authenticated frontend
   ownership, BEL/clipboard drainage, and the strict Lua surface.
-- **Vterm Stage 3 protocol/GPU is framed at Revision 8**: additive protocol
-  v19 complete frames/events, an aggregate glyph-byte bound under the
-  unchanged transport cap, dual viewport bootstrap, authenticated semantic
-  routing, and native fixed-cell GPU terminal rendering. Implementation waits
-  for explicit framing approval.
+- **Vterm Stage 3 protocol/GPU is implemented and in review (PR #135)**:
+  additive protocol v19 complete frames/events, an aggregate glyph-byte bound
+  under the unchanged transport cap, dual viewport bootstrap, authenticated
+  semantic routing, and native fixed-cell GPU terminal rendering. Landing it
+  closes Arc 5's terminal stage.
 
 ### Arc 6 — Folding (keystone gutter rider)
 
diff --git a/docs/vterm-framing.md b/docs/vterm-framing.md
index ee0b59d..b1124c0 100644
--- a/docs/vterm-framing.md
+++ b/docs/vterm-framing.md
@@ -429,6 +429,57 @@ Post-review gates: `cargo fmt --check`; strict workspace Clippy; 1,757 default +
 statusline 7/8 (default/CRDT); M4 120; required GPU 128; workspace sweep 2,921
 across 83 suites (19 ignored); `git diff --check` clean.
 
+### 0.11 Stage 3 review round 2
+
+The second review verified all five round-1 fixes in code, re-ran the
+required-GPU suite clean (a thirteenth consecutive pass, closing the flake
+caveat), and found one new low-severity defect plus minor items.
+
+- **A disconnect in terminal mode hid the notice (finding 1) — real, fixed,
+  hand-verified.** `AttachEvent::Disconnected` set the placeholder text but
+  never left terminal mode, where the document code layer is not prepared at
+  all and the terminal glyph layer keeps painting its last frame. The user was
+  left looking at a frozen, live-looking terminal that silently ignored input —
+  and with GPU auto-reconnect a named deferral, until relaunch.
+  `State::on_daemon_disconnected` now leaves terminal mode, forces a repaint
+  even when the notice text is byte-identical, and requests a redraw. Its test
+  lives in the same file as the fix, so `scripts/bite`'s file granularity
+  cannot bite it; the equivalent was done by hand — neutralizing only the
+  `exit_terminal_mode()` call makes the test fail, restoring it makes it pass.
+- **Per-tick full-grid clone removed (finding 2).**
+  `sync_semantic_terminal_layout` compared geometry via `snapshot(..).size`,
+  cloning the whole visible cell grid every dispatcher tick to answer one
+  comparison. `TerminalManager::screen_size` reads it from the borrowed
+  projection instead.
+- **Roadmap and handoff Arc 5 lines corrected (finding 3).** Both still said
+  Stage 3 was framed and awaiting approval, contradicting this PR's own ledger.
+- **A press that misses the grid no longer arms a drag (nit).** It set
+  `pointer_drag_active` unconditionally, so a later in-grid motion sent a
+  `Drag` with no preceding `Down`. Daemon-side impact was nil
+  (`update_selection` bails without a drag anchor), but the state is now
+  honest. A release still always ends the drag, including one that wandered
+  outside the grid.
+- **Inbound terminal events now require a negotiated v19 session (finding 5).**
+  The outbound `TerminalFrame` was gated twice while the inbound declarations
+  relied on the frontend's send gate alone. A pre-v19 peer cannot construct
+  these variants, so this only refuses a hand-rolled client — and the a32
+  forgery tests already prove such an event reaches nothing but the sender's
+  own authenticated active view — but the asymmetry was not deliberate, and
+  "gated in both directions" should be true of the code rather than only of the
+  frontends we ship.
+
+Deferred from this round, named: **terminal wheel gestures discard scroll
+magnitude.** One winit wheel event becomes one terminal gesture regardless of
+the lines it accumulated, so a two-tick event scrolls the same distance as a
+one-tick event, while the document path scrolls by `lines`. Closing it means
+either sending N gestures (chattier) or widening the terminal pointer event
+with a magnitude — a protocol change. Not worth either inside this stage.
+
+Post-round-2 gates: `cargo fmt --check`; strict workspace Clippy; 1,758 default
++ 1,934 CRDT library tests; Stage 1 acceptance 9/10, Stage 2 4/4, Stage 3 5/7,
+statusline 7/8 (default/CRDT); M4 120; required GPU 129; workspace sweep 2,923
+across 83 suites (19 ignored); `git diff --check` clean.
+
 ## 1. Problem and ownership boundary
 
 Pmacs can supervise a PTY and can parse enough ANSI to turn command output into
diff --git a/pmacs-gpu/src/main.rs b/pmacs-gpu/src/main.rs
index b6ef17d..565e693 100644
--- a/pmacs-gpu/src/main.rs
+++ b/pmacs-gpu/src/main.rs
@@ -1914,12 +1914,21 @@ impl ApplicationHandler<AppEvent> for App {
                 }
                 let mods = translate_mods(self.modifiers);
                 if state.terminal.is_some() {
+                    let hit = self.terminal_pointer_hit(x, y);
+                    let state = self.state.as_mut().expect("checked above");
                     let kind = match button_state {
                         ElementState::Pressed => {
-                            state.pointer_drag_active = true;
+                            // A press that MISSES the grid (the status
+                            // band, the trailing padding) starts no
+                            // drag: arming the flag there would make a
+                            // later in-grid motion send a `Drag` with no
+                            // preceding `Down`.
+                            state.pointer_drag_active = hit.is_some();
                             ProtocolMouseKind::Down(ProtocolMouseButton::Left)
                         }
                         ElementState::Released => {
+                            // A release always ends the drag, including
+                            // one that wandered outside the grid.
                             state.pointer_drag_active = false;
                             ProtocolMouseKind::Up(ProtocolMouseButton::Left)
                         }
@@ -1929,7 +1938,7 @@ impl ApplicationHandler<AppEvent> for App {
                     // must reach the daemon even at the cell the press
                     // landed on.
                     state.last_terminal_pointer_cell = None;
-                    if let Some((buffer_id, coord)) = self.terminal_pointer_hit(x, y) {
+                    if let Some((buffer_id, coord)) = hit {
                         self.send_terminal_pointer(buffer_id, coord, kind, mods);
                     }
                     return;
@@ -2219,7 +2228,7 @@ impl ApplicationHandler<AppEvent> for App {
             }
             AppEvent::Attach(AttachEvent::Disconnected(reason)) => {
                 eprintln!("pmacs-gpu: daemon disconnected ({reason})");
-                state.set_text("(daemon disconnected)");
+                state.on_daemon_disconnected("(daemon disconnected)");
             }
         }
     }
@@ -3904,6 +3913,26 @@ impl State {
         }
     }
 
+    /// Show a disconnect notice, leaving terminal mode first.
+    ///
+    /// Terminal mode prepares NO document code layer, and the terminal
+    /// glyph layer keeps painting the last frame it was given. Setting
+    /// the text without leaving terminal mode therefore writes into a
+    /// layer nothing draws, and the user is left looking at a frozen,
+    /// live-looking terminal that silently ignores input — with GPU
+    /// auto-reconnect a named deferral, until relaunch. The F-008
+    /// "make the teardown visible" contract applies to terminal mode
+    /// too.
+    fn on_daemon_disconnected(&mut self, notice: &str) {
+        self.exit_terminal_mode();
+        if !self.set_text(notice) {
+            // Byte-identical text still needs a repaint: the frame that
+            // is on screen is the terminal's, not this notice.
+            self.reshape();
+        }
+        self.request_redraw();
+    }
+
     /// Leave terminal mode and drop every terminal-only cache.
     fn exit_terminal_mode(&mut self) {
         self.terminal = None;
@@ -13477,6 +13506,54 @@ mod tests {
         assert!(state.last_terminal_pointer_cell.is_none());
     }
 
+    /// Review round 2, finding 1: a disconnect must leave terminal mode,
+    /// or the notice is invisible.
+    ///
+    /// Terminal mode prepares no document code layer while the terminal
+    /// glyph layer keeps painting its last frame, so a notice written
+    /// without leaving terminal mode never reaches the screen and the
+    /// user sees a frozen terminal that ignores input.
+    #[test]
+    fn a_disconnect_leaves_terminal_mode_so_the_notice_is_visible() {
+        let Some(mut state) = headless_or_skip(400, 300, "document text") else {
+            return;
+        };
+        let buffer_id = BufferId::next();
+        state.current_buffer_id = Some(buffer_id);
+        state.apply_terminal_frame(plain_terminal_frame(buffer_id, "live", 8));
+        assert!(
+            state.terminal.is_some(),
+            "the probe starts in terminal mode"
+        );
+        let terminal_px = state.render_offscreen();
+
+        state.on_daemon_disconnected("(daemon disconnected)");
+        assert!(
+            state.terminal.is_none(),
+            "a disconnect must leave terminal mode"
+        );
+        assert!(
+            state.terminal_text_buffers.is_empty(),
+            "terminal-only caches go with it"
+        );
+        assert_eq!(state.current_text, "(daemon disconnected)");
+
+        // The notice actually reaches the screen: the frame differs from
+        // the terminal frame it replaced, which is the whole point of
+        // the fix.
+        let notice_px = state.render_offscreen();
+        let differing = terminal_px
+            .iter()
+            .zip(&notice_px)
+            .filter(|(a, b)| a != b)
+            .count();
+        assert!(
+            differing > 500,
+            "the disconnect notice must repaint over the frozen terminal \
+             ({differing} bytes differ)"
+        );
+    }
+
     /// Acceptance 36: the terminal statusline metadata reaches the band
     /// as text, never as a host-title or control effect.
     #[test]
diff --git a/src/daemon.rs b/src/daemon.rs
index 46ed1d1..fe28112 100644
--- a/src/daemon.rs
+++ b/src/daemon.rs
@@ -799,6 +799,26 @@ fn peer_accepts_statusline_message(protocol_version: u32, message: &InstanceMess
     protocol_version >= 18 || !matches!(message, InstanceMessage::StatuslineSegments { .. })
 }
 
+/// Whether a session negotiated the v19 wire, and may therefore drive
+/// terminal state inbound.
+///
+/// The outbound `TerminalFrame` is gated twice — in the producer and in
+/// the write loop — and the inbound direction is now symmetric. A
+/// pre-v19 peer cannot construct these variants at all (its enum lacks
+/// them), so this only ever refuses a hand-rolled client; the a32
+/// forgery tests already prove such an event can reach nothing but the
+/// sender's own authenticated active view. It is defense in depth, and
+/// it makes "gated in both directions" true of the code rather than
+/// only of the frontends we ship.
+fn peer_declared_terminal_support(
+    session_registry: &SessionRegistry,
+    frontend_id: FrontendId,
+) -> bool {
+    session_registry
+        .session_state(frontend_id)
+        .is_some_and(|state| state.negotiated_protocol_version >= 19)
+}
+
 /// The same belt-and-braces write-loop gate for the additive
 /// protocol-v19 terminal frame. The semantic producer skips construction
 /// for an older peer; this filter independently prevents an unknown
@@ -1735,6 +1755,7 @@ fn handle_dispatcher_event(
                     // the durable controller's declaration reaches the
                     // shared PTY — a declaration never claims control.
                     if semantic_states.contains_key(&source)
+                        && peer_declared_terminal_support(session_registry, source)
                         && editor.semantic_terminal_declaration_is_active(source, buffer_id)
                     {
                         if let Some(sem) = semantic_states.get_mut(&source) {
@@ -1757,7 +1778,9 @@ fn handle_dispatcher_event(
                     // forged id, a stale buffer, a missing declaration,
                     // or an out-of-bounds cell all drop before any view,
                     // controller, selection, menu, or PTY mutation.
-                    if semantic_states.contains_key(&source) {
+                    if semantic_states.contains_key(&source)
+                        && peer_declared_terminal_support(session_registry, source)
+                    {
                         editor.dispatch_semantic_terminal_pointer(
                             source, buffer_id, coord, kind, mods,
                         );
@@ -2854,6 +2877,38 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn inbound_terminal_events_require_a_negotiated_v19_session() {
+        // Review round 2, finding 5: the outbound `TerminalFrame` was
+        // gated twice (producer + write loop) while the inbound
+        // declarations relied on the frontend's send gate alone. A
+        // pre-v19 peer cannot construct these variants, so this only
+        // refuses a hand-rolled client — but it makes "gated in both
+        // directions" true of the code, not just of the frontends we
+        // ship.
+        let mut registry = SessionRegistry::new();
+        let semantic = crate::protocol::NegotiatedCapabilities {
+            multi_frontend: true,
+            crdt_replica: true,
+            semantic_render: true,
+        };
+        let old_peer = FrontendId(2);
+        let new_peer = FrontendId(3);
+        registry.register_session(
+            old_peer,
+            crate::presence::SessionState::new(18, semantic, 0),
+        );
+        registry.register_session(
+            new_peer,
+            crate::presence::SessionState::new(19, semantic, 1),
+        );
+
+        assert!(!peer_declared_terminal_support(&registry, old_peer));
+        assert!(peer_declared_terminal_support(&registry, new_peer));
+        // An unknown session is refused rather than defaulted open.
+        assert!(!peer_declared_terminal_support(&registry, FrontendId(99)));
+    }
+
     #[test]
     fn build_identity_includes_version_and_uptime() {
         let s = DaemonState::new(Some("research".into()));
diff --git a/src/editor.rs b/src/editor.rs
index bcba37c..6ac3509 100644
--- a/src/editor.rs
+++ b/src/editor.rs
@@ -1215,11 +1215,11 @@ impl EditorState {
         if !controls {
             return false;
         }
-        let old_size = self
-            .terminal_manager
-            .borrow()
-            .snapshot(buffer_id)
-            .map(|snapshot| snapshot.size);
+        // Read the size from the borrowed projection rather than a
+        // snapshot: this runs every dispatcher tick, and
+        // `snapshot(..).size` would clone the whole visible grid to
+        // answer one comparison.
+        let old_size = self.terminal_manager.borrow().screen_size(buffer_id);
         if old_size == Some(size) {
             return false;
         }
diff --git a/src/terminal/view.rs b/src/terminal/view.rs
index d79d8b6..5d9d311 100644
--- a/src/terminal/view.rs
+++ b/src/terminal/view.rs
@@ -248,8 +248,19 @@ impl TerminalManager {
     /// Return the publication-consistent child grid size for one view.
     #[must_use]
     pub(crate) fn screen_size_for_view(&self, key: TerminalViewKey) -> Option<CellSize> {
+        self.screen_size(key.buffer_id)
+    }
+
+    /// The shared screen's current size, read from the borrowed
+    /// projection.
+    ///
+    /// Deliberately not `snapshot(..).size`: that clones the whole
+    /// visible cell grid, and geometry comparison runs on every
+    /// dispatcher tick for every frontend with a declared terminal.
+    #[must_use]
+    pub fn screen_size(&self, buffer_id: BufferId) -> Option<CellSize> {
         self.sessions
-            .get(&key.buffer_id)
+            .get(&buffer_id)
             .map(|session| session.screen.projection_ref().size)
     }
 

From 36182896331dc3bedb976c64e2443e5b8df5d2cf Mon Sep 17 00:00:00 2001
From: Levi Neuwirth <ln@levineuwirth.org>
Date: Wed, 22 Jul 2026 15:36:51 -0400
Subject: [PATCH 6/7] docs(vterm): record the #135/#137 rebase-and-regate
 constraint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR #137 (tab-width-parity) is approved and frozen at 5b23e11. Neither
lane copies from or merges the other; whichever lands second rebases
onto the canonical resulting main and reruns the complete gate suite.

The overlap is pmacs-gpu/src/main.rs, pmacs-protocol/src/lib.rs,
Cargo.lock, and the two ledger docs. The lock and docs are mechanical;
the two source files are not — both PRs edit the GPU renderer's
measurement path and widen the protocol crate's export surface in the
same region, so a conflict-free apply is not evidence of a correct
merge.
---
 docs/active-work.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/active-work.md b/docs/active-work.md
index f3396d1..1673ca2 100644
--- a/docs/active-work.md
+++ b/docs/active-work.md
@@ -115,6 +115,38 @@ git worktree add --track \
   githubsucks/vterm-gpu
 ```
 
+## Cross-PR coordination: #135 and #137 overlap
+
+Two PRs are open against canonical `main` at once and they touch the same
+files. **Neither lane copies from or merges the other.** PR #137
+(`tab-width-parity`, "feat(render): unify tab-width projection") is
+APPROVED and FROZEN at `5b23e11`; this lane must not cherry-pick, merge,
+or otherwise absorb it.
+
+**Whichever PR lands SECOND rebases onto the canonical resulting `main`
+and reruns the COMPLETE gate suite** — not a subset, and not the
+pre-rebase results. The overlap is in the renderer and the protocol
+crate's export surface, so a clean textual merge does not imply a
+correct one.
+
+Overlapping paths, and why each one collides:
+
+| Path | #135 (vterm stage 3) | #137 (tab width) |
+| --- | --- | --- |
+| `pmacs-gpu/src/main.rs` | terminal mode: `State` fields, render-batch swaps, input branches, headless probe | tab-width projection in the same renderer |
+| `pmacs-protocol/src/lib.rs` | `pub mod terminal` + the terminal re-export block | its own added export |
+| `Cargo.lock` | `unicode-width` promoted to a workspace dep for `pmacs-protocol` | a `pmacs-gpu` dependency change |
+| `docs/active-work.md`, `docs/agent-handoff.md` | this lane's entries and §1 snapshot | its own entries |
+
+`Cargo.lock` and the docs are mechanical. The two source files are not:
+both PRs edit the GPU renderer's measurement/paint path, and both widen
+`pmacs-protocol`'s public surface in the same `pub use` region. After the
+rebase, re-read the merged region rather than trusting a conflict-free
+apply — in particular that terminal cell geometry (`cell_viewport`,
+`hit_test_cell`, `terminal_run_rect`) still uses the monospace advance
+and is not routed through any new tab-expansion path, since terminal
+columns come from the child and never from document projection.
+
 ## Vterm Stage 3 framing lane (superseded)
 
 - Portable branch: `githubsucks/vterm-stage3-framing`

From 27120e7540a59a752b6fbb96211fa92ebe9068e1 Mon Sep 17 00:00:00 2001
From: Levi Neuwirth <ln@levineuwirth.org>
Date: Wed, 22 Jul 2026 19:13:02 -0400
Subject: [PATCH 7/7] docs(vterm): record the deleted framing/tab-width
 branches
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

vterm-stage3-framing (superseded; content carried on vterm-gpu) and
tab-width-parity (merged via #137) were deleted with authorization —
worktree + local ref + githubsucks ref, origin tracking pruned. The
-framing branches for each are kept. Retires the now-dangling
superseded-lane recovery entry.
---
 docs/active-work.md | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/docs/active-work.md b/docs/active-work.md
index ab47d8a..154da9d 100644
--- a/docs/active-work.md
+++ b/docs/active-work.md
@@ -164,13 +164,6 @@ still uses the monospace advance and is not routed through
 expansion is a DOCUMENT projection concern. That is verified rather than
 assumed — see the integration gates on the lane above.
 
-## Vterm Stage 3 framing lane (superseded)
-
-- Portable branch: `githubsucks/vterm-stage3-framing`
-- Revision 8 framing, reviewed and approved. Its content is carried on
-  `vterm-gpu`; this branch is kept only as the approval record and has no
-  unmerged runtime work.
-
 ## Parked lane: kill-ring browser + persistence
 
 - Portable branch: `githubsucks/kill-ring-browser`
@@ -207,11 +200,22 @@ git worktree add --track \
 
 ## Closed since the last snapshot
 
+- **Branches deleted 2026-07-22 (authorized):** `vterm-stage3-framing`
+  (Revision 8 framing; its content is carried on `vterm-gpu`, verified as a
+  superset before deletion — the branch was NOT an ancestor of `vterm-gpu`
+  because the framing was copied rather than merged, so it needed a forced
+  local delete) and `tab-width-parity` (a clean ancestor of `main` via
+  #137). Both removed as worktree + local ref + `githubsucks` ref; the
+  `origin` tracking refs were pruned. The `-framing` branches for each are
+  deliberately kept.
+
 - **Tab-width rendering parity — MERGED as #137** (`main` @ `2625ec7`,
   2026-07-22). One fixed 8-column `TAB_STOP_COLUMNS` in `pmacs-protocol`
   now drives core/TUI columns, GPU code projection, and minimap width;
-  source bytes and protocol ranges are unchanged. Its lane and worktree
-  are done. This closes the long-standing "tab width is a rendering-parity
+  source bytes and protocol ranges are unchanged. Its lane, worktree, and
+  `tab-width-parity` branch (local + `githubsucks`) are deleted; the
+  `tab-width-parity-framing` branch is kept. This closes the long-standing
+  "tab width is a rendering-parity
   bug, NOT a config gap" deferral recorded in `docs/agent-handoff.md` §5.
 - **Locals-query processing — MERGED as #134** (with handoff #136), and
   **modeline detection handoff #133**. Both landed between this lane's