neuwirth
/
pmacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Levi Neuwirth 2026-07-22 19:54:14 -04:00
parent cac4961c73
commit e316ba3a27
3 changed files with 55 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
docs/active-work.md
View File

@ -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
locals-query #134 and modeline detection #132; protocol v18 on `main`).
`githubsucks/main` @ `cac4961` (Vterm Stage 3 #135 merged after tab-width
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`

65
docs/agent-handoff.md
View File

@ -1,12 +1,10 @@
# Agent handoff — cross-machine continuity
**Last updated: 2026-07-22, after tab-width rendering parity (#137) and
locals-query processing (#134) landed on `main`, and canonical `main` was
merged into the Vterm Stage 3 lane. Vterm Stage 3 (protocol v19, GPU
terminal) is implemented on `vterm-gpu` and in review as PR #135; see
`docs/active-work.md`. Vterm Stage 2 (#130), modeline detection (#132),
mode system wiring (#129), config registry (#127), Vterm Stage 1 (#126),
and completed Themes Arc 4 (#120/#124/#125) are on `main`.**
**Last updated: 2026-07-22, after Vterm Stage 3 (#135, protocol v19 and
native GPU terminal) landed on `main`, following tab-width rendering parity
(#137), locals-query processing (#134), modeline detection (#132), mode system
wiring (#129), config registry (#127), Vterm Stages 1–2 (#126/#130), and
completed Themes Arc 4 (#120/#124/#125).**
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),
protocol **v18** on `main`, **v19** on `vterm-gpu`
(`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`, v17 =
`FontFacts`, v18 = `StatuslineSegments`).
- `main` @ `cac4961` (Vterm Stage 3 #135 atop tab-width parity #137),
protocol **v19** (`SUPPORTED=[6..=19]`; v16 = `ThemeFacts`, v17 =
`FontFacts`, v18 = `StatuslineSegments`, v19 = terminal frames/events).
- **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
`docs/vterm-framing.md` Revision 9, criteria 28-37; awaiting review).
- **Stage 3 GPU/protocol LANDED ON `main` — #135** (merge `cac4961`;
`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
v18 until Stage 3.
PTY smoke. Stage 2 changed no wire schema or GPU renderer; protocol
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
core (#126), and Vterm TUI (#130) landed; protocol/GPU Stage 3 is
implemented and in review as PR #135.
- **Arc 5 terminal stage COMPLETE** — compile mode (#113), Vterm terminal
core (#126), TUI frontend (#130), and protocol/GPU Stage 3 (#135) landed.
- **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
test alone (`-- --test-threads=1`) before investigating. Also: 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`.
`cfg!(macos)`-disabled). Vterm Stage 3's merge CI saw one macOS timeout in
`real_tui_terminal_smoke_restores_host_after_output_input_resize_scroll_copy_and_bell`;
the complete failed-job rerun passed. The required-GPU gate also failed once
in `headless_diag_face_recolors_band_counter_despite_unchanged_text`, then
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

24
docs/roadmap-2026-07.md
View File

@ -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)**:
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. The 16 MiB
transport cap is preserved: the measured legal-worst frame encodes to
13,437,863 bytes under an 8 MiB aggregate glyph bound, never chunked.
Landing it closes Arc 5's terminal stage.
- **Vterm Stage 3 protocol/GPU landed in #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. The 16 MiB transport cap is
preserved: the measured legal-worst frame encodes to 13,437,863 bytes under
an 8 MiB aggregate glyph bound, never chunked.
### 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).
- Delete or mark-superseded stale docs: `pmacs-gpu-editing-perf-handoff.md`
(freeze fixed by PR #60 arc), `session-5-stale-styling-handover.md`
(fixed, task #25 closed), `python_experiment.md`, `#run.sh#`,
`semantic-frontend-protocol.md.local-bak`.
- ~~Merge PR #91 (gutter click classification + fit guard).~~ Landed on
2026-07-07.
- Machine-local handoff/experiment files are intentionally untracked; see
`docs/agent-handoff.md` §7. They are not repository housekeeping targets.
- `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.