pmacs/docs/gpu-probe-sigint-framing.md

GPU launcher / probe SIGINT teardown — framing

Revision 3. Status: awaiting approval. No implementation.

Revisions 1 and 2 were each rejected on five findings. Every correction is recorded in place rather than quietly rewritten, because three of them were claims this document itself had advanced:

• r1 → r2: the ">6 s selector" and the "≥8 s lifetime" arithmetic (§5); "two processes with default disposition" (§3); "119 binaries green, one red" (§1); an unobtainable A2 (§8); "journey steps touched: none" (§9).
• r2 → r3: "R9 ran the same binaries" — it did not (§4); "the probe never blocks indefinitely" (§3); the launcher call-site count (§5); reduction provenance, now in docs/probe-sigint-evidence.md; and ledger corrections that had not been made portable (§11).

1. The problem, stated as what is observed

ctrl_c_on_launcher_group_does_not_reach_spawned_daemon fails with

child did not exit within 5s   (tests/gpu_invocation_acceptance.rs:180, called from :1115)

The test spawns pmacs --gpu --socket <s> in its own process group (process_group(0), :1107), waits for the probe to report phase=ready, sends SIGINT to the group (:1113), and requires the launcher to exit within five seconds.

It fails in two binaries, not one. tests/gpu_initial_target_acceptance.rs includes the suite as a module, so a reproducing sweep reds twice. Reference run 20260816T064549Z-2144707/09-sweep-crdt.log:

	line	result
gpu_initial_target_acceptance	3097	FAILED. 14 passed; 1 failed … 5.19s
gpu_invocation_acceptance	3131	FAILED. 14 passed; 1 failed … 5.18s
green result summaries	—	119

So the correct statement is 119 green result summaries and two red binaries. Revision 1 said "119 binaries green, one red", which was wrong on both halves.

This is pre-existing on main. The identical build-crdt && sweep-crdt pair at 72da24a, clean worktree, own target directory, fails the same test.

2. Why this blocks more than one lane

sweep-crdt is stage 15 of the sixteen-stage --protocol gate. While it reds, no branch can present a green gate, main included. panel-mapping-generation (§5b) is complete with its own fifteen stages green and is held behind this lane by explicit instruction.

3. Ground truth (cited), and what it does not establish

• Neither binary contains signal-handling code. run_gpu (src/main.rs:324) blocks in command.status() (:363) — a plain waitpid — with no handler installed. Grepping SIGINT|signal_hook|sigaction|ctrlc|set_handler|pthread_sigmask|sigprocmask across pmacs-gpu/src returns nothing.
• The probe's event loop wakes at least every 50 ms. run_headless_managed_probe (pmacs-gpu/src/main.rs:1065) loops on event_rx.recv_timeout(Duration::from_millis(50)). Revision 2 said "never blocks indefinitely", which is false: the probe's stdin reader thread blocks in read_to_end (:1109) with no timeout, and once ready the loop has no deadline of its own — it leaves only when stdin closes (:1212). So the process is not bounded; only the event wakeup is.
• The daemon does handle signals, deliberately. src/daemon.rs:629-641 registers SIGTERM/SIGINT via signal_hook::flag. The daemon is the process the test asserts must survive, detached from the launcher's group.

Correction to revision 1. Revision 1 concluded from the first two bullets that "two processes with default SIGINT disposition should both die at once". That does not follow, and it contradicted this document's own leading hypothesis. Absence of handler code says nothing about runtime disposition: SIG_IGN is inherited across fork and survives exec, so either process can hold a non-default disposition it never installed — from the test harness, from cargo, or from the invoking shell. Inherited ignore is a live candidate precisely because the source is silent. What the source establishes is narrower: neither binary sets a disposition itself, so whatever disposition they hold at runtime was inherited, and that is measurable rather than arguable.

4. Reductions attempted

Full provenance lives in docs/probe-sigint-evidence.md, which is pushed with this branch: exact command, worktree, HEAD, cleanliness, the artifact family actually executed, result, and log digest for every physical run. Log bodies stay machine-local under /home/jeans/build/pmacs-gate-targets/probe-sigint-evidence/ — /tmp is a tmpfs and they were nearly lost to a cleanup mid-lane.

