From 87369ed5db99c21747ac2cca556ec2d255e90059 Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Tue, 21 Jul 2026 16:56:42 -0400 Subject: [PATCH] docs(handoff): record Vterm Stage 1 merge Advance canonical main to the #126 merge, retire the completed active lane, and record the landed headless terminal core plus the remaining TUI/GPU stages. --- docs/active-work.md | 46 ++--------------------------------------- docs/agent-handoff.md | 25 ++++++++++++++++------ docs/roadmap-2026-07.md | 21 ++++++++++++------- 3 files changed, 34 insertions(+), 58 deletions(-) diff --git a/docs/active-work.md b/docs/active-work.md index 4cf2503..9071eda 100644 --- a/docs/active-work.md +++ b/docs/active-work.md @@ -14,7 +14,7 @@ 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` @ `7bc0c61` (#125 merged; protocol v18). + `githubsucks/main` @ `643d1e1` (#126 merged; 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,52 +48,10 @@ git worktree list git status --short --branch ``` -The first command must expose `7bc0c61` or a newer intentional main. +The first command must expose `643d1e1` or a newer intentional main. If it does not, stop and repair the remote/fetch configuration. -## Active lane: Vterm Stage 1 terminal core - -- Portable branch: `githubsucks/vterm-core` -- Implementation commits: `bbc1f33` (Stage 1), `962944b` (Darwin signal), - first-review fixes `f0a235f`, `28f2e6c`, `bf972a7`, and second-review - hardening `9797ada`; current branch head: `fc4e0ce`. -- Pull request: #126, - — open, non-draft, targeting - canonical `main`; not merged. -- State: Arc 5 Stage 2's first of three PRs is implemented, two review rounds - are addressed, and the branch is fully gated against protocol-v18 `main`. - It is the headless terminal core only; the Stage 2 TUI/Lua surface and Stage - 3 protocol/GPU renderer are not implemented and must start only after their - preceding PR lands. -- Framing: `docs/vterm-framing.md` Revision 5 maps Stage 1 Acceptance 1–14, - records both review rounds, and preserves the downstream TUI/GPU contracts. -- Final from-start sequence after review round 2: Clippy clean; 1,661 default + - 1,837 CRDT library tests (3 ignored each); 9 default + 10 CRDT vterm - acceptance; M4 114 passed (3 ignored, 1 filtered); required GPU 109; - workspace 2,769 passed across 79 suites (19 ignored, 1 filtered); diff check - clean. Updated PR CI for `fc4e0ce` is green across Linux/macOS, Lua - 5.4/LuaJIT, GPU, format, lint, acceptance, and performance jobs. -- `scripts/bite main src/lib.rs --test vterm_stage1_acceptance` returned - `bite: OK` because the old crate root could not compile the new terminal API; - this is explicitly weaker compile-time API evidence, not a clean behavioral - assertion failure. -- `scripts/bite HEAD^ src/ansi.rs --lib - parser_split_points_produce_identical_screen` returned `bite: OK` with a - clean behavioral cursor-position failure against the pre-dispatch parser. -- `scripts/bite HEAD^ src/terminal/screen.rs --test vterm_stage1_acceptance - terminal_cells_reject_child_control_characters` returned `bite: OK` with a - clean behavioral control-cell failure against the pre-hardening screen. - -Recovery worktree, only if no existing worktree owns the branch: - -```sh -git worktree add --track \ - -b vterm-core \ - ../pmacs-vterm-core \ - githubsucks/vterm-core -``` - ## 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 0929075..c1ca3f6 100644 --- a/docs/agent-handoff.md +++ b/docs/agent-handoff.md @@ -1,8 +1,8 @@ # Agent handoff — cross-machine continuity -**Last updated: 2026-07-21, after Themes Arc 4 completed with -statusline segments (#125), JSON/YAML (#123), GPU font preferences -(#124), named UI faces (#120), and multi-language injections (#122).** +**Last updated: 2026-07-21, after Vterm Stage 1 terminal core (#126) +landed on `main` atop completed Themes Arc 4 (#120/#124/#125). Vterm +Stages 2 and 3 are 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` @@ -16,7 +16,7 @@ commands, read `docs/active-work.md` immediately after this file. ## 1. Where the project stands (2026-07-21) -- `main` @ `7bc0c61` (statusline segments #125), protocol **v18** +- `main` @ `643d1e1` (Vterm Stage 1 #126), protocol **v18** (`SUPPORTED=[6..18]`; v16 = `ThemeFacts`, v17 = `FontFacts`, v18 = `StatuslineSegments`). - **Syntax-highlight / language-detection side-quest (#114–#118) @@ -155,6 +155,19 @@ commands, read `docs/active-work.md` immediately after this file. right-pins the protected suffix under narrow clipping. Review hardening pins fixed-face sortedness, retains flattened provider tracebacks, and names unavailable layout contexts accurately. +- **Vterm Stage 1 terminal core LANDED — #126** + (`docs/vterm-framing.md` rev 5). `AnsiParserProfile::{LineOriented, + FullScreen}` preserves compile/REPL behavior while terminal PTYs emit the + full cursor/mode/device operation set. `src/terminal/{screen,input,session}.rs` + owns a bounded terminal screen, encoders, and the transactional lifecycle + registry; one pathless read-only identity buffer anchors each private + process/screen. Review hardening added IND/NEL/RI, `TERM=xterm-256color`, + portable shutdown liveness, custom-tab-stop preservation, control-free + cells, and button-preserving SGR mouse release. Final gates: 1,661 default + + 1,837 CRDT library tests; 9 default + 10 CRDT Vterm acceptance; 114 M4; 109 + required GPU; workspace 2,769 across 79 suites; CI green. This is headless: + Vterm Stage 2 TUI/Lua and Stage 3 protocol/GPU start as separate PRs from + post-#126 `main`. - **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 @@ -171,8 +184,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 stage 1 COMPLETE** — compile mode (#113); stage 2 vterm is - the next formal roadmap stage. + - **Arc 5 terminal stage ACTIVE** — compile mode (#113) and Vterm terminal + core (#126) landed; Vterm TUI is the next formal stage. ## 2. How we work (the part that must not drift) diff --git a/docs/roadmap-2026-07.md b/docs/roadmap-2026-07.md index 2aeba17..a6f5d11 100644 --- a/docs/roadmap-2026-07.md +++ b/docs/roadmap-2026-07.md @@ -80,15 +80,20 @@ preference at protocol v17; and composable per-window `pmacs.statusline` providers transported to semantic/GPU frontends by protocol-v18 `StatuslineSegments`. -### Arc 5 — Terminal, staged ← NEXT FORMAL ARC +### Arc 5 — Terminal, staged — VTERM CORE LANDED -- **Stage 1 — LANDED (#113)**: compile mode streams line-oriented - process output through the PTY/ANSI substrate, with error-regex - navigation and `M-x compile`. -- **Stage 2 (vterm)**: extend `ansi.rs` into a 2D grid model - (alt-screen, cursor addressing, scrollback — parser already - recognizes and discards these), grid-backed buffer view, GPU - rendering question (grid cells vs text buffer). +- **Compile mode landed in #113**: line-oriented PTY/ANSI output, + error-regex navigation, and `M-x compile`. +- **Vterm Stage 1 terminal core landed in #126**: compatibility parser + profiles, bounded VT screen/scrollback/reflow state, input encoders, + internal `TerminalManager`, read-only identity buffers, process lifecycle, + control-free renderer-boundary cells, and headless real-PTY acceptance. +- **Vterm Stage 2 TUI is next**: terminal-window composition, input/resize, + per-context scroll/selection/copy, and the 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. ### Arc 6 — Folding (keystone gutter rider)