Add --shm orphan sweep to tractor-reap

Since `tractor.ipc._mp_bs.disable_mantracker()` turns off
`mp.resource_tracker` entirely (see the conc-anal doc
`subint_forkserver_mp_shared_memory_issue.md`), a
hard-crashing actor can leave `/dev/shm/<key>` segments
that nothing else GCs. New `tractor-reap` phase 2 sweeps
them.

Deats,
- `tractor/_testing/_reap.py`: add `find_orphaned_shm()`
  + `reap_shm()` helpers. Match criteria: regular file
  under `/dev/shm`, owned by current uid, AND no live
  proc has it open (mmap'd or fd-held). In-use
  enumeration via `psutil.Process.memory_maps()` +
  `.open_files()` — xplatform, kernel-canonical (same
  answer `lsof` would give), no reliance on
  tractor-specific shm-key naming.
- `_ensure_shm_supported()` guard: helpers raise
  `NotImplementedError` outside Linux/FreeBSD bc macOS
  POSIX shm has no fs-visible path (`shm_open` only)
  and Windows is a different story.
- `scripts/tractor-reap`: new `--shm` (run after
  process reap) and `--shm-only` (skip process phase)
  flags. `-n` dry-runs both phases. Exit code is `1`
  if either phase had survivors/errors.
- `pyproject.toml` + `uv.lock`: add `psutil>=7.0.0` to
  the `testing` dep group; lazy-imported in `_reap.py`
  so the process-reap path stays import-clean without
  it.

Also,
- doc `--shm` in `.claude/skills/run-tests/SKILL.md`
  (new section 10c) — covers match criteria + the
  preservation guarantee for unrelated apps.
- flip mitigation status in
  `subint_forkserver_mp_shared_memory_issue.md` from
  "could extend `tractor-reap`" to "implemented", with
  a note that callers should still UUID-pin shm keys to
  avoid cross-session collisions.

Verified locally vs 81 in-use segments held by `piker`,
`lttng-ust-*`, `aja-shm-*` — all preserved; only the
genuinely-orphaned tractor segments got unlinked.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code

Author: goodboy

.claude/skills/run-tests/SKILL.md

@@ -585,3 +585,41 @@ to force-reap under a still-live supervisor.
 active in another terminal. It's safe (won't touch
 that session's live children in orphan-mode) but can
 race if the target session is mid-teardown.
+
+### c) `--shm` / `--shm-only`: orphan-segment sweep
+
+Because `tractor.ipc._mp_bs.disable_mantracker()`
+turns off `mp.resource_tracker` (see
+`ai/conc-anal/subint_forkserver_mp_shared_memory_issue.md`),
+a hard-crashing actor can leave `/dev/shm/<key>`
+segments behind that nothing else GCs.
+
+```sh
+# process reap THEN shm sweep
+scripts/tractor-reap --shm
+
+# shm sweep only (skip process phase)
+scripts/tractor-reap --shm-only
+
+# dry-run: list candidates, don't unlink
+scripts/tractor-reap --shm -n
+```
+
+**Match criteria** (very conservative — this is a
+shared-system path, can't be wrong):
+- segment is a regular file under `/dev/shm`,
+- owned by the **current uid** (`stat.st_uid`),
+- AND **no live process holds it open** —
+  enumerated by walking every readable
+  `/proc/<pid>/maps` (post-mmap mappings) AND
+  `/proc/<pid>/fd/*` (pre-mmap shm-opened fds).
+
+The "nobody has it open" check is the
+kernel-canonical "is this leaked?" test — same
+answer `lsof /dev/shm/<key>` would give. No
+reliance on tractor-specific naming, so it works
+for any tractor app. Critically, it WILL NOT touch
+segments held by other apps you have running
+(e.g. `piker`, `lttng-ust-*`, `aja-shm-*` —
+verified locally with 81 in-use segments correctly
+preserved).

ai/conc-anal/subint_forkserver_mp_shared_memory_issue.md

@@ -132,14 +132,20 @@ segment (legitimate race in shared-key setups).
 
 - **Crash-leaked segments.** If an actor segfaults
   or is `SIGKILL`'d before its lifetime stack runs,
-  `/dev/shm/<key>` will leak. Mitigations:
-  - `tractor-reap` (the new
-    `scripts/tractor-reap` CLI) doesn't yet sweep
-    `/dev/shm` — could extend it.
-  - Higher-level apps using shm should pin a UUID
-    into the key (the `'shml_<uuid>'` pattern in
-    `test_child_attaches_alot`) so leaks are
-    distinct per session and easy to GC out-of-band.
+  `/dev/shm/<key>` will leak. Mitigation:
+  `scripts/tractor-reap --shm` walks `/dev/shm`,
+  filters to segments owned by the current uid that
+  no live process is mapping or holding open (via
+  `/proc/*/maps` + `/proc/*/fd/*`), and unlinks
+  them. The "nobody-has-it-open" filter is
+  kernel-canonical so it never touches in-flight
+  segments held by sibling apps (verified locally
+  against 81 piker/lttng/aja-held segments — all
+  preserved).
+  - Higher-level apps using shm should still pin a
+    UUID into the key (the `'shml_<uuid>'` pattern
+    in `test_child_attaches_alot`) so concurrent
+    sessions don't collide on the same key.
 - **Cross-actor unlink races.** Two actors holding
   the same shm key racing on `unlink()` — handled
   by the `FileNotFoundError` swallow.

pyproject.toml

@@ -84,6 +84,11 @@ testing = [
   # known-hanging `subint`-backend audit tests; see
   # `ai/conc-anal/subint_*_issue.md`).
   "pytest-timeout>=2.3",
+  # used by `tractor._testing._reap` for the
+  # `tractor-reap` zombie-subactor + leaked-shm
+  # cleanup utility (xplatform `Process.memory_maps`,
+  # `Process.open_files`).
+  "psutil>=7.0.0",
 ]
 repl = [
   "pyperclip>=1.9.0",

scripts/tractor-reap

@@ -4,14 +4,26 @@
 #
 # SPDX-License-Identifier: AGPL-3.0-or-later
 '''
-`tractor-reap` — SC-polite zombie-subactor reaper.
+`tractor-reap` — SC-polite zombie-subactor reaper +
+optional `/dev/shm/` orphan-segment sweep.
 
-Finds `tractor` subactor processes left alive after a
-`pytest` (or any tractor-app) run that failed to fully
-cancel its actor tree, then sends SIGINT with a bounded
-grace window before escalating to SIGKILL.
+Two cleanup phases (run in order when both are enabled):
 
-Detection modes (auto-selected):
+1. **process reap** — finds `tractor` subactor processes
+   left alive after a `pytest` (or any tractor-app) run
+   that failed to fully cancel its actor tree, then sends
+   SIGINT with a bounded grace window before escalating
+   to SIGKILL.
+
+2. **shm sweep** (`--shm` / `--shm-only`) — unlinks
+   `/dev/shm/<file>` entries owned by the current uid
+   that no live process has open (mmap'd or fd-held).
+   Needed because `tractor` disables
+   `mp.resource_tracker` (see `tractor.ipc._mp_bs`), so a
+   hard-crashing actor leaves leaked segments that
+   nothing else GCs.
+
+Process-reap detection modes (auto-selected):
 
     --parent <pid>  : descendant-mode — kill procs whose
                       PPid == <pid>. Use when a parent
@@ -29,14 +41,21 @@ Detection modes (auto-selected):
 
 Usage:
 
-    # after a pytest run crashed/was Ctrl+C'd
+    # process reap only (default)
     scripts/tractor-reap
 
+    # process reap + shm sweep
+    scripts/tractor-reap --shm
+
+    # only the shm sweep, skip process reap
+    scripts/tractor-reap --shm-only
+
     # from inside a still-live supervisor
     scripts/tractor-reap --parent 12345
 
-    # dry-run: list what would be reaped, don't signal
+    # dry-run: list what would be reaped, don't act
     scripts/tractor-reap -n
+    scripts/tractor-reap --shm -n
 
 '''
 import argparse
@@ -83,7 +102,21 @@ def main() -> int:
     parser.add_argument(
         '--dry-run', '-n',
         action='store_true',
-        help='list matched pids but do not signal',
+        help='list matched pids/paths but do not signal/unlink',
+    )
+    parser.add_argument(
+        '--shm',
+        action='store_true',
+        help=(
+            'after process reap, also unlink orphaned '
+            '/dev/shm segments owned by the current user '
+            'that no live process is mapping or holding open'
+        ),
+    )
+    parser.add_argument(
+        '--shm-only',
+        action='store_true',
+        help='skip process reap; only do the shm sweep',
     )
     args = parser.parse_args()
 
@@ -95,29 +128,54 @@ def main() -> int:
     from tractor._testing._reap import (
         find_descendants,
         find_orphans,
+        find_orphaned_shm,
         reap,
+        reap_shm,
     )
 
-    if args.parent is not None:
-        pids: list[int] = find_descendants(args.parent)
-        mode: str = f'descendants of PPid={args.parent}'
-    else:
-        pids = find_orphans(repo)
-        mode = f'orphans (PPid=1, cwd={repo})'
-
-    if not pids:
-        print(f'[tractor-reap] no {mode} to reap')
-        return 0
-
-    if args.dry_run:
-        print(f'[tractor-reap] dry-run — {mode}:\n  {pids}')
-        return 0
-
-    signalled, survivors = reap(pids, grace=args.grace)
-    # exit 0 if everyone exited cleanly, else 1 to signal
-    # escalation happened — makes the command useful in
-    # CI health-checks and `||`-chaining.
-    return 0 if not survivors else 1
+    rc: int = 0
+
+    # --- phase 1: process reap (skipped under --shm-only) ---
+    if not args.shm_only:
+        if args.parent is not None:
+            pids: list[int] = find_descendants(args.parent)
+            mode: str = f'descendants of PPid={args.parent}'
+        else:
+            pids = find_orphans(repo)
+            mode = f'orphans (PPid=1, cwd={repo})'
+
+        if not pids:
+            print(f'[tractor-reap] no {mode} to reap')
+        elif args.dry_run:
+            print(
+                f'[tractor-reap] dry-run — {mode}:\n  {pids}'
+            )
+        else:
+            _, survivors = reap(pids, grace=args.grace)
+            if survivors:
+                rc = 1
+
+    # --- phase 2: shm sweep (opt-in) ---
+    if args.shm or args.shm_only:
+        leaked: list[str] = find_orphaned_shm()
+        if not leaked:
+            print(
+                '[tractor-reap] no orphaned /dev/shm '
+                'segments to sweep'
+            )
+        elif args.dry_run:
+            print(
+                f'[tractor-reap] dry-run — {len(leaked)} '
+                f'orphaned shm segment(s):\n  {leaked}'
+            )
+        else:
+            _, errors = reap_shm(leaked)
+            if errors:
+                rc = 1
+
+    # exit 0 if everything cleaned cleanly, else 1 — useful
+    # for CI health-check chaining.
+    return rc
 
 
 if __name__ == '__main__':