fix(fspy): replace quiescence locking with crash-tolerant shared-memory publication

[wan9chi]

Motivation

Collecting a run's file accesses required every writer to hold still. The receiver could only read the frame stream once each sender had released a file lock, and that coupling broke in two ways:

• #544: a traced process that closes inherited file descriptors (python-daemon, for one) releases the lock while keeping the shared memory writable. The reader then races live writers and reads path bytes as a frame header, panicking the runner.
• A descendant that outlives the task blocks collection for as long as it runs. #577 tried an in-mapping writer count instead, but any process that dies between increment and decrement poisons it forever, since no userspace cleanup runs on SIGKILL.

Correctness cannot depend on how long a file descriptor lives, or on writers running cleanup while the task tears down.

The protocol

fspy_shared::ipc::channel::shm_io publishes frames through a descriptor table instead of inline headers. README.md in that directory is the full description; the shape is:

| counters | descriptor table (one slot per frame) | payloads (the rest, grow up) |

• Claiming is wait-free. Two fetch_adds reserve payload bytes and a slot, with no retry loop and no lock. Each writer checks what the counter returned against a fixed limit, so overshooting costs nothing: no counter says where data is, since every committed descriptor carries its own offset and length.
• Publishing is one store. The writer fills a span nobody else knows about, then stores the descriptor with Release. Only the writer that claimed a slot ever writes it, so it needs no compare-and-swap. The receiver loads with Acquire, so a descriptor it sees brings the payload bytes along.
• Death and abandonment are the same state. An unfinished slot stays zero and the receiver ignores it. No cleanup code runs because none exists — no exit hooks, PID checks, heartbeats or timeouts.
• Sealing never waits and never writes. One swap puts the CLOSED gate into the claim counter and reads the old value, drawing the boundary and shutting the gate at a single point in that counter's modification order. Sealing a channel holding ten million frames costs what sealing an empty one costs. Frames are then read in place, straight out of shared memory, with no copies.

The channel asks one thing of its users: publish a record before performing the action it describes. A dead writer's missing record then describes an action that never happened, and a record refused after the seal describes one performed after the channel closed. The receiver drops both, and both answers are truthful. This holds across the Unix preload and the Windows detours; the Linux seccomp path collects supervisor-side and is unaffected.

Running out of room

A claim with nowhere to go sets the CLOSED gate before returning, and the writer skips that record and carries on — recording must never stop the program doing the work. The gate is also what tells the receiver: a seal that finds it already set hands back nothing, so the run is reported as untracked rather than as having touched only the paths that fit.

Setting the bit first matters for the same reason publishing before acting does. If the seal misses the bit, the writer set it after the boundary, so the skipped record describes an action performed after the channel closed; and a writer that died before setting it never performed its action.

This replaces a panic, and that panic is #533: on the base of this PR a full region aborts the traced process, because the panic fires inside an interposed extern "C" function that cannot unwind. It is reachable by workload rather than by any bug — #533 was hit as a SIGABRT storm when vite-plus#2123's bunx self-recursion flooded the channel — so a large enough build could kill the compiler doing the work. It now costs an uncached task instead, which is the fail-open behaviour that issue asks for, down to flagging the trace incomplete so nothing caches from it.

One clause of #533 is not met, deliberately. It asks for no panic in a no-unwind context at all, and Sender::send still has asserts that only a disagreement between this crate and its codec can trip. Attaching a sender is a further, deliberate exception in the other direction: see the last point below.

Consequences elsewhere

• The lock file is gone. ChannelConf carries the shm id and the slot count, and Receiver::lock became a consuming, nonblocking Receiver::close.
• The ouroboros self-referencing guard in fspy::ipc is gone with it, since frames are borrowed from the mapping the reader owns.
• Receiver::close reports only the one failure a caller can act on — a record a sender could not write — and panics on a region that cannot hold the protocol, which channel proved it could before any sender saw it.
• A run whose tracking came up short no longer fails the task. The runner reports it as a not-cached reason, since the task did its work and only the record of it is missing.
• Attaching a sender now fails only when the channel is already over. Anything else — a file that will not open, or one that cannot hold the protocol — panics, because a process with no writer cannot tell the receiver it recorded nothing, and a trace that silently omits every access is worse than no trace. Panicking in the preload is not new: the base panics on a failed claim, an empty record, a size that does not fit a usize, and an underfilled frame. This PR removes the reachable one and adds one that only a broken channel reaches.

