Doc the #477 migration outcome + one-shot-acm sketch

Fold the endeavour's resolution into the plan doc + log the
session per prompt-io policy,

- `ria_nursery_removal_plan.md`: RESOLVED section — migrate
  everything, remove the API; the migration-pattern table
  (blocking / fire-and-forget / fan-out / collect-don't-cancel
  / mutual-rendezvous), the semantic deltas (cancel-on-first +
  `collapse_eg()` chain collapse vs the old teardown-reap BEG),
  the excision inventory and the structural dissolution of the
  reap-hang class.
- adds the `to_actor.open_one_shot()` follow-up sketch: an
  `@acm` + private task-nursery over the existing blocking
  `run()` — done-`trio.Event` as a result memo (NOT a
  cancel-relay), no `Portal` in the iface, errors always
  propagate at scope exit; zero `_supervise` coupling.
- prompt-io entry `20260706T172818Z_ad42871e` (+ raw diff-ref
  companion) covering commits `d01a2123..ad42871e`.

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

.github/workflows/ci.yml

@@ -91,6 +91,10 @@ jobs:
     name: '${{ matrix.os }} Python${{ matrix.python-version }} spawn_backend=${{ matrix.spawn_backend }} tpt_proto=${{ matrix.tpt_proto }}'
     timeout-minutes: 16
     runs-on: ${{ matrix.os }}
+    # Windows support is nascent: its full test suite remains
+    # informational, while setup and the `import tractor` smoke below
+    # are hard signals. Promote the test step to required once the
+    # suite is green.
 
     strategy:
       fail-fast: false
@@ -98,6 +102,7 @@ jobs:
         os: [
           ubuntu-latest,
           macos-latest,
+          windows-latest,
         ]
         python-version: [
           '3.13',
@@ -118,10 +123,10 @@ jobs:
           'tcp',
           'uds',
         ]
-        # https://github.com/orgs/community/discussions/26253#discussioncomment-3250989
         exclude:
-          # don't do UDS run on macOS (for now)
-          - os: macos-latest
+          # UDS is POSIX-only; Windows has no `AF_UNIX` so the
+          # backend is intentionally unavailable there.
+          - os: windows-latest
             tpt_proto: 'uds'
 
     steps:
@@ -150,7 +155,14 @@ jobs:
       - name: List deps tree
         run: uv tree
 
+      # hard signal for the Windows import-safety fix: `import
+      # tractor` must succeed everywhere, and `HAS_UDS` reflects
+      # platform capability (False on Windows, True on POSIX).
+      - name: 'Smoke: import tractor'
+        run: uv run python -c "import sys; import tractor; from tractor.ipc._uds import HAS_UDS; assert sys.platform != 'win32' or not HAS_UDS; print('import tractor OK | HAS_UDS=', HAS_UDS)"
+
       - name: Run tests
+        continue-on-error: ${{ matrix.os == 'windows-latest' }}
         run: >
           uv run
           pytest

ai/prompt-io/claude/20260702T155006Z_65bf9df5_prompt_io.md

@@ -0,0 +1,77 @@
+---
+model: claude-fable-5
+service: claude
+session: b8ec2ffe-1e47-4db5-8bc3-5bebc5feaaf6
+timestamp: 2026-07-02T15:50:06Z
+git_ref: 65bf9df5
+scope: code
+substantive: true
+raw_file: 20260702T155006Z_65bf9df5_prompt_io.raw.md
+---
+
+## Prompt
+
+From `ai/prompt-io/prompts/issue_473.md`:
+
+> NOTE: you MUST pause this work at 12:50PM EST (BEFORE
+> your weekly limit reset) for review by a human!
+>
+> resolve GH #473: https://github.com/goodboy/tractor/issues/474
+> do it with /open-wkt.
+
+(The prompt's issue-number/URL mismatch was resolved in
+favor of #473 — file name, session name and prompt text
+all say #473; the `/474` URL is a typo.)
+
+GH #473: "Root-cause UDS-on-macOS —
+`uds_transport_actor_tree` example fails on CI".
+
+## Response summary
+
+Worked all four #473 next-step checkboxes in wkt
+`uds_macos_473`:
+
+1. **stderr surfacing**: `test_docs_examples.py` now
+   raises with the full subproc stderr (+stdout) on ANY
+   non-zero exit. The old last-line-'Error' check could
+   never fire for `tractor` crashes since root-actor
+   stderr always ends with the strict-EG collapse note
+   `( ^^^ this exc was collapsed from a group ^^^ )` —
+   proven against the real PR #460 macOS CI log (bare
+   `assert 1 == 0`, no traceback).
+2. **root-cause (linux-provable layer)**: macOS-only
+   addr corruption in
+   `MsgpackUDSStream.get_stream_addrs()` — no
+   `SO_PASSCRED`/autobind on darwin means the accept
+   side's `getpeername()` is `''`, and the
+   `(str(), str())` arm took `peername` unconditionally →
+   `Path('')` garbage addrs on every accepted conn.
+   Proven + fixed via linux no-autobind simulation.
+   Possibly not the final macOS crasher (non-fatal on
+   linux-sim); the diagnostic patch guarantees the next
+   macOS CI run shows any remaining layer.
+3. **CI matrix**: removed the `macos-latest`+`uds`
+   exclude.
+4. **un-skip**: dropped the macOS+CI skip of the example.
+
+Also: `start_listener()` bindspace mkdir hardened
+(`parents=True, exist_ok=True`), example docstring
+peer-pid mechanism corrected for macOS.
+
+## Files changed
+
+- `tests/test_docs_examples.py` — surface full stderr on
+  non-zero exit; remove macOS skip of the UDS example
+- `tractor/ipc/_uds.py` — fix no-autobind
+  `get_stream_addrs()` arm; harden bindspace mkdir;
+  document autobind semantics
+- `.github/workflows/ci.yml` — add macOS UDS leg (remove
+  matrix exclude)
+- `examples/uds_transport_actor_tree.py` — platform-
+  correct peer-pid docs
+
+## Human edits
+
+None yet — pending human review (hard-stop review
+checkpoint at 12:50PM EST per prompt); commit staging and
+any edits are the human's.

ai/prompt-io/claude/20260702T155006Z_65bf9df5_prompt_io.raw.md

