diff --git a/docs/process-signal-tolerance-framing.md b/docs/process-signal-tolerance-framing.md
new file mode 100644
index 0000000..1d3c45d
--- /dev/null
+++ b/docs/process-signal-tolerance-framing.md
@@ -0,0 +1,258 @@
+# Framing — make the PTY terminate failure self-describing (diagnostic only)
+
+**Revision 4.** Status: awaiting review round 4. Lane:
+`pty-terminate-eperm`, worktree `../pmacs-math-slice`, based on
+`githubsucks/main` @ `ccf29e3`.
+
+**Diagnostic only. No disposition changes, no tolerance rules, no
+behavioural fix.** Every rule this document proposed across revisions 1
+to 3 is parked (§5). The lane's entire deliverable is that the next
+occurrence of the failure explains itself.
+
+## Revision history
+
+**Revision 3 → 4**, after review round 3 (two blocking, one major) and
+its scope call. All accepted.
+
+- **Group-directed ESRCH was also unsafe**, for the same reason EPERM
+  was: it proves the selected *foreground group* vanished, not that the
+  leader exited. A job-control race — foreground job exits after
+  `tcgetpgrp` and before `kill`, shell alive and not yet reclaiming the
+  terminal — would have been reported as success with the leader never
+  signalled. Rev 3's acceptance 7 pinned that unsafe behaviour. **All
+  tolerance is parked** (§5).
+- **Rev 3's Stage A implemented Stage B.** It declared itself
+  diagnostic-only, then listed tolerance and bookkeeping acceptances.
+  Removed.
+- **Q#PS6 (already-reaped `terminate` is `Ok`) is parked separately.**
+  It is an independent behavioural fix answering a different failure;
+  under one-feature/one-PR it does not ride with instrumentation.
+- **"Strictly additive / cannot regress behaviour" was overstated** and
+  is narrowed (Q#PD3).
+- The injected-kill seam is restored as an explicit decision (Q#PD4).
+
+**Rounds 1–3, for the record.** Rev 1 classified on errno alone and
+claimed a live owned child cannot yield EPERM — false. Rev 2 gated on
+`try_wait`, which observes the leader while a PTY signal targets the
+foreground group — unsound whenever those diverge, and it could not be
+shown to fix the observed failure at all. Rev 3 corrected EPERM but left
+ESRCH unsafe and mixed the stages. **Three consecutive designs were
+wrong in the same direction: each tried to conclude something about a
+process from something that was not about that process.**
+
+
+## 0. Coherence impact (COHERENCE §20)
+
+- **Journey step 8, "Open a terminal"** (§2), teardown half. **No grade
+  change and no behavioural change** — this lane only improves what a
+  failure reports.
+- **Serves §9 (worker model), failure attribution**, in its most literal
+  sense: an error that names only an errno cannot be attributed.
+- **Interaction islands: none. Config registry: not adopted.
+  Background-work attribution: unchanged.**
+- **No audited claim in COHERENCE.md changes**, so under §25 no
+  COHERENCE edit rides this PR.
+
+
+## 1. Ground truth (scouted @ `ccf29e3`, re-verified each revision)
+
+### 1.1 The failure reports an errno and nothing else
+
+`ProcessSupervisor::signal` (`src/process.rs:921`) maps the `kill`
+failure to `format!("kill: {e}")` (`:931`). That string is everything a
+reader gets.
+
+### 1.2 The signal target is not the observation target
+
+- **Signal target** — `signal_target` (`:687`) returns `-pgrp` for a
+  PTY, where `pgrp = master.process_group_leader()`: the tty's
+  **current foreground process group**, read at signal time.
+- **Observation target** — `ChildHandle::try_wait` (`:668`) observes the
+  **spawned leader**.
+
+They coincide only while the leader owns the terminal. Job control is
+precisely the mechanism that makes them diverge, and the PTY path is
+**always group-directed by design** — spawn rejects `group = true` for
+PTY mode with the rationale that "PTY children already lead their own
+session and are signaled group-wide" (`:1428-1429`).
+
+**This is why every tolerance rule across rev 1–3 failed review**, and
+why the diagnostic must record the target and the leader state as
+*separate* facts.
+
+### 1.3 The reap ledger is disjoint from this path
+
+`tick_reap_ledger` (`:1075`) treats any probe error as "nothing left we
+can reach" for **bounded growth**, asserting EPERM "cannot happen for our
+own children". It is armed only for `proc.spec.group`, which PTY mode
+cannot set. Rev 1's "asymmetry" argument was a misreading; withdrawn.
+
+### 1.4 The observed failure, and the limits of the evidence
+
+macOS CI, PR #172 (**docs-only** diff), `Test (macos-latest / luajit)`,
+`acc28_child_input_and_the_c_c_escape_work_unchanged_in_a_panel`
+([attempt 1](https://github.com/levineuwirth/pmacs/actions/runs/30177276839/attempts/1)):
+
+```
+in function 'terminate'
+cause: ExternalError(Process("kill: EPERM: Operation not permitted"))
+```
+
+**Established:** the errno, and the call path
+(`pmacs.terminal.terminate` → `session.rs:566` → `signal`).
+
+**Not established:** that the child had exited (the probe's last source
+statement is a file write at
+`tests/bottom_panel_stage1_acceptance.rs:2239`; CPython teardown follows
+and does not synchronise with it); that any pgid was recycled; or what
+the signal target actually was.
+
+**This is the whole reason the lane is diagnostic.** Every candidate fix
+needs at least one of those three facts, and none is available.
+
+### 1.5 Caller inventory
+
+| Caller | Disposition |
+|---|---|
+| `src/lsp.rs:1364`, `:2427` | discards (`let _ =`) |
+| `src/mcp.rs:1229`, `:1239`, `:1915` | discards (`let _ =`) |
+| `src/terminal/session.rs:319`, `:607`, `:635` | discards (`let _ =`) |
+| **`src/terminal/session.rs:566`** (propagating at `:577`) | **propagates** as `TerminalError::Process` |
+| supervisor-internal `shutdown` path | discards |
+| `src/lua_bindings/mod.rs:8150`, `:8164` | propagates to Lua |
+| `src/lua_bindings/mod.rs:8717` | propagates (via `session.rs:566`) |
+| `src/daemon.rs:4162` | **test-only** `.expect`, not production |
+
+No test in the repository asserts either error string, so widening the
+message breaks nothing.
+
+### 1.6 `portable-pty` caches the exit status on Unix
+
+Pinned `portable-pty 0.9.0`: `spawn_command` returns
+`std::process::Child` (`unix.rs:228`), and `impl Child for
+std::process::Child::try_wait` delegates to
+`std::process::Child::try_wait` (`lib.rs:271-277`), which caches into
+`self.status`. Both `ChildHandle` variants therefore cache.
+
+
+## 2. Decisions
+
+### Q#PD1 — what the widened error records
+
+On a `kill` failure in `signal`, the error carries:
+
+| Field | Why |
+|---|---|
+| **target source** — `tcgetpgrp` vs `group` vs `leader-pid` fallback | which branch of `signal_target` (`:687`) ran |
+| **target kind and value** — `-pgid` or `pid`, with the number | the entity actually signalled |
+| **spawn-time pgid / leader pid** | a divergence from the target is the job-control hypothesis, visible only by comparison |
+| **errno** | as today |
+| **leader `try_wait` state** — `exited(status)` / `live` / `unobservable(e)` | separates "the leader is gone" from "the group we signalled is gone" — the distinction all three failed designs collapsed |
+
+Every candidate Stage B rule is decidable from these five together, and
+none is decidable from the errno alone.
+
+### Q#PD2 — the disposition is preserved exactly
+
+The call still fails, with the same `Err`, in every case. No state
+transition changes, no ledger arming changes, no tolerance. A reader
+diffing behaviour should find none.
+
+### Q#PD3 — the honest claim is "no disposition change", not "strictly additive"
+
+Rev 3 said the diagnostic was only an error-string change and could not
+regress behaviour. **That overstated it.** `try_wait` on an exited child
+**reaps it and caches the status**, so consulting it in the failure path
+is an internal state change: the child may be reaped earlier than it
+otherwise would be.
+
+Observably safe, because both variants cache (§1.6) and `poll_one`
+(`:1133`) will still see `Ok(Some(_))` and emit its event. But safe by
+argument is not safe by assertion, so the terminate-failure-then-tick
+event pin is retained (acceptance 5).
+
+### Q#PD4 — the injected-kill seam injects the KILL, never the observation
+
+Acceptance 5 needs a forced `kill` failure while the **real**
+`ChildHandle::try_wait` runs against the **real** child. A stubbed
+observation would bypass exactly the code path in question.
+
+So the seam is a test-only override of the *kill attempt's result*,
+consumed once by the signal path; everything downstream — target
+selection, the observation, the error construction — runs for real. This
+also makes the diagnostic's own fields testable without racing the
+kernel.
+
+### Q#PD5 — nothing else lands here
+
+No tolerance rule, no idempotence change, no `signal_target` change. See
+§5.
+
+
+## 3. Bets (falsifiable)
+
+- **B1 — The five fields are sufficient to discriminate the §1.4
+  hypotheses.** Falsified if a recurrence carries all five and still
+  leaves the cause ambiguous — which would itself be a finding worth
+  having.
+- **B2 — Widening the message breaks no caller.** Evidence: §1.5, and no
+  test asserts the string.
+
+*Retracted across revisions and not reinstated:* rev 1's "a live owned
+child cannot yield EPERM"; rev 2's "exit observation suffices"; rev 2's
+"this removes the failure class"; rev 3's "group ESRCH is safe to
+tolerate".
+
+
+## 4. Acceptance
+
+1. A group-directed `kill` failure produces an error carrying all five
+   Q#PD1 fields, with the target rendered as `-pgid` and the leader
+   state distinct from it.
+2. A leader-directed `kill` failure does the same, with the target
+   rendered as `pid` and the target source recorded as the fallback
+   branch.
+3. The leader state renders each of `exited(status)`, `live`, and
+   `unobservable(e)` correctly.
+4. **The disposition is unchanged**: every injected failure still
+   returns `Err`, with no state transition and no ledger arming
+   (Q#PD2). Falsified by revert — flipping any arm to `Ok` fails this.
+5. **Forced injected kill failure against the real PTY child
+   observation**, then tick: exactly one exit event, with the correct
+   status (Q#PD3/Q#PD4). A fully stubbed observation does not satisfy
+   this and is rejected as vacuous.
+6. The existing suites stay green, pinning "no behavioural change" from
+   the outside.
+
+
+## 5. Parked (not deferred-and-forgotten — each needs its own evidence)
+
+- **All tolerance rules.** Group-directed EPERM *and* ESRCH both fail on
+  the §1.2 entity split; leader-directed tolerance is plausible but
+  unmotivated until evidence shows the fallback branch is ever taken.
+  Needs Stage A evidence first.
+- **Q#PS6, `terminate` on an already-reaped process returning `Ok`.**
+  Independent behavioural fix, different failure (§1.6 of rev 3), its
+  own lane under one-feature/one-PR.
+- **`signal_target`'s read-then-kill of `tcgetpgrp`** — still the most
+  likely real fix site, still unframed.
+- `terminate` cancelling pending restarts; PTYs in
+  `pmacs.process.list`; any change to `C-c` delivery.
+
+
+## 6. Gates
+
+Full suite per `CLAUDE.md`. Touched suites:
+`bottom_panel_stage1_acceptance`, the vterm stages, and
+`compile_mode_acceptance`. Sweep with `-- --skip basedpyright`.
+
+
+## 7. Branch plan
+
+`pty-terminate-eperm`, one PR, diagnostic only. This framing is its first
+commit; the instrumentation and its tests are the second.
+
+**The lane then closes.** It does not wait for the flake to recur: the
+next occurrence — whenever it happens, under whoever's PR — carries its
+own evidence, and Stage B is framed then. Math work proceeds immediately
+after this lands.