From 78339352d454ee01c7c529ffa22fa66d3e208787 Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Thu, 23 Jul 2026 12:40:03 -0400 Subject: [PATCH] Record second GPU invocation review closure Advance the framing to Revision 6 and record the strengthened non-CRDT, Ctrl-C, strict-operand, probe-throttling, and PID-cleanup contracts. Update the durable and volatile checkpoints to implementation commit 154cb9f. --- docs/active-work.md | 25 +++++++++------- docs/agent-handoff.md | 4 +-- docs/gpu-invocation-framing.md | 53 +++++++++++++++++++++------------- 3 files changed, 49 insertions(+), 33 deletions(-) diff --git a/docs/active-work.md b/docs/active-work.md index 57a63e0..a10dd16 100644 --- a/docs/active-work.md +++ b/docs/active-work.md @@ -57,18 +57,21 @@ If it does not, stop and repair the remote/fetch configuration. - Portable branch: `githubsucks/gpu-invocation` - Pull request: **#141 OPEN — do not merge without explicit user approval.** - Base: `githubsucks/main` @ `96d0bae`; protocol remains v19. -- Implementation checkpoints: `69825d0` (exception-safe immediate reaper - ownership) atop `82355ca` (first implementation-review fixes) and - `6fd5834`; approved framing began at `821835b` and is now Revision 5. -- State: all six implementation-review findings are resolved, all 18 - acceptance criteria complete, and the PR awaits another user review. Public - path is additive `pmacs --gpu [--socket NAME|PATH]`; bare `pmacs [FILE]` - remains TUI and `pmacs --gpu FILE` remains rejected. +- Implementation checkpoints: `154cb9f` (second implementation-review fixes) + atop `69825d0` (exception-safe immediate reaper ownership), `82355ca` + (first implementation-review fixes), and `6fd5834`; approved framing began + at `821835b` and is now Revision 6. +- State: both implementation reviews are resolved, all 18 acceptance criteria + complete, and the PR awaits user review. Public path is additive + `pmacs --gpu [--socket NAME|PATH]`; bare `pmacs [FILE]` remains TUI and + `pmacs --gpu FILE` remains rejected. - Review fixes: pre-state GPU events are buffered until winit state exists; - daemon stderr is detached; spawned-child ownership is handed off without a - leak window; direct CLI guidance, help operands, and sibling-file discovery - are strict; transient retry, timeout reporting, hermetic socket paths, and - deterministic concurrent-loser reaping have behavioral coverage. + daemon stdio is detached; spawned-child ownership is handed off without a + leak window; direct CLI guidance, help/path operands, and sibling-file + discovery are strict; transient retry, timeout reporting, hermetic socket + paths, deterministic concurrent-loser reaping, pre-I/O non-CRDT gating, and + post-SIGINT use of a pre-attached frontend have behavioral coverage. Probe + disconnect polling remains bounded and cleanup skips already-reaped PIDs. - Verification: strict workspace and CRDT acceptance Clippy; 1,768 default + 1,944 CRDT library tests; root CLI 33; GPU 149 required; GPU invocation acceptance 1 default + 9 CRDT; Vterm Stage 3 7; M4 121 with 3 ignored and diff --git a/docs/agent-handoff.md b/docs/agent-handoff.md index c021cc3..393805c 100644 --- a/docs/agent-handoff.md +++ b/docs/agent-handoff.md @@ -24,8 +24,8 @@ commands, read `docs/active-work.md` immediately after this file. `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`, final implementation-review checkpoint - `69825d0`, framing Revision 5). The additive public path is + `main`** (`gpu-invocation`, second implementation-review checkpoint + `154cb9f`, framing Revision 6). The additive public path is `pmacs --gpu [--socket NAME|PATH]`; bare `pmacs [FILE]` remains the TUI. Root owns the CRDT gate, socket resolution, sibling-regular-file GPU discovery/PATH fallback, and GPU outcome. The separate `pmacs-gpu` binary diff --git a/docs/gpu-invocation-framing.md b/docs/gpu-invocation-framing.md index 744a136..01c8860 100644 --- a/docs/gpu-invocation-framing.md +++ b/docs/gpu-invocation-framing.md @@ -1,7 +1,7 @@ # GPU invocation — one-command broker framing -**Revision 5 — implementation review complete on `gpu-invocation`. Ground -truth: canonical `main` @ `96d0bae`, protocol v19, 2026-07-23.** +**Revision 6 — second implementation review complete on `gpu-invocation`. +Ground truth: canonical `main` @ `96d0bae`, protocol v19, 2026-07-23.** The GPU editor works, but reaching it is still a development-session ritual: build two packages with different feature requirements, keep a foreground @@ -42,6 +42,12 @@ inherits no launcher stdio. Direct GPU help points normal users to the root broker and labels raw socket attach as advanced. The retry, timeout, socket type, and concurrent-loser contracts now have deterministic behavioral tests. +Revision 6 closes the remaining non-blocking review findings. The managed +probe throttles after its event channel disconnects; option-like path operands +are rejected; cleanup never signals an already-reaped daemon PID; and the +acceptance suite now proves both pre-I/O non-CRDT gating and post-SIGINT use of +a frontend attached before the launcher exits. + ## Ground truth ### Current user path @@ -550,9 +556,10 @@ Vterm probe continues to cover offscreen wgpu. argument named. Bare `pmacs --socket research` (with or without a local file / `-nw`) exits 2 and says which owning mode is required. 2. **Non-CRDT build fails before socket or spawn:** a default-feature - `pmacs --gpu` names `--features crdt`; a capable daemon already listening - does not weaken the gate, and fake GPU/daemon executables record zero - invocations. The default socket remains unowned. + `pmacs --gpu` names `--features crdt`, invokes no GPU executable, and leaves + the default socket absent under a private runtime directory. Repeating the + command against an already-listening Unix socket neither invokes the GPU + nor disturbs that socket, proving the gate precedes socket I/O. 3. **Sibling discovery wins:** with executable fixtures at the current-exe sibling and on PATH, the sibling regular file receives the managed arguments. A directory at the sibling pathname is ignored in favor of @@ -566,12 +573,14 @@ Vterm probe continues to cover offscreen wgpu. handshake, receives the first `BufferSnapshot`, and leaves the daemon connectable after the probe exits. 6. **Ctrl-C does not kill the daemon:** spawn the managed probe/broker in its - own process group, wait for the probe's `phase=ready`, attach a second real - frontend, then simulate terminal Ctrl-C with `kill(-pgid, SIGINT)`. Assert - the launcher/frontend exit while the separately grouped daemon and second - session remain usable. This does not require a controlling terminal or a - foreground-process-group claim in CI. Direct foreground `pmacs --daemon` - still exits cleanly on SIGINT. + own process group, wait for the probe's `phase=ready`, and complete a second + real frontend's handshake and initial snapshot/grid sync before simulating + terminal Ctrl-C with `kill(-pgid, SIGINT)`. After the launcher/frontend + exits, resize the pre-existing second frontend and require its full-grid + response; the separately grouped daemon and existing session remain usable. + This does not require a controlling terminal or a foreground-process-group + claim in CI. Direct foreground `pmacs --daemon` still exits cleanly on + SIGINT. 7. **Concurrent launchers converge:** hold two daemon wrappers behind a shared barrier so both managed probes authorize and spawn before either daemon binds the absent named socket. Exactly one daemon owns the lock; both @@ -615,9 +624,10 @@ Vterm probe continues to cover offscreen wgpu. direct `--attach PATH` as advanced. Existing `--headless-probe SOCKET REPORT` and hidden `--headless-managed-probe SOCKET REPORT DAEMON_EXE` accept exactly their operands. Missing/trailing/unknown/incomplete args - exit 2; trailing help/version operands say those flags accept no operands. - `--version` prints package and protocol versions without initializing - winit/wgpu. + exit 2; trailing help/version operands say those flags accept no operands; + option-like path operands are rejected and require an explicit `./` + prefix when they name a real relative path. `--version` prints package and + protocol versions without initializing winit/wgpu. 16. **Existing direct and Vterm paths remain intact:** rebuilt `pmacs-gpu --attach RAW_PATH` still renders an existing CRDT daemon, and `tests/vterm_stage3_acceptance.rs` still invokes its unchanged @@ -652,13 +662,16 @@ Vterm probe continues to cover offscreen wgpu. protocol/capability failures never authorize replacement. - `--headless-managed-probe SOCKET REPORT DAEMON_EXE` drives the production managed connector, writes atomic `phase=ready` / `phase=complete` reports, - holds on stdin, and exposes disconnect plus daemon-reaper observations. -- `tests/gpu_invocation_acceptance.rs` covers the root broker, non-CRDT gate, - existing/missing/stale/racing daemon paths, process-group SIGINT isolation, - capability and protocol mismatches, bounded startup failure, deterministic - losing-child reaping, outcome propagation, and strict headless CLI behavior. + holds on stdin, exposes disconnect plus daemon-reaper observations, and + retains its 50-ms cadence after the event channel closes. +- `tests/gpu_invocation_acceptance.rs` covers the root broker, pre-I/O + non-CRDT gate, existing/missing/stale/racing daemon paths, process-group + SIGINT isolation with a pre-attached surviving frontend, capability and + protocol mismatches, bounded startup failure, deterministic losing-child + reaping without signaling freed PIDs, outcome propagation, and strict + headless CLI behavior. -Verification on 2026-07-23 after the implementation review: +Verification on 2026-07-23 after the second implementation review: - root CLI unit suite: 33 passed; - required GPU suite: 149 passed;