diff --git a/docs/gpu-terminal-input-framing.md b/docs/gpu-terminal-input-framing.md new file mode 100644 index 0000000..a383c14 --- /dev/null +++ b/docs/gpu-terminal-input-framing.md @@ -0,0 +1,415 @@ +# GPU terminal input — the double terminal-layout sync + +**Revision 2 — approved 2026-07-25. Scouted against canonical `main` @ +`8c86d34`; implemented on branch `gpu-terminal-input` off `main` @ `46a1b8f`, +whose only delta (#161) touches no file on this fix surface. Protocol stays +v20.** + +Revision 2 answers Q#GT4 from the code instead of deferring it, which changes +the proposed fix from a one-line guard to a **split of `sync_terminal_layout` +into a frontend-kind-neutral liveness half and a grid-only geometry half**; +rescores B1 as half-false; gives acceptance criteria 2 and 3 a landable +observation seam; and corrects four line citations plus the criterion-4 +rationale. Revision 1's diagnosis is unchanged — the defect, its measurements, +and the three falsified hypotheses all stand. + +Reported symptom: *"Text input within the terminal doesn't work on GUI, this +is fine in TUI."* + +This is a bug-fix framing, not a feature. It repairs a defect in Vterm Stage 3 +(#135) that ships on `main` today, and it closes the acceptance hole that let +the defect ship: the Stage 3 real-path acceptance drives a terminal session +end to end, and *still could not see this*. + +## Summary of the defect + +Every dispatcher tick, the daemon applies **both** terminal-layout syncs to +**every** attached frontend: + +```rust +// src/daemon.rs:1536-1554 (current main) +for frontend_id in &attached_fids { + if let Some(size) = term_sizes.get(frontend_id).copied() { + editor.sync_terminal_layout(*frontend_id, size); // GRID path + } + if let Some((buffer_id, size)) = semantic_states + .get(frontend_id) + .and_then(SemanticRenderState::terminal_viewport) + { + editor.sync_semantic_terminal_layout(*frontend_id, buffer_id, size); // SEMANTIC path + } +} +``` + +They are written as twins — the comment on the semantic arm even says *"right +beside the grid sync"* — but they are applied as **siblings, not +alternatives**. A GPU session has an entry in `term_sizes` (its `AttachRequest` +carries an initial cell size, and `Resize` events maintain it) *and* a +semantic terminal declaration. So both run, every tick. + +The two disagree by construction, and the semantic arm's own doc comment says +why: + +> 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**. + +That is exactly what the grid arm then does. Measured, on a real daemon with a +real PTY and the real GPU attach client: + +``` +PROBE sync_semantic old=Some(24x80) declared=25x92 +PROBE manager.resize BufferId(3) 25x92 +PROBE manager.resize BufferId(3) 22x80 +PROBE sync_semantic old=Some(22x80) declared=25x92 +PROBE manager.resize BufferId(3) 25x92 +PROBE manager.resize BufferId(3) 22x80 +... +``` + +The PTY is resized **twice per dispatcher tick, forever**. Each resize is a +`TIOCSWINSZ` + `SIGWINCH` to the child and a screen reflow in +`TerminalScreen`, so the child gets a SIGWINCH storm at tick cadence and the +screen alternates between two geometries. An interactive line editor +(readline, zle, fish's reader) redraws on every SIGWINCH, so what the user +types is continuously destroyed before it can settle — while ordinary child +*output* keeps flowing, which is why the terminal looks alive. + +Measured user-visible effect, real bash `-i` in the real GPU path, typing one +character: + +| | frames for a static screen | typed `Z` ever visible at the prompt | +|---|---|---| +| `main` today | **730** in a 20 s window | **no** | +| with the guard | **2** | (see Q#GT5 — a separate question) | + +The TUI is unaffected: a grid session has no semantic terminal declaration, so +only one arm ever runs for it. This is a **frontend-kind** defect, which is +why it presents as "GUI broken, TUI fine". + +## Ground truth (measured this session, not inferred) + +Everything below was established against `main` @ `8c86d34` with a real +daemon, a real PTY child, and the real `pmacs-gpu` attach client. The probe +harness is preserved (see "Verification plan"). + +### What is *not* wrong — three hypotheses falsified + +Recording these because each is a plausible-looking cause that a future +reader (or a review round) will re-propose. + +1. **The GPU's optimistic-CRDT path is not implicated.** The first hypothesis + was that a typed character becomes a `CrdtOp` against the read-only + terminal identity buffer and is dropped. It does not. Terminal buffers are + already marked round-trip — `core.set_round_trip_input(buffer_id, true)` + at `src/terminal/session.rs:338`, beside `set_read_only(true)` — so + `dispatch_idle_for` returns **false** while a terminal window is focused, + the daemon publishes `DispatchIdle { idle: false }`, and the GPU's + `daemon_intercepts_keys()` is true. Measured on the wire: + `dispatch_idle_in_terminal=false`, `intercept_in_terminal=true`, + `input_route=send_key(intercept)`. The optimistic gate is shut. +2. **Key transport is not implicated.** The keystroke reaches the daemon, + resolves a terminal view key, encodes, and is written to the PTY without + error: `PROBE dispatch_key ... terminal_key=Some(TerminalViewKey { .. })`, + `PROBE terminal transport encode=Some([90])`, `PROBE after send status=""`. + With a `cat` child the byte comes back on screen through the whole real GPU + path (`echoed_typed_char=true`). +3. **The `pmacs --attach` TUI replica does *not* share the defect.** It gates + its optimistic path on `dispatch_idle` alone (`src/attach.rs:843`), and + that signal is already correct for terminals per (1). + +### The mechanism + +- `EditorInstance::sync_terminal_layout` (`src/editor.rs:1195`) is the grid + path: it runs the TUI placement helper over the frontend's *frame* size. +- `EditorInstance::sync_semantic_terminal_layout` (`src/editor.rs:1331`) is + the semantic path: it consumes a declared *content* rectangle directly. +- Both resolve the same controller and call `TerminalManager::resize` on the + same session. Each has a correct `old_size == size` idempotence guard + (`src/editor.rs:1239` grid, `src/editor.rs:1360` semantic) — the guards are + individually sound and jointly useless, because each arm sees the size the + *other* just installed. +- `TerminalViewStore::record_view_size` (`src/terminal/view.rs:276-292`) + returns `true` for any valid declaration with no unchanged-size dedupe, + which is why the semantic arm re-fires every tick against the grid arm's + flip rather than settling. +- Loop order is grid first, semantic second, so the screen *ends* each tick at + the declared size. That is why rendering looks alive while the child is + whipsawed — and why a frame-based assertion is the wrong instrument + (acceptance criteria 2 and 3). +- `TerminalScreen::changed` bumps `generation` per mutation + (`src/terminal/screen.rs:1467`), which is why generation advances by + **exactly 2** per tick — one bump per resize. +- Frame suppression is full-struct equality + (`self.last_terminal_frame.as_ref() == Some(&frame)`, + `src/semantic_render.rs:882`). It is behaving correctly: the frames really + do differ. The churn is upstream, and fixing the churn fixes the frame + storm. **No suppression change is proposed.** + +### Why the Stage 3 acceptance could not catch it + +`a37_real_daemon_real_pty_and_headless_gpu_render_one_terminal_session` +(`tests/vterm_stage3_acceptance.rs:637`) is a genuine real-daemon + +real-PTY + real-wgpu path, and it still passes on the broken tree. Three +reasons, each worth keeping: + +1. Its child is `sh` printing 400 rows on a timer. **A frame storm is + invisible against a child that legitimately produces ~400 frames**, and its + only frame-count assertion is `frames >= 2`. +2. Its input step is `client.send_key(...)` called **directly** + (`pmacs-gpu/src/main.rs:784-785`), so it pins transport, not routing — and + it asserts nothing about the result of that input reaching the child. +3. It resizes **once, deliberately**, and asserts the new width comes back. + A geometry that oscillates *through* the asserted width satisfies that + assertion. This is the project's own "a geometric readout is not a state + predicate" lesson (`docs/active-work.md`, bottom-panel round 2) in a new + place: `observed_resized_frame` says "a frame at this width arrived", not + "the geometry settled at this width". + +## Decisions + +**Q#GT1 — Where does the fix go?** `sync_terminal_layout` is **split**, and +only its geometry half is gated by frontend kind. A bare "skip the grid arm +for semantic frontends" guard is wrong — see Q#GT4, which establishes that the +grid arm is also the only per-tick controller-liveness release. Not by +removing `term_sizes` for semantic sessions: semantic key and mouse dispatch +hard-depend on it (`src/daemon.rs:2191-2213`). + +The function has three separable concerns +(`src/editor.rs:1195-1260`), and they do not split where the name suggests: + +| lines | concern | frontend kind | +|---|---|---| +| 1199 | `reconcile_panel_layout` (Q#BP2b per-tick defensive) | **neutral** | +| 1200-1221 | controller liveness: released when the frontend has no view, or its active window no longer shows that terminal | **neutral** — reads only `core.views` / `core.windows` / the controller, never `term_size` | +| 1222-1259 | TUI placement (`window_placements`) + `resize` | **grid only** | + +So the daemon loop becomes: run the neutral half for every attached frontend +every tick, then exactly one geometry arm per frontend kind. +`sync_terminal_layout` survives as the composition of both halves, so +`editor::run`'s in-process loop and `LOCAL` keep byte-identical behavior. The +liveness half must run **once** per frontend per tick — reconciliation is +idempotent, so a double call is safe rather than wrong, but the loop should +not pay for it. + +**The trap inside the split:** the third release, at `src/editor.rs:1226` +(no placement found for the window), looks like liveness and is **not** — it +is grid geometry. A semantic frontend has no `window_placements` entry at all, +so moving that arm into the neutral half would release a GPU session's +controller on every single tick. That would be a new defect of exactly the +family this framing fixes, so it stays in the grid half. + +**Q#GT2 — Which arm wins for a semantic frontend?** The semantic one, +unconditionally. It is the only arm that consumes a *content* rectangle; the +grid arm's modeline subtraction is meaningless for a frontend that draws no +modeline into the terminal band. A GPU frontend that has not yet declared a +terminal viewport gets **neither** arm, which is correct: the terminal keeps +the geometry it was opened with until the frontend declares one. + +**Q#GT3 — Is the guard "no semantic state" or "not a semantic session"?** +`semantic_states` keyed by frontend id is the same map the semantic arm reads +one line later, so the two arms become provably exclusive by construction +rather than by two independent predicates that could drift apart. Rejected +alternative: keying on the negotiated `semantic_render` capability bit — it is +the *same* fact one indirection away, and the pair could then disagree. + +**Q#GT4 — Does anything else in `sync_terminal_layout` need to keep running +for a semantic frontend? Yes: the controller-liveness release, and the +semantic arm neither performs it nor can be made to.** Revision 1 left this +open; the code answers it. + +`release_controller` is called from exactly five sites, all in +`src/editor.rs`: the three grid-arm early returns (1210, 1219, 1226), +`dispatch_focus(gained = false)` (1189), and `reconcile_panel_layout`'s +unsatisfiable-panel path (848). **`sync_semantic_terminal_layout` releases +nothing.** When the window has switched away, `semantic_terminal_key` returns +`None` (`src/editor.rs:1278` — `window.buffer_id != buffer_id`) and the arm +returns `false` without touching the controller. + +Growing a release inside the semantic arm — revision 1's stated fallback for +B1 — **cannot work**, and the reason is worth keeping: when a GPU window +switches from the terminal to a document, the buffer-follow snapshot clears +the viewport declaration (`on_buffer_snapshot_sent` sets +`terminal_viewport = None`, `src/semantic_render.rs:574`), so +`terminal_viewport()` returns `None` and the semantic arm **stops running +entirely** for that frontend. A release placed inside it would never execute +in precisely the scenario that needs it. + +Nor do the other two sites cover it: `dispatch_focus(false)` fires on +whole-frontend focus loss, not on a window or buffer switch, and semantic +sessions are not panel-capable yet (`panel_capable_for` is false for them — +`src/daemon.rs:1893-1898`), so 848 never fires either. + +Consequence of shipping revision 1's guard as written: a GPU frontend that +switches away from its terminal **holds the controller indefinitely**. Because +another frontend's grid sync early-returns on a +`controller_view_for_frontend` mismatch, that peer then cannot resize the PTY +until it explicitly re-claims. This is why Q#GT1 splits the function instead +of gating it. + +**Q#GT7 — The per-tick defensive panel reconcile stays for semantic +frontends.** It is the only per-tick pre-paint reconcile the Q#BP2b contract +names (`src/editor.rs:822-830`), and today the grid arm supplies it for GPU +sessions too. Putting it in the neutral half of the split preserves that +exactly. It is harmless-either-way today — semantic sessions have unknown +frame geometry until the bottom-panel GPU band lands — but "harmless today" +is not a reason to remove a contract's only per-tick enforcement point in a +PR about something else. + +**Q#GT5 — Typed characters not echoing by an interactive shell is a +*separate* question and is deliberately out of scope.** Measured: with `bash +--norc -i` on a `TerminalMode::Raw` PTY, typed characters are not echoed to +the screen — **and this reproduces identically in-process**, i.e. on the TUI's +own path, where the user reports the terminal works. Because it is not +frontend-specific it cannot be the GUI/TUI asymmetry, and folding it in would +make this PR two features. It gets its own scout: whether `TerminalMode::Raw` +is the right mode for a `pmacs.terminal.open` child, and what pmacs owes a +child that expects to own its termios. Named, not silently dropped. + +**Q#GT6 — Protocol impact: none.** No wire shape, no negotiation, no version +change. Stays v20. + +## Bets + +- **B1 — SCORED HALF-FALSE before implementation (revision 2).** "Removing the + grid arm for semantic frontends removes the storm without removing any + behavior a GPU session relies on." The first clause holds (measured). The + second is **false**: it also removes the only controller-liveness release + and the only per-tick Q#BP2b reconcile a GPU session gets (Q#GT4, Q#GT7). + Its stated contingency — "the semantic arm grows the release" — is false + too, for a structural reason (`terminal_viewport` is cleared by the very + snapshot that signals the switch-away). Hence the split in Q#GT1. Recorded + rather than deleted: the failure mode is one a reviewer or a future + simplification will re-propose. +- **B2.** The user's reported symptom is this defect. *Partially scored: the + storm is proven and GUI-only, and its shape (line editor unusable, output + still flowing) matches the report. Not fully scored until the user, or an + acceptance running the **user's own shell**, confirms typing works after the + fix. Q#GT5 is the reason this bet is stated rather than assumed.* +- **B3.** No other pair of per-frontend-kind daemon operations is applied as + siblings rather than alternatives. *Scored by an explicit audit of the + dispatcher's per-frontend loop during implementation — this defect's shape + is "twins applied as siblings", and it would be negligent to fix one + instance without looking for others.* + +## Deferred (named) + +- Interactive-shell echo on a raw-mode PTY (Q#GT5) — its own scout. +- `TerminalFrame` suppression including `screen_generation` in its equality: + correct today and load-bearing for correctness, but it means any future + content-neutral generation bump re-emits a frame. Recorded, not changed. +- The `a37` probe's structural weaknesses beyond what the acceptance below + fixes (it still cannot exercise `App::window_event`'s routing, because that + logic is inline in the winit handler with no extractable seam). Making GPU + key routing testable is a real refactor and belongs to its own lane. + +## Acceptance criteria + +**The observation seam (revision 2).** Criteria 2, 3 and 6 assert daemon-side +state, and `TestDaemon` runs the daemon as a **subprocess** +(`tests/common/daemon.rs:90`), so nothing in-process can see it and the +scouting instrumentation does not land. The seam that does land: **extract the +dispatcher loop's per-frontend terminal-layout step into a named function** +that takes `(&mut EditorState, &[FrontendId], &term_sizes, &semantic_states)`. +That is required by Q#GT1's split anyway, it makes the grid/semantic +exclusivity structural rather than two adjacent `if`s, and it lets an +in-process test in the style of the existing `src/daemon.rs` unit tests +(3375ff) drive **the real loop body** rather than a re-implementation — which +is the a37 lesson applied to this PR's own tests. + +The observable is `TerminalScreen::generation`, reachable through +`TerminalManager::snapshot(..).generation`. It advances once per screen +mutation (`src/terminal/screen.rs:1467`), so with a quiet child it is a +**state predicate**, not a readout: "the geometry settled" is exactly +"generation stopped advancing". + +1. On a real daemon + real PTY + real GPU attach, a terminal session that + receives no child output produces a **bounded** number of terminal frames + (settling to zero new frames once the screen is static) — not one per tick. + Fails on `main` with ~730 frames in 20 s; passes with ≤ a small constant. +2. Driving the extracted loop body N times against a semantic frontend with a + fixed declaration and a quiet child: `TerminalManager::resize` takes effect + **exactly once** (generation advances once, then is constant for the + remaining N-1 iterations). Fails on `main`, where generation advances by + two per iteration. +3. After a declaration, `screen_size(buffer)` **equals the declared content + rectangle and stays equal** across subsequent iterations — the state + predicate, not the "a frame at this width arrived" readout that + `observed_resized_frame` provides today. +4. A character sent through the real GPU attach client reaches the child and + its echo appears in a rendered frame. **This is a keep-working pin, not a + fix discriminator: it already passes on today's broken `main`** (falsified + hypothesis 2 measured `echoed_typed_char=true`). Pinned with a `cat` child + — not because `cat` echoes (termios `ECHO` is off in raw mode; nothing + echoes) but because `cat` *copies stdin to stdout*, so the byte comes back + exactly once, with no line discipline and no double echo to disambiguate. +5. A grid (TUI) session's terminal resize behavior is **unchanged** — pinned + against the existing Stage 2 real-TUI PTY smoke, which must stay green + without modification. +6. A semantic frontend whose window stops showing the terminal **releases its + controller** (Q#GT4), pinned through the extracted loop body — driven by an + actual buffer switch, not by calling the release directly. This one bites + against revision 1's guard as well as against `main`. +7. End-to-end SIGWINCH count through the real PTY: a child trapping `WINCH` + and printing a **fresh distinct breadcrumb per signal** (`WINCH 1`, + `WINCH 2`, …) shows a bounded count. The distinctness is load-bearing — + the established PTY-paint trap is that cell diffing skips both spaces and + already-matching cells, so a repeated identical marker can assert nothing. +8. Bite-verified: reverting the split fails 2, 3, 6 and 7 specifically. + Criteria 1 and 7 fail against `main`; criterion 6 fails against **both** + `main` and revision 1's guard, which is the point of keeping B1's + half-false score on the record. + +Criteria 1, 2 and 7 are deliberately expressed as **quiet-child** assertions, +because the existing acceptance's chatty child is exactly what hid this. + +## Coherence impact (`COHERENCE.md` §20) + +- **§2 golden journey, step 8 ("Open a terminal")** — currently graded *"Works + but undiscoverable"*. On the GPU frontend it does not work; this restores + the step for the frontend the document calls the more capable one. Priority + 1 explicitly treats journey regressions as release blockers. +- **§16 Productize the Semantic Frontend Architecture** — graded *strong*, + with "graceful per-frontend degradation is practiced, not aspirational" as + its evidence, citing per-frontend fold projection. This defect is the + counter-example: a per-frontend-kind operation applied to both kinds at + once. The section's claim survives, but the audit should record that the + practice is enforced by convention, not by structure — two arms that must be + alternatives are currently just two adjacent `if`s. Q#GT1's extracted loop + body makes this one structural; the audit note should say the *pattern* is + still convention-enforced everywhere else (B3). +- **§6 Eliminate Hardcoded Interaction Islands** — the audit's row 6 note that + the GPU optimistic classifier "is kept honest by `dispatch_idle_for`" is + **confirmed correct** by this investigation (falsified hypothesis 1), and the + §6 citation `crate::optimistic::classify_key` should be corrected: that + symbol is `src/optimistic.rs`, the **`pmacs --attach` TUI replica's** + classifier. The GPU's separate, unrelated classifier is + `optimistic_insert_text` / `optimistic_crdt_insert` in + `pmacs-gpu/src/main.rs`. Two replica frontends, two classifiers; the audit + conflates them. +- **§19 Product Coherence Acceptance Tests** — this is a concrete instance of + the section's thesis. Every subsystem test passed; the defect lives in how + two correct subsystems compose per frontend kind. Criterion 1's quiet-child + shape is the transferable technique. +- No interaction island added, no config registry surface, no background-work + attribution change. + +## Verification plan + +Full gate suite per `CLAUDE.md`, plus: + +- `cargo test --features crdt --test vterm_stage3_acceptance` (the suite this + repairs) and `--test vterm_stage2_acceptance` (the TUI no-regression pin). +- `PMACS_REQUIRE_GPU=1 cargo test -p pmacs-gpu`. +- The scouting harness is preserved and should be re-run against the branch: + a quiet-child variant of the `a37` probe plus daemon-side resize tracing, + saved as `scratch_gui_terminal_input.rs`, `scratch_inproc_input.rs`, and + `gui-terminal-probe-instrumentation.patch`. The instrumentation is scratch; + the acceptance criteria above are what lands. +- Manual confirmation with the user's own shell (fish) in a real GPU window, + since B2 is not fully scored by any automated test (Q#GT5). + +**Ops.** This doc is currently untracked in a detached-HEAD worktree +(`../pmacs-gui-term-input`), so it does not travel. On approval it becomes the +branch's first commit before any implementation, per the standing workflow — +no cross-machine expectation should attach to it until then.