Add prompt-io log for GH #473 UDS-on-macOS work

Provenance entry (+ unedited raw output) for the root-cause
session behind the prior three patches, per the NLNet
generative-AI policy tracked under `ai/prompt-io/`.

(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

@@ -118,11 +118,6 @@ 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
-            tpt_proto: 'uds'
 
     steps:
       - uses: actions/checkout@v4

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).

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'

tests/test_docs_examples.py

@@ -145,21 +145,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,10 +163,11 @@ def test_example(
         code = ex.read()
 
         with run_example_in_subproc(code) as proc:
+            out = None
             err = None
             try:
                 if not proc.poll():
-                    _, err = proc.communicate(timeout=timeout)
+                    out, err = proc.communicate(timeout=timeout)
 
             except subprocess.TimeoutExpired as e:
                 test_log.exception(
@@ -190,9 +176,34 @@ def test_example(
                 proc.kill()
                 err = e.stderr
 
+            errmsg: str = err.decode() if err else ''
+
+            # XXX, ALWAYS surface the subproc's full stderr
+            # whenever it exits non-zero!
+            #
+            # 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() if out else ''
+                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 err:
-                errmsg = err.decode()
+            if errmsg:
                 errlines = errmsg.splitlines()
                 last_error = errlines[-1]
                 if (

tractor/ipc/_uds.py

@@ -301,7 +301,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 +563,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 +586,24 @@ class MsgpackUDSStream(MsgpackTransport):
             case (bytes(), str()):
                 sock_path: Path = Path(sockname)
 
-            case (str(), str()):  # XXX, likely macOS
-                sock_path: Path = Path(peername)
+            # XXX, 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(