Three provenance caveats are recorded there rather than smoothed over: R1 and R2 have no preserved log (revision 2 cited gpu3.log for both R2 and R6; that log is R6's three-suite run alone, and counting one run as two was wrong); cleanliness is UNKNOWN for every pre-manifest run, because it was not recorded at the time and is not inferrable; and R1–R10 ran in the panel-mapping-generation worktree, not at main. D0 re-runs the matrix under a harness that captures all of it, at main, before any row here is relied on.

All rows carry --features crdt. Full argv, worktree, HEAD, cleanliness and artifact family per run: docs/probe-sigint-evidence.md.

#	reduction (after cargo test)	runs	result	log
R1	--test gpu_invocation_acceptance ctrl_c_on_launcher_group	3	green, 0.15–0.17 s	no log preserved
R2	--test gpu_invocation_acceptance (whole suite)	1	green, 15 passed	no log preserved
R3	--workspace --no-fail-fast -- --skip basedpyright ctrl_c_on_launcher_group	1	green — every binary runs, only this test executes	filtered.log
R4	--lib --test gpu_invocation_acceptance --no-fail-fast	1	green, 2145 + 15	two.log
R5	--test gate_script_acceptance --test gpu_invocation_acceptance	1	green	suspect.log
R6	--test gpu_font_acceptance --test gpu_initial_target_acceptance --test gpu_invocation_acceptance	1	green	gpu3.log
R7	--lib --bins + --test×14 (targets 6–19) + the suite	1	green	half1.log
R8	--test×18 (targets 20–37) + the suite	1	green	half2.log
R9	--lib --bins + --test×32 (targets 6–37) + the suite	1	green (reduction artifacts)	prefix.log
R10	--workspace ... --test gpu_initial_target_acceptance --test gpu_invocation_acceptance	1	green (workspace artifacts)	wsonly.log
F1–F5	full --workspace --no-fail-fast -- --skip basedpyright	5	red, 5/5	base-sweep.log (at 72da24a), postclean.log, sweep-inst.log, sweep-diag.log, gate …-2144707

Correction to revision 2: R9 did not run the same binaries. It executed gpu_initial_target_acceptance-91f51d0b5303ff9f and gpu_invocation_acceptance-6b4b8223dea45247; the failing sweeps executed -5d9105cb7047aab8 and -d4dae4f01bcdef62. Those artifacts are byte-different (sha256/16 36912fa2… vs 1b3cc86c…, and 858d7148… vs ede0c07d…; see docs/probe-sigint-evidence.md). Cargo's target selection changes the fingerprint, so command shape changes the executable. R9 therefore establishes same target names and order, not same binaries.

What the evidence actually supports is an interaction, and only that:

prior targets execute	workspace artifact family	result
yes	no	R9 green
no	yes	R10 green
yes	yes	F1–F5 red

Neither factor alone reproduces it. So --workspace artifact selection is not sufficient by itself — and, importantly, not ruled out either, which is how revision 2 phrased it. Later-selected packages can influence Cargo's build graph and fingerprints before their test executables ever run, so "their targets execute after the failure at line 3066" does not exonerate them. The same applies to the claim that other packages "cannot be implicated": withdrawn.

Also refuted, by measurement: machine load (red on a quiet box, load 2.77); tmpfs starving RAM (tested by experiment — /tmp 21 G → 1.2 G, available 27 G → 45 G, still red); leaked daemons (peak 58, +8 per sweep, green runs already at 46–60); inotify (47 of 1024).

5. Two retracted claims, both mine, kept as warnings

Claim A — "mechanism located". Reported the launcher blocked in do_wait on a probe child in futex_do_wait.

Claim B — the retraction of A. Argued A was unsupported because the failing launcher "must live ≥ 8 s" while the sampler's longest-lived was 5 s.

Claim B's arithmetic is false. Both reproducing binaries finish in ~5.19 s including the five-second timeout (:3097, :3131), so phase=ready is reached in roughly a tenth of a second and the failing launcher lives about 5.1 s total — squarely inside what the sampler observed. A ">6 s" selector would therefore have captured nothing, repeating the very sampling error it was written to correct.

So A is not refuted by B. A remains unproven for a different reason: under --features crdt the suite spawns root launchers from six call sites — :509, :534, :544, :574, :725, :1097, all inside #[cfg(feature = "crdt")] mod crdt (:88). Eight --gpu arguments appear in the file, but :38 and :65 sit under #[cfg(not(feature = "crdt"))] (:26) and are compiled out of the failing configuration. Revision 2 said "five" while citing eight, which was wrong twice over. Six is the number; what matters is that it is more than one, so a launcher captured by command line alone cannot be attributed to this test. The do_wait / futex_do_wait pair is consistent with the failing instance and consistent with a healthy sibling, and nothing recorded distinguishes them.

The standing lesson is now the opposite of revision 1's: do not key on process age at all. Key on identity.

6. Bets

1. The failure is a real teardown defect — a user pressing Ctrl-C on pmacs --gpu sees the same hang. This is a bet, not a finding, and the current witness does not reach the real GUI path: it goes through a wrapper script and --headless-managed-probe (:1090-1093), not a live wgpu frontend. Confirming or dropping this bet is D4 below.
2. It is not a timing margin. A green run finishes in 0.15 s against a 5 s deadline — 33×. Margins that large do not erode.
3. Therefore raising the deadline is not a fix and is out of scope. If the conclusion turns out to be that the deadline is wrong, that needs its own argument and its own approval.

7. First step — diagnostics keyed on identity, not age

No fix is proposed; the mechanism is unknown. The first commit is diagnostic only, and it must discriminate the three live candidates: blocked delivery, inherited ignore, and an escaped or wrong process group.

• D0 — re-run the §4 matrix with captured provenance, at main, recording the artifact hashes actually executed. Revision 2's strongest claim collapsed because command shape silently changed the binary; no further reduction should be trusted until each row names the executable it ran.
• D1 — key on the PID this test records. The test already owns launcher.id(). Capture around its own kill, not by scanning for age or command line.
• D2 — snapshot before and after the signal, for the test parent, the launcher, and the probe:
  • SigIgn, SigCgt, SigBlk — per thread, from /proc/<pid>/task/*/status, since SigBlk is thread-specific and a process-wide reading would hide a blocked delivery on the one thread that matters;
  • SigPnd and ShdPnd — a pending-but-undelivered SIGINT is exactly what distinguishes blocked delivery from ignore;
  • PID, PPID, PGID, SID for each — which settles whether the signal was even addressed to the right group, and whether anything escaped it. A post-failure snapshot alone cannot prove inheritance; the before/after pair is what makes the claim provable.
• D3 — run the full sweep under D1/D2 until the failure is captured with its diagnostics. Only then propose a fix.
• D4 — settle bet 1 separately. Establish whether a real pmacs --gpu session, not the wrapper/headless probe, reproduces the hang. The answer decides whether A5 is an obligation or is dropped.

8. Acceptance criteria for the eventual fix

Written now so the fix cannot quietly become "make the test pass".

• A1. The mechanism is stated and demonstrated, not inferred: a witness failing before the change and passing after, plus a mutation showing the witness bites its own clause.
• A2. sweep-crdt green for three consecutive full runs on the reviewed fixed head of this branch. Not "on main" — that is unobtainable before this lane is approved, gated and merged, and revision 1 stated an impossible precondition. Post-merge confirmation on main is a follow-up, not a gate on the fix.
• A3. The R9 paradox is explained, or explicitly recorded as unexplained. A fix that greens the sweep without accounting for why every subset passed leaves a gap, and the gap is stated rather than left for the next reader.
• A4. No deadline raised, no test skipped, retried, or serialised to obtain green.
• A5. Conditional on D4. If bet 1 holds, this is unconditional: Ctrl-C on a real pmacs --gpu session tears down the frontend and leaves the daemon running. If D4 shows the hang is reachable only through the wrapper/headless path, bet 1 is dropped, A5 is struck, and the lane is recorded as gate-correctness only.

9. Coherence impact (COHERENCE.md §20)

• Journey step touched: 12(a), "closing is clean." Ctrl-C teardown of a GPU session is exactly that step, whether or not its grade moves. Revision 1 said "journey steps touched: none", which was false — it reasoned from grade movement, which §20 explicitly warns against.
• Grade movement: none expected. This restores a property that is supposed to hold, rather than opening a new one.
• Interaction islands: none added.
• Config registry: not touched. Background-work attribution: not touched.
• Beyond step 12(a), what this lane restores is every other lane's ability to prove itself, since no branch can show a green gate while stage 15 reds.

10. Out of scope

• Raising or removing the 5 s deadline (bet 3).
• The ~10 daemons each sweep leaks — real, separately recorded, and not implicated: green runs already ran at 46–60 leaked daemons.
• gpu_initial_target_acceptance including the suite as a module. It is why the failure reds twice, and it is a tidiness question, not a correctness one.

11. Record corrections owed to other ledgers

A correction is not made until it is portable. Two were outstanding when revision 2 was reviewed, and both are closed by this revision:

• This branch's ledger asserted that two default-disposition processes "should both die at once" and then withdrew that same claim further down. The assertion is removed; only the withdrawal and its reasoning remain.
• panel-mapping-generation @ 16cf3a2 still carried "119 binaries green, one red", the ≥8 s arithmetic, the "default action" claim and the ">6 s selector". Pushing 16cf3a2 made the retraction portable but not the correction. That ledger is corrected on its own branch and pushed, so the held lane no longer transports falsified claims.