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

# GPU launcher / probe SIGINT teardown — framing

Revision 1. Status: **awaiting approval. No implementation.**

## 1. The problem, stated as what is observed

`gpu_invocation_acceptance::crdt::ctrl_c_on_launcher_group_does_not_reach_spawned_daemon`
fails inside the `sweep-crdt` gate stage 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**, and requires the
launcher to exit within five seconds.

This is **pre-existing on `main`**. It is not caused by any feature
branch: the identical `build-crdt && sweep-crdt` pair run at `72da24a`
in a clean worktree with its own target directory fails the same test —
119 test binaries green, one red.

## 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. The
`panel-mapping-generation` (§5b) lane is complete with its own fifteen
stages green and is held behind this lane by explicit instruction.

## 3. Ground truth (cited, not recalled)

- **The launcher does not handle signals.** `run_gpu`
  (`src/main.rs:324`) builds a `Command` for the GPU binary and blocks
  in `command.status()` (`:363`) — a plain `waitpid`. It installs no
  handler, so `SIGINT`'s default action should terminate it outright.
- **`pmacs-gpu` does not handle signals either.** Grepping
  `SIGINT|signal_hook|sigaction|ctrlc|set_handler|pthread_sigmask|sigprocmask`
  across `pmacs-gpu/src` returns **nothing**. The probe should also die
  on the default action.
- **The probe never blocks indefinitely.** `run_headless_managed_probe`
  (`pmacs-gpu/src/main.rs:1065`) loops on
  `event_rx.recv_timeout(Duration::from_millis(50))`, so it wakes twenty
  times a second regardless of traffic.
- **The daemon *does* handle signals**, and deliberately:
  `src/daemon.rs:629-641` registers `SIGTERM`/`SIGINT` through
  `signal_hook::flag`. The daemon is the process the test asserts must
  **survive**; it is detached from the launcher's group, which is the
  property under test.
- **Only one test in the suite uses `process_group(0)`** — this one.

Taken together the ground truth **deepens** the puzzle rather than
explaining it: two processes with default `SIGINT` disposition, one of
them polling at 50 ms, should both die immediately.

## 4. What has been ruled out, each by measurement

Recorded so this lane does not re-run them.

| hypothesis | how it was refuted |
|---|---|
| machine load | red on a quiet box, load 2.77 at launch |
| tmpfs starving RAM | `/tmp` 21 G → 1.2 G, available 27 G → 45 G; still red |
| leaked test daemons | peak 58, only +8 per sweep; green runs already sat at 46–60 |
| inotify exhaustion | 47 instances in use of 1024 |
| `--workspace` feature unification | same two targets under `--workspace` are green |
| a specific preceding test | **all 37 preceding targets + the suite run green** |
| later targets / other packages | they run at log lines 4848+, after the failure at 3066 |

**The last row is the strange one and is the real shape of this
problem**: the same binaries, in the same order, with the same tests
before it, pass as a subset and fail as part of the whole 119-target
sweep. Reproduction is 5/5 in the full sweep across two trees, and 0/N
in every reduction attempted.

## 5. One retracted claim, kept as a warning

An earlier attempt reported the mechanism as "the launcher blocks in
`do_wait` on a probe child stuck in `futex_do_wait`". **That was
retracted on its own evidence.** The sampler behind it caught 394
launchers and the longest-lived was **5 s total**; the failing instance
must outlive its `SIGINT` by 5 s, so its lifetime would be 8 s or more.
What was described is a *healthy* teardown from another test in the
suite. The pair is worth keeping only as the normal shape.

The lesson binds this lane's first step: **an instrument that samples
every launcher and hopes to catch the failing one is not good enough.**

## 6. Bets

1. The failure is a real teardown defect reachable by a user pressing
   Ctrl-C, not a test artifact — because the test asserts an ordinary
   product property and the two binaries involved carry no signal
   handling at all.
2. It is **not** a timing margin. A green run finishes in 0.15 s against
   a 5 s deadline (33×). A margin that large does not erode; something
   different happens.
3. Therefore **raising the deadline is not a fix** and is explicitly out
   of scope. If the conclusion turns out to be that the deadline is
   wrong, that requires its own argument and its own approval.

## 7. First step — an instrument that keys on the failing instance

No fix is proposed yet, because the mechanism is unknown. The first
commit is diagnostic only:

- **D1.** Sample only launchers whose lifetime exceeds ~6 s, so the
  failing instance is the *only* thing recorded, and capture for it:
  `/proc/<pid>/status` (`SigBlk`, `SigIgn`, `SigCgt`, `State`), the
  per-thread `wchan` under `/proc/<pid>/task/*/wchan`, and the same for
  every child. `SigIgn`/`SigBlk` answers directly whether `SIGINT` was
  ignored or blocked — including whether it was **inherited**, since
  `SIG_IGN` survives both `fork` and `exec` while handlers do not.
- **D2.** Record whether the launcher had already reaped its child at
  the moment the deadline expired, which separates "the child will not
  die" from "the launcher will not notice".
- **D3.** Run the full sweep under D1/D2 until the failure is captured
  **with** its diagnostics, and only then propose a fix.

## 8. Acceptance criteria for the eventual fix

Deliberately written now, so the fix cannot quietly become "make the
test pass".

- **A1.** The named mechanism is stated and demonstrated, not inferred:
  a witness that fails before the change and passes after, plus a
  mutation showing the witness bites its own clause.
- **A2.** `sweep-crdt` green on `main` for **three consecutive full
  runs** — 1/1 is not evidence for a defect that hid from every
  reduction.
- **A3.** The reduction paradox is explained or explicitly recorded as
  unexplained. If the fix makes the sweep green without accounting for
  why subsets always passed, that gap is stated in the record rather
  than left for the next reader to rediscover.
- **A4.** No deadline is raised, and no test is skipped, retried, or
  serialised to obtain green.
- **A5.** If the mechanism proves to be in `pmacs-gpu`'s shutdown path,
  a Ctrl-C on a real `pmacs --gpu` session tears down the frontend and
  leaves the daemon running — the product property the test encodes.

## 9. Coherence impact (`COHERENCE.md` §20)

- **Journey steps touched: none.** This is a teardown-correctness and
  gate-trustworthiness lane; no journey step changes grade.
- **Interaction islands: none added.**
- **Config registry: not touched.**
- **Background-work attribution: not touched.**

Naming these explicitly matters: a reader auditing §20 by grade movement
would otherwise conclude this lane touches nothing, when what it
restores is the ability of every other lane to prove itself.

## 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 here — green runs already ran at 46–60 leaked daemons.
- The `gpu_initial_target_acceptance` binary including this suite as a
  module, which makes a reproducing sweep report the failure twice. A
  tidiness question, not a correctness one.