docs: record Vterm Stage 3 landing

Advance canonical state to protocol v19, close the Vterm lane and roadmap arc, preserve the cross-PR integration lesson, mark PR #91 landed, and point machine-local housekeeping at the durable policy.

docs/active-work.md

@@ -14,8 +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` @ `2625ec7` (tab-width parity #137 merged atop
+  `githubsucks/main` @ `cac4961` (Vterm Stage 3 #135 merged after tab-width
-  locals-query #134 and modeline detection #132; protocol v18 on `main`).
+  parity #137; protocol v19).
 - 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
@@ -49,121 +49,9 @@ git worktree list
 git status --short --branch
 ```
 
-The first command must expose `2625ec7` or a newer intentional main.
+The first command must expose `cac4961` or a newer intentional main.
 If it does not, stop and repair the remote/fetch configuration.
 
-## Vterm Stage 3 implementation lane
-
-- Portable branch: `githubsucks/vterm-gpu`
-- Framing carried as the first commit; implementation follows it.
-- Base: cut from canonical `main` @ `1dd47fc`, NOT stacked on
-  `vterm-stage3-framing`, per the framing's §8. Canonical `main` @
-  `2625ec7` (tab-width parity #137, locals-query #134, modeline handoff
-  #133/#136) is MERGED IN — see the integration entry below.
-- 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)
-  (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`.
-- 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.
-- 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 (pre-integration): 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.
-- **Post-integration gates (canonical `main` @ `2625ec7` merged in):**
-  `cargo fmt --check`; strict workspace Clippy; `pmacs-protocol` 17;
-  `cargo test --lib` 1,768; `--features crdt` 1,944 (3 ignored each);
-  vterm Stage 1 9/10, Stage 2 4/4, Stage 3 5/7, statusline 7/8, tab-width
-  2/2 (default/CRDT); M4 121 passed (3 ignored, 1 filtered); required GPU
-  139; workspace sweep 2,946 passed across 84 suites (19 ignored), one
-  invocation; `git diff --check` clean.
-- Closed caveat: the once-seen required-GPU failure did not reproduce in
-  eight author runs plus five reviewer runs. Treated as environmental.
-- Canonical-main integration after #137 landed: the agreed order was
-  #137 first (it was approved and FROZEN at `5b23e11`, so it could not
-  absorb a rebase without breaking its freeze), then this lane second.
-  Integrated by MERGING canonical main into the branch, matching repo
-  precedent (`Merge canonical main into vterm-tui`, `… into modeline
-  detection`) rather than a rebase, which would have force-pushed away
-  the review anchors on #135. Main had also moved past this lane's base
-  by #133/#134/#136, so the integration surface was wider than the
-  #135/#137 overlap: `src/semantic_render.rs` was a fourth overlapping
-  code file and auto-merged, as did `pmacs-protocol/src/lib.rs`. The one
-  code conflict was the `pmacs_protocol` import list in
-  `pmacs-gpu/src/main.rs` (`TAB_STOP_COLUMNS` against the terminal
-  types) — resolved as a union.
-- Next: further user review rounds on the PR.
-
-Recovery worktree:
-
-```sh
-git worktree add --track \
-  -b vterm-gpu \
-  ../pmacs-vterm-gpu \
-  githubsucks/vterm-gpu
-```
-
-
-## Cross-PR coordination: #135 and #137 (resolved)
-
-**Resolved 2026-07-22: #137 merged first, #135 integrated second.** Kept
-as the worked example, because the deciding argument is reusable.
-
-#137 was APPROVED and FROZEN at `5b23e11`. "Frozen" and "rebase onto the
-resulting main" are mutually exclusive, so the frozen PR had to land
-first — the alternative would have broken its freeze and voided its
-approval. Three arguments pointed the same way: the approved PR should
-not wait on an unapproved one; the PR carrying the protocol byte pins
-should be the one that integrates, because its own suite is what detects
-a disturbed discriminant; and the larger, more invasive change should
-pay the integration cost, since its author has the context to verify the
-merged result.
-
-The named overlap (`pmacs-gpu/src/main.rs`, `pmacs-protocol/src/lib.rs`,
-`Cargo.lock`, both ledger docs) was accurate but incomplete — main had
-also moved by #133/#134/#136, making `src/semantic_render.rs` a fourth
-overlapping code file. **Lesson: derive the integration surface from
-`git diff <base>..main`, not from the other PR's file list.**
-
-The feared semantic collision did not occur. Terminal cell geometry
-still uses the monospace advance and is not routed through
-`TAB_STOP_COLUMNS`: terminal columns come from the child, and tab
-expansion is a DOCUMENT projection concern. That is verified rather than
-assumed — see the integration gates on the lane above.
-
 ## Parked lane: kill-ring browser + persistence
 
 - Portable branch: `githubsucks/kill-ring-browser`

docs/agent-handoff.md

@@ -1,12 +1,10 @@
 # Agent handoff — cross-machine continuity
 
-**Last updated: 2026-07-22, after tab-width rendering parity (#137) and
+**Last updated: 2026-07-22, after Vterm Stage 3 (#135, protocol v19 and
-locals-query processing (#134) landed on `main`, and canonical `main` was
+native GPU terminal) landed on `main`, following tab-width rendering parity
-merged into the Vterm Stage 3 lane. Vterm Stage 3 (protocol v19, GPU
+(#137), locals-query processing (#134), modeline detection (#132), mode system
-terminal) is implemented on `vterm-gpu` and in review as PR #135; see
+wiring (#129), config registry (#127), Vterm Stages 1–2 (#126/#130), and
-`docs/active-work.md`. Vterm Stage 2 (#130), modeline detection (#132),
+completed Themes Arc 4 (#120/#124/#125).**
-mode system wiring (#129), config registry (#127), Vterm Stage 1 (#126),
-and completed Themes Arc 4 (#120/#124/#125) are on `main`.**
 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`
@@ -20,10 +18,9 @@ commands, read `docs/active-work.md` immediately after this file.
 
 ## 1. Where the project stands (2026-07-22)
 
-- `main` @ `2625ec7` (tab-width parity #137 atop locals-query #134),
+- `main` @ `cac4961` (Vterm Stage 3 #135 atop tab-width parity #137),
-  protocol **v18** on `main`, **v19** on `vterm-gpu`
+  protocol **v19** (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`, v17 =
-  (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`, v17 =
+  `FontFacts`, v18 = `StatuslineSegments`, v19 = terminal frames/events).
-  `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
@@ -268,11 +265,11 @@ 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 GPU/protocol is IMPLEMENTED on `vterm-gpu`** (framing
+  - **Stage 3 GPU/protocol LANDED ON `main` — #135** (merge `cac4961`;
-    `docs/vterm-framing.md` Revision 9, criteria 28-37; awaiting review).
+    `docs/vterm-framing.md` Revision 9, criteria 28–37).
     Protocol **v19**: `InstanceMessage::TerminalFrame` (discriminant 26,
     daemon-gated) plus `FrontendEvent::TerminalResize` (11) and
-    `TerminalPointer` (12), both frontend-gated - the first bump gating in
+    `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
@@ -300,6 +297,16 @@ commands, read `docs/active-work.md` immediately after this file.
     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.
+  - #135 integrated canonical `main` after #137 landed. The one code conflict
+    joined `TAB_STOP_COLUMNS` with the terminal imports in
+    `pmacs-gpu/src/main.rs`; terminal geometry remains fixed-cell and never
+    consumes the document tab-stop projection.
+  - Final post-integration gates: strict Clippy; 1,768 default + 1,944 CRDT
+    library tests; Vterm Stages 1/2/3 at 9/10, 4/4, and 5/7 default/CRDT;
+    statusline 7/8; tab-width 2/2; M4 121; required GPU 139; workspace 2,946
+    passed across 84 suites; formatting and diff check clean. The first
+    macOS/LuaJIT CI run timed out waiting for `VTERM_ALT_READY` in the Stage 2
+    real-TUI smoke; the complete failed-job rerun passed all 12 checks.
   - **Stage 2 TUI LANDED ON `main` — #130** (merge `86fc1bc`;
     `docs/vterm-framing.md` Revision 7, criteria 15–27). `TerminalViewKey` keys
     per-frontend/window projection state over one shared process/screen; logical
@@ -324,8 +331,8 @@ commands, read `docs/active-work.md` immediately after this file.
     and pure `ui.modeline.terminal` process/scroll segment.
   - `tests/vterm_stage2_acceptance.rs` maps Lua transactionality, shared-view
     isolation, clipboard/modeline behavior, and a hermetic real `/bin/sh` TUI
-    PTY smoke. Stage 2 changes no wire schema or GPU renderer; protocol remains
+    PTY smoke. Stage 2 changed no wire schema or GPU renderer; protocol
-    v18 until Stage 3.
+    remained v18 until Stage 3.
   - PR #130 review round 1 (`8702791`) aligned dispatch with the approved
     escape-prefix contract, closed the non-terminal Lua error path, made
     controller replacement atomic, retained zero-area view anchors, removed
@@ -388,9 +395,8 @@ 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), Vterm terminal
+  - **Arc 5 terminal stage COMPLETE** — compile mode (#113), Vterm terminal
-    core (#126), and Vterm TUI (#130) landed; protocol/GPU Stage 3 is
+    core (#126), TUI frontend (#130), and protocol/GPU Stage 3 (#135) landed.
-    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
@@ -459,11 +465,16 @@ before trusting them:
   `m6_8_supervisor_reaps_all_children_across_cycles`) are timing-based;
   `editor::composition_overhead_under_ten_percent` is a render-ratio
   microbenchmark that fails ~1/3 even isolated single-threaded (already
-  `cfg!(macos)`-disabled). A lone failure of one of these → rerun that
+  `cfg!(macos)`-disabled). Vterm Stage 3's merge CI saw one macOS timeout in
-  test alone (`-- --test-threads=1`) before investigating. Also: run the
+  `real_tui_terminal_smoke_restores_host_after_output_input_resize_scroll_copy_and_bell`;
-  workspace sweep as ONE `cargo test` invocation piped to a full log — a
+  the complete failed-job rerun passed. The required-GPU gate also failed once
-  double invocation + `grep -c "test result: ok"` can mask real
+  in `headless_diag_face_recolors_band_counter_despite_unchanged_text`, then
-  failures with a misleading `0`.
+  passed both an isolated single-thread rerun and the full 139-test rerun. A
+  lone timing failure → rerun the test alone (`-- --test-threads=1`) before
+  investigating. Run the workspace
+  sweep as ONE `cargo test` invocation piped to a full log — a double
+  invocation + `grep -c "test result: ok"` can mask real failures with a
+  misleading `0`.
 - **GPU tests** need a Vulkan device. `PMACS_REQUIRE_GPU=1` makes
   absence a hard failure instead of a silent skip. Headless option:
   lavapipe (see `docs/repository-audit-2026-07-03.md` for the CI
@@ -543,6 +554,12 @@ cannot detect a discriminant shift.
 - **Stacked PRs**: retarget the child to main BEFORE merging the
   parent — GitHub auto-closes a PR whose base branch is deleted and
   cannot reopen it (#104 → re-opened as #105).
+- **Frozen reviewed PRs do not absorb moving overlapping work.** For #135 and
+  #137, the approved/frozen #137 landed first; the larger #135 lane then
+  merged canonical `main`, retained its review anchors, and reran every gate.
+  Derive that integration surface from `git diff <base>..main`, not the other
+  PR's file list — concurrent landed work added an overlap the original
+  two-PR comparison missed.
 - **Scripted edits (sed/python) in files with repeated similar blocks**
   (`src/lsp.rs` JSON builders): anchor on a unique line or you will
   silently edit the wrong block. This produced a vacuously-passing test

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 IN REVIEW
+### Arc 5 — Terminal, staged — COMPLETE
 
 - **Compile mode landed in #113**: line-oriented PTY/ANSI output,
   error-regex navigation, and `M-x compile`.
@@ -92,13 +92,12 @@ 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 implemented and in review (PR #135)**:
+- **Vterm Stage 3 protocol/GPU landed in #135**: additive protocol-v19
-  additive protocol v19 complete frames/events, an aggregate glyph-byte bound
+  complete frames/events, an aggregate glyph-byte bound under the unchanged
-  under the unchanged transport cap, dual viewport bootstrap, authenticated
+  transport cap, dual viewport bootstrap, authenticated semantic routing, and
-  semantic routing, and native fixed-cell GPU terminal rendering. The 16 MiB
+  native fixed-cell GPU terminal rendering. The 16 MiB transport cap is
-  transport cap is preserved: the measured legal-worst frame encodes to
+  preserved: the measured legal-worst frame encodes to 13,437,863 bytes under
-  13,437,863 bytes under an 8 MiB aggregate glyph bound, never chunked.
+  an 8 MiB aggregate glyph bound, never chunked.
-  Landing it closes Arc 5's terminal stage.
 
 ### Arc 6 — Folding (keystone gutter rider)
 
@@ -122,11 +121,10 @@ after daemon restart, cursor blink, font/theme config (overlaps Arc 4).
 
 ## Housekeeping (do opportunistically)
 
-- Merge PR #91 (gutter click classification + fit guard).
+- ~~Merge PR #91 (gutter click classification + fit guard).~~ Landed on
-- Delete or mark-superseded stale docs: `pmacs-gpu-editing-perf-handoff.md`
+  2026-07-07.
-  (freeze fixed by PR #60 arc), `session-5-stale-styling-handover.md`
+- Machine-local handoff/experiment files are intentionally untracked; see
-  (fixed, task #25 closed), `python_experiment.md`, `#run.sh#`,
+  `docs/agent-handoff.md` §7. They are not repository housekeeping targets.
-  `semantic-frontend-protocol.md.local-bak`.
 - `V0.2-PREREQUISITES.md` cited twice by CHANGELOG but missing on disk —
   reconstruct or unlink.
 - README still leads with "What v0.1 ships with" — refresh.