Each file carries one argument: layout holds the shared shape, the descriptor codec and the three-rule memory-ordering contract that the code cites by rule number; writer and reader each carry a single aliasing justification.

Known regression: Linux task launch

The benchmark's Linux launch rows read +158% dynamic and +221% static, against roughly 0% on macOS and Windows and roughly 0% on every access row. Read that as an absolute number rather than a ratio: it is the one-off cost of first-touching the region's first pages, a millisecond or two, and the benchmark's launch target opens nothing at all, so a couple of milliseconds is most of what it measures. Against a real tsc or vitest task it is not visible. It is also per channel, which is per tracked spawn, so a build spawning hundreds of tasks pays it hundreds of times.

Two things about it are settled by earlier work on this branch: the cost is in the fault path rather than block allocation, so fallocate(KEEP_SIZE) does not help (measured — it went backwards), and reads of holes on this runner cost the same as writes. A Linux-gated background pre-fault thread used to hide it and brought the row to ~+21-28%; it was removed on this branch because it buys nothing where /tmp is tmpfs and cost more than it saved on the other platforms.

The fix that would remove the cost rather than mask it is to put the region on a filesystem that does not journal — /dev/shm on Linux, with temp_dir() as the fallback elsewhere. That is a separate change, and this project's history says to measure it rather than reason about it.

Everything else measured flat: access +1.83%/+0.34% on Linux, +0.96% macOS, +0.17% Windows, all inside the benchmark's ~2.3pp noise floor.

Verification

Miri covers the protocol tests, including the slot state machine, seal races and concurrent writers. Cross-process tests cover real shared memory and a writer hard-killed mid-frame (SIGKILL / TerminateProcess via Child::kill).

The e2e case from the base PR now does what it was written for. A 64 KiB channel holds a thousand records — one descriptor slot per 64 bytes of the region — and the task makes twenty thousand accesses, so the snapshot shows the task printing its last line and exiting cleanly, with the run reported as not cached, twice over: the second run does not replay an entry built from part of a trace. The case skips musl, which has no preload and collects through the seccomp supervisor, so there is no channel there to fill.

Closes #544. Fixes #533. Partly addresses #605, whose signal-handler, post-fork and errno requirements this does not touch. Supersedes #577. Stacked on #680.

🤖 Generated with Claude Code

[github-actions]

fspy benchmark

linux

dynamic/launch             change +158.81%  [+136.04% .. +189.36%]  overhead  +308.59%
dynamic/access             change  +2.57%  [ -4.53% .. +37.70%]  overhead   +11.16%
dynamic/access-relative    change  +3.18%  [ -6.49% .. +36.49%]  overhead   +48.83%
static/launch              change +209.67%  [+177.86% .. +249.11%]  overhead  +669.39%
static/access              change  +0.04%  [ -9.40% ..  +8.17%]  overhead  +814.64%
static/access-relative     change  -0.07%  [ -4.90% ..  +4.15%]  overhead +1162.54%

macos

dynamic/launch             change  +0.88%  [ -4.49% ..  +5.14%]  overhead  +237.79%
dynamic/access             change  +0.33%  [ -3.34% ..  +3.38%]  overhead    +3.49%
dynamic/access-relative    change  +1.44%  [-10.32% .. +20.81%]  overhead  +243.16%

windows

dynamic/launch             change  -2.31%  [ -6.74% ..  +3.50%]  overhead   +26.25%
dynamic/access             change  -0.19%  [ -2.86% ..  +1.50%]  overhead    +1.13%
dynamic/access-relative    change  +0.00%  [ -1.43% ..  +7.30%]  overhead    +0.93%