Record GPU invocation review checkpoint

Update the durable handoff and volatile active-work ledger for open PR #141, including the implementation checkpoint, accepted architecture, verification record, visible Wayland/Vulkan smoke, and cross-machine recovery commands.

docs/active-work.md

@@ -1,6 +1,6 @@
 # Active work — cross-machine resume ledger
 
-**Snapshot: 2026-07-22.** This file records volatile work that has not
+**Snapshot: 2026-07-23.** This file records volatile work that has not
 landed on `main`. Read it after `docs/agent-handoff.md`. Remove completed
 entries when their PR merges; do not let this become a second permanent
 backlog.
@@ -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` @ `cac4961` (Vterm Stage 3 #135 merged after tab-width
-  parity #137; protocol v19).
+  `githubsucks/main` @ `96d0bae` (documentation refresh #140 atop Vterm
+  Stage 3 #135 and 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,9 +49,41 @@ git worktree list
 git status --short --branch
 ```
 
-The first command must expose `cac4961` or a newer intentional main.
+The first command must expose `96d0bae` or a newer intentional main.
 If it does not, stop and repair the remote/fetch configuration.
 
+## Active lane: one-command GPU invocation
+
+- Portable branch: `githubsucks/gpu-invocation`
+- Pull request: **#141 OPEN — do not merge without explicit user approval.**
+- Base: `githubsucks/main` @ `96d0bae`; protocol remains v19.
+- Implementation checkpoint: `6fd5834` (approved Revision-4 framing is the
+  preceding `821835b`).
+- State: implementation and all 18 acceptance criteria complete; awaiting user
+  review. Public path is additive `pmacs --gpu [--socket NAME|PATH]`; bare
+  `pmacs [FILE]` remains TUI and `pmacs --gpu FILE` remains rejected.
+- Verification: strict workspace Clippy; 1,768 default + 1,944 CRDT library
+  tests; root CLI 33; GPU 145 required; GPU invocation acceptance 1 default +
+  9 CRDT; Vterm Stage 3 7; M4 121 with 3 ignored and the requested
+  `basedpyright` skip; formatting and diff check clean. Unified release build
+  passed. Two real Wayland/Vulkan launches attached at protocol v19; the
+  second reused the daemon retained after the first GPU process exited.
+- Distribution remains source-checkout/workspace oriented: `pmacs-gpu` is
+  still unpublished. No install/service packaging claim was added.
+
+Recovery:
+
+```sh
+git fetch githubsucks --prune
+git worktree add --track \
+  -b gpu-invocation \
+  ../pmacs-gpu-invocation \
+  githubsucks/gpu-invocation
+cd ../pmacs-gpu-invocation
+cargo build -p pmacs-gpu
+cargo test --features crdt --test gpu_invocation_acceptance
+```
+
 ## Parked lane: kill-ring browser + persistence
 
 - Portable branch: `githubsucks/kill-ring-browser`

docs/agent-handoff.md

@@ -1,10 +1,11 @@
 # Agent handoff — cross-machine continuity
 
-**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).**
+**Last updated: 2026-07-23, with the approved one-command GPU invocation
+broker implemented on open PR #141, after the documentation refresh (#140),
+Vterm Stage 3 (#135, protocol v19 and native GPU terminal), 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`
@@ -16,11 +17,21 @@ reads it the way you just did.
 For volatile branches, checkpoints, verification, and recovery
 commands, read `docs/active-work.md` immediately after this file.
 
-## 1. Where the project stands (2026-07-22)
+## 1. Where the project stands (2026-07-23)
 
-- `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).
+- `main` @ `96d0bae` (documentation refresh #140 atop Vterm Stage 3 #135
+  and tab-width parity #137), protocol **v19** (`SUPPORTED=[6..=19]`; v16 =
+  `ThemeFacts`, v17 = `FontFacts`, v18 = `StatuslineSegments`, v19 = terminal
+  frames/events).
+- **One-command GPU invocation is implemented on OPEN PR #141, not yet on
+  `main`** (`gpu-invocation`, implementation checkpoint `6fd5834`, framing
+  Revision 4). The additive public path is `pmacs --gpu [--socket NAME|PATH]`;
+  bare `pmacs [FILE]` remains the TUI. Root owns the CRDT gate, socket
+  resolution, sibling-first GPU discovery/PATH fallback, and GPU outcome.
+  The separate `pmacs-gpu` binary owns connect-or-start, a five-second /
+  50-ms retry window, daemon process-group isolation, and named child
+  reaping. Direct `pmacs-gpu --attach RAW_PATH` remains strict and never
+  auto-starts. No protocol change.
 - **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