@@ -0,0 +1,101 @@
+---
+model: claude-fable-5
+service: claude
+timestamp: 2026-07-02T15:50:06Z
+git_ref: 65bf9df5
+diff_cmd: git diff main..wkt/uds_macos_473
+---
+
+# Raw output — GH #473 UDS-on-macOS root-cause session
+
+NOTE: code output is diff-referenced (not copied) per
+prompt-io diff-ref mode; all generated code is on branch
+`wkt/uds_macos_473` relative to `main` (65bf9df5).
+
+## Diagnostic narrative (verbatim)
+
+Root-cause work proceeded by linux-side simulation since no
+macOS host is available:
+
+1. Pulled the actual macOS CI failure log from PR #460 run
+   28343878933 (job 84115107992): the failure is a bare
+   `assert 1 == 0` on `proc.returncode` with NO stderr
+   surfaced — the harness only re-raised when the LAST
+   stderr line contained 'Error'.
+
+2. Reproduced the stderr-swallow mechanism on linux: any
+   `tractor` root-actor crash ends stderr with the
+   strict-EG collapse note
+   `( ^^^ this exc was collapsed from a group ^^^ )` which
+   never matches 'Error' — so EVERY possible crash was
+   swallowed. (Verified by sabotaging the runtime dir via
+   an over-long `XDG_RUNTIME_DIR` → `OSError: AF_UNIX path
+   too long` → rc=1 + swallowed.)
+
+3. Found + proved a macOS-only addr-corruption bug in
+   `MsgpackUDSStream.get_stream_addrs()`: the
+   `(str(), str())` match-arm unconditionally took
+   `peername`, but on no-autobind platforms (macOS lacks
+   linux's `SO_PASSCRED`-triggered autobind) the accept
+   side's `getpeername()` is `''` → `Path('')` garbage
+   laddr/raddr on EVERY accepted UDS conn. Simulated on
+   linux by nulling `SO_PASSCRED` (no autobind → same `''`
+   shape): pre-fix the example printed
+   `listener sock file: .`; post-fix it prints the real
+   registry sockpath. Non-fatal on linux-sim (rc=0), so
+   possibly not the final macOS crasher — the diagnostic
+   patch guarantees the next macOS CI run reveals any
+   remaining layer.
+
+4. Falsified the missing-parent-dir theory:
+   `get_rt_dir()` already `mkdir(parents=True,
+   exist_ok=True)`s at import (and macOS TCP CI passes),
+   so `~/Library/Caches/TemporaryItems` absence cannot be
+   the crasher. Hardened `start_listener()`'s bindspace
+   mkdir anyway (custom `filedir` case + racing actors).
+
+## Generated changes (diff pointers)
+
+> `git diff main..wkt/uds_macos_473 -- tests/test_docs_examples.py`
+
+- always raise with FULL subproc stderr (+stdout) on any
+  non-zero example exit; keep legacy last-line 'Error'
+  check for zero-rc cases; drop the macOS+CI skip of
+  `uds_transport_actor_tree.py` (GH #473 next-step).
+
+> `git diff main..wkt/uds_macos_473 -- tractor/ipc/_uds.py`
+
+- `get_stream_addrs()`: document the autobind semantics
+  (bytes = linux abstract-ns autobind artifact), add
+  no-autobind `(str, str)` arm picking the non-empty name
+  (`peername` connect-side, `sockname` accept-side) with
+  an empty-pair `ValueError` guard.
+- `start_listener()`: `bs.mkdir(parents=True,
+  exist_ok=True)`.
+
+> `git diff main..wkt/uds_macos_473 -- .github/workflows/ci.yml`
+
+- remove the `macos-latest`+`uds` matrix exclude so
+  UDS-on-macOS is exercised by CI (GH #473 next-step).
+
+> `git diff main..wkt/uds_macos_473 -- examples/uds_transport_actor_tree.py`
+
+- docs nit: peer-pid mechanism is `SO_PEERCRED` on linux,
+  `LOCAL_PEERPID` on macOS.
+
+## Verification (verbatim summary)
+
+- macOS-shape sim (no autobind) + fix: example rc=0 with
+  correct listener sockpath.
+- native linux post-fix: example rc=0, autobind arms
+  unchanged.
+- sabotage smoke-test: diagnostic patch surfaces the full
+  EG traceback incl. collapse-note line.
+- `pytest tests/ipc/ tests/test_2way.py tests/discovery/
+  --tpt-proto uds`: 61 passed, 1 `TooSlowError` flake
+  (test_simple_rpc) that passes solo in 2.2s — attributed
+  to a concurrent full-suite run (other session) loading
+  the host.
+- full `tests/test_docs_examples.py` run pending at
+  raw-file write time (queued behind the concurrent
+  session's suite).

ai/prompt-io/claude/20260702T155626Z_65bf9df5_prompt_io.md

@@ -0,0 +1,83 @@
+---
+model: claude-fable-5
+service: claude
+session: b6b42e23-0454-4d9b-be1c-0a89d65aed1b
+timestamp: 2026-07-02T15:56:26Z
+git_ref: 65bf9df5
+scope: code
+substantive: true
+raw_file: 20260702T155626Z_65bf9df5_prompt_io.raw.md
+---
+
+## Prompt
+
+From `ai/prompt-io/prompts/issue_470.md`:
+
+> attempt to resolve
+> https://github.com/goodboy/tractor/issues/470
+> do it with /open-wkt, ensure you /run-tests on all
+> changes
+
+(plus a hard pause-for-human-review deadline of
+12:50PM EST.)
+
+Issue #470 asks to trim the ~0.42s `import tractor`
+cost — which dominates per-actor spawn latency on the
+`trio` backend — by lazy-importing heavy/optional deps
+(`pdbp`, `stackscope`, `multiaddr`, + audit of
+`colorlog`/`bidict`/`wrapt`/`setproctitle`).
+
+## Response summary
+
+Profiling showed the issue's dep-list only accounted
+for ~20ms; the dominant cost (~244ms) was
+`log.get_logger()`'s `get_caller_mod()` calling
+`inspect.stack()` at module level in ~39 modules —
+each call walks every stack frame (deep during nested
+imports) and scans `sys.modules` per frame via
+`inspect.getmodule()`.
+
+Changes, in impact order:
+
+1. `get_caller_mod()` -> `sys._getframe()` +
+   `f_globals['__name__']` `sys.modules` lookup
+   (~240ms saved).
+2. Issue's lazy-import checklist: `bidict`,
+   `multiaddr`, `colorlog`, `wrapt` moved to
+   `TYPE_CHECKING`/function-local imports;
+   `platformdirs` function-local; `asyncio` +
+   `.to_asyncio` deferred out of the `devx.debug` +
+   `spawn._entry` eager paths (~15ms saved).
+3. PEP 562 `__getattr__` on `tractor/__init__.py`
+   preserving public `tractor.to_asyncio` attr access.
+
+Results: `import tractor` 0.42s -> ~0.145s (~65%);
+sequential `start_actor` latency 0.40-0.44s ->
+~0.179s/actor. `pdbp` (needs `_repl.py` class-base
+restructure) + `platformdirs` (needs
+`UDSAddress.def_bindspace` protocol rework) documented
+as follow-ups.
+
+## Files changed
+
+- `tractor/log.py` — `get_caller_mod()` perf fix +
+  lazy `colorlog`
+- `tractor/__init__.py` — PEP 562 lazy `to_asyncio`
+- `tractor/discovery/_addr.py` — `bidict` ->
+  `TYPE_CHECKING`
+- `tractor/discovery/_multiaddr.py` — lazy `multiaddr`
+- `tractor/ipc/_tcp.py`, `tractor/ipc/_uds.py` —
+  `Multiaddr` -> `TYPE_CHECKING`
+- `tractor/runtime/_state.py` — lazy `platformdirs`
+- `tractor/devx/_frame_stack.py` — lazy `pdbp` +
+  `wrapt`
+- `tractor/devx/debug/_trace.py`,
+  `tractor/devx/debug/_tty_lock.py` — lazy `asyncio` +
+  `.to_asyncio`
+- `tractor/spawn/_entry.py` — lazy
+  `run_as_asyncio_guest`
+
+## Human edits
+
+None yet — pending user review at the 12:50PM EST
+pause gate (test-suite results reported in-session).

ai/prompt-io/claude/20260702T155626Z_65bf9df5_prompt_io.raw.md

@@ -0,0 +1,122 @@
+---
+model: claude-fable-5
+service: claude
+timestamp: 2026-07-02T15:56:26Z
+git_ref: 65bf9df5
+diff_cmd: git diff main..wkt/boot_latency_470
+---
+
+# Raw AI output — gh #470 `import tractor` latency trim
+
+All generated code is committed on the
+`wkt/boot_latency_470` branch; per diff-ref mode each
+file's content is referenced via its diff instead of
+copied verbatim.
+
+## Profiling findings (verbatim analysis output)
+
+Baseline: `import tractor` ~0.39-0.42s wall.
+
+`python -X importtime` + `cProfile` traced the cost NOT
+primarily to third-party deps (the issue's hypothesis)
+but to `tractor/log.py:get_logger()` calling
+`get_caller_mod()` -> `inspect.stack()` at module level
+in ~39 tractor modules:
+
+- `inspect.stack()` builds `FrameInfo` (incl. src-file
+  and line-context resolution) for EVERY frame on the
+  stack; during nested imports the stack is dozens of
+  importlib frames deep.
+- each `FrameInfo` resolution calls
+  `inspect.getmodule()` which scans all of
+  `sys.modules` per frame (1.4M `ismodule()` calls in
+  one profiled import).
+- aggregate: ~244ms of tractor-own module "self" time
+  vs ~20ms for ALL the issue-listed third-party deps
+  (`pdbp` ~10ms, `bidict` ~4.5ms, `multiaddr` ~3.5ms,
+  `wrapt`/`colorlog` ~1ms each); `trio` itself is
+  ~70-100ms and unavoidable.
+
+## Generated changes
+
+> `git diff main..wkt/boot_latency_470 -- tractor/log.py`
+
+`get_caller_mod()` rewritten from `inspect.stack()` +
+`inspect.getmodule()` to `sys._getframe(frames_up)` +
+`frame.f_globals['__name__']` -> `sys.modules` lookup
+(O(1) vs O(stack x sys.modules)). Unused `inspect`
+imports dropped; `FrameType` imported from `types`.
+Also `colorlog` lazy-imported inside
+`get_console_log()`.
+
+> `git diff main..wkt/boot_latency_470 -- tractor/discovery/_addr.py`
+
+`bidict` import moved under `TYPE_CHECKING`
+(annotation-only use; `_address_types` is a plain dict
+literal).
+
+> `git diff main..wkt/boot_latency_470 -- tractor/discovery/_multiaddr.py`
+
+`from __future__ import annotations` added; `multiaddr`
+import moved under `TYPE_CHECKING` + function-local
+imports in `mk_maddr()`/`parse_maddr()`.
+
+> `git diff main..wkt/boot_latency_470 -- tractor/ipc/_tcp.py tractor/ipc/_uds.py`
+
+`Multiaddr` imports moved under `TYPE_CHECKING`
+(annotation-only in both transports).
+
+> `git diff main..wkt/boot_latency_470 -- tractor/runtime/_state.py`
+
+`platformdirs` lazy-imported inside `get_rt_dir()`
+(NOTE: still imported eagerly via
+`UDSAddress.def_bindspace` class-var eval; see
+follow-ups).
+
+> `git diff main..wkt/boot_latency_470 -- tractor/devx/_frame_stack.py`
+
+`pdbp` + `wrapt` lazy-imported inside
+`hide_runtime_frames()` / `api_frame()` respectively.
+
+> `git diff main..wkt/boot_latency_470 -- tractor/devx/debug/_trace.py tractor/devx/debug/_tty_lock.py`
+
+`asyncio` moved to `TYPE_CHECKING` + call-site local
+imports (`asyncio.current_task()` sites);
+`tractor.to_asyncio.run_trio_task_in_future` imports
+moved into the infected-aio runtime branches.
+
+> `git diff main..wkt/boot_latency_470 -- tractor/spawn/_entry.py`
+
+`run_as_asyncio_guest` import moved into the
+`infect_asyncio=True` branches of `_mp_main()` /
+`_trio_main()`.
+
+> `git diff main..wkt/boot_latency_470 -- tractor/__init__.py`
+
+PEP 562 module `__getattr__` added so
+`tractor.to_asyncio` attr-access still works (required
+by `tests/test_child_manages_service_nursery.py` and
+any downstream user) while keeping `asyncio` off the
+eager import path.
+
+## Measured results (verbatim)
+
+- `import tractor`: 0.39-0.42s -> ~0.145s (~65% cut)
+- `start_actor` spawn+boot+reg+cancel: ~0.40-0.44s ->
+  ~0.179s/actor (n=5 sequential, warm parent)
+- post-change eager-module check: only `pdbp` +
+  `platformdirs` of the issue's list remain eager.
+
+## Known follow-ups (not implemented, deadline-bound)
+
+- `pdbp` (~10ms): still eager via
+  `devx/debug/_repl.py` class bases
+  (`class PdbREPL(pdbp.Pdb)`) + `_tty_lock.py`
+  module-level `@pdbp.hideframe`; needs `_repl`
+  restructure + PEP 562 in `devx.debug.__init__`.
+- `platformdirs` (~1.5ms): eager via
+  `UDSAddress.def_bindspace: ClassVar = get_rt_dir()`
+  class-body call; needs `Address`-protocol rework of
+  `def_bindspace` to a lazy accessor.
+- `stackscope` + `setproctitle`: already lazy/absent —
+  no change needed.

ai/prompt-io/opencode/20260817T231825Z_359fe75c_prompt_io.md

@@ -0,0 +1,39 @@
+---
+model: openai/gpt-5.6-sol
+service: opencode
+session: pr475-review-fixes-20260817
+timestamp: 2026-08-17T23:18:25Z
+git_ref: 359fe75c
+scope: code
+substantive: true
+raw_file: 20260817T231825Z_359fe75c_prompt_io.raw.md
+---
+
+## Prompt
+
+Continue the `/code-review-changes` pass for PR #475 in its isolated
+worktree. Address the seven accepted manual-review findings in
+`tractor/ipc/_types.py` and `tractor/ipc/_uds.py`, preserve the existing
+Windows capability behavior, verify the result, and prepare the work for
+human-controlled commit and review-reply steps. Do not publish replies,
+stage, commit, or push without the required explicit authorization.
+
+## Response summary
+
+Restored project quote, docstring, multiline-expression, and
+`match/case` conventions while retaining the Windows-safe UDS guard.
+Removed unnecessary structural and comment churn, then verified the
+focused transport, discovery, and lazy-import paths plus the missing
+`AF_UNIX` behavior.
+
+## Files changed
+
+- `tractor/ipc/_types.py` - restore project style and guarded
+  socket-family dispatch.
+- `tractor/ipc/_uds.py` - format the UDS capability gate
+  consistently.
+
+## Human edits
+
+None - the generated patch remains uncommitted and awaits human
+review.

ai/prompt-io/opencode/20260817T231825Z_359fe75c_prompt_io.raw.md

@@ -0,0 +1,45 @@
+---
+model: openai/gpt-5.6-sol
+service: opencode
+timestamp: 2026-08-17T23:18:25Z
+git_ref: 359fe75c
+diff_cmd: git diff HEAD~1..HEAD
+---
+
+Applied the seven accepted manual-review fixes for PR #475 while
+preserving the Windows transport capability behavior.
+
+> `git diff HEAD~1..HEAD -- tractor/ipc/_types.py`
+
+The generated changes restore the project's single-quote docstring and
+string conventions, remove the unnecessary helper divider, simplify the
+transport-registry comments, and restore `match/case` socket-family
+dispatch. The UDS case retains a `HAS_UDS` guard that short-circuits
+before `socket.AF_UNIX` is evaluated on unsupported hosts. Nearby error
+messages are wrapped without changing their content.
+
+> `git diff HEAD~1..HEAD -- tractor/ipc/_uds.py`
+
+The generated change reformats the `HAS_UDS` conjunction according to
+the project's multiline boolean-expression convention and simplifies
+the adjacent capability comment.
+
+Verification:
+
+`/home/goodboy/repos/tractor/py313/bin/pytest -q tests/test_lazy_imports.py tests/discovery tests/ipc/test_server.py`
+
+Result: `66 passed, 2 xpassed in 60.62s`.
+
+`ruff check --no-cache --output-format=json tractor/ipc/_types.py tractor/ipc/_uds.py`
+
+Result: no findings.
+
+`git diff --check`
+
+Result: no whitespace errors.
+
+An explicit missing-`AF_UNIX` probe set `HAS_UDS = False`, removed the
+socket constant, and exercised an unsupported socket family. It raised
+the expected `NotImplementedError` instead of `AttributeError`.
+
+No review replies, commits, or pushes were published.

docs/explain/architecture.rst

@@ -130,9 +130,10 @@ UDS: same-host, creds included
 
 Pass ``enable_transports=['uds']`` and actors instead talk over
 unix-domain sockets, with socket files placed in the per-user
-runtime dir (``$XDG_RUNTIME_DIR/tractor/`` on linux, the
-``platformdirs`` equivalent elsewhere). Two perks over tcp on a
-single host:
+runtime dir: ``$XDG_RUNTIME_DIR/tractor/`` on linux, a short
+owner-only ``/tmp/tractor-<uid>`` dir on Darwin, and the
+``platformdirs`` equivalent elsewhere. Two perks over tcp on a single
+host:
 
 - no ports to fight over; addrs are just file paths,
 - the kernel snitches on your peer for free: the listening side

docs/guide/discovery.rst

@@ -44,8 +44,9 @@ clan shares one registry with zero config on your part.
 The bootstrap rule inside ``open_root_actor()`` is delightfully
 simple:
 
-- on boot, ping every socket addr in ``registry_addrs``; when none
-  are passed the per-transport defaults are used: for TCP the
+- on boot, probe every addr in ``registry_addrs`` with a bounded
+  Tractor ``Aid`` handshake; when none are passed the per-transport
+  defaults are used: for TCP the
   loopback ``('127.0.0.1', 1616)``, for UDS a
   ``registry@1616.sock`` file,
 
@@ -53,9 +54,11 @@ simple:
   actor and register with the *existing* registry; your own IPC
   server binds random same-transport addrs instead,
 
-- if **nothing answers, congratulations: you just became the
-  registrar**. Your transport server binds the registry addrs
-  themselves and you start serving lookups for everyone else.
+- if every address is absent, congratulations: you just became the
+  registrar. Your transport server binds the registry addrs
+  themselves and you start serving lookups for everyone else,
+- if no registrar answers but an address is occupied by a foreign or
+  non-responsive endpoint, startup fails instead of binding over it.
 
 Pass ``ensure_registry=True`` when your program *requires* being
 the one-and-only registrar; boot then fails loudly with a
@@ -196,9 +199,10 @@ the existing registrar:
 
     trio.run(main)
 
-Per the bootstrap rules above, if the registrar at those addrs is
-*not* reachable this process simply becomes its own (registrar)
-root — so the same code works standalone and as a tree-joiner.
+Per the bootstrap rules above, if those addrs are absent this process
+becomes its own registrar root, so the same code works standalone and
+as a tree-joiner. An occupied address that does not complete a Tractor
+registrar handshake fails startup instead of being rebound.
 
 "Arbiter"? A legacy naming note
 -------------------------------

docs/guide/testing.rst

@@ -185,8 +185,10 @@ first with a bounded grace window — so actor runtimes can run
 their ``trio`` teardown paths — escalating to ``SIGKILL`` only as
 a last resort. The ``--shm`` sweep unlinks ``/dev/shm/`` segments
 that no live process has open (it leans on psutil_, already in
-your dev venv, to check live mappings and fds) and ``--uds``
-clears socket files whose binder pid is dead.
+your dev venv, to check live mappings and fds) and ``--uds`` clears
+dead-binder sockets from Tractor's platform-specific runtime dir. It
+also unconditionally removes ``registry@1616.sock``; do not run the UDS
+sweep while a live registrar is serving from that default address.
 
 Testing your own ``tractor`` app
 --------------------------------

examples/parallelism/we_are_processes.py

@@ -23,18 +23,10 @@ async def endpoint(
     await trio.sleep_forever()
 
 
-async def spawn_and_open_ep(
-    an: tractor.ActorNursery,
+async def open_ep(
+    ptl: tractor.Portal,
     i: int,
 ) -> None:
-    '''
-    Spawn a subactor, start a remote `endpoint()`-task in it.
-
-    '''
-    ptl: tractor.Portal = await an.start_actor(
-        name=f'worker_{i}',
-        enable_modules=[__name__],
-    )
     ctx: tractor.Context
     async with ptl.open_context(endpoint) as (
         ctx,
@@ -47,7 +39,33 @@ async def spawn_and_open_ep(
         await ctx.wait_for_result()
 
 
-async def main():
+async def spawn_and_open_ep(
+    an: tractor.ActorNursery,
+    i: int,
+    maybe_ptl: tractor.Portal|None = None,
+) -> None:
+    '''
+    Spawn a subactor, start a remote `endpoint()`-task in it.
+
+    '''
+    if maybe_ptl is None:
+        maybe_ptl: tractor.Portal = await an.start_actor(
+            name=f'worker_{i}',
+            enable_modules=[__name__],
+        )
+    await open_ep(
+        ptl=maybe_ptl,
+        i=i,
+    )
+
+
+async def main(
+    # spawn subs concurrently (in bg `trio.Task`s) so each
+    # actor's cold `import tractor` (~0.4s, see #470) overlaps
+    # instead of stacking; once forkserver (#463) lands, spawn
+    # is cheap enough to just loop sequentially.
+    spawn_subs_in_bg_tasks: bool = True,
+):
     '''
     Spawn a subactor-per-CPU then self-destruct the cluster.
 
@@ -60,17 +78,21 @@ async def main():
             # https://github.com/goodboy/tractor/pull/463
             # start_method='main_thread_forkserver',
         ) as an,
-        # spawn subs concurrently (in bg `trio.Task`s) so each
-        # actor's cold `import tractor` (~0.4s, see #470) overlaps
-        # instead of stacking; once forkserver (#463) lands, spawn
-        # is cheap enough to just loop sequentially.
         trio.open_nursery() as tn,
     ):
         for i in range(cpu_count()):
+
+            maybe_ptl: tractor.Portal|None = None
+            if not spawn_subs_in_bg_tasks:
+                maybe_ptl: tractor.Portal = await an.start_actor(
+                    name=f'worker_{i}',
+                    enable_modules=[__name__],
+                )
             tn.start_soon(
                 spawn_and_open_ep,
                 an,
                 i,
+                maybe_ptl,
             )
         destruct_in: int = 2
         print(

examples/uds_transport_actor_tree.py

@@ -6,7 +6,8 @@ subactor inherits the preference.
 
 Every channel address is a filesystem socket path (no TCP port
 in sight!) and, as a kernel-provided bonus, the peer's pid is
-exchanged for free via `SO_PEERCRED`.
+exchanged for free via `SO_PEERCRED` on linux,
+`LOCAL_PEERPID` on macOS.
 
 '''
 import os
@@ -42,7 +43,7 @@ async def main() -> None:
         # (named for the root registrar) this channel rode in
         # on, NOT a per-child path; the child-specific identity
         # we get for free is the kernel-reported peer pid (via
-        # `SO_PEERCRED`).
+        # `SO_PEERCRED` on linux, `LOCAL_PEERPID` on macOS).
         print(
             f'portal chan tpt proto: {raddr.proto_key!r}\n'
             f'listener sock file: {raddr.sockpath}\n'

nooz/473.bugfix.rst

@@ -0,0 +1,4 @@
+Fix Unix-domain-socket actor trees and registrar discovery on macOS.
+Runtime sockets now use a short, owner-only runtime directory,
+generated socket names remain within platform limits, and transient
+or reset pre-handshake connections no longer destabilize discovery.

scripts/tractor-reap

@@ -23,10 +23,10 @@ Two cleanup phases (run in order when both are enabled):
    hard-crashing actor leaves leaked segments that
    nothing else GCs.
 
-3. **UDS sweep** (`--uds` / `--uds-only`) — unlinks
-   `${XDG_RUNTIME_DIR}/tractor/<name>@<pid>.sock` files
-   whose binder pid is dead (or the `1616` registry
-   sentinel). Needed because the IPC server's
+3. **UDS sweep** (`--uds` / `--uds-only`) — unlinks socket
+   files from Tractor's platform-specific default bindspace whose
+   binder pid is dead (or the `1616` registry sentinel). Needed
+   because the IPC server's
    `os.unlink()` cleanup lives in a `finally:` block
    that doesn't always run on hard exits (SIGKILL,
    escaped `KeyboardInterrupt`, etc.) — see issue #452.
@@ -137,8 +137,8 @@ def main() -> int:
         action='store_true',
         help=(
             'after process reap, also unlink orphaned '
-            '${XDG_RUNTIME_DIR}/tractor/*.sock files '
-            'whose binder pid is dead (or the 1616 '
+            'sockets from Tractor\'s platform default '
+            'bindspace whose binder pid is dead (or the 1616 '
             'registry sentinel). See issue #452.'
         ),
     )
@@ -212,7 +212,9 @@ def main() -> int:
 
     # --- phase 3: UDS sweep (opt-in) ---
     if args.uds or args.uds_only:
-        leaked_uds: list[str] = find_orphaned_uds()
+        leaked_uds: list[str] = find_orphaned_uds(
+            include_registry_sentinel=True,
+        )
         if not leaked_uds:
             print(
                 '[tractor-reap] no orphaned UDS sock-files '

tests/devx/test_debugger.py

@@ -1300,19 +1300,31 @@ def test_ctxep_pauses_n_maybe_ipc_breaks(
             if _non_linux:
                 tpt: str = 'TCP'
 
-            assert_before(
+            before: str = assert_before(
                 child,
                 ['peer IPC channel closed abruptly?',
                  'another task closed this fd',
                  'Debug lock request was CANCELLED?',
-                 f"'Msgpack{tpt}Stream' was already closed locally?",
-                 f"TransportClosed: 'Msgpack{tpt}Stream' was already closed 'by peer'?",
                  ]
 
                  # XXX races on whether these show/hit?
                   # 'Failed to REPl via `_pause()` You called `tractor.pause()` from an already cancelled scope!',
                   # 'AssertionError',
             )
+
+            # Error shipment and peer receive race after local close.
+            # Either diagnostic proves the transport was torn down.
+            closed_locally: str = (
+                f"'Msgpack{tpt}Stream' was already closed locally?"
+            )
+            closed_by_peer: str = (
+                f"TransportClosed: 'Msgpack{tpt}Stream' was "
+                f"already closed 'by peer'?"
+            )
+            assert (
+                closed_locally in before
+                or closed_by_peer in before
+            )
             # OSc(ancel) the hanging tree
             do_ctlc(
                 child=child,

tests/discovery/conftest.py

@@ -1,21 +1,18 @@
 '''
-Discovery-suite fixtures, including the `daemon`
-remote-registrar subprocess used by the multi-program
-discovery tests.
+Discovery-suite fixtures, including the `daemon` remote-registrar
+subprocess used by the multi-program discovery tests.
 
 Lives here (vs. the parent `tests/conftest.py`)
-because `daemon` is a discovery-protocol primitive —
-boots a separate `tractor.run_daemon()` process whose
-sole purpose is to serve as a registrar peer for
+because `daemon` is a discovery-protocol primitive: it boots a child
+that enters `open_root_actor()` and waits as a registrar peer for
 discovery-roundtrip tests. Pytest fixtures inherit
 DOWNWARD through conftest hierarchy, so anything
 under `tests/discovery/` automatically picks this up.
 
 '''
 from __future__ import annotations
-import os
+from pathlib import Path
 import platform
-import socket
 import subprocess
 import sys
 import time
@@ -31,33 +28,27 @@ from ..conftest import (
 
 
 def _wait_for_daemon_ready(
-    reg_addr: tuple,
-    tpt_proto: str,
+    ready_path: Path,
     *,
     deadline: float = 10.0,
     poll_interval: float = 0.05,
     proc: subprocess.Popen|None = None,
 ) -> None:
     '''
-    Active-poll the daemon's bind address until it
-    accepts a connection (proving it has called
-    `bind() + listen()` and is ready to handle IPC).
+    Poll until the daemon reports completed actor startup.
 
     Replaces the historical blind `time.sleep()` in the
     `daemon` fixture which was racy under load — see
     `ai/conc-anal/test_register_duplicate_name_daemon_connect_race_issue.md`.
 
-    Uses stdlib `socket` directly (no trio runtime
-    bootstrap cost) — sufficient because
-    `tractor.run_daemon()` doesn't return from
-    bootstrap until the runtime is fully ready to
-    accept IPC.
+    The child writes `ready_path` only after entering
+    `open_root_actor()`, which guarantees all transport listeners are
+    serving without requiring a raw connection probe.
 
     Raises `TimeoutError` on `deadline` exceeded. If
     `proc` is given, ALSO raises early if the daemon
-    process exits non-zero before the deadline (catches
-    daemon-startup-crash that the blind sleep used to
-    silently mask).
+    process exits before the deadline (catches a daemon startup crash
+    that the blind sleep used to silently mask).
 
     '''
     end: float = time.monotonic() + deadline
@@ -70,43 +61,25 @@ def _wait_for_daemon_ready(
         if proc is not None and proc.poll() is not None:
             raise RuntimeError(
                 f'Daemon proc exited (rc={proc.returncode}) '
-                f'before becoming ready to accept on '
-                f'{reg_addr!r}'
+                f'before reporting ready at {ready_path!r}'
             )
         try:
-            if tpt_proto == 'tcp':
-                # `socket.create_connection` does the
-                # `socket() + connect()` dance with a
-                # builtin timeout — perfect primitive
-                # for a one-shot probe.
-                with socket.create_connection(
-                    reg_addr,
-                    timeout=poll_interval,
-                ):
+            if ready_path.is_file():
+                if proc is not None and proc.poll() is not None:
+                    raise RuntimeError(
+                        f'Daemon proc exited (rc={proc.returncode}) '
+                        f'after reporting ready at {ready_path!r}'
+                    )
                 return
-            else:
-                # UDS — `reg_addr` is a `(filedir, sockname)`
-                # tuple per `tractor.ipc._uds.UDSAddress.unwrap`.
-                sockpath: str = os.path.join(*reg_addr)
-                sock = socket.socket(socket.AF_UNIX)
-                try:
-                    sock.settimeout(poll_interval)
-                    sock.connect(sockpath)
-                    return
-                finally:
-                    sock.close()
         except (
-            ConnectionRefusedError,
             FileNotFoundError,
             OSError,
-            socket.timeout,
         ) as exc:
             last_exc = exc
         time.sleep(poll_interval)
     raise TimeoutError(
-        f'Daemon never accepted on {reg_addr!r} within '
-        f'{deadline}s (last connect-attempt exc: '
-        f'{last_exc!r})'
+        f'Daemon never reported ready at {ready_path!r} within '
+        f'{deadline}s (last sentinel-state exc: {last_exc!r})'
     )
 
 
@@ -136,18 +109,27 @@ def daemon(
         )
         loglevel: str = 'info'
 
+    ready_path: Path = (
+        Path(str(testdir.tmpdir))
+        / 'daemon-ready'
+    )
+    ready_path.unlink(missing_ok=True)
     code: str = (
-        "import tractor; "
-        "tractor.run_daemon([], "
-        "registry_addrs={reg_addrs}, "
-        "enable_transports={enable_tpts}, "
-        "debug_mode={debug_mode}, "
-        "loglevel={ll})"
-    ).format(
-        reg_addrs=str([reg_addr]),
-        enable_tpts=str([tpt_proto]),
-        ll="'{}'".format(loglevel) if loglevel else None,
-        debug_mode=debug_mode,
+        f'from pathlib import Path\n'
+        f'import tractor\n'
+        f'import trio\n'
+        f'\n'
+        f'async def main():\n'
+        f'    async with tractor.open_root_actor(\n'
+        f'        registry_addrs={[reg_addr]!r},\n'
+        f'        enable_transports={[tpt_proto]!r},\n'
+        f'        debug_mode={debug_mode!r},\n'
+        f'        loglevel={loglevel!r},\n'
+        f'    ):\n'
+        f'        Path({str(ready_path)!r}).touch()\n'
+        f'        await trio.sleep_forever()\n'
+        f'\n'
+        f'trio.run(main)\n'
     )
     cmd: list[str] = [
         sys.executable,
@@ -163,9 +145,9 @@ def daemon(
         **kwargs,
     )
 
-    # Active-poll the daemon's bind address until it's
-    # ready to accept connections — replaces the legacy
-    # blind `time.sleep(2.2)` which was racy under load
+    # Poll the child's ready sentinel, published after actor startup,
+    # instead of connecting to its transport socket. This replaces
+    # the legacy blind `time.sleep(2.2)` which was racy under load
     # (see
     # `ai/conc-anal/test_register_duplicate_name_daemon_connect_race_issue.md`).
     #
@@ -176,20 +158,22 @@ def daemon(
         15.0 if (_non_linux and ci_env)
         else 10.0
     )
+    try:
         _wait_for_daemon_ready(
-        reg_addr=reg_addr,
-        tpt_proto=tpt_proto,
+            ready_path=ready_path,
             deadline=deadline,
             proc=proc,
         )
 
         assert not proc.returncode
         yield proc
+    finally:
+        if proc.poll() is None:
             sig_prog(proc, _INT_SIGNAL)
 
-    # XXX! yeah.. just be reaaal careful with this bc
-    # sometimes it can lock up on the `_io.BufferedReader`
-    # and hang..
+        # NOTE: these blocking reads can hang when descendants retain
+        # inherited pipe descriptors. Keep teardown signaling above
+        # them and avoid adding subprocesses outside the actor tree.
         #
         # NB, drain happens at TEARDOWN (post-yield), so the
         # test body has its chance to read `proc.stderr`
@@ -219,5 +203,4 @@ def daemon(
             )
             if rc < 0:
                 raise RuntimeError(msg)
-
             test_log.error(msg)

tests/discovery/test_daemon_fixture.py

@@ -0,0 +1,76 @@
+'''
+Discovery daemon fixture regressions.
+
+This module imports private helpers from the sibling
+`tests.discovery.conftest` plugin to exercise that fixture machinery
+directly, rather than testing a production `tractor` API.
+
+'''
+from unittest.mock import (
+    call,
+    Mock,
+)
+
+from .conftest import _wait_for_daemon_ready
+
+
+def test_daemon_ready_check_does_not_connect(
+    monkeypatch,
+    tmp_path,
+):
+    '''
+    Observe completed daemon startup without a raw connection.
+
+    The old UDS readiness helper connected and immediately closed. That
+    entered Tractor's actor-handshake handler with no `Aid` payload and
+    destabilized the remote registrar on macOS before discovery tests
+    started. This test creates the child sentinel, forbids all socket
+    construction and connection helpers, then proves readiness returns
+    without touching the transport layer.
+
+    '''
+    ready_path = tmp_path / 'daemon-ready'
+    ready_path.touch()
+    socket_ctor = Mock(side_effect=AssertionError('socket opened'))
+    connect = Mock(side_effect=AssertionError('socket connected'))
+    monkeypatch.setattr('socket.socket', socket_ctor)
+    monkeypatch.setattr('socket.create_connection', connect)
+
+    _wait_for_daemon_ready(
+        ready_path=ready_path,
+        deadline=.1,
+        poll_interval=.01,
+    )
+
+    socket_ctor.assert_not_called()
+    connect.assert_not_called()
+
+
+def test_daemon_ready_check_backs_off(monkeypatch):
+    '''
+    Back off while waiting for the child startup sentinel.
+
+    The sentinel may appear after several parent polling intervals.
+    A deterministic false/false/true path sequence proves the helper
+    sleeps between unsuccessful observations instead of hot-spinning
+    and starving a booting daemon on constrained CI workers.
+
+    '''
+    ready_path = Mock()
+    ready_path.is_file.side_effect = [False, False, True]
+    sleep = Mock()
+    monotonic = Mock(side_effect=[0, 0, 0, 0])
+    monkeypatch.setattr('time.sleep', sleep)
+    monkeypatch.setattr('time.monotonic', monotonic)
+
+    _wait_for_daemon_ready(
+        ready_path=ready_path,
+        deadline=.2,
+        poll_interval=.01,
+    )
+
+    assert ready_path.is_file.call_count == 3
+    assert sleep.call_args_list == [
+        call(.01),
+        call(.01),
+    ]

tests/discovery/test_tpt_bind_addrs.py

@@ -2,23 +2,211 @@
 `open_root_actor(tpt_bind_addrs=...)` test suite.
 
 Verify all three runtime code paths for explicit IPC-server
-bind-address selection in `_root.py`:
+bind-address selection in `_root.py` and registry probing in
+`discovery._api`:
 
 1. Non-registrar, no explicit bind -> random addrs from registry proto
 2. Registrar, no explicit bind -> binds to registry_addrs
 3. Explicit bind given -> wraps via `wrap_address()` and uses them
 
 '''
+from contextlib import asynccontextmanager as acm
+from unittest.mock import (
+    AsyncMock,
+    call,
+    Mock,
+)
+
 import pytest
 import trio
 import tractor
+from tractor.discovery import _api
 from tractor.discovery._addr import (
     wrap_address,
 )
 from tractor.discovery._multiaddr import mk_maddr
+from tractor.ipc import _connect_chan
 from tractor._testing.addr import get_rando_addr
 
 
+def test_registry_probe_retries_transient_handshake(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    '''
+    Retry a connected registrar after transient handshake timeout.
+
+    Loaded macOS runners can accept the transport while delaying the
+    actor handshake beyond one second. Treating that first timeout as
+    final makes a healthy remote daemon look occupied and cascades into
+    discovery failures. This deterministic fake fails once, succeeds
+    on the second complete handshake, and proves one bounded backoff.
+
+    '''
+    async def stall_handshake(**kwargs):
+        await trio.sleep_forever()
+
+    first_handshake = AsyncMock(side_effect=stall_handshake)
+    second_handshake = AsyncMock(
+        return_value=tractor.msg.Aid(
+            name='registrar',
+            uuid='registrar-uuid',
+            pid=1234,
+            is_registrar=True,
+        ),
+    )
+    chans = [
+        Mock(_do_handshake=first_handshake),
+        Mock(_do_handshake=second_handshake),
+    ]
+    closed: list[object] = []
+
+    @acm
+    async def connect_chan(addr, close_timeout):
+        assert close_timeout == .2
+        chan = chans[len(closed)]
+        try:
+            yield chan
+        finally:
+            closed.append(chan)
+
+    sleep = AsyncMock()
+    monkeypatch.setattr(_api, '_connect_chan', connect_chan)
+    monkeypatch.setattr(_api.trio, 'sleep', sleep)
+
+    async def main():
+        status = await _api._probe_registry(
+            addr=wrap_address(('127.0.0.1', 1616)),
+            timeout=.3,
+            attempt_timeout=.1,
+            max_attempts=3,
+            retry_delay=.01,
+        )
+        assert status == 'registrar'
+
+    trio.run(main)
+
+    first_handshake.assert_awaited_once()
+    second_handshake.assert_awaited_once()
+    assert first_handshake.await_args.kwargs['timeout'] == .1
+    assert second_handshake.await_args.kwargs['timeout'] == .1
+    assert closed == chans
+    sleep.assert_has_awaits([call(.01)])
+
+
+def test_probe_channel_close_is_bounded(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    '''
+    Bound shielded channel cleanup after a registry probe.
+
+    `_connect_chan()` shields `.aclose()` so cancellation cannot leak
+    ordinary channels. A stalled close previously let registry probing
+    exceed every connect and handshake deadline. This fake close never
+    completes; the explicit cleanup allowance must still return control
+    to the caller without cancelling its surrounding task.
+
+    '''
+    chan = Mock()
+    chan.aclose = AsyncMock(side_effect=trio.sleep_forever)
+    monkeypatch.setattr(
+        tractor.Channel,
+        'from_addr',
+        AsyncMock(return_value=chan),
+    )
+
+    async def main():
+        with trio.fail_after(.5):
+            async with _connect_chan(
+                ('127.0.0.1', 1616),
+                close_timeout=.01,
+            ):
+                pass
+
+    trio.run(main)
+    chan.aclose.assert_awaited_once()
+
+
+def test_transport_only_listener_is_not_registrar():
+    '''
+    Require a Tractor handshake before accepting a registry address.
+
+    The old election probe marked an address live after transport
+    connect alone. A non-Tractor listener, or a registrar still
+    failing its initial handshake, was therefore selected as the
+    remote registry. This test accepts the probe and closes it without
+    replying, then proves `open_root_actor()` rejects that occupied
+    endpoint instead of selecting it or binding over it.
+
+    '''
+    async def transport_only_handler(
+        stream: trio.SocketStream,
+    ) -> None:
+        await stream.aclose()
+
+    async def main():
+        listeners = await trio.open_tcp_listeners(0)
+        listener = listeners[0]
+        sockname = listener.socket.getsockname()
+        reg_addr: tuple[str, int] = (
+            sockname[0],
+            sockname[1],
+        )
+
+        async with trio.open_nursery() as tn:
+            tn.start_soon(
+                trio.serve_listeners,
+                transport_only_handler,
+                listeners,
+            )
+            with pytest.raises(
+                RuntimeError,
+                match='occupied but did not answer',
+            ):
+                async with tractor.open_root_actor(
+                    registry_addrs=[reg_addr],
+                    enable_transports=['tcp'],
+                ):
+                    pytest.fail('foreign listener selected as registrar')
+
+            tn.cancel_scope.cancel()
+
+    trio.run(main)
+
+
+def test_registry_probe_preserves_no_peers_state(
+    reg_addr: tuple,
+    tpt_proto: str,
+):
+    '''
+    Keep an idle registrar peer-free after an election probe.
+
+    Probe handshakes exchange registrar capability but must not enter
+    `IPCServer._peers`. Resetting `_no_more_peers` before identifying a
+    probe left an idle registrar reporting phantom peers and delayed
+    shutdown. This test probes the live local registrar and proves its
+    peer map and no-peers event remain unchanged afterward.
+
+    '''
+    async def main():
+        async with tractor.open_root_actor(
+            registry_addrs=[reg_addr],
+            enable_transports=[tpt_proto],
+        ):
+            actor = tractor.current_actor()
+            server = actor.ipc_server
+
+            probe_status = await _api._probe_registry(
+                addr=wrap_address(reg_addr),
+            )
+            assert probe_status == 'registrar'
+
+            await trio.sleep(0)
+            assert not server._peers
+            assert server._no_more_peers.is_set()
+
+    trio.run(main)
+
+
 # ------------------------------------------------------------------
 # helpers
 # ------------------------------------------------------------------

tests/ipc/test_each_tpt.py

@@ -3,14 +3,21 @@ Unit-ish tests for specific IPC transport protocol backends.
 
 '''
 from __future__ import annotations
+import os
 from pathlib import Path
+import socket
+import stat
+import sys
+import tempfile
+from types import SimpleNamespace
+from unittest.mock import Mock
 
 import pytest
 import trio
 import tractor
 from tractor import Actor
-from tractor.runtime import _state
 from tractor.discovery import _addr
+from tractor.runtime import _state
 
 
 @pytest.fixture
@@ -31,6 +38,381 @@ def bindspace_dir_str() -> str:
         bs_dir.rmdir()
 
 
+def test_macos_rt_dir_fits_uds_path_limit(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+):
+    '''
+    Keep the default Darwin UDS bindpath below its 104-byte limit.
+
+    `platformdirs` normally places the runtime directory below the
+    long `~/Library/Caches/TemporaryItems` path. Pytest also assigns
+    a deeply nested temporary home, so appending a registry socket
+    name made every macOS UDS listener fail with `AF_UNIX path too
+    long`. This test simulates Darwin and an intentionally long
+    platformdirs result, then proves `get_rt_dir()` uses the short
+    system temporary directory and leaves room for the socket name.
+
+    '''
+    long_rt_dir: Path = tmp_path / ('long' * 30)
+    monkeypatch.setattr(sys, 'platform', 'darwin')
+    monkeypatch.setattr(
+        'platformdirs.user_runtime_dir',
+        lambda appname: str(long_rt_dir / appname),
+    )
+    monkeypatch.setattr(_state, '_DARWIN_TMPDIR', tmp_path)
+    rt_dir: Path = _state.get_rt_dir()
+    sockpath: Path = (
+        Path('/tmp')
+        / f'tractor-{os.getuid()}'
+        / 'registry@1616.sock'
+    )
+
+    assert rt_dir == tmp_path / f'tractor-{os.getuid()}'
+    assert len(os.fsencode(sockpath)) < 104
+    assert stat.S_IMODE(rt_dir.stat().st_mode) == 0o700
+
+
+def test_macos_rt_dir_rejects_symlink(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+):
+    '''
+    Reject a pre-created symlink at the Darwin runtime path.
+
+    Darwin uses the predictable `/tmp/tractor-<uid>` path to stay
+    below its `AF_UNIX` limit. A hostile local user could otherwise
+    point that path at a victim-owned directory and make
+    `get_rt_dir()` chmod or place sockets in the symlink target. The
+    test replaces `/tmp` with a controlled directory, installs the
+    malicious link, and proves non-following validation rejects it.
+
+    '''
+    runtime_link: Path = tmp_path / f'tractor-{os.getuid()}'
+    target_dir: Path = tmp_path / 'target'
+    target_dir.mkdir(mode=0o755)
+    runtime_link.symlink_to(target_dir, target_is_directory=True)
+    monkeypatch.setattr(sys, 'platform', 'darwin')
+    monkeypatch.setattr(_state, '_DARWIN_TMPDIR', tmp_path)
+
+    with pytest.raises(PermissionError, match='Unsafe Darwin'):
+        _state.get_rt_dir()
+
+    assert stat.S_IMODE(target_dir.stat().st_mode) == 0o755
+
+
+def test_reaper_uses_default_uds_bindspace(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+):
+    '''
+    Sweep the same platform-specific bindspace used by UDS actors.
+
+    The reaper previously consulted only `XDG_RUNTIME_DIR`, missing
+    Darwin sockets after the runtime moved to `/tmp/tractor-<uid>`.
+    This test replaces `UDSAddress.def_bindspace` and proves the test
+    harness resolves that shared transport default directly.
+
+    '''
+    from tractor._testing import _reap
+    from tractor.ipc._uds import UDSAddress
+
+    monkeypatch.setattr(
+        UDSAddress,
+        'def_bindspace',
+        tmp_path,
+    )
+
+    assert _reap.get_uds_dir() == str(tmp_path)
+
+
+def test_automatic_reaper_preserves_registry_sentinel(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    '''
+    Reserve unconditional registry cleanup for the explicit CLI.
+
+    The `registry@1616.sock` suffix does not encode its binder PID, so
+    automatic pytest cleanup cannot distinguish a leak from another
+    live registrar. This test creates registry and actor sockets,
+    proves the default sweep selects only the dead actor, then proves
+    explicit sentinel inclusion retains the CLI's documented behavior.
+
+    '''
+    from tractor._testing import _reap
+
+    with tempfile.TemporaryDirectory(
+        prefix='tractor-reap-',
+        dir='/tmp',
+    ) as tmpdir:
+        bindspace: Path = Path(tmpdir)
+        registry_path: Path = bindspace / 'registry@1616.sock'
+        actor_path: Path = bindspace / 'worker@1234.sock'
+        socks: list[socket.socket] = []
+        for path in (registry_path, actor_path):
+            sock = socket.socket(socket.AF_UNIX)
+            sock.bind(str(path))
+            socks.append(sock)
+
+        monkeypatch.setattr(_reap, '_is_alive', lambda pid: False)
+        try:
+            assert _reap.find_orphaned_uds(
+                uds_dir=str(bindspace),
+            ) == [str(actor_path)]
+            assert set(
+                _reap.find_orphaned_uds(
+                    uds_dir=str(bindspace),
+                    include_registry_sentinel=True,
+                )
+            ) == {
+                str(registry_path),
+                str(actor_path),
+            }
+        finally:
+            for sock in socks:
+                sock.close()
+
+
+def test_rt_dir_rejects_non_directory(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+):
+    '''
+    Preserve the non-Darwin runtime-directory type contract.
+
+    Replacing `Path.is_dir()` with unguarded `lstat()` briefly made
+    existing files look like valid runtime directories on Linux.
+    This test points `platformdirs` at a regular file and proves
+    `get_rt_dir()` rejects it during initialization.
+
+    '''
+    rt_file: Path = tmp_path / 'runtime-file'
+    rt_file.touch()
+    monkeypatch.setattr(sys, 'platform', 'linux')
+    monkeypatch.setattr(
+        'platformdirs.user_runtime_dir',
+        lambda appname: str(rt_file),
+    )
+
+    with pytest.raises(
+        PermissionError,
+        match='Unsafe POSIX',
+    ):
+        _state.get_rt_dir()
+
+    new_rt_dir: Path = tmp_path / 'new-runtime-dir'
+    monkeypatch.setattr(
+        'platformdirs.user_runtime_dir',
+        lambda appname: str(new_rt_dir),
+    )
+    assert _state.get_rt_dir() == new_rt_dir
+    assert stat.S_IMODE(new_rt_dir.stat().st_mode) == 0o700
+
+
+def test_linux_rt_dir_secures_existing_path(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+):
+    '''
+    Enforce owner-only access on an existing Linux runtime directory.
+
+    Linux previously accepted any existing directory returned by
+    `platformdirs`, without checking ownership or correcting a
+    traversable mode. This test creates an owner-controlled `0o755`
+    directory and proves `get_rt_dir()` normalizes the managed
+    bindspace to `0o700` before returning it.
+
+    '''
+    rt_dir: Path = tmp_path / 'tractor'
+    rt_dir.mkdir(mode=0o755)
+    monkeypatch.setattr(sys, 'platform', 'linux')
+    monkeypatch.setattr(
+        'platformdirs.user_runtime_dir',
+        lambda appname: str(rt_dir),
+    )
+
+    assert _state.get_rt_dir() == rt_dir
+    assert stat.S_IMODE(rt_dir.stat().st_mode) == 0o700
+
+
+def test_linux_rt_dir_rejects_foreign_owner(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+):
+    '''
+    Reject an existing Linux runtime directory owned by another UID.
+
+    A pre-created bindspace must never be made private with `chmod`
+    until ownership is verified. This test makes the current process
+    appear to have a different UID and proves `get_rt_dir()` rejects
+    the directory without changing its original mode.
+
+    '''
+    rt_dir: Path = tmp_path / 'tractor'
+    rt_dir.mkdir(mode=0o755)
+    original_mode: int = stat.S_IMODE(rt_dir.stat().st_mode)
+    monkeypatch.setattr(sys, 'platform', 'linux')
+    monkeypatch.setattr(
+        'platformdirs.user_runtime_dir',
+        lambda appname: str(rt_dir),
+    )
+    monkeypatch.setattr(
+        os,
+        'getuid',
+        lambda: rt_dir.stat().st_uid + 1,
+    )
+
+    with pytest.raises(
+        PermissionError,
+        match='Unsafe POSIX',
+    ):
+        _state.get_rt_dir()
+
+    assert stat.S_IMODE(rt_dir.stat().st_mode) == original_mode
+
+
+def test_macos_rt_dir_rejects_intermediate_symlink(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+):
+    '''
+    Reject symlinks in nested Darwin runtime subdirectories.
+
+    The earlier final-component check allowed `link/child` to follow
+    an intermediate symlink and create `child` outside the secured
+    runtime root. This test installs that link and proves traversal
+    stops before anything is created in its target.
+
+    '''
+    rt_root: Path = tmp_path / f'tractor-{os.getuid()}'
+    target_dir: Path = tmp_path / 'target'
+    rt_root.mkdir(mode=0o700)
+    target_dir.mkdir()
+    (rt_root / 'link').symlink_to(
+        target_dir,
+        target_is_directory=True,
+    )
+    monkeypatch.setattr(sys, 'platform', 'darwin')
+    monkeypatch.setattr(_state, '_DARWIN_TMPDIR', tmp_path)
+
+    with pytest.raises(PermissionError, match='Unsafe Darwin'):
+        _state.get_rt_dir(subdir='link/child')
+
+    assert not (target_dir / 'child').exists()
+
+
+@pytest.mark.parametrize(
+    ('platform_name', 'path_limit'),
+    [
+        ('darwin', 104),
+        ('linux', 108),
+    ],
+)
+def test_uds_sockname_compaction(
+    monkeypatch: pytest.MonkeyPatch,
+    platform_name: str,
+    path_limit: int,
+):
+    '''
+    Keep generated actor sockets safe and below Darwin's byte limit.
+
+    Actor names are unrestricted identity strings. A long, multibyte,
+    or path-like name previously produced overlong or escaping socket
+    paths. These cases prove `UDSAddress.get_sockname()` preserves a
+    short legacy name, deterministically compacts unsafe names, keeps
+    the reaper's `@pid.sock` suffix, and stays within Darwin's byte
+    limit.
+
+    '''
+    from tractor.ipc._uds import UDSAddress
+
+    bindspace: Path = Path('/tmp/tractor-501')
+    pid: int = 12345
+    from tractor.ipc import _uds
+
+    monkeypatch.setattr(sys, 'platform', platform_name)
+    monkeypatch.setattr(_uds, '_SUN_PATH_LIMIT', path_limit)
+
+    short: Path = UDSAddress.get_sockname(
+        name='worker',
+        pid=pid,
+        bindspace=bindspace,
+    )
+    long_name: str = 'actor-' + ('\u00e9' * 100)
+    compact: Path = UDSAddress.get_sockname(
+        name=long_name,
+        pid=pid,
+        bindspace=bindspace,
+    )
+    unsafe: Path = UDSAddress.get_sockname(
+        name='../worker',
+        pid=pid,
+        bindspace=bindspace,
+    )
+
+    assert short == Path(f'worker@{pid}.sock')
+    assert compact == UDSAddress.get_sockname(
+        name=long_name,
+        pid=pid,
+        bindspace=bindspace,
+    )
+    assert compact.name.endswith(f'@{pid}.sock')
+    assert unsafe.parent == Path('.')
+    assert '..' not in unsafe.name
+    assert len(os.fsencode(bindspace / compact)) < path_limit
+
+    with pytest.raises(ValueError) as exc_info:
+        UDSAddress.get_sockname(
+            name=long_name,
+            pid=pid,
+            bindspace=Path('/tmp') / ('x' * 90),
+        )
+
+    errmsg: str = str(exc_info.value)
+    assert 'leaves no room' in errmsg
+    assert 'name was unsafe: False' in errmsg
+    assert 'name was over budget: True' in errmsg
+    assert f'AF_UNIX path limit: {path_limit}' in errmsg
+
+
+def test_uds_reaper_ignores_unreconstructable_path(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    '''
+    Keep post-kill UDS cleanup best-effort on path overflow.
+
+    `unlink_uds_bind_addrs()` reconstructs a self-assigned socket from
+    the dead actor's name and PID. An over-budget bindspace makes that
+    naming helper raise before `os.unlink()`; propagating the error
+    would replace the original supervision outcome after the child was
+    already killed. This test forces overflow and proves cleanup skips
+    reconstruction without attempting an unlink or raising.
+
+    '''
+    from tractor.ipc import _uds
+    from tractor.spawn import _reap
+
+    long_bindspace: Path = Path('/tmp') / ('x' * 120)
+    proc = SimpleNamespace(pid=12345)
+    subactor = SimpleNamespace(
+        aid=SimpleNamespace(name='worker'),
+    )
+    unlink = Mock()
+    monkeypatch.setattr(
+        _uds.UDSAddress,
+        'def_bindspace',
+        long_bindspace,
+    )
+    monkeypatch.setattr(_reap.os, 'unlink', unlink)
+
+    _reap.unlink_uds_bind_addrs(
+        proc=proc,
+        subactor=subactor,
+    )
+
+    unlink.assert_not_called()
+
+
 def test_uds_bindspace_created_implicitly(
     debug_mode: bool,
     bindspace_dir_str: str,

tests/ipc/test_server.py

@@ -3,7 +3,13 @@ High-level `.ipc._server` unit tests.
 
 '''
 from __future__ import annotations
+import errno
+from unittest.mock import (
+    AsyncMock,
+    Mock,
+)
 
+import msgspec
 import pytest
 import trio
 from tractor import (
@@ -14,6 +20,11 @@ from tractor import (
 from tractor._testing.addr import (
     get_rando_addr,
 )
+from tractor._exceptions import TransportClosed
+from tractor.ipc._chan import Channel
+from tractor.ipc import _server
+from tractor.ipc._transport import MsgpackTransport
+from tractor.msg.types import Aid
 # TODO, use/check-roundtripping with some of these wrapper types?
 #
 # from .._addr import Address
@@ -23,6 +34,165 @@ from tractor._testing.addr import (
 # from ._tcp import TCPAddress
 
 
+def test_send_normalizes_only_grouped_peer_resets():
+    '''
+    Normalize only all-peer-close grouped transport failures.
+
+    A UDS peer may disconnect before completing the actor handshake.
+    Darwin can report the server's first handshake write as
+    `ECONNRESET`, wrapped by `trio.BrokenResourceError` and potentially
+    nested in an `ExceptionGroup`. This fake stream first groups reset
+    and broken-pipe branches, proving `.send()` normalizes a complete
+    peer-close tree to `TransportClosed`. It then groups a reset with
+    an unrelated `ValueError`, proving the mixed failure remains a
+    `trio.BrokenResourceError` instead of hiding the application error.
+
+    '''
+    def broken_resource(err_no: int) -> trio.BrokenResourceError:
+        try:
+            raise OSError(
+                err_no,
+                'Peer closed',
+            )
+        except OSError as peer_err:
+            try:
+                raise trio.BrokenResourceError from peer_err
+            except trio.BrokenResourceError as broken_err:
+                return broken_err
+
+    class GroupedFailureStream:
+        def __init__(self, exceptions: list[Exception]) -> None:
+            self.exceptions = exceptions
+
+        async def send_all(self, data: bytes) -> None:
+            grouped_err = ExceptionGroup(
+                'concurrent send failures',
+                self.exceptions,
+            )
+            raise trio.BrokenResourceError from grouped_err
+
+    async def main():
+        transport = object.__new__(MsgpackTransport)
+        transport.stream = GroupedFailureStream([
+            broken_resource(errno.ECONNRESET),
+            broken_resource(errno.EPIPE),
+        ])
+        transport._send_lock = trio.StrictFIFOLock()
+        transport._laddr = 'local'
+        transport._raddr = 'remote'
+        transport._task = trio.lowlevel.current_task()
+
+        with pytest.raises(TransportClosed) as exc_info:
+            await transport.send(
+                {'probe': True},
+                strict_types=False,
+            )
+
+        grouped_err = exc_info.value.src_exc.__cause__
+        assert isinstance(grouped_err, ExceptionGroup)
+        assert len(grouped_err.exceptions) == 2
+
+        transport.stream = GroupedFailureStream([
+            ValueError('unrelated failure'),
+            broken_resource(errno.ECONNRESET),
+        ])
+        with pytest.raises(trio.BrokenResourceError) as exc_info:
+            await transport.send(
+                {'probe': True},
+                strict_types=False,
+            )
+
+        grouped_err = exc_info.value.__cause__
+        assert isinstance(grouped_err, ExceptionGroup)
+        assert isinstance(grouped_err.exceptions[0], ValueError)
+
+    trio.run(main)
+
+
+def test_handshake_normalizes_decode_error():
+    '''
+    Keep malformed pre-handshake frames out of the service nursery.
+
+    A non-msgpack peer can trigger `msgspec.DecodeError` before a
+    remote `Aid` exists. Letting that decoder error escape the inbound
+    handler cancels the actor's shared IPC nursery. This fake channel
+    proves `_do_handshake()` presents only `TransportClosed` upward.
+
+    '''
+    chan = object.__new__(Channel)
+    chan.send = AsyncMock()
+    chan.recv = AsyncMock(
+        side_effect=msgspec.DecodeError('malformed handshake'),
+    )
+
+    async def main():
+        with pytest.raises(TransportClosed) as exc_info:
+            await chan._do_handshake(
+                aid=Aid(
+                    name='local',
+                    uuid='local-uuid',
+                    pid=1234,
+                ),
+                timeout=.1,
+            )
+
+        assert isinstance(
+            exc_info.value.src_exc,
+            msgspec.DecodeError,
+        )
+
+    trio.run(main)
+
+
+def test_server_uses_independent_handshake_timeout(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    '''
+    Give ordinary actor handshakes a distinct, generous deadline.
+
+    Registry probes use short retries, but ordinary portal and child
+    connections do not retry. Applying the probe's one-second timeout
+    in the server can terminate a valid delayed child and leave its
+    parent blocked in `IPCServer.wait_for_peer()`. This handler fake
+    proves the server uses its separate pre-registration budget.
+
+    '''
+    handshake = AsyncMock(
+        side_effect=TransportClosed(message='stop after assertion'),
+    )
+    chan = Mock(_do_handshake=handshake)
+    actor = Mock(
+        aid=Aid(
+            name='local',
+            uuid='local-uuid',
+            pid=1234,
+        ),
+    )
+    monkeypatch.setattr(
+        Channel,
+        'from_stream',
+        Mock(return_value=chan),
+    )
+    monkeypatch.setattr(
+        _server._state,
+        'current_actor',
+        Mock(return_value=actor),
+    )
+
+    async def main():
+        await _server.handle_stream_from_peer(
+            stream=Mock(),
+            server=Mock(),
+        )
+
+    trio.run(main)
+    handshake.assert_awaited_once_with(
+        aid=actor.aid,
+        timeout=_server._PRE_REG_HANDSHAKE_TIMEOUT,
+    )
+    assert _server._PRE_REG_HANDSHAKE_TIMEOUT == 10
+
+
 @pytest.mark.parametrize(
     '_tpt_proto',
     ['uds', 'tcp']

tests/test_docs_examples.py

@@ -5,11 +5,13 @@ Let's make sure them docs work yah?
 from contextlib import contextmanager
 import itertools
 import os
+import signal
 import sys
 import subprocess
 import platform
 import shutil
 from typing import Callable
+from unittest.mock import Mock
 
 import pytest
 import tractor
@@ -21,6 +23,184 @@ _non_linux: bool = platform.system() != 'Linux'
 _friggin_macos: bool = platform.system() == 'Darwin'
 
 
+def _kill_proc_tree(proc: subprocess.Popen) -> None:
+    '''
+    Terminate an example process and its POSIX descendants.
+
+    '''
+    try:
+        if platform.system() == 'Windows':
+            proc.kill()
+        else:
+            os.killpg(proc.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+
+
+def _reap_killed_proc(
+    proc: subprocess.Popen,
+) -> tuple[bytes, bytes]:
+    '''
+    Reap a killed process without waiting on Windows descendants.
+
+    '''
+    if platform.system() != 'Windows':
+        return proc.communicate()
+
+    proc.wait(timeout=5)
+    if proc.stdin:
+        proc.stdin.close()
+    if proc.stdout:
+        proc.stdout.close()
+    if proc.stderr:
+        proc.stderr.close()
+    return b'', b''
+
+
+def _wait_for_proc(
+    proc: subprocess.Popen,
+    timeout: float,
+    test_log: tractor.log.StackLevelAdapter,
+) -> None:
+    '''
+    Wait for an example process and surface its captured output.
+
+    '''
+    try:
+        out, err = proc.communicate(timeout=timeout)
+
+    except subprocess.TimeoutExpired as timeout_exc:
+        test_log.exception(
+            f'Example failed to finish within {timeout}s ??\n'
+        )
+        _kill_proc_tree(proc)
+        out, err = _reap_killed_proc(proc)
+        if platform.system() == 'Windows':
+            out = timeout_exc.output or b''
+            err = timeout_exc.stderr or b''
+
+    errmsg: str = err.decode(errors='replace')
+
+    # NOTE: always include captured stdout and stderr for a non-zero
+    # exit. Depending on the final stderr line previously hid grouped
+    # exception diagnostics; see GH #473.
+    #
+    # The prior impl only raised when the LAST stderr
+    # line contained 'Error', swallowing any crash whose
+    # traceback ends in a non-`XxxError:` line; in
+    # particular EVERY `tractor` root-actor crash ends
+    # with the strict-EG collapse note,
+    # '( ^^^ this exc was collapsed from a group ^^^ )',
+    # so ALL such failures were reduced to a bare
+    # `assert 1 == 0` in CI logs.. see GH #473.
+    rc: int|None = proc.returncode
+    if rc:
+        outmsg: str = out.decode(errors='replace')
+        raise Exception(
+            f'Example script exited with rc={rc} !?\n'
+            f'\n'
+            f'stdout:\n'
+            f'{outmsg}\n'
+            f'\n'
+            f'stderr:\n'
+            f'{errmsg}\n'
+        )
+
+    # if we get some gnarly output let's aggregate and raise
+    if errmsg:
+        errlines = errmsg.splitlines()
+        last_error = errlines[-1]
+        if (
+            'Error' in last_error
+
+            # XXX: currently we print this to console, but maybe
+            # shouldn't eventually once we figure out what's
+            # a better way to be explicit about aio side
+            # cancels?
+            and
+            'asyncio.exceptions.CancelledError' not in last_error
+        ):
+            raise Exception(errmsg)
+
+    assert proc.returncode == 0
+
+
+def test_wait_for_failed_example_captures_output():
+    '''
+    Preserve diagnostics from a subprocess which already exited.
+
+    The previous `poll()` guard skipped `communicate()` when a fast
+    failure returned a non-zero status before the parent checked it.
+    Its stdout and stderr were therefore reported as empty. This
+    fake process begins with `returncode=1` and returns non-UTF-8
+    output, proving the helper always drains both pipes and replaces
+    undecodable bytes without hiding the original process failure.
+
+    '''
+    proc = Mock()
+    proc.returncode = 1
+    proc.communicate.return_value = (
+        b'stdout\xff',
+        b'stderr\xff',
+    )
+
+    with pytest.raises(Exception) as exc_info:
+        _wait_for_proc(
+            proc=proc,
+            timeout=1,
+            test_log=Mock(),
+        )
+
+    proc.communicate.assert_called_once_with(timeout=1)
+    errmsg: str = str(exc_info.value)
+    assert 'stdout\ufffd' in errmsg
+    assert 'stderr\ufffd' in errmsg
+
+
+@pytest.mark.skipif(
+    platform.system() == 'Windows',
+    reason='POSIX process groups are unavailable on Windows',
+)
+def test_wait_for_timed_out_example_reaps_group(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    '''
+    Kill the example process group and reap its leader on timeout.
+
+    The old timeout branch killed only the immediate process and
+    never drained it. Actor descendants could retain the capture
+    pipes while the leader remained unreaped, hanging CI until its
+    job timeout. This fake process raises `TimeoutExpired` on the
+    timed wait and completes on the second `communicate()` call;
+    the assertions prove group-directed `SIGKILL` precedes that
+    final drain and leaves a concrete non-zero return code.
+
+    '''
+    proc = Mock()
+    proc.pid = 1234
+
+    def communicate(timeout=None):
+        if timeout is not None:
+            raise subprocess.TimeoutExpired('example', timeout)
+        proc.returncode = -signal.SIGKILL
+        return b'', b'timed out'
+
+    proc.communicate.side_effect = communicate
+    killpg = Mock()
+    monkeypatch.setattr(os, 'killpg', killpg)
+
+    with pytest.raises(Exception, match='timed out'):
+        _wait_for_proc(
+            proc=proc,
+            timeout=.01,
+            test_log=Mock(),
+        )
+
+    killpg.assert_called_once_with(1234, signal.SIGKILL)
+    assert proc.communicate.call_count == 2
+    assert proc.returncode == -signal.SIGKILL
+
+
 @pytest.fixture
 def run_example_in_subproc(
     loglevel: str,
@@ -61,14 +241,14 @@ def run_example_in_subproc(
             ]
         else:
             script_file = testdir.makefile('.py', script_code)
+            kwargs['start_new_session'] = True
             cmdargs = [
                 sys.executable,
                 str(script_file),
             ]
 
-        # XXX: BE FOREVER WARNED: if you enable lots of tractor logging
-        # in the subprocess it may cause infinite blocking on the pipes
-        # due to backpressure!!!
+        # Captured pipes are drained by `_wait_for_proc()` while the
+        # example runs.
         proc = testdir.popen(
             cmdargs,
             stdin=subprocess.PIPE,
@@ -77,9 +257,20 @@ def run_example_in_subproc(
             **kwargs,
         )
         assert not proc.returncode
+        try:
             yield proc
-        proc.wait()
-        assert proc.returncode == 0
+        except BaseException:
+            if proc.poll() is None:
+                try:
+                    _kill_proc_tree(proc)
+                    _reap_killed_proc(proc)
+                except Exception:
+                    pass
+            raise
+        else:
+            if proc.poll() is None:
+                _kill_proc_tree(proc)
+                _reap_killed_proc(proc)
 
     yield run
 
@@ -145,21 +336,6 @@ def test_example(
             'This test does run just fine "in person" however..'
         )
 
-    if (
-        'uds_transport_actor_tree' in ex_file
-        and
-        _friggin_macos
-        and
-        ci_env
-    ):
-        pytest.skip(
-            'UDS-transport example reliably fails on macOS CI.\n'
-            'UDS-on-macOS is otherwise un-exercised by the matrix\n'
-            '(no `tpt_proto=uds` macOS job), so this new example is\n'
-            'the first to surface it; the macOS UDS path needs\n'
-            'root-causing. Passes on Linux.'
-        )
-
     from .conftest import cpu_perf_headroom
 
     timeout: float = (
@@ -178,33 +354,8 @@ def test_example(
         code = ex.read()
 
         with run_example_in_subproc(code) as proc:
-            err = None
-            try:
-                if not proc.poll():
-                    _, err = proc.communicate(timeout=timeout)
-
-            except subprocess.TimeoutExpired as e:
-                test_log.exception(
-                    f'Example failed to finish within {timeout}s ??\n'
+            _wait_for_proc(
+                proc=proc,
+                timeout=timeout,
+                test_log=test_log,
             )
-                proc.kill()
-                err = e.stderr
-
-            # if we get some gnarly output let's aggregate and raise
-            if err:
-                errmsg = err.decode()
-                errlines = errmsg.splitlines()
-                last_error = errlines[-1]
-                if (
-                    'Error' in last_error
-
-                    # XXX: currently we print this to console, but maybe
-                    # shouldn't eventually once we figure out what's
-                    # a better way to be explicit about aio side
-                    # cancels?
-                    and
-                    'asyncio.exceptions.CancelledError' not in last_error
-                ):
-                    raise Exception(errmsg)
-
-            assert proc.returncode == 0

tests/test_infected_asyncio.py

@@ -20,6 +20,18 @@ from typing import (
 import pytest
 import trio
 import tractor
+
+# `infect_asyncio` mode is unsupported on Windows (asyncio's
+# `ProactorEventLoop` is incompatible with our `trio` guest-mode
+# interop and currently hangs/crashes the run). Skip the module on
+# Windows so the CI leg completes + reports the rest of the suite.
+import platform
+if platform.system() == 'Windows':
+    pytest.skip(
+        'infect_asyncio mode is unsupported on Windows',
+        allow_module_level=True,
+    )
+
 from tractor import (
     current_actor,
     Actor,

tests/test_lazy_imports.py

@@ -0,0 +1,160 @@
+'''
+Regression tests for the cold package import surface.
+
+'''
+import json
+import os
+from statistics import median
+import subprocess
+import sys
+from typing import (
+    Any,
+    get_type_hints,
+)
+
+from tractor.discovery import (
+    _addr,
+    _multiaddr,
+)
+from tractor.ipc import (
+    _tcp,
+    _uds,
+)
+
+
+def run_cold_import(code: str) -> dict[str, object]:
+    result = subprocess.run(
+        [
+            sys.executable,
+            '-c',
+            code,
+        ],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return json.loads(result.stdout)
+
+
+def test_lazy_to_asyncio_package_api():
+    '''
+    Keep the public lazy submodule discoverable without eagerly
+    importing it.
+
+    Before the lazy conversion, package import side effects exposed
+    `to_asyncio` to `dir()` and wildcard imports. Exercise those APIs
+    in cold interpreters so this test proves normal `import tractor`
+    leaves `asyncio` unloaded, while discovery and wildcard access
+    still advertise and resolve the public submodule.
+
+    '''
+    cold = run_cold_import(
+        'import json, sys, tractor; '
+        'print(json.dumps({'
+        '"advertised": "to_asyncio" in dir(tractor), '
+        '"asyncio_loaded": "asyncio" in sys.modules}))'
+    )
+    assert cold == {
+        'advertised': True,
+        'asyncio_loaded': False,
+    }
+
+    wildcard = run_cold_import(
+        'import json; '
+        'from tractor import *; '
+        'print(json.dumps({'
+        '"module": to_asyncio.__name__}))'
+    )
+    assert wildcard == {
+        'module': 'tractor.to_asyncio',
+    }
+
+
+def test_cold_import_budget():
+    '''
+    Keep cold package import below the pre-optimization regression.
+
+    The original `inspect.stack()` caller lookup made a fresh
+    `import tractor` take about 0.42s and dominate actor startup.
+    Run seven independent interpreters and gate their median at a
+    deliberately broad 0.35s: over twice the measured ~0.145s
+    baseline, but low enough to catch restoration of that hot path.
+
+    Taking the median absorbs process-start and shared-runner noise.
+    The child measures only its import, rather than parent-side
+    process creation. `TRACTOR_IMPORT_BUDGET_S` provides an explicit,
+    reviewable override for platforms that establish a different
+    baseline instead of silently weakening the project default.
+
+    Each child also reports the modules whose eager loading this PR
+    intentionally removes, proving a timing pass cannot hide a
+    dependency-import regression.
+
+    '''
+    budget_s = float(
+        os.environ.get(
+            'TRACTOR_IMPORT_BUDGET_S',
+            '0.35',
+        )
+    )
+    optional_mods = (
+        'asyncio',
+        'bidict',
+        'colorlog',
+        'multiaddr',
+        'wrapt',
+    )
+    code = (
+        'import json, sys, time; '
+        'started = time.perf_counter(); '
+        'import tractor; '
+        'elapsed = time.perf_counter() - started; '
+        f'optional = {optional_mods!r}; '
+        'print(json.dumps({'
+        '"elapsed": elapsed, '
+        '"loaded": [name for name in optional '
+        'if name in sys.modules]}))'
+    )
+    samples = [
+        run_cold_import(code)
+        for _ in range(7)
+    ]
+    elapsed = [
+        float(sample['elapsed'])
+        for sample in samples
+    ]
+    loaded = {
+        name
+        for sample in samples
+        for name in sample['loaded']
+    }
+
+    assert not loaded
+    assert median(elapsed) < budget_s, (
+        f'cold import median exceeded {budget_s:.3f}s budget: '
+        f'{elapsed!r}'
+    )
+
+
+def test_lazy_annotation_names_resolve():
+    '''
+    Resolve annotations without importing optional dependencies.
+
+    Moving annotation-only third-party names under `TYPE_CHECKING`
+    left their runtime globals undefined, causing
+    `typing.get_type_hints()` to raise `NameError`. Resolve every
+    affected API and prove the lazy aliases retain import-free runtime
+    introspection.
+
+    '''
+    assert get_type_hints(_multiaddr.mk_maddr)['return'] is Any
+    assert get_type_hints(_tcp.MsgpackTCPStream.maddr.fget)[
+        'return'
+    ] is Any
+    assert get_type_hints(_uds.MsgpackUDSStream.maddr.fget)[
+        'return'
+    ] == Any|str
+    assert get_type_hints(_addr.Address.get_random)[
+        'current_actor'
+    ] is Any
+    assert _addr.__annotations__['_address_types'].startswith('dict')

tests/test_log_sys.py

@@ -2,9 +2,11 @@
 `tractor.log`-wrapping unit tests.
 
 '''
+import importlib
 import logging
 from pathlib import Path
 import shutil
+import sys
 from types import ModuleType
 
 import pytest
@@ -165,6 +167,53 @@ def test_implicit_mod_name_applied_for_child(
     assert submod.log.logger in sub_logs
 
 
+def test_implicit_mod_name_from_unregistered_namespace(
+    tmp_path: Path,
+):
+    '''
+    Preserve implicit logger naming for dynamic module namespaces.
+
+    The fast `sys.modules` caller lookup cannot resolve `runpy`,
+    plugin-loader, or `exec()` namespaces that are not registered.
+    Compile a real package file under an unregistered module name so
+    the rare filename fallback must recover its imported package and
+    retain the same package-level logger name.
+
+    '''
+    pkg_name = 'dynamic_logger_pkg'
+    pkg_dir = tmp_path / pkg_name
+    pkg_dir.mkdir()
+    init_path = pkg_dir / '__init__.py'
+    init_path.write_text('')
+    mod_path = pkg_dir / 'plugin.py'
+    mod_path.write_text('')
+
+    sys.path.insert(0, str(tmp_path))
+    try:
+        importlib.import_module(pkg_name)
+        namespace = {
+            '__name__': f'{pkg_name}.unregistered',
+            '__package__': pkg_name,
+            'tractor': tractor,
+        }
+        exec(
+            compile(
+                'log = tractor.log.get_logger('
+                f'pkg_name={pkg_name!r})',
+                str(mod_path),
+                'exec',
+            ),
+            namespace,
+        )
+        dynamic_log = namespace.get('log')
+    finally:
+        sys.path.remove(str(tmp_path))
+        sys.modules.pop(pkg_name, None)
+
+    assert dynamic_log is not None
+    assert dynamic_log.name == pkg_name
+
+
 def test_io_custom_level_registered():
     '''
     The `IO`(21) level (registered via `add_log_level()` at

tests/test_ringbuf.py

@@ -1,10 +1,22 @@
 import time
+import platform
 
 import trio
 import pytest
 
 import tractor
 
+# `tractor.ipc._ringbuf` is built on linux `eventfd(2)`; importing
+# it pulls in `tractor.ipc._linux` whose module-level
+# `ffi.dlopen(None)` raises on non-linux. Skip the whole module at
+# COLLECTION before that crashing import runs (a `pytestmark` skip
+# is too late — markers apply only after the import succeeds).
+if platform.system() != 'Linux':
+    pytest.skip(
+        'ringbuf (eventfd) IPC is linux-only',
+        allow_module_level=True,
+    )
+
 # XXX `cffi` dun build on py3.14 yet..
 pytest.importorskip("cffi")
 

tests/test_root_infect_asyncio.py

@@ -9,6 +9,17 @@ from functools import partial
 import pytest
 import trio
 import tractor
+
+# `infect_asyncio` mode is unsupported on Windows (see
+# `test_infected_asyncio`); skip at COLLECTION before the
+# asyncio-interop imports below so the CI leg completes.
+import platform
+if platform.system() == 'Windows':
+    pytest.skip(
+        'infect_asyncio mode is unsupported on Windows',
+        allow_module_level=True,
+    )
+
 from tractor import (
     to_asyncio,
 )

tests/test_rpc.py

@@ -4,11 +4,18 @@ related API and error checks.
 
 '''
 import itertools
+from unittest.mock import (
+    AsyncMock,
+    Mock,
+)
 
 import pytest
 import tractor
 import trio
 
+from tractor._exceptions import TransportClosed
+from tractor.runtime import _rpc
+
 
 async def sleep_back_actor(
     actor_name,
@@ -46,6 +53,126 @@ async def short_sleep():
     await trio.sleep(0)
 
 
+def test_rpc_runs_after_startack_disconnect():
+    '''
+    Complete an accepted RPC when its caller closes before `StartAck`.
+
+    Registrar teardown opens short-lived `unregister_actor` RPCs. A
+    loaded caller can close its channel while the registrar sends the
+    acknowledgement; normalized `TransportClosed` previously escaped
+    into the shared service nursery before the already-created
+    coroutine was awaited. This fake fails the first response send and
+    proves the RPC side effect still runs with no later send attempt.
+
+    '''
+    async def main():
+        rpc_ran = trio.Event()
+
+        chan = Mock()
+        chan.send = AsyncMock(
+            side_effect=TransportClosed(
+                message='caller closed before StartAck',
+            ),
+        )
+        chan.connected.return_value = False
+        ctx = Mock(
+            chan=chan,
+            cid='rpc-cid',
+            _scope=None,
+            _task='rpc-task',
+        )
+        actor = Mock()
+        actor.get_context.return_value = ctx
+        actor._rpc_tasks = {}
+        actor._ongoing_rpc_tasks = trio.Event()
+        actor._ongoing_rpc_tasks.set()
+
+        async def rpc_func():
+            assert (chan, ctx.cid) in actor._rpc_tasks
+            rpc_ran.set()
+
+        async def invoke(task_status):
+            await _rpc._invoke(
+                actor=actor,
+                cid=ctx.cid,
+                chan=chan,
+                func=rpc_func,
+                kwargs={},
+                task_status=task_status,
+            )
+
+        async with trio.open_nursery() as nursery:
+            started_ctx = await nursery.start(invoke)
+            assert started_ctx is ctx
+            await rpc_ran.wait()
+
+        assert rpc_ran.is_set()
+        assert not actor._rpc_tasks
+        assert actor._ongoing_rpc_tasks.is_set()
+        chan.send.assert_awaited_once()
+
+    trio.run(main)
+
+
+def test_error_shipment_ignores_closed_response_channel(monkeypatch):
+    '''
+    Preserve an application error when its response channel is closed.
+
+    A caller can disconnect after submitting an RPC but before its
+    error response. Normalized `TransportClosed` from that final send
+    is terminal response failure, not a new actor-wide service error.
+    This test proves error shipment logs and returns without replacing
+    the original application exception.
+
+    '''
+    chan = Mock()
+    chan.send = AsyncMock(
+        side_effect=[
+            None,
+            TransportClosed(
+                message='caller closed before Error response',
+            ),
+        ],
+    )
+    error_msg = Mock(boxed_type_str='ValueError')
+    monkeypatch.setattr(
+        _rpc,
+        'pack_error',
+        Mock(return_value=error_msg),
+    )
+    ctx = Mock(
+        chan=chan,
+        cid='rpc-cid',
+        _scope=None,
+        _task='rpc-task',
+    )
+    actor = Mock()
+    actor.get_context.return_value = ctx
+    actor._rpc_tasks = {}
+    actor._ongoing_rpc_tasks = trio.Event()
+    actor._ongoing_rpc_tasks.set()
+
+    async def failing_rpc():
+        raise ValueError('application failure')
+
+    async def main():
+        async with trio.open_nursery() as nursery:
+            started_ctx = await nursery.start(
+                _rpc._invoke,
+                actor,
+                ctx.cid,
+                chan,
+                failing_rpc,
+                {},
+            )
+            assert started_ctx is ctx
+
+    trio.run(main)
+    assert chan.send.await_count == 2
+    assert not actor._rpc_tasks
+    assert actor._ongoing_rpc_tasks.is_set()
+
+
 @pytest.mark.parametrize(
     'to_call', [
         ([], 'short_sleep', tractor.RemoteActorError),

tests/test_runtime.py

@@ -73,6 +73,11 @@ async def test_lifetime_stack_wipes_tmpfile(
         1.6 if error_in_child
         else 1
     )
+    # scale for slow/noisy CI (esp. macOS) so the child error
+    # propagates before the deadline; otherwise `move_on_after`
+    # cancels first and flips the `error_in_child=True` assert.
+    from .conftest import cpu_perf_headroom
+    timeout *= cpu_perf_headroom()
     try:
         with trio.move_on_after(timeout) as cs:
             async with tractor.open_nursery(

tests/test_shm.py

@@ -120,6 +120,13 @@ async def child_read_shm_list(
                 print(f'(child): reading frame: {frame}')
 
 
+@pytest.mark.skipif(
+    platform.system() == 'Windows',
+    reason=(
+        'parent/child shm IPC deadlocks on Windows '
+        '(frame-size dependent hang); nascent — see #404'
+    ),
+)
 @pytest.mark.parametrize(
     'use_str',
     [False, True],

tractor/__init__.py

@@ -75,3 +75,39 @@ from .discovery._registry import (
     Arbiter as Arbiter,
 )
 # from . import hilevel as hilevel
+
+
+__all__: tuple[str, ...] = tuple(
+    name
+    for name in globals()
+    if not name.startswith('_')
+) + (
+    'to_asyncio',
+)
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))
+
+
+def __getattr__(name: str):
+    '''
+    PEP 562 lazy sub-module loading, presently only for
+    `.to_asyncio` which (transitively) imports `asyncio`
+    itself: a non-trivial multi-ms chunk of the eager
+    `import tractor` cost (gh #470) unneeded by
+    `trio`-only apps.
+
+    Any `tractor.to_asyncio.<attr>` access (or a
+    `from tractor import to_asyncio`) still works, the
+    sub-mod is simply imported on first-access instead
+    of at pkg-import time.
+
+    '''
+    if name == 'to_asyncio':
+        from importlib import import_module
+        return import_module('.to_asyncio', __name__)
+
+    raise AttributeError(
+        f'module {__name__!r} has no attribute {name!r}'
+    )

tractor/_root.py

@@ -47,9 +47,7 @@ from .devx import (
 from .spawn import _spawn
 from .runtime import _state
 from . import log
-from .ipc import (
-    _connect_chan,
-)
+from .discovery._api import _probe_registry_addrs
 from .discovery._addr import (
     Address,
     UnwrappedAddress,
@@ -451,49 +449,22 @@ async def open_root_actor(
             from .devx._stackscope import enable_stack_on_sig
             enable_stack_on_sig()
 
-        # closed into below ping task-func
-        ponged_addrs: list[Address] = []
+        ponged_addrs: list[Address]
+        occupied_addrs: list[Address]
+        (
+            ponged_addrs,
+            occupied_addrs,
+        ) = await _probe_registry_addrs(uw_reg_addrs)
 
-        async def ping_tpt_socket(
-            addr: Address,
-            timeout: float = 1,
-        ) -> None:
-            '''
-            Attempt temporary connection to see if a registry is
-            listening at the requested address by a tranport layer
-            ping.
-
-            If a connection can't be made quickly we assume none no
-            server is listening at that addr.
-
-            '''
-            try:
-                # TODO: this connect-and-bail forces us to have to
-                # carefully rewrap TCP 104-connection-reset errors as
-                # EOF so as to avoid propagating cancel-causing errors
-                # to the channel-msg loop machinery. Likely it would
-                # be better to eventually have a "discovery" protocol
-                # with basic handshake instead?
-                with trio.move_on_after(timeout):
-                    async with _connect_chan(addr.unwrap()):
-                        ponged_addrs.append(addr)
-
-            except OSError:
-                # ?TODO, make this a "discovery" log level?
-                logger.info(
-                    f'No root-actor registry found @ {addr!r}\n'
-                )
-
-        # !TODO, this is basically just another (abstract)
-        # happy-eyeballs, so we should try for formalize it somewhere
-        # in a `.[_]discovery` ya?
-        #
-        async with trio.open_nursery() as tn:
-            for uw_addr in uw_reg_addrs:
-                addr: Address = wrap_address(uw_addr)
-                tn.start_soon(
-                    ping_tpt_socket,
-                    addr,
+        if (
+            not ponged_addrs
+            and
+            occupied_addrs
+        ):
+            raise RuntimeError(
+                f'Registry address(es) are occupied but did not '
+                f'answer as Tractor registrars!\n'
+                f'occupied_addrs: {occupied_addrs!r}\n'
             )
 
         if tpt_bind_addrs is None:

tractor/_testing/_reap.py

@@ -111,14 +111,13 @@ SHM_DIR: str = '/dev/shm'
 
 # UDS-socket leak sweep — see `find_orphaned_uds()` /
 # `reap_uds()` below. Tractor's UDS transport
-# (`tractor.ipc._uds`) creates sock files under
-# `${XDG_RUNTIME_DIR}/tractor/<name>@<pid>.sock`; a
+# (`tractor.ipc._uds`) creates sock files in its platform-specific
+# default bindspace; a
 # crash / SIGKILL / mid-cancel teardown can leave the
 # file behind because `os.unlink()` lives in the
 # `_serve_ipc_eps` `finally:` block which doesn't always
 # get to run on hard exits. The reaper here is best-effort
 # cleanup for the test harness + the `tractor-reap` CLI.
-_UDS_SUBDIR: str = 'tractor'
 # `<actor-name>@<pid>.sock` — pid is the binder's pid at
 # creation time. Special sentinel: `registry@1616.sock`
 # uses the magic `1616` not a real pid (the root
@@ -738,19 +737,16 @@ def reap_shm(
 
 def get_uds_dir() -> str|None:
     '''
-    Path of tractor's per-user UDS sock-file dir
-    (`${XDG_RUNTIME_DIR}/tractor/`).
+    Path of Tractor's platform-specific default UDS bindspace.
 
-    Returns `None` when `XDG_RUNTIME_DIR` is unset (e.g.
-    non-systemd hosts, or inside a container without the
-    var plumbed through). Caller should treat that as
-    "no UDS leaks possible to detect — skip".
+    Returns `None` only when the bindspace cannot be resolved.
 
     '''
-    xdg: str|None = os.environ.get('XDG_RUNTIME_DIR')
-    if not xdg:
+    try:
+        from tractor.ipc._uds import UDSAddress
+        return str(UDSAddress.def_bindspace)
+    except Exception:
         return None
-    return os.path.join(xdg, _UDS_SUBDIR)
 
 
 def _parse_uds_name(filename: str) -> tuple[str, int]|None:
@@ -768,16 +764,16 @@ def _parse_uds_name(filename: str) -> tuple[str, int]|None:
 def find_orphaned_uds(
     *,
     uds_dir: str|None = None,
+    include_registry_sentinel: bool = False,
 ) -> list[str]:
     '''
     `<uds_dir>/*.sock` paths whose binder pid is no
-    longer alive (orphaned). Includes the
-    `registry@1616.sock` sentinel — `1616` is a magic
-    sentinel pid (not a real one) so the file's
-    presence alone signals a leak from a dead session.
+    longer alive (orphaned). Explicit callers may include the
+    `registry@1616.sock` sentinel; automatic pytest cleanup excludes
+    it because binder liveness cannot be inferred from magic `1616`.
 
-    Returns `[]` on platforms without `XDG_RUNTIME_DIR`
-    or when the dir doesn't exist. Files whose name
+    Returns `[]` when the platform bindspace cannot be resolved or the
+    dir doesn't exist. Files whose name
     doesn't match the `<name>@<pid>.sock` pattern are
     skipped (we don't unlink things we don't recognize).
 
@@ -811,9 +807,7 @@ def find_orphaned_uds(
             continue
         _name, pid = parsed
         if pid == _UDS_REGISTRY_SENTINEL_PID:
-            # sentinel — never a real pid; if the file
-            # exists nobody live is "owning" it via
-            # /proc lookup, so always orphaned
+            if include_registry_sentinel:
                 leaked.append(path)
             continue
         if not _is_alive(pid):
@@ -933,8 +927,8 @@ def track_orphaned_uds_per_test():
     teardown that flakifies sibling tests via
     sock-file rebind races).
 
-    Snapshots `${XDG_RUNTIME_DIR}/tractor/` before and
-    after each test; any `<name>@<pid>.sock` files
+    Snapshots Tractor's platform-specific default UDS bindspace before
+    and after each test; any `<name>@<pid>.sock` files
     created during the test that survive teardown AND
     whose creator pid is dead are surfaced as a loud
     warning AND reaped, so the next test starts with a
@@ -950,8 +944,8 @@ def track_orphaned_uds_per_test():
     it (vs. blanket session-end sweep) makes blame
     obvious + prevents cascade flakiness.
 
-    Cheap: 2x `os.listdir` + a few `os.stat`s per test.
-    Skips silently when `XDG_RUNTIME_DIR` isn't set.
+    Cheap: 2x `os.listdir` + a few `os.stat`s per test. Skips silently
+    when the platform bindspace cannot be resolved.
 
     '''
     uds_dir: str|None = get_uds_dir()

tractor/devx/_frame_stack.py

@@ -39,14 +39,15 @@ from typing import (
     Type,
 )
 
-import pdbp
+# NOTE, `pdbp` + `wrapt` are lazy-imported at their
+# single use-sites below to keep them off the eager
+# `import tractor` path (gh #470).
 from tractor.log import get_logger
 import trio
 from tractor.msg import (
     pretty_struct,
     NamespacePath,
 )
-import wrapt
 
 
 log = get_logger()
@@ -257,6 +258,7 @@ def api_frame(
     caller_frames_up: int = 1,
 
 ) -> Callable:
+    import wrapt
 
     # handle the decorator called WITHOUT () case,
     # i.e. just @api_frame, NOT @api_frame(extra=<blah>)
@@ -320,6 +322,8 @@ def hide_runtime_frames() -> dict[FunctionType, CodeType]:
     as possible, particularly from inside a `PdbREPL`.
 
     '''
+    import pdbp
+
     # XXX HACKZONE XXX
     #  hide exit stack frames on nurseries and cancel-scopes!
     # |_ so avoid seeing it when the `pdbp` REPL is first engaged from

tractor/devx/_stackscope.py

@@ -31,12 +31,21 @@ from threading import (
     RLock,
 )
 import multiprocessing as mp
+
+import platform
+
 from signal import (
     signal,
     getsignal,
-    SIGUSR1,
     SIGINT,
 )
+
+
+if platform.system() != "Windows":
+    from signal import SIGUSR1
+else:
+    SIGUSR1 = None
+
 # import traceback
 from types import ModuleType
 from typing import (
@@ -347,8 +356,8 @@ def dump_tree_on_sig(
 
 
 def enable_stack_on_sig(
-    sig: int = SIGUSR1,
-) -> ModuleType:
+    sig: int|None = SIGUSR1,
+) -> ModuleType|None:
     '''
     Enable `stackscope` tracing on reception of a signal; by
     default this is SIGUSR1.
@@ -367,6 +376,16 @@ def enable_stack_on_sig(
     >> pkill --signal SIGUSR1 -f <part-of-cmd: str>
 
     '''
+    # no `SIGUSR1` on this platform (e.g. Windows) -> nothing to
+    # wire up; degrade gracefully instead of crashing callers that
+    # only guard against a missing `stackscope` (`ImportError`).
+    if sig is None:
+        log.warning(
+            'No `SIGUSR1` on this platform;\n'
+            'skipping `stackscope` trace-on-signal setup!\n'
+        )
+        return None
+
     try:
         # NOTE, `stackscope._glue` does intentional async-gen type
         # introspection at import-time which trips

tractor/devx/debug/_trace.py

@@ -24,7 +24,6 @@ mult-process support within a single actor tree.
 
 '''
 from __future__ import annotations
-import asyncio
 import bdb
 from contextlib import (
     AbstractContextManager,
@@ -53,7 +52,6 @@ from trio import (
 )
 import tractor
 from tractor.log import get_logger
-from tractor.to_asyncio import run_trio_task_in_future
 from tractor._context import Context
 from tractor.runtime import _state
 from tractor._exceptions import (
@@ -85,6 +83,10 @@ from ..pformat import (
 )
 
 if TYPE_CHECKING:
+    # NOTE, `asyncio` (and `.to_asyncio`) are
+    # lazy-imported at their use-sites to keep them off
+    # the eager `import tractor` path (gh #470).
+    import asyncio
     from trio.lowlevel import Task
     from threading import Thread
     from tractor.runtime._runtime import (
@@ -164,6 +166,7 @@ async def _pause(
                 'An `asyncio` task should not be calling this!?'
             ) from rte
         else:
+            import asyncio
             task = asyncio.current_task()
 
     if debug_func is not None:
@@ -946,6 +949,7 @@ def pause_from_sync(
 
         asyncio_task: asyncio.Task|None = None
         if is_infected_aio:
+            import asyncio
             asyncio_task = asyncio.current_task()
 
         # TODO: we could also check for a non-`.to_thread` context
@@ -1059,6 +1063,9 @@ def pause_from_sync(
             greenback: ModuleType = maybe_import_greenback()
 
             if greenback.has_portal():
+                from tractor.to_asyncio import (
+                    run_trio_task_in_future,
+                )
                 DebugStatus.shield_sigint()
                 fute: asyncio.Future = run_trio_task_in_future(
                     partial(

tractor/devx/debug/_tty_lock.py

@@ -20,7 +20,6 @@ Root-actor TTY mutex-locking machinery.
 
 '''
 from __future__ import annotations
-import asyncio
 from contextlib import (
     AbstractContextManager,
     asynccontextmanager as acm,
@@ -52,7 +51,6 @@ from trio import (
     TaskStatus,
 )
 import tractor
-from tractor.to_asyncio import run_trio_task_in_future
 from tractor.log import get_logger
 from tractor._context import Context
 from tractor.runtime import _state
@@ -66,6 +64,10 @@ from tractor.runtime._state import (
 )
 
 if TYPE_CHECKING:
+    # NOTE, `asyncio` (and `.to_asyncio`) are
+    # lazy-imported at their use-sites to keep them off
+    # the eager `import tractor` path (gh #470).
+    import asyncio
     from trio.lowlevel import Task
     from threading import Thread
     from tractor.ipc import (
@@ -910,6 +912,9 @@ class DebugStatus:
                     async def _set_repl_release():
                         repl_release.set()
 
+                    from tractor.to_asyncio import (
+                        run_trio_task_in_future,
+                    )
                     fute: asyncio.Future = run_trio_task_in_future(
                         _set_repl_release
                     )

tractor/discovery/_addr.py

@@ -16,13 +16,13 @@
 from __future__ import annotations
 from uuid import uuid4
 from typing import (
+    Any,
     Protocol,
     ClassVar,
     Type,
     TYPE_CHECKING,
 )
 
-from bidict import bidict
 from trio import (
     SocketListener,
 )
@@ -32,14 +32,20 @@ from ..runtime._state import (
     _def_tpt_proto,
 )
 from ..ipc._tcp import TCPAddress
-from ..ipc._uds import UDSAddress
+from ..ipc._uds import (
+    UDSAddress,
+    HAS_UDS,
+)
 
 if TYPE_CHECKING:
+    # ONLY type-annots, the eager import costs ~4.5ms
+    # of `import tractor` wall-time (gh #470).
     from ..runtime._runtime import Actor
+else:
+    Actor = Any
 
 log = get_logger()
 
-
 # TODO, maybe breakout the netns key to a struct?
 # class NetNs(Struct)[str, int]:
 #     ...
@@ -170,25 +176,36 @@ class Address(Protocol):
         ...
 
 
-_address_types: bidict[str, Type[Address]] = {
-    'tcp': TCPAddress,
-    'uds': UDSAddress
+# the address types available on this host: TCP always, UDS only
+# where usable (`HAS_UDS`). Both registries derive from this single
+# list via each type's `proto_key`.
+_address_protos: list[Type[Address]] = [TCPAddress]
+if HAS_UDS:
+    _address_protos.append(UDSAddress)
+
+_address_types: dict[str, Type[Address]] = {
+    cls.proto_key: cls
+    for cls in _address_protos
 }
 
 
 # TODO! really these are discovery sys default addrs ONLY useful for
 # when none is provided to a root actor on first boot.
-_default_lo_addrs: dict[
-    str,
-    UnwrappedAddress
-] = {
-    'tcp': TCPAddress.get_root().unwrap(),
-    'uds': UDSAddress.get_root().unwrap(),
+_default_lo_addrs: dict[str, UnwrappedAddress] = {
+    cls.proto_key: cls.get_root().unwrap()
+    for cls in _address_protos
 }
 
 
 def get_address_cls(name: str) -> Type[Address]:
+    try:
         return _address_types[name]
+    except KeyError:
+        raise NotImplementedError(
+            f'No IPC transport backend for {name!r} on this '
+            f'platform!\n'
+            f'(available: {list(_address_types)})\n'
+        )
 
 
 def is_wrapped_addr(addr: any) -> bool:
@@ -286,7 +303,14 @@ def default_lo_addrs(
     for an input transport key set.
 
     '''
-    return [
-        _default_lo_addrs[transport]
-        for transport in transports
-    ]
+    lo_addrs: list[UnwrappedAddress] = []
+    for transport in transports:
+        try:
+            lo_addrs.append(_default_lo_addrs[transport])
+        except KeyError:
+            raise NotImplementedError(
+                f'No default loopback addr for transport '
+                f'{transport!r} on this platform!\n'
+                f'(available: {list(_default_lo_addrs)})\n'
+            )
+    return lo_addrs

tractor/discovery/_api.py

@@ -21,14 +21,18 @@ management of (service) actors.
 """
 from __future__ import annotations
 import ipaddress
+import os
 import socket
 from typing import (
     AsyncGenerator,
     AsyncContextManager,
+    Literal,
     TYPE_CHECKING,
 )
 from contextlib import asynccontextmanager as acm
 
+import trio
+
 from tractor.log import get_logger
 from ..trionics import (
     gather_contexts,
@@ -40,6 +44,7 @@ from ..ipc._uds import UDSAddress
 from ._addr import (
     UnwrappedAddress,
     Address,
+    mk_uuid,
     wrap_address,
 )
 from ..runtime._portal import (
@@ -52,6 +57,7 @@ from ..runtime._state import (
     _runtime_vars,
     _def_tpt_proto,
 )
+from ..msg.types import Aid
 
 if TYPE_CHECKING:
     from ..runtime._runtime import Actor
@@ -60,6 +66,115 @@ if TYPE_CHECKING:
 log = get_logger()
 
 
+async def _probe_registry(
+    addr: Address,
+    timeout: float = 3,
+    attempt_timeout: float = 1,
+    max_attempts: int = 3,
+    retry_delay: float = .05,
+    close_timeout: float = .2,
+) -> Literal[
+    'absent',
+    'occupied',
+    'registrar',
+]:
+    '''
+    Confirm an address serves the Tractor actor handshake.
+
+    Connection and handshake work share `timeout`; each attempt gets
+    `attempt_timeout`. Shielded cleanup may add up to `close_timeout`
+    per attempted channel.
+
+    '''
+    from .._exceptions import TransportClosed
+
+    connected_once: bool = False
+    with trio.move_on_after(timeout):
+        for attempt in range(max_attempts):
+            try:
+                with trio.move_on_after(attempt_timeout) as attempt_cs:
+                    async with _connect_chan(
+                        addr.unwrap(),
+                        close_timeout=close_timeout,
+                    ) as chan:
+                        connected_once = True
+                        peer_aid: Aid = await chan._do_handshake(
+                            aid=Aid(
+                                name='registry-probe',
+                                uuid=mk_uuid(),
+                                pid=os.getpid(),
+                                is_probe=True,
+                            ),
+                            timeout=attempt_timeout,
+                        )
+                        if peer_aid.is_registrar is not False:
+                            return 'registrar'
+                        return 'occupied'
+
+                if attempt_cs.cancelled_caught:
+                    if not connected_once:
+                        return 'absent'
+
+            except OSError:
+                return (
+                    'occupied'
+                    if connected_once
+                    else 'absent'
+                )
+            except TransportClosed:
+                pass
+
+            if attempt + 1 < max_attempts:
+                await trio.sleep(retry_delay * (attempt + 1))
+
+    return 'occupied'
+
+
+async def _probe_registry_addrs(
+    addrs: list[UnwrappedAddress],
+    timeout: float = 3,
+) -> tuple[
+    list[Address],
+    list[Address],
+]:
+    '''
+    Concurrently classify candidate registrar addresses.
+
+    Return confirmed registrar addresses followed by addresses occupied
+    by non-registrar or unresponsive Tractor peers.
+
+    '''
+    registrar_addrs: list[Address] = []
+    occupied_addrs: list[Address] = []
+
+    async def probe_addr(addr: Address) -> None:
+        probe_status = await _probe_registry(
+            addr=addr,
+            timeout=timeout,
+        )
+        if probe_status == 'registrar':
+            registrar_addrs.append(addr)
+        elif probe_status == 'occupied':
+            occupied_addrs.append(addr)
+        else:
+            # ?TODO, make this a "discovery" log level?
+            log.info(
+                f'No root-actor registry found @ {addr!r}\n'
+            )
+
+    async with trio.open_nursery() as nursery:
+        for unwrapped_addr in addrs:
+            nursery.start_soon(
+                probe_addr,
+                wrap_address(unwrapped_addr),
+            )
+
+    return (
+        registrar_addrs,
+        occupied_addrs,
+    )
+
+
 def _is_local_addr(addr: Address) -> bool:
     '''
     Determine whether `addr` is reachable on the

tractor/discovery/_multiaddr.py

@@ -24,14 +24,23 @@ Multiaddress support using the upstream `py-multiaddr` lib
 - https://github.com/multiformats/multiaddr/blob/master/protocols/unix.md
 
 '''
+from __future__ import annotations
 import ipaddress
 from pathlib import Path
-from typing import TYPE_CHECKING
-
-from multiaddr import Multiaddr
+from typing import (
+    Any,
+    TYPE_CHECKING,
+)
 
 if TYPE_CHECKING:
+    # NOTE, `multiaddr` is lazy-imported at first use
+    # (in the fns below) to keep it off the eager
+    # `import tractor` path (gh #470).
+    from multiaddr import Multiaddr
     from tractor.discovery._addr import Address
+else:
+    Multiaddr = Any
+    Address = Any
 
 # map from tractor-internal `proto_key` identifiers
 # to the standard multiaddr protocol name strings.
@@ -56,6 +65,8 @@ def mk_maddr(
     multiaddr-spec-compliant protocol path.
 
     '''
+    from multiaddr import Multiaddr
+
     proto_key: str = addr.proto_key
     maddr_proto: str|None = _tpt_proto_to_maddr.get(proto_key)
     if maddr_proto is None:
@@ -98,6 +109,7 @@ def parse_maddr(
 
     '''
     # lazy imports to avoid circular deps
+    from multiaddr import Multiaddr
     from tractor.ipc._tcp import TCPAddress
     from tractor.ipc._uds import UDSAddress
 

tractor/ipc/_chan.py

@@ -33,6 +33,7 @@ from typing import (
 )
 import warnings
 
+import msgspec
 import trio
 
 from ._types import (
@@ -495,6 +496,7 @@ class Channel:
     async def _do_handshake(
         self,
         aid: Aid,
+        timeout: float|None = None,
 
     ) -> Aid:
         '''
@@ -505,8 +507,28 @@ class Channel:
         "actor model" parlance.
 
         '''
+        try:
+            with trio.fail_after(
+                timeout if timeout is not None else float('inf')
+            ):
                 await self.send(aid)
                 peer_aid: Aid = await self.recv()
+            if not isinstance(peer_aid, Aid):
+                raise TypeError(
+                    f'Expected {Aid!r}, received {peer_aid!r}'
+                )
+        except (
+            MsgTypeError,
+            msgspec.DecodeError,
+            TypeError,
+            UnicodeDecodeError,
+            trio.TooSlowError,
+        ) as handshake_err:
+            raise TransportClosed(
+                message='Peer sent an invalid actor handshake!\n',
+                src_exc=handshake_err,
+                loglevel='warning',
+            ) from handshake_err
         log.runtime(
             f'Received hanshake with peer\n'
             f'<= {peer_aid.reprol(sin_uuid=False)}\n'
@@ -518,7 +540,8 @@ class Channel:
 
 @acm
 async def _connect_chan(
-    addr: UnwrappedAddress
+    addr: UnwrappedAddress,
+    close_timeout: float|None = None,
 ) -> typing.AsyncGenerator[Channel, None]:
     '''
     Create and connect a `Channel` to the provided `addr`, disconnect
@@ -529,6 +552,18 @@ async def _connect_chan(
 
     '''
     chan = await Channel.from_addr(addr)
+    try:
         yield chan
+    finally:
         with trio.CancelScope(shield=True):
+            if close_timeout is None:
                 await chan.aclose()
+            else:
+                with trio.move_on_after(close_timeout) as close_cs:
+                    await chan.aclose()
+                if close_cs.cancelled_caught:
+                    log.warning(
+                        f'Timed out closing channel after '
+                        f'{close_timeout}s\n'
+                        f'|_{chan}\n'
+                    )

tractor/ipc/_server.py

@@ -62,16 +62,19 @@ from .. import log
 from ..discovery._addr import Address
 from ._chan import Channel
 from ._transport import MsgTransport
-from ._uds import UDSAddress
-from ._tcp import TCPAddress
+
 
 if TYPE_CHECKING:
     from ..runtime._runtime import Actor
     from ..runtime._supervise import ActorNursery
 
 
+from ._tcp import TCPAddress
+from ._uds import UDSAddress
+
 log = log.get_logger()
 
+_PRE_REG_HANDSHAKE_TIMEOUT: float = 10
 
 async def maybe_wait_on_canced_subs(
     uid: tuple[str, str],
@@ -316,8 +319,6 @@ async def handle_stream_from_peer(
       )
 
     '''
-    server._no_more_peers = trio.Event()  # unset by making new
-
     # TODO, debug_mode tooling for when hackin this lower layer?
     # with debug.maybe_open_crash_handler(
     #     pdb=True,
@@ -335,6 +336,7 @@ async def handle_stream_from_peer(
         if actor := _state.current_actor():
             peer_aid: msgtypes.Aid = await chan._do_handshake(
                 aid=actor.aid,
+                timeout=_PRE_REG_HANDSHAKE_TIMEOUT,
             )
     except (
         TransportClosed,
@@ -351,12 +353,9 @@ async def handle_stream_from_peer(
         # "kinda-error" that we expect to tolerate during
         # discovery-sys related pings, queires, DoS etc.
     ):
-        # XXX: This may propagate up from `Channel._aiter_recv()`
-        # and `MsgpackStream._inter_packets()` on a read from the
-        # stream particularly when the runtime is first starting up
-        # inside `open_root_actor()` where there is a check for
-        # a bound listener on the registrar addr.  the reset will be
-        # because the handshake was never meant took place.
+        # `TransportClosed` is expected when a peer disconnects or
+        # fails the initial typed handshake, including foreign clients
+        # and probes racing shutdown.
         log.runtime(
             con_status
             +
@@ -364,6 +363,13 @@ async def handle_stream_from_peer(
         )
         return
 
+    # Registry election probes need only the server's `Aid` capability
+    # response; never register them as ordinary RPC peers.
+    if peer_aid.is_probe:
+        return
+
+    server._no_more_peers = trio.Event()  # unset by making new
+
     uid: tuple[str, str] = (
         peer_aid.name,
         peer_aid.uuid,

tractor/ipc/_tcp.py

@@ -20,7 +20,9 @@ TCP implementation of tractor.ipc._transport.MsgTransport protocol
 from __future__ import annotations
 import ipaddress
 from typing import (
+    Any,
     ClassVar,
+    TYPE_CHECKING,
 )
 # from contextlib import (
 #     asynccontextmanager as acm,
@@ -33,7 +35,6 @@ from trio import (
     open_tcp_listeners,
 )
 
-from multiaddr import Multiaddr
 from tractor.msg import MsgCodec
 from tractor.log import get_logger
 from tractor.discovery._multiaddr import mk_maddr
@@ -42,6 +43,13 @@ from tractor.ipc._transport import (
     MsgpackTransport,
 )
 
+if TYPE_CHECKING:
+    # ONLY type-annots, the eager import costs
+    # `import tractor` wall-time (gh #470).
+    from multiaddr import Multiaddr
+else:
+    Multiaddr = Any
+
 
 log = get_logger()
 

tractor/ipc/_transport.py

@@ -33,6 +33,7 @@ from collections.abc import (
     AsyncGenerator,
     AsyncIterator,
 )
+import errno
 import struct
 
 import trio
@@ -61,6 +62,68 @@ if TYPE_CHECKING:
 log = get_logger()
 
 
+def _peer_closed_errno(exc: BaseException) -> int|None:
+    '''
+    Classify a complete transport exception tree as peer closure.
+
+    Follow explicit cause/context links. For a `BaseExceptionGroup`,
+    require every child branch to resolve to a peer-close errno so an
+    unrelated concurrent failure is never hidden as `TransportClosed`.
+
+    '''
+    def find_peer_errno(
+        current_exc: BaseException,
+        ancestors: set[int],
+    ) -> int|None:
+        exc_id: int = id(current_exc)
+        if exc_id in ancestors:
+            return None
+
+        ancestors = ancestors | {exc_id}
+        if (
+            isinstance(current_exc, OSError)
+            and
+            current_exc.errno in {
+                errno.ECONNRESET,
+                errno.EPIPE,
+            }
+        ):
+            return current_exc.errno
+
+        if isinstance(current_exc, BaseExceptionGroup):
+            child_errnos: list[int|None] = [
+                find_peer_errno(
+                    child_exc,
+                    ancestors,
+                )
+                for child_exc in current_exc.exceptions
+            ]
+            if all(
+                child_errno is not None
+                for child_errno in child_errnos
+            ):
+                return child_errnos[0]
+            return None
+
+        chained_exc: BaseException|None = (
+            current_exc.__cause__
+            or
+            current_exc.__context__
+        )
+        if chained_exc is not None:
+            return find_peer_errno(
+                chained_exc,
+                ancestors,
+            )
+
+        return None
+
+    return find_peer_errno(
+        exc,
+        set(),
+    )
+
+
 # (codec, transport)
 MsgTransportKey = tuple[str, str]
 
@@ -443,23 +506,23 @@ class MsgpackTransport(MsgTransport):
                 trans_err = _re
                 tpt_name: str = f'{type(self).__name__!r}'
 
-                trans_err_msg: str = trans_err.args[0]
+                trans_err_msg: str = (
+                    str(trans_err.args[0])
+                    if trans_err.args
+                    else ''
+                )
                 by_whom: str = {
                     'another task closed this fd': 'locally',
                     'this socket was already closed': 'by peer',
                 }.get(trans_err_msg)
                 match trans_err:
 
-                    # XXX, specifc to UDS transport and its,
-                    # well, "speediness".. XD
-                    # |_ likely todo with races related to how fast
-                    #    the socket is setup/torn-down on linux
-                    #    as it pertains to rando pings from the
-                    #    `.discovery` subsys and protos.
+                    # UDS peers can disconnect before handshake.
+                    # Linux normally reports `EPIPE`; Darwin reports
+                    # `ECONNRESET` for the same expected closure.
                     case trio.BrokenResourceError() if (
-                        '[Errno 32] Broken pipe'
-                        in
-                        trans_err_msg
+                        _peer_closed_errno(trans_err)
+                        is not None
                     ):
                         tpt_closed = TransportClosed.from_src_exc(
                             message=(

tractor/ipc/_types.py

@@ -18,17 +18,13 @@
 IPC subsys type-lookup helpers?
 
 '''
-from typing import (
-    Type,
-    # TYPE_CHECKING,
-)
-
-import trio
+from typing import Type
 import socket
+import trio
 
 from tractor.ipc._transport import (
     MsgTransportKey,
-    MsgTransport
+    MsgTransport,
 )
 from tractor.ipc._tcp import (
     TCPAddress,
@@ -37,37 +33,33 @@ from tractor.ipc._tcp import (
 from tractor.ipc._uds import (
     UDSAddress,
     MsgpackUDSStream,
+    HAS_UDS,
 )
 
-# if TYPE_CHECKING:
-#     from tractor._addr import Address
-
-
+# the UDS backend is importable everywhere but only *usable* when
+# `HAS_UDS` is `True`; otherwise the runtime registers TCP only.
 Address = TCPAddress|UDSAddress
 
-# manually updated list of all supported msg transport types
-_msg_transports = [
+# the available msg-transport backends on this host: TCP always,
+# UDS only where usable (`HAS_UDS`). The lookup maps below derive
+# from this single list via each backend's `codec_key` and
+# `address_type`: register a backend here and every map picks it up.
+_msg_transports: list[Type[MsgTransport]] = [
     MsgpackTCPStream,
-    MsgpackUDSStream
 ]
+if HAS_UDS:
+    _msg_transports.append(MsgpackUDSStream)
 
-
-# convert a MsgTransportKey to the corresponding transport type
-_key_to_transport: dict[
-    MsgTransportKey,
-    Type[MsgTransport],
-] = {
-    ('msgpack', 'tcp'): MsgpackTCPStream,
-    ('msgpack', 'uds'): MsgpackUDSStream,
+# map a `MsgTransportKey` -> `MsgTransport` type
+_key_to_transport: dict[MsgTransportKey, Type[MsgTransport]] = {
+    (t.codec_key, t.address_type.proto_key): t
+    for t in _msg_transports
 }
 
-# convert an Address wrapper to its corresponding transport type
-_addr_to_transport: dict[
-    Type[TCPAddress|UDSAddress],
-    Type[MsgTransport]
-] = {
-    TCPAddress: MsgpackTCPStream,
-    UDSAddress: MsgpackUDSStream,
+# map an `Address`-wrapper -> `MsgTransport` type
+_addr_to_transport: dict[Type[Address], Type[MsgTransport]] = {
+    t.address_type: t
+    for t in _msg_transports
 }
 
 
@@ -81,41 +73,51 @@ def transport_from_addr(
 
     '''
     try:
-        return _addr_to_transport[type(addr)]
+        addr_type = type(addr)
+        return _addr_to_transport[addr_type]
 
     except KeyError:
         raise NotImplementedError(
-            f'No known transport for address {repr(addr)}'
+            f'No known transport for address '
+            f'{addr!r}'
         )
 
 
 def transport_from_stream(
     stream: trio.abc.Stream,
-    codec_key: str = 'msgpack'
+    codec_key: str = 'msgpack',
 ) -> Type[MsgTransport]:
     '''
     Given an arbitrary `trio.abc.Stream` and a desired codec,
     find the corresponding `MsgTransport` type.
 
     '''
-    transport = None
+    transport: str|None = None
+
     if isinstance(stream, trio.SocketStream):
         sock: socket.socket = stream.socket
         match sock.family:
             case socket.AF_INET | socket.AF_INET6:
                 transport = 'tcp'
 
-            case socket.AF_UNIX:
+            # `HAS_UDS` short-circuits before `socket.AF_UNIX` on
+            # hosts where that constant is absent.
+            case fam if (
+                HAS_UDS
+                and
+                fam == socket.AF_UNIX
+            ):
                 transport = 'uds'
 
-            case _:
+            case fam:
                 raise NotImplementedError(
-                    f'Unsupported socket family: {sock.family}'
+                    f'Unsupported socket family: {fam}'
                 )
 
     if not transport:
         raise NotImplementedError(
-            f'Could not figure out transport type for stream type {type(stream)}'
+            f'Could not figure out transport type for stream type '
+            f'{type(stream)}'
         )
 
     key = (codec_key, transport)

tractor/ipc/_uds.py

@@ -21,17 +21,29 @@ from __future__ import annotations
 from contextlib import (
     contextmanager as cm,
 )
+import hashlib
 from pathlib import Path
 import os
 import sys
 from socket import (
-    AF_UNIX,
     SOCK_STREAM,
     SOL_SOCKET,
     error as socket_error,
 )
+# NOTE, `AF_UNIX` is absent on Windows / any CPython built without
+# unix-domain-socket support. Keep this module importable
+# everywhere (so `UDSAddress` stays referenceable for type and
+# `isinstance()` checks plus registry lookups); the `AF_UNIX`-using
+# code paths below are runtime-only and are never reached when the
+# UDS backend is unusable (gated on `trio`'s `has_unix`, see
+# `HAS_UDS`).
+try:
+    from socket import AF_UNIX
+except ImportError:
+    AF_UNIX = None
 import struct
 from typing import (
+    Any,
     Type,
     TYPE_CHECKING,
     ClassVar,
@@ -49,7 +61,6 @@ from trio._highlevel_open_unix_stream import (
     has_unix,
 )
 
-from multiaddr import Multiaddr
 from tractor.msg import MsgCodec
 from tractor.log import get_logger
 from tractor.discovery._multiaddr import mk_maddr
@@ -63,7 +74,13 @@ from tractor.runtime._state import (
 )
 
 if TYPE_CHECKING:
+    # ONLY type-annots, the eager import costs
+    # `import tractor` wall-time (gh #470).
+    from multiaddr import Multiaddr
     from tractor.runtime._runtime import Actor
+else:
+    Multiaddr = Any
+    Actor = Any
 
 
 # Platform-specific credential passing constants
@@ -90,6 +107,22 @@ else:
 
 log = get_logger()
 
+_SUN_PATH_LIMIT: int = (
+    108
+    if sys.platform == 'linux'
+    else 104
+)
+
+
+# single source of truth for whether the UDS backend is usable on this
+# host. Windows can expose `AF_UNIX`, but this backend remains
+# POSIX-only until its credential and lifecycle paths are supported.
+HAS_UDS: bool = (
+    sys.platform != 'win32'
+    and
+    has_unix
+)
+
 
 def unwrap_sockpath(
     sockpath: Path,
@@ -190,7 +223,7 @@ class UDSAddress(
             err_on_no_runtime=False,
         )
         if actor:
-            sockname: str = f'{actor.aid.name}@{pid}'
+            sockname: str = actor.aid.name
             # XXX, orig version which broke both macOS (file-name
             # length) and `multiaddrs` ('::' invalid separator).
             # sockname: str = '::'.join(actor.uid) + f'@{pid}'
@@ -216,15 +249,72 @@ class UDSAddress(
             # `(?P<name>.+)@(?P<pid>\d+)\.sock` regex, and the
             # `spawn._reap` `{name}@{pid}.sock` reconstruction.
             token: str = uuid4().hex[:8]
-            sockname: str = f'{prefix}.{token}@{pid}'
+            sockname = f'{prefix}.{token}'
 
-        sockpath: Path = Path(f'{sockname}.sock')
+        sockpath: Path = cls.get_sockname(
+            name=sockname,
+            pid=pid,
+            bindspace=filedir,
+        )
         return UDSAddress(
             filedir=filedir,
             filename=sockpath,
             maybe_pid=pid,
         )
 
+    @classmethod
+    def get_sockname(
+        cls,
+        name: str,
+        pid: int,
+        bindspace: Path,
+    ) -> Path:
+        '''
+        Build a safe, deterministic UDS socket filename.
+
+        '''
+        suffix: str = f'@{pid}.sock'
+        filename: str = f'{name}{suffix}'
+        unsafe: bool = (
+            '\0' in name
+            or
+            '/' in name
+            or
+            bool(os.altsep and os.altsep in name)
+            or
+            Path(filename).is_absolute()
+        )
+        too_long: bool = (
+            len(os.fsencode(bindspace / filename))
+            >= _SUN_PATH_LIMIT
+        )
+        if (
+            unsafe
+            or
+            too_long
+        ):
+            digest: str = hashlib.blake2s(
+                os.fsencode(name),
+                digest_size=16,
+            ).hexdigest()
+            filename = f'actor.{digest}{suffix}'
+
+        sockpath: Path = bindspace / filename
+        path_nbytes: int = len(os.fsencode(sockpath))
+        if path_nbytes >= _SUN_PATH_LIMIT:
+            raise ValueError(
+                f'UDS bindspace leaves no room for an AF_UNIX '
+                f'socket filename!\n'
+                f'bindspace: {bindspace}\n'
+                f'name was unsafe: {unsafe}\n'
+                f'name was over budget: {too_long}\n'
+                f'compacted filename: {filename}\n'
+                f'encoded path bytes: {path_nbytes}\n'
+                f'AF_UNIX path limit: {_SUN_PATH_LIMIT}\n'
+            )
+
+        return Path(filename)
+
     @classmethod
     def get_root(cls) -> UDSAddress:
         def_uds_filename: Path = 'registry@1616.sock'
@@ -301,7 +391,16 @@ async def start_listener(
             f'>{{\n'
             f'|_{bs!r}\n'
         )
-        bs.mkdir()
+        bs.mkdir(
+            # ensure the full ancestor tree for any nested
+            # (custom `filedir`) bindspace; the default
+            # `get_rt_dir()` space is pre-created but a custom
+            # one may have missing parents.
+            parents=True,
+            # avoid `FileExistsError` from racing actors, same
+            # guard as in `get_rt_dir()`.
+            exist_ok=True,
+        )
 
     with _reraise_as_connerr(
         src_excs=(
@@ -554,11 +653,18 @@ class MsgpackUDSStream(MsgpackTransport):
     ]:
         sock: trio.socket.socket = stream.socket
 
-        # NOTE XXX, it's unclear why one or the other ends up being
-        # `bytes` versus the socket-file-path, i presume it's
-        # something to do with who is the server (called `.listen()`)?
-        # maybe could be better implemented using another info-query
-        # on the socket like,
+        # NOTE, the `bytes` case is a linux-only artifact: setting
+        # `SO_PASSCRED` (see `open_unix_socket_w_passcred()`)
+        # causes the kernel to *autobind* the un-named client
+        # sock to an abstract-namespace addr which python
+        # delivers as `bytes`; the listener-bound end is always
+        # the fs-path `str`. On platforms WITHOUT autobind
+        # (macOS et al) the un-bound end instead reports as an
+        # empty `str` so BOTH names arrive as `str`s and the
+        # real fs-path is whichever is non-empty: `peername` on
+        # the connect side, `sockname` on the accept side.
+        #
+        # for socket-api deats see,
         # https://beej.us/guide/bgnet/html/split-wide/system-calls-or-bust.html#gethostnamewho-am-i
         sockname: str|bytes = sock.getsockname()
         # https://beej.us/guide/bgnet/html/split-wide/system-calls-or-bust.html#getpeernamewho-are-you
@@ -570,8 +676,24 @@ class MsgpackUDSStream(MsgpackTransport):
             case (bytes(), str()):
                 sock_path: Path = Path(sockname)
 
-            case (str(), str()):  # XXX, likely macOS
-                sock_path: Path = Path(peername)
+            # NOTE, no-autobind case (macOS): the un-bound end
+            # is `''`, NOT a `bytes` abstract-ns addr; taking
+            # `peername` unconditionally (as prior impl did)
+            # delivers garbage `Path('')` addrs on the accept
+            # side!
+            case (str(), str()):
+                bound_name: str = (
+                    peername
+                    or
+                    sockname
+                )
+                if not bound_name:
+                    raise ValueError(
+                        f'Empty UDS (peername, sockname) pair ??\n'
+                        f'peername: {peername!r}\n'
+                        f'sockname: {sockname!r}\n'
+                    )
+                sock_path: Path = Path(bound_name)
 
             case _:
                 raise TypeError(

tractor/log.py

@@ -26,11 +26,6 @@ built on `tractor`.
 '''
 from collections.abc import Mapping
 from functools import partial
-from inspect import (
-    FrameInfo,
-    getmodule,
-    stack,
-)
 import sys
 import logging
 from logging import (
@@ -38,10 +33,16 @@ from logging import (
     Logger,
     StreamHandler,
 )
-from types import ModuleType
+from types import (
+    FrameType,
+    ModuleType,
+)
 import warnings
 
-import colorlog  # type: ignore
+# NOTE, `colorlog` is lazy-imported in
+# `get_console_log()` to keep it off the eager
+# `import tractor` path (gh #470).
+#
 # ?TODO, some other (modern) alt libs?
 # import coloredlogs
 # import colored_traceback.auto  # ?TODO, need better config?
@@ -436,17 +437,41 @@ def get_logger(
         pkg_name: str =  _root_name
 
     def get_caller_mod(
-        frames_up:int = 2
-    ):
+        frames_up: int = 2,
+    ) -> ModuleType|None:
         '''
-        Attempt to get the module which called `tractor.get_logger()`.
+        Attempt to get the module which called
+        `tractor.get_logger()`.
+
+        Resolve the caller's frame with `sys._getframe()` and
+        map its `__name__` through `sys.modules`; `inspect.stack()`
+        (the previous impl) builds src-file info for EVERY frame
+        on the stack, scanning all of `sys.modules` per frame via
+        `inspect.getmodule()`, which made module-level
+        `get_logger()` calls dominate `import tractor` time
+        (see gh #470).
 
         '''
-        callstack: list[FrameInfo] = stack()
-        caller_fi: FrameInfo = callstack[frames_up]
-        caller_mod: ModuleType = getmodule(caller_fi.frame)
+        try:
+            caller_frame: FrameType = sys._getframe(frames_up)
+        except ValueError:
+            return None
+
+        mod_name: str|None = caller_frame.f_globals.get(
+            '__name__',
+        )
+        if mod_name is None:
+            return None
+
+        if caller_mod := sys.modules.get(mod_name):
             return caller_mod
 
+        # Preserve caller discovery for `runpy`, plugin loaders,
+        # and `exec()` namespaces not registered in `sys.modules`.
+        # Import `inspect` only on this rare fallback path.
+        from inspect import getmodule
+        return getmodule(caller_frame)
+
     # --- Auto--naming-CASE ---
     # -------------------------
     # Implicitly introspect the caller's module-name whenever `name`
@@ -780,6 +805,10 @@ def get_console_log(
             None,
         )
     ):
+        # lazy-imported to keep it off the eager
+        # `import tractor` path (gh #470).
+        import colorlog  # type: ignore
+
         fmt: str = LOG_FORMAT  # always apply our format?
         handler = StreamHandler()
         formatter = colorlog.ColoredFormatter(

tractor/msg/types.py

@@ -144,6 +144,8 @@ class Aid(
     name: str
     uuid: str
     pid: int|None = None
+    is_registrar: bool|None = None
+    is_probe: bool = False
 
     # TODO? can/should we extend this field set?
     # -[ ] use built-in support for UUIDs? `uuid.UUID` which has

tractor/runtime/_rpc.py

@@ -94,6 +94,33 @@ if TYPE_CHECKING:
 log = get_logger('tractor')
 
 
+def _register_rpc_task(
+    actor: Actor,
+    chan: Channel,
+    func: Callable,
+    is_rpc: bool,
+    task_status: TaskStatus[
+        Context | BaseException
+    ],
+    ctx: Context,
+) -> None:
+    '''
+    Register an RPC task before publishing it to `Nursery.start()`.
+
+    '''
+    if is_rpc:
+        if not actor._rpc_tasks:
+            actor._ongoing_rpc_tasks = trio.Event()
+
+        actor._rpc_tasks[(chan, ctx.cid)] = (
+            ctx,
+            func,
+            trio.Event(),
+        )
+
+    task_status.started(ctx)
+
+
 # ?TODO? move to a `tractor.lowlevel._rpc` with the below
 # func-type-cases implemented "on top of" `@context` defs:
 # -[ ] std async func helper decorated with `@rpc_func`?
@@ -142,7 +169,14 @@ async def _invoke_non_context(
         # is propagated!
         with cancel_scope as cs:
             ctx._scope = cs
-            task_status.started(ctx)
+            _register_rpc_task(
+                actor,
+                chan,
+                func,
+                is_rpc,
+                task_status,
+                ctx,
+            )
             async with aclosing(coro) as agen:
                 async for item in agen:
                     # TODO: can we send values back in here?
@@ -178,7 +212,14 @@ async def _invoke_non_context(
         )
         with cancel_scope as cs:
             ctx._scope = cs
-            task_status.started(ctx)
+            _register_rpc_task(
+                actor,
+                chan,
+                func,
+                is_rpc,
+                task_status,
+                ctx,
+            )
             await coro
 
         if not cs.cancelled_caught:
@@ -202,23 +243,29 @@ async def _invoke_non_context(
             )
             await chan.send(ack)
         except (
+            TransportClosed,
             trio.ClosedResourceError,
             trio.BrokenResourceError,
             BrokenPipeError,
         ) as ipc_err:
             failed_resp = True
-            if is_rpc:
-                raise ipc_err
-            else:
-                log.exception(
+            log.warning(
                 f'Failed to ack runtime RPC request\n\n'
                 f'{func} x=> {ctx.chan}\n\n'
                 f'{ack}\n'
+                f' |_{ipc_err!r}\n'
             )
 
         with cancel_scope as cs:
             ctx._scope: CancelScope = cs
-            task_status.started(ctx)
+            _register_rpc_task(
+                actor,
+                chan,
+                func,
+                is_rpc,
+                task_status,
+                ctx,
+            )
             result = await coro
             fname: str = func.__name__
 
@@ -247,6 +294,7 @@ async def _invoke_non_context(
                     )
                     await chan.send(ret_msg)
                 except (
+                    TransportClosed,
                     BrokenPipeError,
                     trio.BrokenResourceError,
                 ):
@@ -673,7 +721,14 @@ async def _invoke(
             ):
                 ctx._scope_nursery = tn
                 rpc_ctx_cs = ctx._scope = tn.cancel_scope
-                task_status.started(ctx)
+                _register_rpc_task(
+                    actor,
+                    chan,
+                    func,
+                    is_rpc,
+                    task_status,
+                    ctx,
+                )
 
                 # invoke user endpoint fn.
                 res: Any|PayloadT = await coro
@@ -920,6 +975,7 @@ async def try_ship_error_to_remote(
         # downward should be mostly wrapping such cases in a
         # tpt-closed; the `.critical()` usage is warranted.
         except (
+            TransportClosed,
             trio.ClosedResourceError,
             trio.BrokenResourceError,
             BrokenPipeError,
@@ -1221,18 +1277,6 @@ async def process_messages(
                             )
                             continue
 
-                        else:
-                            # mark our global state with ongoing rpc tasks
-                            actor._ongoing_rpc_tasks = trio.Event()
-
-                            # store cancel scope such that the rpc task can be
-                            # cancelled gracefully if requested
-                            actor._rpc_tasks[(chan, cid)] = (
-                                ctx,
-                                func,
-                                trio.Event(),
-                            )
-
                     # XXX RUNTIME-SCOPED! remote (likely internal) error
                     # (^- bc no `Error.cid` -^)
                     #

tractor/runtime/_runtime.py

@@ -259,6 +259,7 @@ class Actor:
             name=name,
             uuid=uuid,
             pid=os.getpid(),
+            is_registrar=self.is_registrar,
         )
         self._task: trio.Task|None = None
 

tractor/runtime/_state.py

@@ -22,7 +22,10 @@ from __future__ import annotations
 from contextvars import (
     ContextVar,
 )
+import os
 from pathlib import Path
+import stat
+import sys
 from typing import (
     Any,
     Callable,
@@ -30,7 +33,6 @@ from typing import (
     TYPE_CHECKING,
 )
 
-import platformdirs
 from trio.lowlevel import current_task
 
 from msgspec import (
@@ -43,6 +45,9 @@ if TYPE_CHECKING:
     from .._context import Context
 
 
+_DARWIN_TMPDIR: Path = Path('/tmp')
+
+
 # default IPC transport protocol settings
 TransportProtocolKey = Literal[
     'tcp',
@@ -318,6 +323,60 @@ def current_ipc_ctx(
 
 
 
+def _ensure_owner_only_posix_dir(
+    path: Path,
+    *,
+    parents: bool = False,
+) -> None:
+    '''
+    Create or validate a UID-owned POSIX runtime directory.
+
+    Pre-existing directories are accepted only when owned by the
+    current user. Their mode is normalized to `0o700` because runtime
+    directories hold IPC sockets and are private bindspaces.
+
+    '''
+    # TODO: https://github.com/goodboy/tractor/issues/494
+    # Research having the actor-tree root process choose and create
+    # this bindspace, then propagate it to every subactor. On
+    # Linux, a private mount namespace could isolate it while letting
+    # spawned subactors inherit access; independently launched
+    # discovery clients would need an explicit join or fallback path.
+    # POSIX metadata alone records UID/GID ownership, so other systems
+    # still need explicit runtime metadata and lifecycle management.
+    try:
+        dir_stat: os.stat_result = path.lstat()
+    except FileNotFoundError:
+        try:
+            path.mkdir(
+                mode=0o700,
+                parents=parents,
+            )
+        except FileExistsError:
+            pass
+        dir_stat = path.lstat()
+
+    if (
+        not stat.S_ISDIR(dir_stat.st_mode)
+        or
+        dir_stat.st_uid != os.getuid()
+    ):
+        platform_name: str = (
+            'Darwin'
+            if sys.platform == 'darwin'
+            else 'POSIX'
+        )
+        raise PermissionError(
+            f'Unsafe {platform_name} runtime directory!\n'
+            f'path: {path}\n'
+            f'owner uid: {dir_stat.st_uid}\n'
+            f'mode: {stat.filemode(dir_stat.st_mode)}\n'
+        )
+
+    if stat.S_IMODE(dir_stat.st_mode) != 0o700:
+        path.chmod(0o700)
+
+
 def get_rt_dir(
     subdir: str|Path|None = None,
     appname: str = 'tractor',
@@ -327,12 +386,26 @@ def get_rt_dir(
     userspace apps stick their IPC and cache related system
     util-files.
 
-    On linux we use a `${XDG_RUNTIME_DIR}/tractor/` subdir by
-    default, but equivalents are mapped for each platform using
-    the lovely `platformdirs` lib.
+    Linux uses an owner-only `${XDG_RUNTIME_DIR}/tractor/`; Darwin
+    uses a short, owner-only `/tmp/tractor-<uid>` path; other
+    platforms use the lovely `platformdirs` lib.
 
     '''
-    rt_dir: Path = Path(
+    # lazy-imported to keep it off the eager
+    # `import tractor` path (gh #470).
+    import platformdirs
+
+    rt_root: Path|None = None
+    if sys.platform == 'darwin':
+        # Darwin's AF_UNIX path limit is 104 bytes. The standard
+        # platformdirs path can consume that before the sock name.
+        rt_root = (
+            _DARWIN_TMPDIR
+            / f'{appname}-{os.getuid()}'
+        )
+        rt_dir: Path = rt_root
+    else:
+        rt_dir = Path(
             platformdirs.user_runtime_dir(
                 appname=appname,
             ),
@@ -341,6 +414,7 @@ def get_rt_dir(
     # Normalize and validate that `subdir` is a relative path
     # without any parent-directory ("..") components, to prevent
     # escaping the runtime directory.
+    subdir_path: Path|None = None
     if subdir:
         subdir_path = (
             subdir
@@ -358,13 +432,28 @@ def get_rt_dir(
                 f'{subdir!r}\n'
             )
 
-        rt_dir: Path = rt_dir / subdir_path
-
+    if os.name != 'posix':
+        if subdir_path is not None:
+            rt_dir = rt_dir / subdir_path
         if not rt_dir.is_dir():
             rt_dir.mkdir(
+                # Runtime dirs hold IPC sockets; owner-only access
+                # prevents other users from traversing the bindspace.
+                mode=0o700,
                 parents=True,
-            exist_ok=True,  # avoid `FileExistsError` from conc calls
+                exist_ok=True,
             )
+        return rt_dir
+
+    _ensure_owner_only_posix_dir(
+        rt_dir,
+        parents=(rt_root is None),
+    )
+
+    if subdir_path is not None:
+        for part in subdir_path.parts:
+            rt_dir = rt_dir / part
+            _ensure_owner_only_posix_dir(rt_dir)
 
     return rt_dir
 

tractor/spawn/_entry.py

@@ -38,7 +38,11 @@ from ..devx import (
     pformat,
 )
 # from ..msg import pretty_struct
-from ..to_asyncio import run_as_asyncio_guest
+#
+# NOTE, `.to_asyncio` (and thus `asyncio` itself) is
+# lazy-imported at the `infect_asyncio=True` use-sites
+# below to keep it off the eager `import tractor` path
+# (gh #470).
 from ..discovery._addr import UnwrappedAddress
 from ..runtime._runtime import (
     async_main,
@@ -96,6 +100,7 @@ def _mp_main(
     )
     try:
         if infect_asyncio:
+            from ..to_asyncio import run_as_asyncio_guest
             actor._infected_aio = True
             run_as_asyncio_guest(trio_main)
         else:
@@ -156,6 +161,7 @@ def _trio_main(
     )
     try:
         if infect_asyncio:
+            from ..to_asyncio import run_as_asyncio_guest
             actor._infected_aio = True
             run_as_asyncio_guest(trio_main)
         else:

tractor/spawn/_reap.py

@@ -35,14 +35,14 @@ Future-work TODO — authoritative UDS bind-addr tracking
 `unlink_uds_bind_addrs()` currently has two cleanup paths:
 
 1. Explicit `bind_addrs` (when parent set them at spawn time)
-2. **Convention-based reconstruction** —
-   `<XDG_RUNTIME_DIR>/tractor/<name>@<pid>.sock` — for the
+2. **Convention-based reconstruction** in the platform default UDS
+   bindspace — for the
    common case where the subactor self-assigned a random sock
    via `UDSAddress.get_random()`.
 
-Path (2) hardcodes the `<name>@<pid>.sock` convention from
-`tractor.ipc._uds.UDSAddress`. If that convention ever
-changes — or the subactor binds to a non-default
+Path (2) delegates filename reconstruction to
+`tractor.ipc._uds.UDSAddress.get_sockname()`. If the subactor binds to
+a non-default
 `bindspace`/`filedir` — we'll silently fail to unlink.
 
 A more authoritative approach would be:
@@ -71,6 +71,7 @@ fd leak. Different bug class but same broader theme of
 from __future__ import annotations
 
 import os
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 import trio
@@ -104,7 +105,7 @@ def unlink_uds_bind_addrs(
     `_serve_ipc_eps` `finally:` block (which normally calls
     `os.unlink(addr.sockpath)`) never runs. Without this
     parent-side cleanup, the dead subactor's
-    `${XDG_RUNTIME_DIR}/tractor/<name>@<pid>.sock` file
+    platform-default UDS socket file
     accumulates on the filesystem (see issue #454 + the
     autouse `_track_orphaned_uds_per_test` fixture).
 
@@ -118,7 +119,7 @@ def unlink_uds_bind_addrs(
        picked its own random sock via
        `UDSAddress.get_random()`), reconstruct the path
        from `(subactor.aid.name, proc.pid)` using the
-       same `<name>@<pid>.sock` convention. We can do this
+       same `UDSAddress.get_sockname()` helper. We can do this
        because the subactor uses its OWN `os.getpid()` at
        bind time, which equals `proc.pid` from the
        parent's view.
@@ -154,7 +155,21 @@ def unlink_uds_bind_addrs(
         and subactor is not None
         and proc.pid is not None
     ):
-        sockname: str = f'{subactor.aid.name}@{proc.pid}.sock'
+        try:
+            sockname: Path = UDSAddress.get_sockname(
+                name=subactor.aid.name,
+                pid=proc.pid,
+                bindspace=UDSAddress.def_bindspace,
+            )
+        except Exception:
+            log.exception(
+                f'Failed to reconstruct UDS sock-file for '
+                f'post-kill cleanup — skipping\n'
+                f' |_{proc}\n'
+                f' |_{subactor.aid}\n'
+            )
+            return
+
         sockpath: str = str(
             UDSAddress.def_bindspace / sockname
         )