Ignore deployed `ai.skillz/` state

Record generated ignore blocks for deployed skills, commands, and runtime artifacts so direct symlink deployments remain status-clean. (this commit msg was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))
Correct `run-tests` harness guidance
2026-08-27 13:44:00 -04:00 · 2026-08-27 13:44:00 -04:00 · 2026-08-27 13:44:00 -04:00 · 2026-08-26 22:48:32 -04:00 · 2026-08-26 18:27:11 -04:00 · 2026-08-26 17:00:54 -04:00
167 changed files with 9929 additions and 2501 deletions
--- a/.claude/skills/run-tests/SKILL.md
+++ b/.claude/skills/run-tests/SKILL.md
@ -1,632 +0,0 @@
 ---
 name: run-tests
 description: >
  Run tractor test suite (or subsets). Use when the user wants
  to run tests, verify changes, or check for regressions.
 argument-hint: "[test-path-or-pattern] [--opts]"
 allowed-tools:
  - Bash(python -m pytest *)
  - Bash(python -c *)
  - Bash(python --version *)
  - Bash(UV_PROJECT_ENVIRONMENT=py* uv run python *)
  - Bash(UV_PROJECT_ENVIRONMENT=py* uv run pytest *)
  - Bash(UV_PROJECT_ENVIRONMENT=py* uv sync *)
  - Bash(UV_PROJECT_ENVIRONMENT=py* uv pip show *)
  - Bash(git rev-parse *)
  - Bash(ls *)
  - Bash(cat *)
  - Bash(jq * .pytest_cache/*)
  # process inspection + SIGINT-first cleanup ladder (see
  # the zombie-actor pre-flight / teardown steps below).
  - Bash(ss *)
  - Bash(pgrep *)
  - Bash(pkill *)
  - Bash(sleep *)
  - Bash(rm -f /tmp/registry@*.sock)
  - Read
  - Grep
  - Glob
  - Task
  - AskUserQuestion
 ---
 Run the `tractor` test suite using `pytest`. Follow this
 process:
 ## 1. Parse user intent
 From the user's message and any arguments, determine:
 - **scope**: full suite, specific file(s), specific
  test(s), or a keyword pattern (`-k`).
 - **transport**: which IPC transport protocol to test
  against (default: `tcp`, also: `uds`).
 - **options**: any extra pytest flags the user wants
  (e.g. `--ll debug`, `--tpdb`, `-x`, `-v`).
 If the user provides a bare path or pattern as argument,
 treat it as the test target. Examples:
 - `/run-tests` → full suite
 - `/run-tests test_local.py` → single file
 - `/run-tests test_registrar -v` → file + verbose
 - `/run-tests -k cancel` → keyword filter
 - `/run-tests tests/ipc/ --tpt-proto uds` → subdir + UDS
 ## 2. Construct the pytest command
 Base command:
 ```
 python -m pytest
 ```
 ### Default flags (always include unless user overrides):
 - `-x` (stop on first failure)
 - `--tb=short` (concise tracebacks)
 - `--no-header` (reduce noise)
 ### Path resolution:
 - If the user gives a bare filename like `test_local.py`,
  resolve it under `tests/`.
 - If the user gives a subdirectory like `ipc/`, resolve
  under `tests/ipc/`.
 - Glob if needed: `tests/**/test_*<pattern>*.py`
 ### Key pytest options for this project:
 | Flag | Purpose |
 |---|---|
 | `--ll <level>` | Set tractor log level (e.g. `debug`, `info`, `runtime`) |
 | `--tpdb` / `--debug-mode` | Enable tractor's multi-proc debugger |
 | `--tpt-proto <key>` | IPC transport: `tcp` (default) or `uds` |
 | `--spawn-backend <be>` | Spawn method: `trio` (default), `mp_spawn`, `mp_forkserver` |
 | `-k <expr>` | pytest keyword filter |
 | `-v` / `-vv` | Verbosity |
 | `-s` | No output capture (useful with `--tpdb`) |
 ### Common combos:
 ```sh
 # quick smoke test of core modules
 python -m pytest tests/test_local.py tests/test_rpc.py -x --tb=short --no-header
 # full suite, stop on first failure
 python -m pytest tests/ -x --tb=short --no-header
 # specific test with debug
 python -m pytest tests/discovery/test_registrar.py::test_reg_then_unreg -x -s --tpdb --ll debug
 # run with UDS transport
 python -m pytest tests/ -x --tb=short --no-header --tpt-proto uds
 # keyword filter
 python -m pytest tests/ -x --tb=short --no-header -k "cancel and not slow"
 ```
 ## 3. Pre-flight: venv detection (MANDATORY)
 **Always verify a `uv` venv is active before running
 `python` or `pytest`.** This project uses
 `UV_PROJECT_ENVIRONMENT=py<MINOR>` naming (e.g.
 `py313`) — never `.venv`.
 ### Step 1: detect active venv
 Run this check first:
 ```sh
 python -c "
 import sys, os
 venv = os.environ.get('VIRTUAL_ENV', '')
 prefix = sys.prefix
 print(f'VIRTUAL_ENV={venv}')
 print(f'sys.prefix={prefix}')
 print(f'executable={sys.executable}')
 "
 ```
 ### Step 2: interpret results
 **Case A — venv is active** (`VIRTUAL_ENV` is set
 and points to a `py<MINOR>/` dir under the project
 root or worktree):
 Use bare `python` / `python -m pytest` for all
 commands. This is the normal, fast path.
 **Case B — no venv active** (`VIRTUAL_ENV` is empty
 or `sys.prefix` points to a system Python):
 Use `AskUserQuestion` to ask the user:
 > "No uv venv is active. Should I activate one
 > via `UV_PROJECT_ENVIRONMENT=py<MINOR> uv sync`,
 > or would you prefer to activate your shell venv
 > first?"
 Options:
 1. **"Create/sync venv"** — run
   `UV_PROJECT_ENVIRONMENT=py<MINOR> uv sync` where
   `<MINOR>` is detected from `python --version`
   (e.g. `313` for 3.13). Then use
   `py<MINOR>/bin/python` for all subsequent
   commands in this session.
 2. **"I'll activate it myself"** — stop and let the
   user `source py<MINOR>/bin/activate` or similar.
 **Case C — inside a git worktree** (`git rev-parse
 --git-common-dir` differs from `--git-dir`):
 Verify Python resolves from the **worktree's own
 venv**, not the main repo's:
 ```sh
 python -c "import tractor; print(tractor.__file__)"
 ```
 If the path points outside the worktree, create a
 worktree-local venv:
 ```sh
 UV_PROJECT_ENVIRONMENT=py<MINOR> uv sync
 ```
 Then use `py<MINOR>/bin/python` for all commands.
 **Why this matters**: without the correct venv,
 subprocesses spawned by tractor resolve modules
 from the wrong editable install, causing spurious
 `AttributeError` / `ModuleNotFoundError`.
 ### Fallback: `uv run`
 If the user can't or won't activate a venv, all
 `python` and `pytest` commands can be prefixed
 with `UV_PROJECT_ENVIRONMENT=py<MINOR> uv run`:
 ```sh
 # instead of: python -m pytest tests/ -x
 UV_PROJECT_ENVIRONMENT=py313 uv run pytest tests/ -x
 # instead of: python -c 'import tractor'
 UV_PROJECT_ENVIRONMENT=py313 uv run python -c 'import tractor'
 ```
 `uv run` auto-discovers the project and venv,
 but is slower than a pre-activated venv due to
 lock-file resolution on each invocation. Prefer
 activating the venv when possible.
 ### Step 3: import + collection checks
 After venv is confirmed, always run these
 (especially after refactors or module moves):
 ```sh
 # 1. package import smoke check
 python -c 'import tractor; print(tractor)'
 # 2. verify all tests collect (no import errors)
 python -m pytest tests/ -x -q --co 2>&1 | tail -5
 ```
 If either fails, fix the import error before running
 any actual tests.
 ### Step 4: zombie-actor / stale-registry check (MANDATORY)
 The tractor runtime's default registry address is
 **`127.0.0.1:1616`** (TCP) / `/tmp/registry@1616.sock`
 (UDS). Whenever any prior test run — especially one
 using a fork-based backend like `subint_forkserver` —
 leaks a child actor process, that zombie keeps the
 registry port bound and **every subsequent test
 session fails to bind**, often presenting as 50+
 unrelated failures ("all tests broken"!) across
 backends.
 **This has to be checked before the first run AND
 after any cancelled/SIGINT'd run** — signal failures
 in the middle of a test can leave orphan children.
 ```sh
 # 1. TCP registry — any listener on :1616? (primary signal)
 ss -tlnp 2>/dev/null | grep ':1616' || echo 'TCP :1616 free'
 # 2. leftover actor/forkserver procs — scoped to THIS
 #    repo's python path, so we don't false-flag legit
 #    long-running tractor-using apps (e.g. `piker`,
 #    downstream projects that embed tractor).
 pgrep -af "$(pwd)/py[0-9]*/bin/python.*_actor_child_main|subint-forkserv" \
  | grep -v 'grep\|pgrep' \
  || echo 'no leaked actor procs from this repo'
 # 3. stale UDS registry sockets
 ls -la /tmp/registry@*.sock 2>/dev/null \
  || echo 'no leaked UDS registry sockets'
 ```
 **Interpretation:**
 - **TCP :1616 free AND no stale sockets** → clean,
  proceed. The actor-procs probe is secondary — false
  positives are common (piker, any other tractor-
  embedding app); only cleanup if `:1616` is bound or
  sockets linger.
 - **TCP :1616 bound OR stale sockets present** →
  surface PIDs + cmdlines to the user, offer cleanup:
  ```sh
  # 1. GRACEFUL FIRST (tractor is structured concurrent — it
  #    catches SIGINT as an OS-cancel in `_trio_main` and
  #    cascades Portal.cancel_actor via IPC to every descendant.
  #    So always try SIGINT first with a bounded timeout; only
  #    escalate to SIGKILL if graceful cleanup doesn't complete).
  pkill -INT -f "$(pwd)/py[0-9]*/bin/python.*_actor_child_main|subint-forkserv"
  # 2. bounded wait for graceful teardown (usually sub-second).
  #    Loop until the processes exit, or timeout. Keep the
  #    bound tight — hung/abrupt-killed descendants usually
  #    hang forever, so don't wait more than a few seconds.
  for i in $(seq 1 10); do
    pgrep -f "$(pwd)/py[0-9]*/bin/python.*_actor_child_main|subint-forkserv" >/dev/null || break
    sleep 0.3
  done
  # 3. ESCALATE TO SIGKILL only if graceful didn't finish.
  if pgrep -f "$(pwd)/py[0-9]*/bin/python.*_actor_child_main|subint-forkserv" >/dev/null; then
    echo 'graceful teardown timed out — escalating to SIGKILL'
    pkill -9 -f "$(pwd)/py[0-9]*/bin/python.*_actor_child_main|subint-forkserv"
  fi
  # 4. if a test zombie holds :1616 specifically and doesn't
  #    match the above pattern, find its PID the hard way:
  ss -tlnp 2>/dev/null | grep ':1616'   # prints `users:(("<name>",pid=NNNN,...))`
  # then (same SIGINT-first ladder):
  # kill -INT <NNNN>; sleep 1; kill -9 <NNNN> 2>/dev/null
  # 5. remove stale UDS sockets
  rm -f /tmp/registry@*.sock
  # 6. re-verify
  ss -tlnp 2>/dev/null | grep ':1616' || echo 'TCP :1616 now free'
  ```
 **Never ignore stale registry state.** If you see the
 "all tests failing" pattern — especially
 `trio.TooSlowError` / connection refused / address in
 use on many unrelated tests — check registry **before**
 spelunking into test code. The failure signature will
 be identical across backends because they're all
 fighting for the same port.
 **False-positive warning for step 2:** a plain
 `pgrep -af '_actor_child_main'` will also match
 legit long-running tractor-embedding apps (e.g.
 `piker` at `~/repos/piker/py*/bin/python3 -m
 tractor._child ...`). Always scope to the current
 repo's python path, or only use step 1 (`:1616`) as
 the authoritative signal.
 ## 4. Run and report
 - Run the constructed command.
 - Use a timeout of **600000ms** (10min) for full suite
  runs, **120000ms** (2min) for single-file runs.
 - If the suite is large (full `tests/`), consider running
  in the background and checking output when done.
 - Use `--lf` (last-failed) to re-run only previously
  failing tests when iterating on a fix.
 ### On failure:
 - Show the failing test name(s) and short traceback.
 - If the failure looks related to recent changes, point
  out the likely cause and suggest a fix.
 - **Check the known-flaky list** (section 8) before
  investigating — don't waste time on pre-existing
  timeout issues.
 - **NEVER auto-commit fixes.** If you apply a code fix
  during test iteration, leave it unstaged. Tell the
  user what changed and suggest they review the
  worktree state, stage files manually, and use
  `/commit-msg` (inline or in a separate session) to
  generate the commit message. The human drives all
  `git add` and `git commit` operations.
 ### On success:
 - Report the pass/fail/skip counts concisely.
 ## 5. Test directory layout (reference)
 ```
 tests/
 ├── conftest.py          # root fixtures, daemon, signals
 ├── devx/                # debugger/tooling tests
 ├── ipc/                 # transport protocol tests
 ├── msg/                 # messaging layer tests
 ├── discovery/           # discovery subsystem tests
 │   ├── test_multiaddr.py  # multiaddr construction
 │   └── test_registrar.py  # registry/discovery protocol
 ├── test_local.py        # registrar + local actor basics
 ├── test_rpc.py          # RPC error handling
 ├── test_spawning.py     # subprocess spawning
 ├── test_multi_program.py  # multi-process tree tests
 ├── test_cancellation.py # cancellation semantics
 ├── test_context_stream_semantics.py  # ctx streaming
 ├── test_inter_peer_cancellation.py   # peer cancel
 ├── test_infected_asyncio.py  # trio-in-asyncio
 └── ...
 ```
 ## 6. Change-type → test mapping
 After modifying specific modules, run the corresponding
 test subset first for fast feedback:
 | Changed module(s) | Run these tests first |
 |---|---|
 | `runtime/_runtime.py`, `runtime/_state.py` | `test_local.py test_rpc.py test_spawning.py test_root_runtime.py` |
 | `discovery/` (`_registry`, `_discovery`, `_addr`) | `tests/discovery/ test_multi_program.py test_local.py` |
 | `_context.py`, `_streaming.py` | `test_context_stream_semantics.py test_advanced_streaming.py` |
 | `ipc/` (`_chan`, `_server`, `_transport`) | `tests/ipc/ test_2way.py` |
 | `runtime/_portal.py`, `runtime/_rpc.py` | `test_rpc.py test_cancellation.py` |
 | `spawn/` (`_spawn`, `_entry`) | `test_spawning.py test_multi_program.py` |
 | `devx/debug/` | `tests/devx/test_debugger.py` (slow!) |
 | `to_asyncio.py` | `test_infected_asyncio.py test_root_infect_asyncio.py` |
 | `msg/` | `tests/msg/` |
 | `_exceptions.py` | `test_remote_exc_relay.py test_inter_peer_cancellation.py` |
 | `runtime/_supervise.py` | `test_cancellation.py test_spawning.py` |
 ## 7. Quick-check shortcuts
 ### After refactors (fastest first-pass):
 ```sh
 # import + collect check
 python -c 'import tractor' && python -m pytest tests/ -x -q --co 2>&1 | tail -3
 # core subset (~10s)
 python -m pytest tests/test_local.py tests/test_rpc.py tests/test_spawning.py tests/discovery/test_registrar.py -x --tb=short --no-header
 ```
 ### Inspect last failures (without re-running):
 When the user asks "what failed?", "show failures",
 or wants to check the last-failed set before
 re-running — read the pytest cache directly. This
 is instant and avoids test collection overhead.
 ```sh
 python -c "
 import json, pathlib, sys
 p = pathlib.Path('.pytest_cache/v/cache/lastfailed')
 if not p.exists():
    print('No lastfailed cache found.'); sys.exit()
 data = json.loads(p.read_text())
 # filter to real test node IDs (ignore junk
 # entries that can accumulate from system paths)
 tests = sorted(k for k in data if k.startswith('tests/'))
 if not tests:
    print('No failures recorded.')
 else:
    print(f'{len(tests)} last-failed test(s):')
    for t in tests:
        print(f'  {t}')
 "
 ```
 **Why not `--cache-show` or `--co --lf`?**
 - `pytest --cache-show 'cache/lastfailed'` works
  but dumps raw dict repr including junk entries
  (stale system paths that leak into the cache).
 - `pytest --co --lf` actually *collects* tests which
  triggers import resolution and is slow (~0.5s+).
  Worse, when cached node IDs don't exactly match
  current parametrize IDs (e.g. param names changed
  between runs), pytest falls back to collecting
  the *entire file*, giving false positives.
 - Reading the JSON directly is instant, filterable
  to `tests/`-prefixed entries, and shows exactly
  what pytest recorded — no interpretation.
 **After inspecting**, re-run the failures:
 ```sh
 python -m pytest --lf -x --tb=short --no-header
 ```
 ### Full suite in background:
 When core tests pass and you want full coverage while
 continuing other work, run in background:
 ```sh
 python -m pytest tests/ -x --tb=short --no-header -q
 ```
 (use `run_in_background=true` on the Bash tool)
 ## 8. Known flaky tests
 These tests have **pre-existing** timing/environment
 sensitivity. If they fail with `TooSlowError` or
 pexpect `TIMEOUT`, they are almost certainly NOT caused
 by your changes — note them and move on.
 | Test | Typical error | Notes |
 |---|---|---|
 | `devx/test_debugger.py::test_multi_nested_subactors_error_through_nurseries` | pexpect TIMEOUT | Debugger pexpect timing |
 | `test_cancellation.py::test_cancel_via_SIGINT_other_task` | TooSlowError | Signal handling race |
 | `test_inter_peer_cancellation.py::test_peer_spawns_and_cancels_service_subactor` | TooSlowError | Async timing (both param variants) |
 | `test_docs_examples.py::test_example[we_are_processes.py]` | `assert None == 0` | `__main__` missing `__file__` in subproc |
 **Rule of thumb**: if a test fails with `TooSlowError`,
 `trio.TooSlowError`, or `pexpect.TIMEOUT` and you didn't
 touch the relevant code path, it's flaky — skip it.
 ## 9. The pytest-capture hang pattern (CHECK THIS FIRST)
 **Symptom:** a tractor test hangs indefinitely under
 default `pytest` but passes instantly when you add
 `-s` (`--capture=no`).
 **Cause:** tractor subactors (especially under fork-
 based backends) inherit pytest's stdout/stderr
 capture pipes via fds 1,2. Under high-volume error
 logging (e.g. multi-level cancel cascade, nested
 `run_in_actor` failures, anything triggering
 `RemoteActorError` + `ExceptionGroup` traceback
 spew), the **64KB Linux pipe buffer fills** faster
 than pytest drains it. Subactor writes block → can't
 finish exit → parent's `waitpid`/pidfd wait blocks →
 deadlock cascades up the tree.
 **Pre-existing guards in the tractor harness** that
 encode this same knowledge — grep these FIRST
 before spelunking:
 - `tests/conftest.py:258-260` (in the `daemon`
  fixture): `# XXX: too much logging will lock up
  the subproc (smh)` — downgrades `trace`/`debug`
  loglevel to `info` to prevent the hang.
 - `tests/conftest.py:316`: `# can lock up on the
  _io.BufferedReader and hang..` — noted on the
  `proc.stderr.read()` post-SIGINT.
 **Debug recipe (in priority order):**
 1. **Try `-s` first.** If the hang disappears with
   `pytest -s`, you've confirmed it's capture-pipe
   fill. Skip spelunking.
 2. **Lower the loglevel.** Default `--ll=error` on
   this project; if you've bumped it to `debug` /
   `info`, try dropping back. Each log level
   multiplies pipe-pressure under fault cascades.
 3. **If you MUST use default capture + high log
   volume**, redirect subactor stdout/stderr in the
   child prelude (e.g.
   `tractor.spawn._subint_forkserver._child_target`
   post-`_close_inherited_fds`) to `/dev/null` or a
   file.
 **Signature tells you it's THIS bug (vs. a real
 code hang):**
 - Multi-actor test under fork-based backend
  (`subint_forkserver`, eventually `trio_proc` too
  under enough log volume).
 - Multiple `RemoteActorError` / `ExceptionGroup`
  tracebacks in the error path.
 - Test passes with `-s` in the 5-10s range, hangs
  past pytest-timeout (usually 30+ s) without `-s`.
 - Subactor processes visible via `pgrep -af
  subint-forkserv` or similar after the hang —
  they're alive but blocked on `write()` to an
  inherited stdout fd.
 **Historical reference:** this deadlock cost a
 multi-session investigation (4 genuine cascade
 fixes landed along the way) that only surfaced the
 capture-pipe issue AFTER the deeper fixes let the
 tree actually tear down enough to produce pipe-
 filling log volume. Full post-mortem in
 `ai/conc-anal/subint_forkserver_test_cancellation_leak_issue.md`.
 Lesson codified here so future-me grep-finds the
 workaround before digging.
 ## 10. Reaping zombie subactors (`tractor-reap`)
 **Symptom:** after a `pytest` run crashes, times out,
 or is `Ctrl+C`'d, subactor forks (esp. under
 `subint_forkserver`) can be reparented to `init`
 (PPid==1) and linger. They hold onto ports, inherit
 pytest's capture-pipe fds, and flakify later
 sessions.
 **Two layers of defense:**
 ### a) Session-scoped auto-fixture (always on)
 `tractor/_testing/pytest.py::_reap_orphaned_subactors`
 runs at pytest session teardown. It walks `/proc` for
 direct descendants of the pytest pid, SIGINTs them,
 waits up to 3s, then SIGKILLs survivors. SC-polite:
 gives the subactor runtime a chance to run its trio
 cancel shield + IPC teardown before escalation.
 This is *autouse* and session-scoped — you don't need
 to do anything. It just runs.
 ### b) `scripts/tractor-reap` CLI (manual reap)
 For the **pytest-died-mid-session** case (Ctrl+C, OOM
 kill, hung process you had to `kill -9`), the fixture
 never ran. Reach for the CLI:
 ```sh
 # default: orphans (PPid==1, cwd==repo, cmd contains python)
 scripts/tractor-reap
 # descendant-mode: from a still-live supervisor
 scripts/tractor-reap --parent <pytest-pid>
 # see what would be reaped, don't signal
 scripts/tractor-reap -n
 # tune the SIGINT → SIGKILL grace window
 scripts/tractor-reap --grace 5
 ```
 Exit code: `0` if everyone exited on SIGINT, `1` if
 SIGKILL had to escalate — so you can chain it in CI
 health-checks (`scripts/tractor-reap || <alert>`).
 **What it matches** (orphan-mode):
 - `PPid == 1` (reparented to init → definitely
  orphaned, not just a currently-running child)
 - `cwd == <repo-root>` (keeps the sweep scoped; won't
  touch unrelated init-children elsewhere)
 - `python` in cmdline
 **What it does not do:** kill anything whose PPid is
 still a live tractor parent. If the parent is alive
 it's not an orphan; use `--parent <pid>` if you need
 to force-reap under a still-live supervisor.
 **When NOT to run it:** while a pytest session is
 active in another terminal. It's safe (won't touch
 that session's live children in orphan-mode) but can
 race if the target session is mid-teardown.
 ### c) `--shm` / `--shm-only`: orphan-segment sweep
 Because `tractor.ipc._mp_bs.disable_mantracker()`
 turns off `mp.resource_tracker` (see
 `ai/conc-anal/subint_forkserver_mp_shared_memory_issue.md`),
 a hard-crashing actor can leave `/dev/shm/<key>`
 segments behind that nothing else GCs.
 ```sh
 # process reap THEN shm sweep
 scripts/tractor-reap --shm
 # shm sweep only (skip process phase)
 scripts/tractor-reap --shm-only
 # dry-run: list candidates, don't unlink
 scripts/tractor-reap --shm -n
 ```
 **Match criteria** (very conservative — this is a
 shared-system path, can't be wrong):
 - segment is a regular file under `/dev/shm`,
 - owned by the **current uid** (`stat.st_uid`),
 - AND **no live process holds it open** —
  enumerated by walking every readable
  `/proc/<pid>/maps` (post-mmap mappings) AND
  `/proc/<pid>/fd/*` (pre-mmap shm-opened fds).
 The "nobody has it open" check is the
 kernel-canonical "is this leaked?" test — same
 answer `lsof /dev/shm/<key>` would give. No
 reliance on tractor-specific naming, so it works
 for any tractor app. Critically, it WILL NOT touch
 segments held by other apps you have running
 (e.g. `piker`, `lttng-ust-*`, `aja-shm-*` —
 verified locally with 81 in-use segments correctly
 preserved).
--- a/.claude/skills/run-tests/test-harness-reference.md
+++ b/.claude/skills/run-tests/test-harness-reference.md
@ -0,0 +1,233 @@
 # Tractor Test Harness Reference
 This repository-local file supplements the canonical `/run-tests` skill.
 Keep shared environment permission, process-signal safety, target selection,
 failure inspection, and result reporting policy in the canonical `SKILL.md`.
 ## Project And Environment
 - Project/import: `tractor`
 - Test root: `tests/`
 - Supported Python: `>=3.13,<3.15`
 - Runner: pytest `>=9.0.3`
 - Test dependencies: the `dev` group includes the `testing` group
 - CI uses uv's default `.venv`; the Nix flake uses `py313`.
 - Run from the repository root so pytest loads `pyproject.toml`.
 - Do not use `default.nix` as current test-environment authority; it still
  selects unsupported Python 3.12.
 Environment directory naming is not a harness invariant. Use an already
 verified active project environment when available. Otherwise, use an
 existing uv environment without syncing it:
 ```text
 uv run --frozen --no-sync python -c 'import pathlib, sys, tractor; root = pathlib.Path.cwd().resolve(); mod = pathlib.Path(tractor.__file__).resolve(); print(sys.executable); print(mod); assert mod.is_relative_to(root)'
 ```
 After module moves or collection failures, check collection with:
 ```text
 uv run --frozen --no-sync pytest --collect-only -q tests/
 ```
 Collection is not a mandatory precursor to every narrow run. Ask before
 provisioning or changing an environment.
 Before trusting CLI-selected runtime settings, inspect
 `TRACTOR_SPAWN_METHOD` and `TRACTOR_LOGLEVEL`. They override the spawn method
 and runtime log level passed by callers, so report active values with test
 results rather than claiming the CLI flags alone selected the runtime.
 ## Pytest Configuration And Commands
 `pyproject.toml` configures:
 - `testpaths = ["tests"]` and `--rootdir=./tests`;
 - importlib import mode;
 - the `tractor._testing.pytest` plugin;
 - xonsh plugin disablement;
 - `--show-capture=no` and `--capture=fd`.
 Do not silently add `-x`, `--tb=short`, or `--no-header`; those are not
 project defaults. In a verified active environment, replace `uv run
 --frozen --no-sync pytest` below with `python -m pytest`.
 ```text
 # Full suite
 uv run --frozen --no-sync pytest tests/
 # Narrow file
 uv run --frozen --no-sync pytest tests/test_local.py
 # Exact node
 uv run --frozen --no-sync pytest tests/discovery/test_registrar.py::test_reg_then_unreg
 # Keyword selection
 uv run --frozen --no-sync pytest tests/ -k 'cancel and not slow'
 # Previous failures
 uv run --frozen --no-sync pytest --lf
 ```
 After verifying that the no-sync environment is current, these pytest
 arguments match the Linux TCP CI row:
 ```text
 CI=1 uv run --frozen --no-sync pytest tests/ -rsx --spawn-backend=trio --tpt-proto=tcp --capture=fd
 ```
 ## Plugin Options And Matrices
 Supported spawn backends:
 - `trio` (default)
 - `mp_spawn`
 - `mp_forkserver`
 Do not advertise `subint`, `subint_forkserver`, or
 `main_thread_forkserver` as runnable backends. Supported transports are
 `tcp` (default) and `uds`. Run one transport per pytest session.
 `mp_forkserver` and UDS are POSIX-only.
 Other Tractor plugin options include:
 - `--tpdb` / `--debug-mode`
 - `--ll` / `--loglevel`
 - `--tl` / `--tractor-loglevel`
 - `--enable-stackscope`
 Examples:
 ```text
 uv run --frozen --no-sync pytest tests/ipc/ --tpt-proto=uds
 uv run --frozen --no-sync pytest tests/test_spawning.py --spawn-backend=mp_spawn
 uv run --frozen --no-sync pytest tests/test_spawning.py --spawn-backend=mp_forkserver --capture=sys
 ```
 CI currently exercises Python 3.13 with the `trio` backend: TCP and UDS on
 Linux and macOS, plus an informational TCP row on Windows whose pytest step
 uses `continue-on-error`.
 ## Registry And Transport Isolation
 Tests requesting the `reg_addr` fixture use addresses randomized per session:
 an unreserved unprivileged loopback port for TCP or a unique socket name under
 the platform runtime directory for UDS. A TCP collision remains possible.
 The runtime fallback remains `127.0.0.1:1616` or `registry@1616.sock`.
 Inspect that fallback only when the selected test intentionally uses runtime
 defaults or a failure identifies that address. Do not perform a mandatory
 `:1616` preflight or assume UDS sockets live under `/tmp`.
 ## Capture And Hang Diagnosis
 Normal capture is `fd`. Use `--capture=sys` with `mp_forkserver`; some tests
 switch to `capsys`, but the harness does not enforce that suite-wide.
 For a suspected capture interaction, compare only the exact node:
 ```text
 uv run --frozen --no-sync pytest <node> --capture=sys
 uv run --frozen --no-sync pytest <node> -s
 ```
 Treat `-s` as a diagnostic comparison, not a pass-equivalent workaround. Do
 not use it to reinterpret an ordinary captured pass. Interactive `--tpdb` or
 `tractor.pause()` sessions are different: they require a real TTY and disabled
 capture, normally `-s`.
 Do not add a global pytest timeout. `fail_after_w_trace` is Trio-cooperative;
 `afk_alarm_w_trace` is a POSIX main-thread `SIGALRM` hard backstop and can
 raise asynchronously. Use the latter only as a last resort, not as a generally
 Trio-safe timeout replacement.
 For live task-tree diagnosis:
 ```text
 uv run --frozen --no-sync pytest <node> --enable-stackscope --capture=sys
 kill -USR1 <pytest-or-subactor-pid>
 ```
 Stackscope appends dumps to `/tmp/tractor-stackscope-<pid>.log`, including when
 pytest capture hides terminal output. SIGUSR1 stackscope is unavailable on
 Windows and degrades to a no-op there.
 When a trace guard actually fires and snapshot capture succeeds, it writes
 under `$XDG_CACHE_HOME/tractor/hung-dumps/`, falling back beneath
 `~/.cache/tractor/hung-dumps/`, and prints an end-of-session index. A normal
 non-timeout run creates no snapshot.
 ## Cleanup And `tractor-reap`
 On Linux, normal pytest teardown discovers surviving descendants through
 `/proc`, sends SIGINT, waits three seconds, then escalates survivors to
 SIGKILL. It does not sweep shared memory and cannot run if pytest never reaches
 fixture teardown.
 Process discovery is a no-op off Linux. UDS PID liveness also depends on
 `/proc`; on macOS, recognized PID-named sockets can therefore be classified as
 dead without proof. The session-scoped autouse fixture currently passes those
 candidates directly to `reap_uds()` at teardown. Do not treat its non-Linux
 classification as proof of orphanhood or run concurrent live Tractor sessions
 against the same UDS bindspace.
 Use the CLI in inspection-only mode first:
 ```text
 uv run --frozen --no-sync scripts/tractor-reap -n
 uv run --frozen --no-sync scripts/tractor-reap --parent <pytest-pid> -n
 uv run --frozen --no-sync scripts/tractor-reap --shm --uds -n
 uv run --frozen --no-sync scripts/tractor-reap --uds-only -n
 ```
 Direct `scripts/tractor-reap` execution is acceptable only after verifying its
 `python3` shebang resolves the intended project environment.
 Review every candidate before requesting a mutating run:
 - default orphan mode is not repository-scoped;
 - `--parent` trusts the supplied PID and can include non-Tractor children;
 - `--shm` scans all current-user candidate files, not just Tractor-named
  files;
 - `--uds` treats `registry@1616.sock` as removable even if a live default UDS
  registrar uses it.
 Dry-run output prints only the initially matched root PIDs. A mutating run can
 recursively expand those roots to additional descendants when `psutil` is
 available. Inspect the descendant process tree separately; `-n` is not exact
 signal-set parity and does not by itself authorize signaling unseen children.
 The canonical skill owns signaling and unlinking authorization.
 ## Test Layout And Change Mapping
 | Changed area | Run first |
 |---|---|
 | `tractor/runtime/_runtime.py`, `_state.py`, `tractor/_root.py` | `tests/test_local.py`, `tests/test_root_runtime.py`, `tests/test_runtime.py`, `tests/test_rpc.py` |
 | `tractor/runtime/_portal.py`, `_rpc.py` | `tests/test_rpc.py`, `tests/test_cancellation.py` |
 | `tractor/runtime/_supervise.py` | `tests/test_cancellation.py`, `tests/test_spawning.py` |
 | `tractor/discovery/` | `tests/discovery/`, `tests/test_local.py` |
 | `tractor/ipc/` | `tests/ipc/`, `tests/test_2way.py`, `tests/test_shm.py` as relevant |
 | `tractor/spawn/` | `tests/test_spawning.py`, `tests/discovery/test_multi_program.py`, `tests/test_cancellation.py` |
 | `tractor/_context.py`, `_streaming.py` | `tests/test_context_stream_semantics.py`, `tests/test_advanced_streaming.py`, `tests/test_legacy_one_way_streaming.py` |
 | `tractor/to_asyncio.py` | `tests/test_infected_asyncio.py`, `tests/test_root_infect_asyncio.py` |
 | `tractor/msg/` | `tests/msg/` |
 | `tractor/devx/` | `tests/devx/`; debugger tests use pexpect and are comparatively slow |
 | `tractor/_exceptions.py` | `tests/test_remote_exc_relay.py`, `tests/test_reg_err_types.py`, `tests/test_inter_peer_cancellation.py`, `tests/test_cancellation.py`, `tests/msg/` |
 Current subdirectories include `discovery/`, `ipc/`, `msg/`, `devx/`, and
 `trionics/`. There is no `tests/spawn/` directory.
 ## Expected Outcomes
 Do not maintain a blanket known-flaky exemption list. Classify only current
 explicit skip or xfail marks and exact expected signatures. Notable tracked
 outcomes include:
 - duplicate-name `n_dups=4` and `n_dups=8` variants in
  `tests/discovery/test_multi_program.py` are non-strict xfails;
 - `tests/test_ringbuf.py` is module-skipped;
 - some documentation examples have explicit macOS-CI skips.
 A generic `TooSlowError` or `pexpect.TIMEOUT` is not enough to classify a
 failure as pre-existing.
--- a/.github/workflows/ci.yml
+++ b/.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)
+          # UDS is POSIX-only; Windows has no `AF_UNIX` so the
-          - os: macos-latest
+          # 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
--- a/.gitignore
+++ b/.gitignore
@ -168,3 +168,267 @@ gh/
 # LLM conversations that should remain private
 docs/conversations/
 # BEGIN ai.skillz: direct:symlink:claude:run-tests
 /.claude/skills/run-tests/SKILL.md
 # END ai.skillz: direct:symlink:claude:run-tests
 # BEGIN ai.skillz: direct:symlink:opencode:run-tests
 /.opencode/skills/run-tests/SKILL.md
 # END ai.skillz: direct:symlink:opencode:run-tests
 # BEGIN ai.skillz: direct:symlink:opencode:command:run-tests
 /.opencode/commands/run-tests.md
 # END ai.skillz: direct:symlink:opencode:command:run-tests
 # BEGIN ai.skillz: direct:symlink:claude:gish
 /.claude/skills/gish
 # END ai.skillz: direct:symlink:claude:gish
 # BEGIN ai.skillz: direct:symlink:opencode:gish
 /.opencode/skills/gish
 # END ai.skillz: direct:symlink:opencode:gish
 # BEGIN ai.skillz: direct:symlink:claude:resolve-conflicts
 /.claude/skills/resolve-conflicts
 # END ai.skillz: direct:symlink:claude:resolve-conflicts
 # BEGIN ai.skillz: direct:symlink:opencode:resolve-conflicts
 /.opencode/skills/resolve-conflicts
 # END ai.skillz: direct:symlink:opencode:resolve-conflicts
 # BEGIN ai.skillz: direct:symlink:claude:git-mgmt
 /.claude/skills/git-mgmt
 # END ai.skillz: direct:symlink:claude:git-mgmt
 # BEGIN ai.skillz: direct:symlink:opencode:git-mgmt
 /.opencode/skills/git-mgmt
 # END ai.skillz: direct:symlink:opencode:git-mgmt
 # BEGIN ai.skillz: runtime:open-wkt
 /wkts/
 # END ai.skillz: runtime:open-wkt
 # BEGIN ai.skillz: direct:symlink:claude:open-wkt
 /.claude/skills/open-wkt
 # END ai.skillz: direct:symlink:claude:open-wkt
 # BEGIN ai.skillz: direct:symlink:opencode:open-wkt
 /.opencode/skills/open-wkt
 # END ai.skillz: direct:symlink:opencode:open-wkt
 # BEGIN ai.skillz: direct:symlink:claude:close-wkt
 /.claude/skills/close-wkt
 # END ai.skillz: direct:symlink:claude:close-wkt
 # BEGIN ai.skillz: direct:symlink:opencode:close-wkt
 /.opencode/skills/close-wkt
 # END ai.skillz: direct:symlink:opencode:close-wkt
 # BEGIN ai.skillz: runtime:code-review
 .ai/code-review/reports/
 # END ai.skillz: runtime:code-review
 # BEGIN ai.skillz: direct:symlink:claude:code-review
 /.claude/skills/code-review
 # END ai.skillz: direct:symlink:claude:code-review
 # BEGIN ai.skillz: direct:symlink:opencode:code-review
 /.opencode/skills/code-review
 # END ai.skillz: direct:symlink:opencode:code-review
 # BEGIN ai.skillz: direct:symlink:claude:code-nav-refs
 /.claude/skills/code-nav-refs
 # END ai.skillz: direct:symlink:claude:code-nav-refs
 # BEGIN ai.skillz: direct:symlink:opencode:code-nav-refs
 /.opencode/skills/code-nav-refs
 # END ai.skillz: direct:symlink:opencode:code-nav-refs
 # BEGIN ai.skillz: runtime:code-review-changes
 .claude/review_context.md
 .claude/review_regression.md
 .claude/review_replies/
 # END ai.skillz: runtime:code-review-changes
 # BEGIN ai.skillz: direct:symlink:claude:code-review-changes
 /.claude/skills/code-review-changes
 # END ai.skillz: direct:symlink:claude:code-review-changes
 # BEGIN ai.skillz: direct:symlink:opencode:code-review-changes
 /.opencode/skills/code-review-changes
 # END ai.skillz: direct:symlink:opencode:code-review-changes
 # BEGIN ai.skillz: runtime:commit-msg
 .claude/skills/commit-msg/msgs/
 .claude/git_commit_msg_LATEST.md
 # END ai.skillz: runtime:commit-msg
 # BEGIN ai.skillz: direct:symlink:claude:commit-msg
 /.claude/skills/commit-msg/SKILL.md
 # END ai.skillz: direct:symlink:claude:commit-msg
 # BEGIN ai.skillz: direct:symlink:opencode:commit-msg
 /.opencode/skills/commit-msg/SKILL.md
 # END ai.skillz: direct:symlink:opencode:commit-msg
 # BEGIN ai.skillz: direct:symlink:claude:commit-plan
 /.claude/skills/commit-plan
 # END ai.skillz: direct:symlink:claude:commit-plan
 # BEGIN ai.skillz: direct:symlink:opencode:commit-plan
 /.opencode/skills/commit-plan
 # END ai.skillz: direct:symlink:opencode:commit-plan
 # BEGIN ai.skillz: direct:symlink:claude:dep-supersede-scan
 /.claude/skills/dep-supersede-scan
 # END ai.skillz: direct:symlink:claude:dep-supersede-scan
 # BEGIN ai.skillz: direct:symlink:opencode:dep-supersede-scan
 /.opencode/skills/dep-supersede-scan
 # END ai.skillz: direct:symlink:opencode:dep-supersede-scan
 # BEGIN ai.skillz: direct:symlink:claude:harness-perf
 /.claude/skills/harness-perf
 # END ai.skillz: direct:symlink:claude:harness-perf
 # BEGIN ai.skillz: direct:symlink:opencode:harness-perf
 /.opencode/skills/harness-perf
 # END ai.skillz: direct:symlink:opencode:harness-perf
 # BEGIN ai.skillz: direct:symlink:claude:inter-skill-review
 /.claude/skills/inter-skill-review
 # END ai.skillz: direct:symlink:claude:inter-skill-review
 # BEGIN ai.skillz: direct:symlink:opencode:inter-skill-review
 /.opencode/skills/inter-skill-review
 # END ai.skillz: direct:symlink:opencode:inter-skill-review
 # BEGIN ai.skillz: direct:symlink:claude:opencode-cleaning
 /.claude/skills/opencode-cleaning
 # END ai.skillz: direct:symlink:claude:opencode-cleaning
 # BEGIN ai.skillz: direct:symlink:opencode:opencode-cleaning
 /.opencode/skills/opencode-cleaning
 # END ai.skillz: direct:symlink:opencode:opencode-cleaning
 # BEGIN ai.skillz: direct:symlink:claude:plan-io
 /.claude/skills/plan-io
 # END ai.skillz: direct:symlink:claude:plan-io
 # BEGIN ai.skillz: direct:symlink:opencode:plan-io
 /.opencode/skills/plan-io
 # END ai.skillz: direct:symlink:opencode:plan-io
 # BEGIN ai.skillz: runtime:pr-msg
 .claude/skills/pr-msg/msgs/
 .claude/skills/pr-msg/pr_msg_LATEST.md
 # END ai.skillz: runtime:pr-msg
 # BEGIN ai.skillz: direct:symlink:claude:pr-msg
 /.claude/skills/pr-msg/SKILL.md
 /.claude/skills/pr-msg/references
 /.claude/skills/pr-msg/scripts
 # END ai.skillz: direct:symlink:claude:pr-msg
 # BEGIN ai.skillz: direct:symlink:opencode:pr-msg
 /.opencode/skills/pr-msg/SKILL.md
 /.opencode/skills/pr-msg/references
 /.opencode/skills/pr-msg/scripts
 # END ai.skillz: direct:symlink:opencode:pr-msg
 # BEGIN ai.skillz: direct:symlink:claude:prompt-io
 /.claude/skills/prompt-io
 # END ai.skillz: direct:symlink:claude:prompt-io
 # BEGIN ai.skillz: direct:symlink:opencode:prompt-io
 /.opencode/skills/prompt-io
 # END ai.skillz: direct:symlink:opencode:prompt-io
 # BEGIN ai.skillz: direct:symlink:claude:py-codestyle
 /.claude/skills/py-codestyle
 # END ai.skillz: direct:symlink:claude:py-codestyle
 # BEGIN ai.skillz: direct:symlink:opencode:py-codestyle
 /.opencode/skills/py-codestyle
 # END ai.skillz: direct:symlink:opencode:py-codestyle
 # BEGIN ai.skillz: runtime:taken-export
 .ai/taken/exports/
 # END ai.skillz: runtime:taken-export
 # BEGIN ai.skillz: direct:symlink:claude:taken-export
 /.claude/skills/taken-export
 # END ai.skillz: direct:symlink:claude:taken-export
 # BEGIN ai.skillz: direct:symlink:opencode:taken-export
 /.opencode/skills/taken-export
 # END ai.skillz: direct:symlink:opencode:taken-export
 # BEGIN ai.skillz: direct:symlink:claude:yt-url-lookup
 /.claude/skills/yt-url-lookup
 # END ai.skillz: direct:symlink:claude:yt-url-lookup
 # BEGIN ai.skillz: direct:symlink:opencode:yt-url-lookup
 /.opencode/skills/yt-url-lookup
 # END ai.skillz: direct:symlink:opencode:yt-url-lookup
 # BEGIN ai.skillz: direct:symlink:opencode:command:gish
 /.opencode/commands/gish.md
 # END ai.skillz: direct:symlink:opencode:command:gish
 # BEGIN ai.skillz: direct:symlink:opencode:command:resolve-conflicts
 /.opencode/commands/resolve-conflicts.md
 # END ai.skillz: direct:symlink:opencode:command:resolve-conflicts
 # BEGIN ai.skillz: direct:symlink:opencode:command:git-mgmt
 /.opencode/commands/git-mgmt.md
 # END ai.skillz: direct:symlink:opencode:command:git-mgmt
 # BEGIN ai.skillz: direct:symlink:opencode:command:open-wkt
 /.opencode/commands/open-wkt.md
 # END ai.skillz: direct:symlink:opencode:command:open-wkt
 # BEGIN ai.skillz: direct:symlink:opencode:command:close-wkt
 /.opencode/commands/close-wkt.md
 # END ai.skillz: direct:symlink:opencode:command:close-wkt
 # BEGIN ai.skillz: direct:symlink:opencode:command:code-review
 /.opencode/commands/code-review.md
 # END ai.skillz: direct:symlink:opencode:command:code-review
 # BEGIN ai.skillz: direct:symlink:opencode:command:code-review-changes
 /.opencode/commands/code-review-changes.md
 # END ai.skillz: direct:symlink:opencode:command:code-review-changes
 # BEGIN ai.skillz: direct:symlink:opencode:command:commit-msg
 /.opencode/commands/commit-msg.md
 # END ai.skillz: direct:symlink:opencode:command:commit-msg
 # BEGIN ai.skillz: direct:symlink:opencode:command:commit-plan
 /.opencode/commands/commit-plan.md
 # END ai.skillz: direct:symlink:opencode:command:commit-plan
 # BEGIN ai.skillz: direct:symlink:opencode:command:dep-supersede-scan
 /.opencode/commands/dep-supersede-scan.md
 # END ai.skillz: direct:symlink:opencode:command:dep-supersede-scan
 # BEGIN ai.skillz: direct:symlink:opencode:command:harness-perf
 /.opencode/commands/harness-perf.md
 # END ai.skillz: direct:symlink:opencode:command:harness-perf
 # BEGIN ai.skillz: direct:symlink:opencode:command:opencode-cleaning
 /.opencode/commands/opencode-cleaning.md
 # END ai.skillz: direct:symlink:opencode:command:opencode-cleaning
 # BEGIN ai.skillz: direct:symlink:opencode:command:pr-msg
 /.opencode/commands/pr-msg.md
 # END ai.skillz: direct:symlink:opencode:command:pr-msg
 # BEGIN ai.skillz: direct:symlink:opencode:command:taken-export
 /.opencode/commands/taken-export.md
 # END ai.skillz: direct:symlink:opencode:command:taken-export
 # BEGIN ai.skillz: direct:symlink:opencode:command:yt-url-lookup
 /.opencode/commands/yt-url-lookup.md
 # END ai.skillz: direct:symlink:opencode:command:yt-url-lookup
--- a/ai/conc-anal/ria_nursery_removal_plan.md
+++ b/ai/conc-anal/ria_nursery_removal_plan.md
@ -0,0 +1,463 @@
 # `_ria_nursery` removal plan (issue #477 follow-up)
 Goal: drop the secondary "run-in-actor" spawn nursery (and
 friends) from `ActorNursery`/spawn internals, now that
 `tractor.to_actor.run()` delivers one-shot semantics purely on
 the daemon-spawn + portal primitives.
 ## Verified machinery map (2026-07-02, wkt @ a34aaf98)
 The entire mechanism is 4 files:
 - `runtime/_supervise.py`
  - `ActorNursery.__init__(.., ria_nursery, ..)` stores
    `._ria_nursery` (:202, :238); sole read is
    `run_in_actor()` passing `nursery=self._ria_nursery`
    (:442) into `start_actor()`'s `nursery:
    trio.Nursery|None` escape-hatch param (:305, :367).
  - `._cancel_after_result_on_exit: set` (:244) marks ria
    portals (:457).
  - `_open_and_supervise_one_cancels_all_nursery()` nests
    `da_nursery` (:609) around `ria_nursery` (:622); the
    `finally:` at the ria->da boundary (:747-766) raises
    collected `errors` (single exc or BEG).
 - `runtime/_portal.py`
  - `._expect_result_ctx` (:112) set by `_submit_for_result()`
    (:142, sole caller `run_in_actor()`); consumed by
    `wait_for_result()` (:167) + deprecated `result()` (:220).
    The `None` branch (:184-196) returns the `NoResult`
    sentinel (`_exceptions.py:1164`).
 - `spawn/_spawn.py`
  - `exhaust_portal()` (:129): awaits
    `portal.wait_for_result()`, CATCHES+RETURNS any exc
    (never raises).
  - `cancel_on_completion()` (:177): `exhaust_portal()` ->
    on exc-result stash `errors[uid] = result` (:203) ->
    ALWAYS `portal.cancel_actor()` (:218).
 - `spawn/_trio.py` (:195-222) + `spawn/_mp.py` (:187-213),
  identical shape: after shielded
  `await an._join_procs.wait()`, open a per-child local
  nursery; IFF `portal in an._cancel_after_result_on_exit`
  start `cancel_on_completion` alongside `soft_kill()`; when
  `soft_kill` returns first, `nursery.cancel_scope.cancel()`
  reaps the result-waiter.
 ## The load-bearing semantic (already-deferred errors)
 Remote ria-child errors NEVER raise into `ria_nursery`:
 1. reaper tasks only START after `_join_procs.set()` (block
   exit or the inner error handler),
 2. `exhaust_portal` swallows the exc into a return value,
 3. `cancel_on_completion` stashes it in `errors` + cancels
   that child,
 4. the ria->da `finally:` re-raises collected `errors` (and
   `an.cancel()`s any daemon stragglers).
 So mid-block there is NO error propagation from ria children
 (unless user code explicitly `await portal.wait_for_result()`s)
 — the two-nursery nesting only sequences "reap ria results
 BEFORE blocking on daemon join". A single-nursery impl only
 needs to preserve that sequencing, not any ASAP-cancel
 behavior.
 ## Target design
 ### step A: single-nursery `run_in_actor()` (mechanical)
 - `run_in_actor()` spawns via the DEFAULT (`_da_nursery`)
  path — drop `nursery=self._ria_nursery`.
 - rename `._cancel_after_result_on_exit` ->
  `._ria_portals: dict[portal, Actor]` (need the subactor ref
  for `cancel_on_completion`).
 - move reaper start-up OUT of the backends into
  `_open_and_supervise...`: immediately after EACH
  `an._join_procs.set()` call-site (happy path :642, inner
  error handler :661), start one
  `cancel_on_completion(portal, subactor, errors)` task per
  ria portal into `da_nursery`, then (happy path only)
  `await` their completion BEFORE falling out of the
  `try:`/`finally:` that raises `errors` — e.g. gather in a
  dedicated inner `trio.open_nursery()` block replacing
  today's `ria_nursery` join point.
 - delete the membership branch + local reaper nursery from
  `_trio.py`/`_mp.py` (keep the `soft_kill()` call; the
  per-child local nursery collapses to just `soft_kill`).
 - `_trio.py:310` `_children.pop()` etc. unchanged.
 ### step B: delete the plumbing
 - `_open_and_supervise...`: drop the inner
  `ria_nursery` + merge its `except BaseException` classify
  logic into ONE handler on the (now single) nursery scope;
  `ActorNursery.__init__` loses the `ria_nursery` param.
 - `start_actor()` loses the `nursery:` escape-hatch param
  (the :302-304 TODO).
 - backends: no more `_cancel_after_result_on_exit` refs.
 ### step C: (separate PRs) deprecate + migrate + excise
 - migrate in-repo `.run_in_actor()` usage to
  `to_actor.run()`: tests 46 hits/9 files (test_cancellation
  15, test_infected_asyncio 10, test_spawning 8, registrar 3,
  adv_streaming 4, pubsub 2, rpc 1, runtime 1), examples 28
  hits/13 files (debugging/* dominate), docs 20 hits/8 rst
  files. NOTE: many sites also use deprecated
  `Portal.result()`/`wait_for_result()` — these die with
  `_expect_result_ctx`, so migration must land FIRST.
 - add `DeprecationWarning` to `run_in_actor()` (+
  `_submit_for_result`/`wait_for_result`).
 - final excision: `run_in_actor()`, `_submit_for_result`,
  `_expect_result_ctx`, `wait_for_result`/`result`,
  `exhaust_portal`, `cancel_on_completion`, `NoResult`.
 ## Risk register
 1. hard-killed ria child: today the backend-local
   `nursery.cancel_scope.cancel()` discards a still-parked
   reaper when the proc dies first; a da_nursery-hosted
   reaper instead sees the transport break ->
   `exhaust_portal` returns a `TransportClosed`-ish exc ->
   NEW entry in `errors` that today gets discarded. Guard:
   reap-gather block must cancel remaining reapers once all
   ria procs are dead, or filter transport-death excs for
   already-`cancel_called` children.
 2. error-path ordering: inner handler today sets
   `_join_procs` THEN `an.cancel()`; reapers race the
   cancel-RPC. Keep that ordering when moving reaper spawn.
 3. debugger interplay: `maybe_wait_for_debugger()` calls
   (:654, :730) must stay BEFORE any reap/cancel issuance.
 4. `errors` double-entry: local body error (:646) + child's
   relayed exc (via reaper) can both land for the same
   scenario -> BEG shape changes vs today? (today has the
   same dual-write sites; keep behavior identical.)
 5. mp backend parity: mirror every `_trio.py` edit in
   `_mp.py` (identical block).
 ## Step-A first-probe findings (2026-07-02, WIP in tree)
 Step A is IMPLEMENTED (uncommitted):
 `run_in_actor()` spawns via da_nursery; new
 `_supervise._reap_ria_portals()` helper; reap awaited after
 happy-path `_join_procs.set()`; error-path runs reap
 CONCURRENT with `an.cancel()` in the shielded block;
 backends stripped of the membership branch + per-child
 reaper nursery (+ dead imports).
 Probe history (trio backend):
 - `tests/test_to_actor.py` + `tests/test_spawning.py`:
  20/20 PASS — incl. all `run_in_actor()` result
  round-trips + `test_remote_error` (single erroring child,
  body re-raise -> inner error path).
 - FIRST attempt ran the error-path reap CONCURRENT with
  `an.cancel()` (mimicking the old backend-side race):
  `test_cancellation.py::test_multierror` (2 erroring ria
  children, body re-raises one) DEADLOCKED. Root cause per
  the sequencing fix below: reap + cancel must NOT race at
  this layer (suspected `._children` pop-during-iteration
  and/or double-cancel RPC wedge; not fully root-caused
  since the fix removes the race wholesale).
 - FIX (2nd attempt, current impl): error path SEQUENCES:
  (1) snapshot ria `(portal, subactor)` pairs (backend
  `finally`s pop `._children` as procs reap), (2)
  `await an.cancel()`, (3) bounded reap over the snapshot.
  Bound was first 3s -> blew the `fail_after` deadline in
  `test_cancel_while_childs_child_in_sync_sleep` (hard-
  killed grandchild never relays => reaper parks the full
  bound). Tightened to 0.5s: anything collectable is
  already queued in the local ctx (relayed BEFORE the
  cancel); a parked reaper self-cleans (`trio.Cancelled`
  results are never stashed).
 - RESULT: `tests/test_cancellation.py` FULLY GREEN
  (20 passed, 1 xfailed, 77s); full-suite gate run kicked
  off same session (see final report/next session).
 Remaining risk: on slow CI a relayed-but-undelivered error
 racing the 0.5s bound could drop an `errors` entry
 (BEG-shape flake); if observed, scale the bound via the
 `cpu_perf_headroom()`-style approach or peek
 `Portal._final_result_msg`/ctx queue state instead of
 time-bounding.
 ## Step-B outcome (2026-07-02, done in tree)
 Step A landed as `5cd190c5` (code) + `99310269` (docs).
 Step B implemented on top (uncommitted):
 - `._ria_nursery` is GONE — the inner
  `async with (collapse_eg(), trio.open_nursery() as
  ria_nursery)` layer in
  `_open_and_supervise_one_cancels_all_nursery` is deleted;
  `da_nursery` is now the single nursery for ALL subactors.
 - `ActorNursery.__init__` drops the `ria_nursery` param +
  the `self._ria_nursery` attr; `start_actor()` drops its
  `nursery=` escape-hatch param (uses `self._da_nursery`
  directly).
 - `._cancel_after_result_on_exit` STAYS — it's the
  ria-child discriminator for `_reap_ria_portals()`.
 Deliberately NOT done (deferred to its own higher-risk PR,
 flagged with a TODO at the outer `except`): merging the two
 error handlers into one. Rationale — collapsing the empty
 nursery is provably behavior-preserving (a zero-task
 `trio.open_nursery()` only adds a checkpoint), whereas the
 inner `except BaseException` (swallow-into-`errors`) and
 outer `except (...)` (re-raise, safety-net for the inner
 handler's own non-shielded awaits) have DIFFERENT
 semantics; merging changes error/cancel propagation and
 wants isolated review + its own gate. Both handlers are
 kept, now nested directly under the single nursery.
 Why the collapse is safe: post-step-A NOTHING spawns into
 `ria_nursery` (its only reader, `run_in_actor`'s
 `nursery=self._ria_nursery`, was removed in A; the stored
 attr was never read again). So the layer was pure dead
 weight.
 Gate (trio backend, all 0-failure):
 - targeted set (`test_cancellation test_spawning test_local
  test_rpc test_to_actor`) = 49 passed, 1 xfailed.
 - tail set (`test_reg_err_types remote_exc_relay
  resource_cache ringbuf root_infect_asyncio root_runtime
  runtime shm task_broadcasting trioisms trionics/`) = 63
  passed, 1 skipped, 5 xfailed.
 - full-suite head ~73% (subdirs + `test_2way`..`test_pubsub`)
  = 303 passed before the known-flaky `test_dynamic_pub_sub`
  TooSlowError stall (pre-existing; same hang in the step-A
  full run). Suite ran slow this session (~13min vs 555s
  cold, likely thermal from back-to-back runs), never
  completing within an 800s bound — but split across the
  above three runs EVERY module passed under step B.
 ## Step-B2 outcome (2026-07-02, done in tree)
 Step B committed as `9201a2ed` (code) + `d2e812fb` (docs), then
 branched to `drop_ria_nursery`. Step B2 (the deferred
 handler-merge) implemented on top (uncommitted):
 - the two nested handlers in
  `_open_and_supervise_one_cancels_all_nursery` collapse to
  ONE `except BaseException as _scope_err` + the existing
  `finally`. The `outer_err`/`inner_err` locals go away.
 Why it's safe (trace, not hope): the OLD inner handler records
 `errors[actor.aid.uid]` as its FIRST statement (before any
 await). So whenever an error path runs, `errors` is non-empty.
 The OLD outer handler was only reachable via leakage from the
 inner handler (it catches `BaseException`, so nothing from the
 `yield` scope bypasses it) — and by then `errors` is already
 populated, so the `finally`'s `raise` from `errors` ALWAYS
 superseded the outer handler's own `raise`. i.e. the outer
 `raise` was dead. The outer handler's other effects
 (`_scope_error`, a 2nd debugger-wait, child-cancel) are
 redundant with the merged handler + `finally`. So one handler
 + `finally` is observably equivalent.
 Residual nuance (accepted): in the rare "`trio.Cancelled`
 delivered during the non-shielded `maybe_wait_for_debugger`"
 path, the merged form may leave `_cancel_called` False (cancel
 happens after the wait), so `open_nursery`'s tb-hiding guard
 (`not cancel_called and _scope_error`) can show a tb it
 previously hid. More informative, not less; no test asserts on
 it.
 Gate (box ran ~2.7x slow this session, load-induced
 `TooSlowError` flakiness on timing tests — NOT code; see
 [[env_cpu_throttle_masquerades_as_regression]]):
 - baseline (pre-B2 tip `9201a2ed`) full suite
  (`-k 'not dynamic_pub_sub'`) = 300 passed + 1
  `test_ext_types_over_ipc` `TooSlowError` that passes 6/6 in
  isolation (4.89s).
 - B2 error/cancel gate (`test_cancellation remote_exc_relay
  inter_peer_cancellation advanced_faults oob_cancellation
  to_actor spawning local rpc`) = 71 passed, 1 xfailed
  (125s).
 - B2 full-suite run: see `b2_full.log` (result appended on
  completion). RECOMMEND a clean full-suite run on a
  normal-speed box before this merges.
 ## Regression + fix: ria-reap hang (2026-07-02)
 Human hit a full-suite hang on
 `test_infected_asyncio.py::test_tractor_cancels_aio`. Bisected:
 passes at pre-ria `a34aaf98` (0.59s), hangs at B2 `e617b498`
 (90s+). Root-caused to the STEP-A reaper hoist (`5cd190c5`),
 NOT B2 (`_reap_ria_portals` is byte-identical A->B2).
 Bug: the test does `run_in_actor(asyncio_actor)` then a USER
 `portal.cancel_actor()` and exits the block cleanly -> the
 happy path's `await _reap_ria_portals()`, which waits UNBOUNDED
 on `cancel_on_completion -> wait_for_result()`. The child was
 cancelled out-of-band so no final result is relayed -> parked
 forever. The OLD spawn-backend reaper was raced against
 `soft_kill()` (per-child nursery `cancel_scope.cancel()` on
 subproc death); the hoist dropped that race.
 Fix: `_reap_ria_portals()` runs each `cancel_on_completion()`
 in a local nursery alongside a `proc.poll()` death-watch that
 cancels the parked reaper once the subproc exits — restoring
 the old race, backend-agnostic (guarded by
 `hasattr(proc, 'poll')` for a future `subint` handle).
 Why POLL (`proc.poll()`) not the event-driven `wait_func`:
 the mp waiter (`_spawn.proc_waiter`) does
 `wait_readable(proc.sentinel)`, and `soft_kill()` is ALREADY
 awaiting that same fd concurrently in the daemon nursery — a
 2nd `wait_readable` on one fd raises `trio.BusyResourceError`.
 (`trio.Process.wait()` IS multi-waiter-safe, but mp has no
 async equivalent.) `proc.poll()` — the same liveness check
 `soft_kill` itself falls back to — is the conflict-free common
 denominator. Verified: poll-fix passes on BOTH trio and
 mp_spawn.
 Also added a per-test anti-hang guard: wrapped
 `test_tractor_cancels_aio`'s `main()` in
 `with trio.fail_after(9 * cpu_perf_headroom())` — the blessed
 pattern (`pytest-timeout`'s global cap is intentionally off;
 breaks trio under fork backends, see `pyproject` NOTE). So a
 future recurrence FAILS FAST instead of hanging the suite.
 (Several other tests in the file are still guardless —
 `test_aio_simple_error`, `test_trio_error_cancels_intertask_chan`,
 `test_aio_errors_and_channel_propagates_and_closes` — candidate
 follow-up sweep.)
 Lesson: the B2 focused gate OMITTED `test_infected_asyncio`
 (and the full runs were clipped/slow), so the step-A hang
 slipped through. Any future ria-touching change MUST gate
 `test_infected_asyncio` explicitly.
 Gate: `test_tractor_cancels_aio` green (trio 1.53s, mp 3.98s);
 fix gate (`test_infected_asyncio test_cancellation test_to_actor
 test_spawning`) = 74 passed, 3 xfailed, 0 failures.
 ## PAUSED (2026-07-02): re-assess the reaper's SCOPE
 User's insight (compelling — likely the real root cause of
 the hang, not just the missing proc-death race):
 > the "hoisting" of 5cd190c5 was just not really done right
 > — the hoist should have been into the `to_actor` scope,
 > not `_supervise`.
 The argument: `.run_in_actor()`'s result-waiting/reaping got
 hoisted into `_supervise._reap_ria_portals` (nursery-machinery
 scope), which has NO natural cancel-scope to bound a parked
 `wait_for_result()` — hence the awkward proc-death race +
 the poll-vs-`proc_waiter` dilemma. If the result-wait instead
 lived in the `to_actor` one-shot scope
 (`to_actor._invoke_in_subactor()`), it would sit right next to
 the caller's `an` + a local `trio` task-nursery + cancel-scope
 (the `trio.to_thread`-style model #477 actually wants) — so
 bounding/cancelling the wait is trivial and the hang
 dissolves from correct scoping rather than a bolt-on race.
 Follow-on to re-evaluate on resume:
 - should `_reap_ria_portals` exist AT ALL, or should
  result-waiting move entirely into
  `to_actor._invoke_in_subactor()`?
 - reimplement legacy `run_in_actor()` on top of
  `to_actor.run()` so `_reap_ria_portals` +
  `_cancel_after_result_on_exit` can be DROPPED from
  `_supervise` entirely (the true #477 simplification)?
 - the poll-vs-event decision is MOOT under this re-scoping.
 State at pause: `test_infected_asyncio` anti-hang guard
 COMMITTED (`d1fb4a1a`, intentionally red w/o the fix — the
 user's failing-test-first convention). The poll-based reap
 fix in `_supervise.py` is UNCOMMITTED and likely SUPERSEDED
 by the re-scoping — do NOT land it as-is.
 ## RESOLVED (2026-07-06): migrate everything, remove the API
 The PAUSED re-assessment concluded decisively: rather than
 re-scope `_reap_ria_portals` (or bolt any hack onto it), the
 `run_in_actor()` API itself was REMOVED — its non-blocking
 "result at teardown" semantic predates streaming and confused
 more than it served. Every in-repo caller was migrated
 per-file/-group (each its own commit, each gated):
 - tests: `test_infected_asyncio` `test_runtime` `test_rpc`
  `test_spawning` `test_pubsub` `test_registrar`
  `test_cancellation` (3 groups) `test_advanced_streaming`.
 - examples: 4 non-debugging + all 8 `debugging/` REPL scripts
  (debugger suite byte-identical green, 28p/6s).
 - docs: 8 rst pages + the `experimental/_pubsub` docstring.
 Migration patterns (the `run_in_actor` shape -> successor):
 - blocking result        -> `to_actor.run(fn, an=an, ...)`
 - fire-&-forget/forever  -> bg `to_actor.run()` task in a local
                            `trio` task-nursery (or `start_actor`
                            + bg `Portal.run()` when a portal
                            handle is needed)
 - concurrent fan-out     -> N bg `to_actor.run()` tasks / or
                            `gather_contexts([p.open_context(..)])`
 - reap-all-error-collect -> the "collect don't cancel" pattern:
                            each one-shot catches + stashes its
                            `RemoteActorError`, group raised
                            after the task-nursery joins (see
                            `examples/debugging/multi_subactors.py`)
 - mutual-rendezvous      -> peers must OUTLIVE both dialogs:
                            `start_actor()` daemons + concurrent
                            `Portal.run()`s + explicit
                            `an.cancel()` (eager one-shot reap
                            races the slower peer's dial of the
                            winner's dead sockaddr; found via
                            `test_trynamic_trio` flake).
 Semantic deltas (tests loosened accordingly):
 - teardown-reap-all BEG-of-N is GONE: local task-nurseries are
  cancel-on-first, raced siblings' `Cancelled`s are absorbed,
  and the runtime's `collapse_eg()` unwraps every single-member
  group at each actor boundary — a fully-raced nested tree
  relays a bare (annotated) `RemoteActorError` chain.
 - `test_multierror_fast_nursery`'s obsolete BEG-of-25 assertion
  deleted; `test_concurrent_start_error_reaps_all` retains its
  high-fan-out startup/cancel/reap stress under caller-scoped
  semantics.
 - `test_nested_multierrors` re-purposed separately as deep-tree
  cancel-cascade stress w/ a race-tolerant shape walk.
 Final excision (after zero callers remained): `run_in_actor()`,
 `._cancel_after_result_on_exit`, `_reap_ria_portals()`,
 `Portal._submit_for_result/._expect_result_ctx/
 .wait_for_result()/.result()`, `exhaust_portal()`,
 `cancel_on_completion()`, `NoResult` — net -402 lines. The
 reap-hang class (unbounded `wait_for_result` in machinery
 scope) dissolves structurally: the only result-wait left lives
 in the caller's task inside its own cancel-scope; the
 `d1fb4a1a` anti-hang guard test passes by construction. The
 poll-vs-`proc_waiter` debate is moot as predicted.
 ## Follow-up sketch: `to_actor.open_one_shot()` (run-async parity)
 If deferred-result parity is ever wanted, the design that needs
 NO runtime coupling, NO returned `Portal` and NO cancel-relay
 `trio.Event` machinery:
    async with to_actor.open_one_shot(
        fn, an=an, **kws,
    ) as one_shot:
        ...                       # concurrent caller work
        val = await one_shot.wait()   # optional; errors always
                                      # propagate at scope exit
 an `@acm` that opens a private task-nursery, `start_soon`s ONE
 task running the existing blocking `run()` and stashes the
 value in a slot + sets a done-`trio.Event` (a memo, not a
 cancel relay). Cancellation = plain scope-cancel of the acm's
 nursery (the parked `Portal.run()` unwinds via `Cancelled`, the
 shielded `cancel_actor()` reap still runs); a child error
 raises into the acm scope so an un-`wait()`ed one-shot can
 never silently drop its error. i.e. the old reaper's job is
 done by scoping, not machinery. ~40 lines, all in
 `to_actor/_api.py`, zero `_supervise` involvement.
 ## Verification gate
 - per-migration-commit module gates on `trio` (+ `mp_spawn`
  spot-gates incl. `test_infected_asyncio` per the B2 lesson);
  `tests/devx/test_debugger.py` for the REPL flows.
 - full suite on `trio` + `mp_spawn` at branch tip + CI matrix
  via draft PR #484.
--- a/ai/prompt-io/claude/20260702T154255Z_65bf9df5_prompt_io.md
+++ b/ai/prompt-io/claude/20260702T154255Z_65bf9df5_prompt_io.md
@ -0,0 +1,79 @@
 ---
 model: claude-fable-5
 service: claude
 session: f6c84722-471a-4458-9a80-e453fea9029f
 timestamp: 2026-07-02T15:42:55Z
 git_ref: 65bf9df5
 scope: code
 substantive: true
 raw_file: 20260702T154255Z_65bf9df5_prompt_io.raw.md
 ---
 ## Prompt
 Driver prompt file `ai/prompt-io/prompts/issue_477.md`:
 > attempt to resolve
 > https://github.com/goodboy/tractor/issues/477
 > do it with /open-wkt.
 (plus a hard stop-for-human-review deadline of 12:50PM
 EST the same day)
 Issue #477 asks to factor `ActorNursery.run_in_actor()`
 (and possibly `Portal.run()`) out of the nursery
 internals into a new `tractor.to_actor` wrapper
 subpackage of "higher level one shot" single-remote-task
 APIs, adopting the `trio.to_thread`/`anyio.to_process`
 parlance, so that error collection/propagation moves up
 into the caller's local `trio` scope and the nursery's
 spawn machinery can eventually drop the
 `._ria_nursery` coupling.
 ## Response summary
 First-cut `tractor.to_actor` subpkg delivering the
 one-shot API composed purely from the existing
 daemon-spawn + portal primitives (`start_actor()` +
 `Portal.run()` + `Portal.cancel_actor()`), leaving the
 legacy `.run_in_actor()` machinery untouched (formal
 deprecation deferred until in-repo usage migrates):
 - `to_actor.run(fn, **fn_kwargs) -> Any`: spawn a
  subactor, schedule `fn` as its lone remote task, wait
  on and return its result, ALWAYS reaping the subactor
  (shield-safe `finally`). Remote errors raise in the
  caller's task as boxed `RemoteActorError`s.
 - placement variants: `portal=` reuses a running actor
  (no spawn/reap), `an=` spawns from a caller-managed
  actor-nursery, neither opens a call-scoped private
  `open_nursery()` (implicitly booting the runtime,
  configurable via `runtime_kwargs`).
 - fail-fast validation before any spawn: non-streaming
  async fn required; `portal=`/`an=` mutually
  exclusive; `runtime_kwargs` rejected alongside any
  placement opt.
 - `run_in_actor()` TODO/docstring now cross-reference
  the successor API.
 ## Files changed
 - `tractor/to_actor/__init__.py` — new subpkg,
  re-exports `run`
 - `tractor/to_actor/_api.py` — `run()` +
  `_invoke_in_subactor()` + `_validate_one_shot_fn()`
 - `tractor/__init__.py` — top-level `to_actor`
  re-export
 - `tractor/runtime/_supervise.py` — comment/docstring
  pointers from `run_in_actor()` to the successor
 - `tests/test_to_actor.py` — 11-test suite covering
  all placement variants, error relay, the concurrent
  worker-pool-ish pattern and arg validation
 - `examples/parallelism/to_actor_one_shots.py` —
  runnable demo (auto-collected by
  `test_docs_examples.py`)
 ## Human edits
 None yet — pending human review (work paused before the
 12:50PM EST deadline per the driver prompt).
--- a/ai/prompt-io/claude/20260702T154255Z_65bf9df5_prompt_io.raw.md
+++ b/ai/prompt-io/claude/20260702T154255Z_65bf9df5_prompt_io.raw.md
@ -0,0 +1,100 @@
 ---
 model: claude-fable-5
 service: claude
 timestamp: 2026-07-02T15:42:55Z
 git_ref: 65bf9df5
 diff_cmd: git diff main..wkt/to_actor_subpkg
 ---
 # Raw AI output (diff-ref mode)
 All generated code is committed on the
 `wkt/to_actor_subpkg` branch; per diff-ref mode each
 file's verbatim content is reachable via the pointers
 below rather than duplicated here.
 ## Generated files
 > `git diff main..wkt/to_actor_subpkg -- tractor/to_actor/__init__.py`
 New subpackage init: module docstring establishing the
 `trio.to_thread`/`anyio.to_process` "run it over there"
 parlance for actors, plus the single public re-export
 `run as run` from `._api`.
 > `git diff main..wkt/to_actor_subpkg -- tractor/to_actor/_api.py`
 The one-shot invocation impl, composed entirely from the
 lower level daemon-spawn + portal primitives as
 prescribed by issue #477:
 - `_validate_one_shot_fn()`: the `Portal.run()`
  non-streaming-async-fn constraint checked up-front,
  before any subactor is spawned.
 - `_invoke_in_subactor()`: `an.start_actor()` ->
  `Portal.run()` -> always-reap via
  `Portal.cancel_actor()` in a `finally` (the cancel
  req's bounded wait is internally shielded so the reap
  also runs under caller-scope cancellation).
 - `run()`: the public API. Placement options:
  `portal=` (reuse a running actor, no spawn/reap),
  `an=` (spawn from a caller-managed nursery), or
  neither (private `open_nursery()` scoped to the call,
  implicitly booting the runtime when needed, tunable
  via pass-through `runtime_kwargs`). Spawn opts mirror
  `ActorNursery.start_actor()`; `**fn_kwargs` are
  relayed to the remote task. Errors raise in the
  caller's task as boxed `RemoteActorError`s.
  `runtime_kwargs` alongside any placement opt is a
  hard `ValueError`, never silently ignored.
 > `git diff main..wkt/to_actor_subpkg -- tractor/__init__.py`
 Top-level `from . import to_actor as to_actor`
 re-export.
 > `git diff main..wkt/to_actor_subpkg -- tractor/runtime/_supervise.py`
 Comment/docstring-only: the `run_in_actor()` deprecation
 TODO now points at the implemented `.to_actor.run()`
 successor (checkbox ticked) and the method docstring
 gains a NOTE steering users to the new API; remaining
 TODO items are the `DeprecationWarning` emission +
 in-repo usage migration.
 > `git diff main..wkt/to_actor_subpkg -- tests/test_to_actor.py`
 11-test suite: private-nursery one-shot, implicit
 runtime boot via `runtime_kwargs`, remote-error relay to
 the caller's task (bare + caller-managed nursery),
 caller-nursery spawn, portal reuse w/o implicit reap,
 the concurrent worker-pool-ish pattern (local `trio`
 nursery x shared `an`), and the four validation
 rejections (sync fn, async-gen fn, `portal`+`an`
 combo, `runtime_kwargs`+placement combo).
 > `git diff main..wkt/to_actor_subpkg -- examples/parallelism/to_actor_one_shots.py`
 Runnable example (auto-collected by
 `test_docs_examples.py`): the fully-implicit one-shot
 plus the concurrent worker-pool-ish prime-check pattern
 against a shared caller-managed actor-nursery.
 ## Test runs (verbatim)
 ```
 tests/test_to_actor.py ..........                [100%]
 ============= 10 passed in 4.29s =============
 ```
 Regression subset for touched modules
 (`test_local.py test_rpc.py test_spawning.py
 test_cancellation.py`):
 ```
 38 passed, 1 xfailed, 24 warnings in 80.71s (0:01:20)
 ```
 (warnings are pre-existing stdlib `os.fork()`
 DeprecationWarnings from the mp spawn backends, not
 introduced by this change)
--- a/ai/prompt-io/claude/20260702T155006Z_65bf9df5_prompt_io.md
+++ b/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.
--- a/ai/prompt-io/claude/20260702T155006Z_65bf9df5_prompt_io.raw.md
+++ b/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).
--- a/ai/prompt-io/claude/20260702T165806Z_a34aaf98_prompt_io.md
+++ b/ai/prompt-io/claude/20260702T165806Z_a34aaf98_prompt_io.md
@ -0,0 +1,78 @@
 ---
 model: claude-fable-5
 service: claude
 session: f6c84722-471a-4458-9a80-e453fea9029f
 timestamp: 2026-07-02T16:58:06Z
 git_ref: a34aaf98
 scope: code
 substantive: true
 raw_file: 20260702T165806Z_a34aaf98_prompt_io.raw.md
 ---
 ## Prompt
 Follow-up round in the same session as the
 `tractor.to_actor` landing (see
 `20260702T154255Z_65bf9df5_prompt_io.md`). After
 committing that work the user green-lit the deferred
 items:
 > go go go on this with what time you have left, in
 > particular see if you can get the _ria_nursery
 > removal going!
 then extended the deadline twice to iterate on the
 discovered hang:
 > continue on this up until a 12:58:30 deadline
 and finally chose "Commit step A now" from the
 next-steps prompt.
 ## Response summary
 Step A of the `._ria_nursery` removal (issue #477): hoist
 `.run_in_actor()` result-reaping out of the spawn
 backends into the `ActorNursery` machinery so ria
 children spawn via the default daemon nursery,
 - new `_supervise._reap_ria_portals()` runs one
  `_spawn.cancel_on_completion()` task per ria child
  AFTER `._join_procs` is set; happy path awaits it
  right after `._join_procs.set()`.
 - error path SEQUENCES: snapshot ria
  `(portal, subactor)` pairs -> `await an.cancel()` ->
  0.5s-bounded reap. Two failed intermediates informed
  this: a concurrent reap+cancel DEADLOCKED
  `test_multierror`; a 3s bound blew
  `test_cancel_while_childs_child_in_sync_sleep`'s
  `fail_after` deadline.
 - backends (`spawn/_trio.py`, `spawn/_mp.py`) lose the
  `._cancel_after_result_on_exit` membership branch,
  per-child reaper nursery + dead imports.
 - design/probe-history doc:
  `ai/conc-anal/ria_nursery_removal_plan.md` (from an
  agent-verified machinery map).
 Verification: `test_cancellation.py` fully green
 (20 passed, 1 xfailed) incl. the previously-hung
 `test_multierror`; `test_to_actor`+`test_spawning`
 20/20; bounded full-suite gate SIGINT'd ~30s early at
 303 passed / 0 failures (user opted to commit on that
 signal, deferring the unbounded re-run to step-B
 verification).
 ## Files changed
 - `tractor/runtime/_supervise.py` — `_reap_ria_portals()`
  + two call-sites; `run_in_actor()` off the ria nursery
 - `tractor/spawn/_trio.py` — reaper branch + import drop
 - `tractor/spawn/_mp.py` — same as `_trio.py`
 - `ai/conc-anal/ria_nursery_removal_plan.md` — plan +
  probe history
 ## Human edits
 None yet — committed via the drafted
 `.claude/git_commit_msg_ria_step_a.md` (user-driven
 `git commit --edit`).
--- a/ai/prompt-io/claude/20260702T165806Z_a34aaf98_prompt_io.raw.md
+++ b/ai/prompt-io/claude/20260702T165806Z_a34aaf98_prompt_io.raw.md
@ -0,0 +1,55 @@
 ---
 model: claude-fable-5
 service: claude
 timestamp: 2026-07-02T16:58:06Z
 git_ref: a34aaf98
 diff_cmd: git diff a34aaf98..wkt/to_actor_subpkg
 ---
 # Raw AI output (diff-ref mode)
 Step-A code is committed on `wkt/to_actor_subpkg`
 directly after `a34aaf98`; per diff-ref mode the verbatim
 content is reachable via the pointers below.
 ## Generated files
 > `git diff a34aaf98..wkt/to_actor_subpkg -- tractor/runtime/_supervise.py`
 New `_reap_ria_portals(an, errors, ria_children=None)`
 helper (one `_spawn.cancel_on_completion()` task per ria
 child under `collapse_eg()` + a local nursery);
 `run_in_actor()` drops `nursery=self._ria_nursery`; happy
 path awaits the reap right after `._join_procs.set()`;
 inner error handler snapshots ria pairs, runs
 `await an.cancel()` then a `move_on_after(0.5)`-bounded
 reap over the snapshot.
 > `git diff a34aaf98..wkt/to_actor_subpkg -- tractor/spawn/_trio.py`
 > `git diff a34aaf98..wkt/to_actor_subpkg -- tractor/spawn/_mp.py`
 Both backends: the post-`_join_procs` block collapses to
 a bare `soft_kill()` (membership branch, per-child reaper
 nursery, reaper-cancel logging and the now-unused
 `cancel_on_completion` imports all removed).
 > `git diff a34aaf98..wkt/to_actor_subpkg -- ai/conc-anal/ria_nursery_removal_plan.md`
 Agent-verified machinery map, 3-step design (A/B/C),
 probe history (deadlock -> sequencing fix -> bound
 tightening) and risk register.
 ## Test runs (verbatim)
 ```
 tests/test_cancellation.py: 20 passed, 1 xfailed in 77.28s
 tests/test_to_actor.py + tests/test_spawning.py: 20 passed
 full-suite (SIGINT at 540s bound, ~30s short):
 303 passed, 9 skipped, 1 xfailed, 2 xpassed in 539.42s
 ```
 Failed intermediates (not in final diff): concurrent
 reap+`an.cancel()` deadlocked `test_multierror`; a 3s
 reap bound blew
 `test_cancel_while_childs_child_in_sync_sleep`'s
 `fail_after` deadline.
--- a/ai/prompt-io/claude/20260702T172233Z_5cd190c5_prompt_io.md
+++ b/ai/prompt-io/claude/20260702T172233Z_5cd190c5_prompt_io.md
@ -0,0 +1,60 @@
 ---
 model: claude-opus-4-8
 service: claude
 session: c7860302-6a33-4d92-821c-0807d68be464
 timestamp: 2026-07-02T17:22:33Z
 git_ref: 5cd190c5
 scope: code
 substantive: true
 raw_file: 20260702T172233Z_5cd190c5_prompt_io.raw.md
 ---
 ## Prompt
 Branched session (`to_actor_subpkg_POST_WEEKLY_CUTOFF_2OPUS`,
 now on Opus 4.8) continuing the `._ria_nursery` removal after
 step A committed + pushed (`5cd190c5`/`99310269`):
 > ok continue where your superior left off please
 then, after the commit-split discussion:
 > yup committed and pushed so take a look ma fren.
 i.e. green-lighting step-B prep against the committed step-A
 tree.
 ## Response summary
 Step B of the `._ria_nursery` removal (issue #477): delete
 the now-vestigial secondary nursery,
 - collapse the inner `async with (collapse_eg(),
  trio.open_nursery() as ria_nursery)` layer in
  `_open_and_supervise_one_cancels_all_nursery` — `da_nursery`
  becomes the single nursery for ALL subactors.
 - `ActorNursery.__init__` drops the `ria_nursery` param + the
  `self._ria_nursery` attr; `start_actor()` drops its
  `nursery=` escape-hatch param.
 - `._cancel_after_result_on_exit` kept (ria-child
  discriminator for `_reap_ria_portals()`).
 Verified behavior-preserving via a first-principles argument
 (zero-task nursery = a bare checkpoint) + the targeted gate
 (`test_cancellation test_spawning test_local test_rpc
 test_to_actor` = 49 passed, 1 xfailed on trio). The two
 error handlers were deliberately NOT merged — that changes
 propagation semantics and is deferred to its own PR (TODO
 left at the outer `except`).
 ## Files changed
 - `tractor/runtime/_supervise.py` — collapse the ria nursery
  layer + drop the ctor/`start_actor` params + refresh the
  now-stale nursery comments
 ## Human edits
 None yet — committed via the drafted
 `.claude/git_commit_msg_ria_step_b.md` (user-driven
 `git commit --edit`).
--- a/ai/prompt-io/claude/20260702T172233Z_5cd190c5_prompt_io.raw.md
+++ b/ai/prompt-io/claude/20260702T172233Z_5cd190c5_prompt_io.raw.md
@ -0,0 +1,51 @@
 ---
 model: claude-opus-4-8
 service: claude
 timestamp: 2026-07-02T17:22:33Z
 git_ref: 5cd190c5
 diff_cmd: git diff 5cd190c5..wkt/to_actor_subpkg
 ---
 # Raw AI output (diff-ref mode)
 Step-B code lives on `wkt/to_actor_subpkg` after `5cd190c5`;
 per diff-ref mode the verbatim content is reachable via the
 pointer below.
 ## Generated files
 > `git diff 5cd190c5..wkt/to_actor_subpkg -- tractor/runtime/_supervise.py`
 - `ActorNursery.__init__`: `ria_nursery` param removed;
  `self._ria_nursery = ria_nursery` block deleted;
  `_cancel_after_result_on_exit` comment refreshed.
 - `start_actor()`: `nursery=` param removed; body uses
  `self._da_nursery.start(...)` directly.
 - `_open_and_supervise_one_cancels_all_nursery()`: the inner
  `async with (collapse_eg(), trio.open_nursery() as
  ria_nursery)` layer removed; `an = ActorNursery(actor,
  da_nursery, errors)` constructed once under the single
  `da_nursery`; the inner-try body de-indented one level;
  both error handlers retained; the da-nursery lead comment
  and the outer-`except` TODO refreshed to describe the
  single-nursery reality + flag the (deferred) handler-merge.
 > `git diff 5cd190c5..wkt/to_actor_subpkg -- ai/conc-anal/ria_nursery_removal_plan.md`
 Added a "Step-B outcome" section (collapse rationale,
 handler-merge deferral, safety argument, gate result).
 ## Test runs (verbatim)
 ```
 targeted gate (trio):
 tests/test_cancellation.py tests/test_spawning.py
 tests/test_local.py tests/test_rpc.py tests/test_to_actor.py
 -> 49 passed, 1 xfailed in 88.62s
 signature checks:
 ActorNursery.__init__ params: ['self', 'actor', 'da_nursery', 'errors']
 start_actor has nursery param: False
 full-suite gate: in progress (see stepB_full.log)
 ```
--- a/ai/prompt-io/claude/20260702T222544Z_9201a2ed_prompt_io.md
+++ b/ai/prompt-io/claude/20260702T222544Z_9201a2ed_prompt_io.md
@ -0,0 +1,68 @@
 ---
 model: claude-opus-4-8
 service: claude
 session: c7860302-6a33-4d92-821c-0807d68be464
 timestamp: 2026-07-02T22:25:44Z
 git_ref: 9201a2ed
 scope: code
 substantive: true
 raw_file: 20260702T222544Z_9201a2ed_prompt_io.raw.md
 ---
 ## Prompt
 Continuing on branch `drop_ria_nursery` after step B
 (`9201a2ed`). User green-lit the deferred error-handler merge:
 > yes, i checked us out on a new branch for the ria-tn removal;
 > work off the new wkt branch drop_ria_nursery.
 and (re the migration) "nope, later we'll do this", plus:
 > do ensure the test suite is green in the current state and
 > those going forward ya?
 and the standing reminder: no commits without a human ack.
 ## Response summary
 Step B2 of the `._ria_nursery` removal (issue #477): merge the
 two nested error handlers in
 `_open_and_supervise_one_cancels_all_nursery` into one, now
 that the 2ndary nursery (whose `__aexit__` the outer handler
 originally guarded) is gone.
 Trace-driven justification (see
 `ai/conc-anal/ria_nursery_removal_plan.md` Step-B2 section):
 the old inner handler records `errors[uid]` as its FIRST
 action, so `errors` is always non-empty by the time control
 could reach the outer handler — making the outer handler's
 `raise` DEAD (always superseded by the `finally`'s
 raise-from-`errors`). Collapsing to a single
 `except BaseException as _scope_err` + the existing `finally`
 is therefore behavior-preserving.
 - removed the outer `try` + the
  `except (Exception, BaseExceptionGroup, trio.Cancelled)`
  handler; de-indented the inner handler one level.
 - dropped the now-unused `outer_err`/`inner_err` locals
  (single `_scope_err`).
 - net ~30 lines lighter.
 Gated hard: baseline (pre-B2 tip) = 300 passed + 1
 load-induced `TooSlowError` flake (passes 6/6 in isolation);
 B2 error/cancel gate (`test_cancellation remote_exc_relay
 inter_peer_cancellation advanced_faults oob_cancellation
 to_actor spawning local rpc`) = 71 passed, 1 xfailed; B2
 full-suite run following.
 ## Files changed
 - `tractor/runtime/_supervise.py` — collapse the two handlers
  into one; drop `outer_err`/`inner_err`
 ## Human edits
 None yet — committed via the drafted
 `.claude/git_commit_msg_ria_b2.md` (user-driven
 `git commit --edit`).
--- a/ai/prompt-io/claude/20260702T222544Z_9201a2ed_prompt_io.raw.md
+++ b/ai/prompt-io/claude/20260702T222544Z_9201a2ed_prompt_io.raw.md
@ -0,0 +1,55 @@
 ---
 model: claude-opus-4-8
 service: claude
 timestamp: 2026-07-02T22:25:44Z
 git_ref: 9201a2ed
 diff_cmd: git diff 9201a2ed..drop_ria_nursery
 ---
 # Raw AI output (diff-ref mode)
 Step-B2 code lives on `drop_ria_nursery` after `9201a2ed`; per
 diff-ref mode the verbatim content is reachable via the pointer
 below.
 ## Generated files
 > `git diff 9201a2ed..drop_ria_nursery -- tractor/runtime/_supervise.py`
 `_open_and_supervise_one_cancels_all_nursery`:
 - removed the outer `try:` wrapper and the
  `except (Exception, BaseExceptionGroup, trio.Cancelled) as
  _outer_err:` safety-net handler.
 - the former inner `except BaseException` is now THE handler,
  renamed local `_inner_err` -> `_scope_err`, de-indented one
  level; it sets `an._scope_error`, records `errors[uid]`,
  waits on the debugger, `_join_procs.set()`, then a shielded
  classify/log + snapshot-ria + `an.cancel()` + 0.5s-bounded
  `_reap_ria_portals()`. No re-raise (the `finally` raises
  from `errors`).
 - `finally` block unchanged.
 - dropped the `outer_err`/`inner_err` local decls at fn top.
 (The diff is large — ~119+/149- — because de-indenting the
 handler body one level rewrites every line in the block; the
 logic delta is just "two handlers -> one".)
 ## Test runs (verbatim)
 ```
 baseline (pre-B2, step-B tip 9201a2ed), full suite
 (dynamic_pub_sub deselected):
 1 failed, 300 passed, 9 skipped, 2 deselected, 1 xfailed,
 2 xpassed in 1499.49s
  -> the 1 failure = test_ext_types_over_ipc[...] trio.TooSlowError
     (load-induced; passes 6/6 in isolation in 4.89s)
 B2 error/cancel gate:
 tests/test_cancellation test_remote_exc_relay
 test_inter_peer_cancellation test_advanced_faults
 test_oob_cancellation test_to_actor test_spawning test_local
 test_rpc
 -> 71 passed, 1 xfailed in 125.26s
 B2 full-suite run: see b2_full.log
 ```
--- a/ai/prompt-io/claude/20260706T172818Z_ad42871e_prompt_io.md
+++ b/ai/prompt-io/claude/20260706T172818Z_ad42871e_prompt_io.md
@ -0,0 +1,81 @@
 ---
 model: claude-fable-5
 service: claude
 session: 6db64ac6-6986-4505-9343-df4ee31e67db
 timestamp: 2026-07-06T17:28:18Z
 git_ref: ad42871e
 scope: code
 substantive: true
 raw_file: 20260706T172818Z_ad42871e_prompt_io.raw.md
 ---
 ## Prompt
 Resuming the `drop_ria_nursery` (wkt) branch after the human's
 review pause at `ba4af0ad`, with the directive:
 > we need to resolve the remaining outstandings ... to finish
 > this endeavour we ideally,
 > - finish the ria-tn hoist into the machinery in `to_actor` if
 >   possible.
 > - avoid supporting the `.run_in_actor()` non-blocking API
 >   going forward other then if we can re-wrap `to_actor.run()`
 >   per prior discussion with opus4.8.
 > - get the test harness completely green locally and in CI -
 >   AND ESPECIALLY without any hangs due to the "the old
 >   spawn-backend reaper raced `soft_kill()`'s scope-cancel"
 > - update all docs to reflect these changes once we're happy.
 plus mid-flight additions:
 > make sure both all the test and example code uses the naming
 > `an: ActorNursery` for variable names
 > where we at in terms of a potential hackaround design for
 > supporting a to_actor.run_async() ... without requiring the
 > same malarky ... with a `trio.Event` relay ... i'm totes fine
 > with rejigging the iface to NOT return a Portal as well.
 ## Response summary
 Completed the entire #477 `run_in_actor` removal on
 `drop_ria_nursery` (16 commits this session), gated per-commit:
 - ported the remaining `test_cancellation` groups
  (`some_cancels_all`, `nested_multierrors`+`spawn_and_error`,
  SIGINT + sync-sleep) — one-shots become concurrent
  `to_actor.run()` tasks in local task-nurseries; BEG-shape
  assertions loosened for cancel-on-first + the runtime's
  `collapse_eg()` single-member unwrap (a fully-raced nested
  tree relays a bare annotated `RemoteActorError` chain).
 - fixed a pre-existing `UnboundLocalError` (`timeout` `match`
  had no default arm for non-trio/MTF backends).
 - ported `test_dynamic_pub_sub`, 4 non-debugging examples, all
  8 `debugging/` examples (debugger suite byte-identical,
  28p/6s; `multi_subactors` introduces the "collect don't
  cancel" reap-all replacement pattern), 8 docs pages + the
  `experimental/_pubsub` docstring.
 - EXCISED the API + cluster: `run_in_actor`,
  `_reap_ria_portals`, `_cancel_after_result_on_exit`,
  `Portal._submit_for_result/_expect_result_ctx/
  wait_for_result/result`, `exhaust_portal`,
  `cancel_on_completion`, `NoResult` — net -402 lines. The
  reap-hang class dissolves structurally (result-waits now only
  in caller task-scope).
 - found + fixed a real migration race: mutual-rendezvous peers
  (`test_trynamic_trio`, `a_trynamic_first_scene.py`) flaked
  because an eagerly-reaped one-shot dies while its peer still
  dials the registry-resolved (dead) sockaddr — such peers now
  pin lifetimes via `start_actor()` + concurrent `Portal.run()`
  + explicit `an.cancel()`.
 - `an: ActorNursery` naming sweep across tests/examples (±82
  lines, scoped renames, prose untouched).
 - parked a `to_actor.open_one_shot()` design sketch (acm +
  private task-nursery over blocking `run()`; done-Event as
  memo not cancel-relay; no Portal) in the plan doc.
 ## Files changed
 See commits `d01a2123..ad42871e` on `drop_ria_nursery`
 (tests, examples, docs, `tractor/{runtime,spawn,to_actor,msg}`
 + `_exceptions/_context/experimental`).
--- a/ai/prompt-io/claude/20260706T172818Z_ad42871e_prompt_io.raw.md
+++ b/ai/prompt-io/claude/20260706T172818Z_ad42871e_prompt_io.raw.md
@ -0,0 +1,39 @@
 ---
 model: claude-fable-5
 service: claude
 timestamp: 2026-07-06T17:28:18Z
 git_ref: ad42871e
 diff_cmd: git diff ba4af0ad..ad42871e
 ---
 # Raw AI output (diff-ref mode)
 This session's output spans the 16 migration/excision commits
 `d01a2123..ad42871e` on `drop_ria_nursery`; per diff-ref mode
 the verbatim content is reachable via the pointer below.
 ## Generated files
 > `git diff ba4af0ad..ad42871e`
 Commit-wise (each `Gate:`-footed msg documents its own module
 gate):
 - `d01a2123` port `test_some_cancels_all`
 - `697c6152` fix unbound `timeout` (non-trio/MTF `match` arm)
 - `fa8799d5` port `test_nested_multierrors`
 - `f11754ce` port SIGINT + sync-sleep cancel tests
 - `cb6202e3` port `test_dynamic_pub_sub`
 - `d8af5f12` port non-debugging examples
 - `a3057cb2` port debugging examples (+ `test_debugger`
  nested-nurseries final-shape expectations)
 - `d6bed7c4` port docs (8 rst pages)
 - `07e1669e` fix stale `@pub` docstring example
 - `2a59cefb` REMOVE `run_in_actor()` + the ria reap cluster
  (net -402 lines)
 - `a297a32a` fix mutual-rendezvous premature-reap race
 - `ad42871e` `an: ActorNursery` naming sweep
 Plan/design record updated in
 `ai/conc-anal/ria_nursery_removal_plan.md` (RESOLVED section +
 the `to_actor.open_one_shot()` follow-up sketch).
--- a/ai/prompt-io/opencode/20260817T231825Z_359fe75c_prompt_io.md
+++ b/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.
--- a/ai/prompt-io/opencode/20260817T231825Z_359fe75c_prompt_io.raw.md
+++ b/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.
--- a/ai/prompt-io/opencode/20260818T031532Z_4151b956_prompt_io.md
+++ b/ai/prompt-io/opencode/20260818T031532Z_4151b956_prompt_io.md
@ -0,0 +1,43 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: pr481-review-fixes-p1-20260818
 timestamp: 2026-08-18T03:15:32Z
 git_ref: 4151b956
 scope: code
 substantive: true
 raw_file: 20260818T031532Z_4151b956_prompt_io.raw.md
 ---
 ## Prompt
 Address the approved review findings on PR #481, but work
 iteratively: implement and verify one finding at a time, prepare a
 separate `/commit-plan` after each fix, and stop for the human commit
 before starting the next finding. Begin with the P1 per-child
 lifecycle issue. Also publish the already-approved review findings
 against the reviewed PR head before editing.
 ## Response summary
 Published the approved non-approving review at head `4151b956`, then
 implemented only the P1 lifecycle fix. Owned one-shot actors now use
 a child-specific cancellation and process-reap handshake, including
 hard escalation for unacknowledged cancellation and deterministic
 bookkeeping removal before `to_actor.run()` returns.
 ## Files changed
 - `tractor/runtime/_supervise.py` - coordinate child-specific cancel
  and reap.
 - `tractor/spawn/_trio.py` - wait on the Trio child's reap request.
 - `tractor/spawn/_mp.py` - wait on the multiprocessing child's reap
  request.
 - `tractor/spawn/_spawn.py` - publish monitor completion centrally.
 - `tractor/to_actor/_api.py` - await owned-child process reaping.
 - `tests/test_to_actor.py` - cover cleanup, escalation, and startup
  ordering.
 ## Human edits
 None - the generated P1 patch remains uncommitted for human review.
--- a/ai/prompt-io/opencode/20260818T031532Z_4151b956_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260818T031532Z_4151b956_prompt_io.raw.md
@ -0,0 +1,74 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-18T03:15:32Z
 git_ref: 4151b956
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Implemented only the P1 lifecycle finding from the approved PR #481
 review, preserving the requested one-fix-at-a-time commit boundary.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_supervise.py`
 Added per-child reap request/completion events to `ActorNursery`, a
 shielded child-specific cancel-and-reap operation, late-registration
 latching for nursery teardown, and cancellation escalation that waits
 for debugger release before using non-ignorable process termination.
 The nursery-wide cancellation path snapshots child records before
 checkpointing so concurrent one-shot cleanup cannot invalidate its
 iteration.
 > `git diff HEAD~1..HEAD -- tractor/spawn/_trio.py`
 Changed Trio child monitors to wait on their per-child reap requests.
 > `git diff HEAD~1..HEAD -- tractor/spawn/_mp.py`
 Changed multiprocessing child monitors to wait on their per-child reap
 requests.
 > `git diff HEAD~1..HEAD -- tractor/spawn/_spawn.py`
 Ensured every backend publishes child-reap completion after its process
 monitor exits.
 > `git diff HEAD~1..HEAD -- tractor/to_actor/_api.py`
 Changed owned one-shot cleanup to await child-specific process joining
 and bookkeeping removal instead of treating the cancel RPC as reaping.
 > `git diff HEAD~1..HEAD -- tests/test_to_actor.py`
 Added regressions for immediate caller-managed nursery cleanup, failed
 cancel acknowledgement escalation, and child registration after a
 latched nursery-wide teardown request.
 Verification:
 `pytest -q tests/test_to_actor.py tests/test_cancellation.py tests/test_spawning.py tests/discovery/test_multi_program.py`
 Result: `46 passed, 1 xfailed, 3 xpassed`.
 `pytest -q tests/test_to_actor.py --tpt-proto uds`
 Result: `13 passed`.
 `pytest -q tests/test_to_actor.py --spawn-backend mp_spawn --tpt-proto tcp`
 Result: `13 passed`.
 One broad verification run was mistakenly launched in parallel with
 the UDS and `mp_spawn` actor suites. It timed out
 `test_remote_error_from_caller_nursery`; the node passed immediately
 in isolation and the complete broad selection then passed serially.
 The failure was classified as concurrent test-session interference,
 not accepted as a passing boundary result.
 Ruff, Python compilation, and `git diff --check` passed for the changed
 boundary. Ruff's existing `_trio.py` F401 finding was reproduced at the
 unmodified PR head and excluded from attribution to this patch.
 No source files were staged, committed, pushed, or used for review
 replies. The previously approved top-level review was published before
 the fix at reviewed head `4151b956`.
--- a/ai/prompt-io/opencode/20260818T193001Z_bf06b4f8_prompt_io.md
+++ b/ai/prompt-io/opencode/20260818T193001Z_bf06b4f8_prompt_io.md
@ -0,0 +1,36 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
 timestamp: 2026-08-18T19:30:01Z
 git_ref: bf06b4f8
 scope: code
 substantive: true
 raw_file: 20260818T193001Z_bf06b4f8_prompt_io.raw.md
 ---
 ## Prompt
 Fix cancellation during an indeterminate transport write without
 allowing a second RPC msg to corrupt the stream. Keep the transport
 fix separate from the higher-level `to_actor` remediation and explain
 the length-prefixed protocol rather than using unexplained "framed
 send" terminology.
 ## Response summary
 Close a msgpack transport stream when cancellation interrupts its
 length-prefixed `send_all()` operation. The stream can no longer be
 safely reused because Trio cannot report how many bytes were written.
 ## Files changed
 - `tractor/ipc/_transport.py` - close an interrupted send stream.
 - `tests/ipc/test_each_tpt.py` - cover cancellation during the write.
 ## Human edits
 The human required this transport edge-case fix to land as its own
 behavioral commit with a detailed message. During staged review, the
 human also rejected the unexplained "framed send" wording and asked
 for terminology tied directly to the actual transport operation.
--- a/ai/prompt-io/opencode/20260818T193001Z_bf06b4f8_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260818T193001Z_bf06b4f8_prompt_io.raw.md
@ -0,0 +1,19 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-18T19:30:01Z
 git_ref: bf06b4f8
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Prospective review found that cancellation can interrupt
 `MsgpackTransport.send()` after `send_all()` writes only part of its
 length-prefixed msg. Sending a cancellation request afterward can
 append another msg to the indeterminate stream and desynchronize the
 peer decoder.
 > `git diff HEAD~1..HEAD -- tractor/ipc/_transport.py tests/ipc/test_each_tpt.py`
 Close the stream under a cancellation shield when `send_all()` is
 cancelled. Cover the behavior with a fake stream that checkpoints
 inside the write and records forced closure.
--- a/ai/prompt-io/opencode/20260818T193002Z_bf06b4f8_prompt_io.md
+++ b/ai/prompt-io/opencode/20260818T193002Z_bf06b4f8_prompt_io.md
@ -0,0 +1,37 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
 timestamp: 2026-08-18T19:30:02Z
 git_ref: bf06b4f8
 scope: code
 substantive: true
 raw_file: 20260818T193002Z_bf06b4f8_prompt_io.raw.md
 ---
 ## Prompt
 Distill repeated `Actor._contexts.pop()` machinery into a wrapper like
 the RPC-task registration helper so future teardown sites do not keep
 reconstructing the context-registry key independently. Preserve the
 existing lifecycle-specific cleanup behavior.
 ## Response summary
 Add idempotent `Actor._drop_context()` registry removal keyed from the
 context's own channel and CID. Use it for caller context teardown and
 the strict callee-side RPC deregistration path.
 ## Files changed
 - `tractor/runtime/_runtime.py` - own context-registry removal.
 - `tractor/runtime/_rpc.py` - use the helper for callee teardown.
 - `tractor/_context.py` - use the helper after caller teardown.
 ## Human edits
 The human identified the repeated registry-pop code and requested a
 central primitive analogous to `_register_rpc_task()`. The agent first
 suggested an async helper that also closed receive channels; the final
 design was narrowed to registry removal only so each lifecycle owner
 retains its existing closure, debugger, shielding, and error policy.
--- a/ai/prompt-io/opencode/20260818T193002Z_bf06b4f8_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260818T193002Z_bf06b4f8_prompt_io.raw.md
@ -0,0 +1,18 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-18T19:30:02Z
 git_ref: bf06b4f8
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Repeated teardown sites reconstruct the `Actor._contexts` registry
 key from a portal channel and context ID before popping it. Add an
 idempotent actor-owned helper deriving the key from the context itself,
 then route caller and callee context teardown through that helper.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_runtime.py tractor/runtime/_rpc.py tractor/_context.py`
 Keep receive-channel closure and cancellation shielding in each
 lifecycle owner so the helper centralizes registry machinery without
 changing their teardown ordering.
--- a/ai/prompt-io/opencode/20260818T193003Z_bf06b4f8_prompt_io.md
+++ b/ai/prompt-io/opencode/20260818T193003Z_bf06b4f8_prompt_io.md
@ -0,0 +1,38 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
 timestamp: 2026-08-18T19:30:03Z
 git_ref: bf06b4f8
 scope: code
 substantive: true
 raw_file: 20260818T193003Z_bf06b4f8_prompt_io.raw.md
 ---
 ## Prompt
 Cancel a remote task when its caller is cancelled after `Start`
 publication but before startup acknowledgement. Keep cancellation
 bounded, prevent its private `_cancel_task` RPC from recursively
 cancelling itself and preserve public target kwargs unchanged.
 ## Response summary
 Add private portal startup policy, use it for non-recursive context
 cancellation and clean caller-side startup state under a shield.
 ## Files changed
 - `tractor/runtime/_portal.py` - separate private startup policy.
 - `tractor/_context.py` - disable recursion for cancellation RPCs.
 - `tractor/runtime/_runtime.py` - clean cancelled task startup.
 - `tests/test_context_stream_semantics.py` - control cancellation
  between `Start` publication and acknowledgement.
 ## Human edits
 The human required this cancellation behavior to remain a distinct
 commit from general startup failures and from the public `to_actor`
 API. The human also requested that its runtime comment describe the
 actual length-prefixed transport guarantee and concrete `_cancel_task`
 operation rather than referring to an unnamed wrapper.
--- a/ai/prompt-io/opencode/20260818T193003Z_bf06b4f8_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260818T193003Z_bf06b4f8_prompt_io.raw.md
@ -0,0 +1,20 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-18T19:30:03Z
 git_ref: bf06b4f8
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Cancellation while `Actor.start_remote_task()` waits for `StartAck`
 can strand its caller-side context and leave the remote task running.
 Make one bounded cleanup request, remove local startup state and close
 its receive channel.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_runtime.py tractor/runtime/_portal.py tractor/_context.py tests/test_context_stream_semantics.py`
 Separate private startup-cancellation policy from public target kwargs
 using `Portal._run_from_ns()`. Have `Context.cancel()` disable recursive
 startup cancellation for its own `_cancel_task` RPC. Exercise
 cancellation after `Start` publication and prove the caller-owned actor
 remains reusable without leaked contexts.
--- a/ai/prompt-io/opencode/20260818T193004Z_bf06b4f8_prompt_io.md
+++ b/ai/prompt-io/opencode/20260818T193004Z_bf06b4f8_prompt_io.md
@ -0,0 +1,36 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
 timestamp: 2026-08-18T19:30:04Z
 git_ref: bf06b4f8
 scope: code
 substantive: true
 raw_file: 20260818T193004Z_bf06b4f8_prompt_io.raw.md
 ---
 ## Prompt
 Release caller-side context state for every remote-task startup failure,
 not only local cancellation. Preserve the remote error, avoid unsafe
 follow-up sends and prove pre-publication serialization failures leave
 a reused portal healthy.
 ## Response summary
 Extend remote-task startup cleanup across send, acknowledgement and
 validation errors. Track completed publication, perform only safe
 best-effort cancellation and deterministically remove local state.
 ## Files changed
 - `tractor/runtime/_runtime.py` - clean every startup failure path.
 - `tests/test_context_stream_semantics.py` - cover authorization and
  serialization failures before context entry.
 ## Human edits
 The human accepted the discovered edge-case fixes but required general
 startup cleanup to land separately from cancellation cleanup, transport
 integrity and the public API. This boundary preserves that behavioral
 distinction and its dedicated commit-message rationale.
--- a/ai/prompt-io/opencode/20260818T193004Z_bf06b4f8_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260818T193004Z_bf06b4f8_prompt_io.raw.md
@ -0,0 +1,19 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-18T19:30:04Z
 git_ref: bf06b4f8
 diff_cmd: git diff HEAD~1..HEAD
 ---
 `Actor.start_remote_task()` inserts a context before sending `Start`,
 but startup errors other than cancellation escape without removing or
 closing that caller state. Serialization errors, acknowledgement
 timeouts, malformed acknowledgements and remote authorization errors
 can therefore leak context-registry entries.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_runtime.py tests/test_context_stream_semantics.py`
 Cover the complete send, acknowledgement and validation phase with
 exceptional cleanup. Attempt remote cancellation only when publication
 is known complete or protocol-safe, and always release local state.
--- a/ai/prompt-io/opencode/20260818T193005Z_bf06b4f8_prompt_io.md
+++ b/ai/prompt-io/opencode/20260818T193005Z_bf06b4f8_prompt_io.md
@ -0,0 +1,52 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
 timestamp: 2026-08-18T19:30:05Z
 git_ref: bf06b4f8
 scope: code
 substantive: true
 raw_file: 20260818T193005Z_bf06b4f8_prompt_io.raw.md
 ---
 ## Prompt
 Replace abandoned `Portal.run()` one-shots with a static linked-context
 endpoint. Follow Trio positional-call semantics, use partials for target
 keywords, preserve Python 3.14 Placeholder behavior, keep target lookup
 behind the RPC allowlist and support private, nursery and portal
 placement.
 ## Response summary
 Use `Portal.open_context()` and `Context.wait_for_result()` for one-shot
 tasks. Normalize every partial layer, validate signatures locally and
 send target namespace/function components separately to the authorized
 remote resolver. Retain the client-side function in its `NamespacePath`
 so `to_tuple()` does not re-import it. Owned actors enable the declaring
 `_api.__name__` directly; caller-owned portals opt in through the public
 `to_actor.MODULE` alias.
 ## Files changed
 - `tractor/to_actor/_api.py` - implement linked one-shot calls.
 - `tractor/to_actor/__init__.py` - export `MODULE`.
 - `tractor/msg/ptr.py` - retain refs created by `from_ref()`.
 - `tests/test_to_actor.py` - cover the public API and authorization.
 - `examples/parallelism/to_actor_one_shots.py` - use positional inputs.
 ## Human edits
 The human rejected nested target-kwargs configuration and selected
 Trio-style positional inputs plus `functools.partial()`. During staged
 review the human required a Python 3.14 compatibility comment rather
 than removing Placeholder support, requested separate namespace and
 function inputs, preserved `_get_rpc_func(ns: str, funcname: str)`
 authorization, renamed `RPC_MODULE` to `MODULE`, rejected global module
 exposure and deferred speculative nursery/module-list helpers to the
 `open_taskman()` design line. The human also required this public API
 to land only after its lower-level safety dependencies. In final staged
 review, the human required `_invoke_from_portal()` to use
 `NamespacePath.to_tuple()` with the already-held function ref and
 required internal actor setup to use `_api.__name__` directly, keeping
 `to_actor.MODULE` solely as the public importer-facing alias.
--- a/ai/prompt-io/opencode/20260818T193005Z_bf06b4f8_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260818T193005Z_bf06b4f8_prompt_io.raw.md
@ -0,0 +1,24 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-18T19:30:05Z
 git_ref: bf06b4f8
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Implement `to_actor.run()` with Trio-style positional target arguments,
 `functools.partial` keyword and Python 3.14 Placeholder binding, and a
 static context endpoint that links remote results, errors and caller
 cancellation.
 > `git diff HEAD~1..HEAD -- tractor/to_actor/_api.py tractor/to_actor/__init__.py`
 Resolve target functions through `Actor._get_rpc_func()` so module
 authorization remains authoritative. Automatically expose the helper
 module for actors owned by `to_actor.run()` and document explicit
 exposure for a caller-owned portal.
 > `git diff HEAD~1..HEAD -- tests/test_to_actor.py examples/parallelism/to_actor_one_shots.py`
 Cover placement modes, argument binding, nested partials, caller-linked
 cancellation, remote errors and module authorization.
--- a/ai/prompt-io/opencode/20260819T020757Z_b38efed7_prompt_io.md
+++ b/ai/prompt-io/opencode/20260819T020757Z_b38efed7_prompt_io.md
@ -0,0 +1,34 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: ses_3e4c90d3eafeqHEtRYSIHgHhpA
 timestamp: 2026-08-19T02:07:57Z
 git_ref: b38efed7
 scope: code
 substantive: true
 raw_file: 20260819T020757Z_b38efed7_prompt_io.raw.md
 ---
 ## Prompt
 Resolve the remaining P3 review finding before landing PR #481:
 `runtime_kwargs={}` must not be silently accepted alongside either
 `an=` or `portal=` merely because the dict is falsey. Keep this as its
 own final review-remediation commit.
 ## Response summary
 Treat any non-`None` `runtime_kwargs` value as provided when validating
 placement. Cover both placement APIs with empty and configured dicts,
 proving the error is raised locally before actor startup.
 ## Files changed
 - `tractor/to_actor/_api.py` - validate option presence explicitly.
 - `tests/test_to_actor.py` - cover four invalid option combinations.
 ## Human edits
 No direct line edits. The human accepted the P3 finding, required it to
 remain separate from the five P2 behavioral commits and prioritized it
 before the final PR #484 integration rebase and PR #481 landing steps.
--- a/ai/prompt-io/opencode/20260819T020757Z_b38efed7_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260819T020757Z_b38efed7_prompt_io.raw.md
@ -0,0 +1,25 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-19T02:07:57Z
 git_ref: b38efed7
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Fix the final PR #481 review finding: `runtime_kwargs` is mutually
 exclusive with both caller placement options whenever it is provided,
 including an empty dict.
 > `git diff HEAD~1..HEAD -- tractor/to_actor/_api.py tests/test_to_actor.py`
 Use an explicit `is not None` check rather than dict truthiness. Expand
 the validation regression across `an=` and `portal=`, each with empty
 and configured runtime kwargs, so every invalid combination fails
 before actor runtime startup.
 Verification:
 - Trio/TCP: `23 passed`
 - Trio/UDS: `23 passed`
 - `mp_spawn`/TCP: `23 passed`
 - Ruff and `git diff --check`: clean
--- a/ai/prompt-io/opencode/20260819T184640Z_481ba003_prompt_io.md
+++ b/ai/prompt-io/opencode/20260819T184640Z_481ba003_prompt_io.md
@ -0,0 +1,56 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-19T18:46:40Z
 git_ref: 481ba003
 scope: code
 substantive: true
 raw_file: 20260819T184640Z_481ba003_prompt_io.raw.md
 ---
 ## Prompt
 Rebase PR #484 onto final PR #481, migrate every affected one-shot call
 to the new positional target API and continue through downstream tests,
 examples and documentation review.
 ## Response summary
 Converted stale target keyword calls to target partials so previously
 named inputs remain explicit while placement/runtime controls stay
 direct. Updated error expectations for local signature validation and
 linked remote error propagation, then corrected docs which still
 described the removed one-shot implementation. Linked spawning and
 context lifecycle prose to the corresponding API methods and detailed
 context guide.
 ## Files changed
 - `docs/api/core.rst` - describe linked one-shot context execution.
 - `docs/guide/rpc.rst` - update placement and target call semantics.
 - `docs/guide/spawning.rst` - document positional target inputs.
 - `examples/debugging/multi_nested_subactors_error_up_through_nurseries.py` - migrate nested actor target inputs.
 - `examples/debugging/root_cancelled_but_child_is_in_tty_lock.py` - preserve named recursive target inputs with partials.
 - `tests/test_advanced_streaming.py` - migrate streaming target inputs.
 - `tests/test_cancellation.py` - migrate calls and tighten errors.
 - `tests/test_infected_asyncio.py` - bind asyncio target options.
 - `tests/test_rpc.py` - migrate RPC target argument binding.
 - `tests/test_runtime.py` - preserve named runtime target inputs.
 - `tests/test_spawning.py` - preserve named spawning target inputs.
 ## Human edits
 The human selected the stack order and final PR #481 base, asked the
 agent to continue after each diagnostic step and required a complete
 commit plan after independently force-pushing the rebased history.
 After reviewing the migration, the human required every formerly named
 target input to remain visibly named through `functools.partial()`
 rather than becoming positional. These were human-directed agent edits;
 the human also required plain `start_actor()` and `open_context()`
 references in the spawning and RPC guides to link to their API methods
 and the detailed context guide, then clarified that `to_actor.run()`
 already uses the full context API while `Portal.run()` should share
 linked lifecycle machinery without necessarily delegating through
 `Portal.open_context()` or adding a `Started` message. The human made
 no direct source-line edits.
--- a/ai/prompt-io/opencode/20260819T184640Z_481ba003_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260819T184640Z_481ba003_prompt_io.raw.md
@ -0,0 +1,30 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-19T18:46:40Z
 git_ref: 481ba003
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Migrate PR #484's downstream one-shot calls to PR #481's final
 `tractor.to_actor.run()` contract after the stack rebase.
 > `git diff HEAD~1..HEAD -- docs examples tests`
 Pass target arguments positionally and bind target keyword-only inputs
 with `functools.partial()`. Keep placement and runtime controls as
 direct `to_actor.run()` keywords. Update the invalid-target-argument
 test to expect local signature binding before actor startup and require
 direct `RemoteActorError` propagation from linked one-shots.
 Update API and guide prose to describe positional target inputs,
 linked `Portal.open_context()` execution and per-child reaping instead
 of the removed `Portal.run()` and target-`**kwargs` conventions.
 Verification:
 - core and migrated runtime batches: `97 passed`
 - discovery and related lifecycle batch: `33 passed, 1 skipped`
 - changed executable examples: `9 passed`
 - mapped debugger cases: `12 passed, 6 skipped`
 - Ruff, compilation and `git diff --check`: clean
--- a/ai/prompt-io/opencode/20260819T234823Z_557065d8_prompt_io.md
+++ b/ai/prompt-io/opencode/20260819T234823Z_557065d8_prompt_io.md
@ -0,0 +1,37 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-19T23:48:23Z
 git_ref: 557065d8
 scope: tests
 substantive: true
 raw_file: 20260819T234823Z_557065d8_prompt_io.raw.md
 ---
 ## Prompt
 Investigate PR #481's red CI run, explain the missing T-800 and
 debugger-output failures, and proceed with fixes in the PR #481
 worktree.
 ## Response summary
 Updated stale teardown assertions to match #481's direct hard-reap
 path and observable process-lifetime invariants. Made nested debugger
 checks consume the complete pexpect transcript rather than only the
 last prompt latch.
 ## Files changed
 - `tests/devx/test_debugger.py` - assert EOF/dead-process teardown and
  accumulate nested debugger output across prompt boundaries.
 - `tests/devx/test_tooling.py` - assert cancel-timeout hard-reap
  escalation instead of the bypassed T-800 backend marker.
 ## Human edits
 The human reported the still-red PR #481 CI, supplied a failing job URL,
 required work in `/wkts/pr481_review_fixes` and directed the agent to
 continue immediately. No direct source-line edits were made by the
 human.
--- a/ai/prompt-io/opencode/20260819T234823Z_557065d8_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260819T234823Z_557065d8_prompt_io.raw.md
@ -0,0 +1,26 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-19T23:48:23Z
 git_ref: 557065d8
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Diagnose and fix the stale debugger and reaper assertions failing PR
 #481's Unix CI jobs.
 > `git diff HEAD~1..HEAD -- tests/devx/test_debugger.py tests/devx/test_tooling.py`
 Replace the old T-800 backend-log requirement with the new bounded
 cancel-ack escalation evidence. Prove debugger teardown with EOF and a
 dead child process instead of requiring optional `KeyboardInterrupt`
 text. Accumulate all pexpect prompt chunks for nested error propagation
 so expected tracebacks are not lost when `child.before` advances.
 Verification:
 - exact failed debugger/reaper nodes: `4 passed`
 - debugger/tooling TCP: `39 passed, 6 skipped`
 - debugger/tooling UDS: `39 passed, 6 skipped`
 - full TCP suite: `478 passed, 9 skipped, 7 xfailed, 3 xpassed`
 - full UDS rerun: `476 passed, 11 skipped, 8 xfailed, 2 xpassed`
--- a/ai/prompt-io/opencode/20260819T234824Z_557065d8_prompt_io.md
+++ b/ai/prompt-io/opencode/20260819T234824Z_557065d8_prompt_io.md
@ -0,0 +1,43 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-19T23:48:24Z
 git_ref: 557065d8
 scope: code
 substantive: true
 raw_file: 20260819T234824Z_557065d8_prompt_io.raw.md
 ---
 ## Prompt
 Investigate and fix PR #481's macOS TCP clustering and stream-overrun
 failures without sacrificing IPC frame integrity or structured
 concurrency.
 ## Response summary
 Changed cancellation during `send_all()` from actor-wide stream closure
 to shielded complete-frame publication followed by immediate pending
 cancellation. Prevented failed overrun error shipment from promoting a
 secondary transport closure over the context-local primary condition.
 ## Files changed
 - `tractor/ipc/_transport.py` - complete in-flight frames before
  delivering sender cancellation.
 - `tractor/_context.py` - absorb transport closure while reporting an
  overrun on an already-closing channel.
 - `tests/ipc/test_each_tpt.py` - prove complete framing, cancellation
  delivery and channel reuse.
 - `tests/test_context_stream_semantics.py` - prove overrun reporting
  tolerates a closed transport.
 ## Human edits
 The human reported PR #481's red CI, asked for diagnosis and directed
 the agent to proceed in the dedicated PR #481 worktree. During final
 review, the human required preservation of the original far-end
 cancellation rationale and fuller documentation of frame shielding,
 shared-channel ownership and cancellation-delay tradeoffs. These were
 human-directed agent edits; the human made no direct source-line edits.
--- a/ai/prompt-io/opencode/20260819T234824Z_557065d8_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260819T234824Z_557065d8_prompt_io.raw.md
@ -0,0 +1,31 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-19T23:48:24Z
 git_ref: 557065d8
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Fix the macOS TCP regressions where cancellation during a framed send
 closed the actor-wide channel and replaced primary stream errors with
 secondary `TransportClosed` failures.
 > `git diff HEAD~1..HEAD -- tractor/ipc/_transport.py tractor/_context.py tests/ipc/test_each_tpt.py tests/test_context_stream_semantics.py`
 Shield complete frame publication, then deliver pending cancellation
 immediately after leaving the shield. Preserve channel reuse instead of
 closing the multiplexed socket from a context-local sender. Treat
 `TransportClosed` while shipping `StreamOverrun` as failed delivery so
 the secondary error can not crash the actor-wide RPC loop.
 Add deterministic unit regressions for cancellation in the middle of a
 frame and overrun reporting after transport closure.
 Verification:
 - transport/context unit regressions: `3 passed`
 - exact TCP and UDS CI-node batches: `11 passed, 1 skipped`
 - transport/context/clustering/RPC TCP: `88 passed`
 - transport/context/clustering/RPC UDS: `86 passed, 2 skipped`
 - full TCP suite: `478 passed, 9 skipped, 7 xfailed, 3 xpassed`
 - full UDS rerun: `476 passed, 11 skipped, 8 xfailed, 2 xpassed`
--- a/ai/prompt-io/opencode/20260820T023004Z_88a23449_prompt_io.md
+++ b/ai/prompt-io/opencode/20260820T023004Z_88a23449_prompt_io.md
@ -0,0 +1,32 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-20T02:30:04Z
 git_ref: 88a23449
 scope: tests
 substantive: true
 raw_file: 20260820T023004Z_88a23449_prompt_io.raw.md
 ---
 ## Prompt
 Inspect the two failed macOS jobs in PR #481's new CI run and continue
 toward a green landing candidate.
 ## Response summary
 Confirmed both jobs fail only the known nested crash-REPL scenario from
 issue #320, while Ubuntu TCP/UDS and Windows pass. Added a targeted
 macOS-CI skip without reducing Linux coverage.
 ## Files changed
 - `tests/devx/test_debugger.py` - skip the issue #320 nested
  crash-REPL node on Darwin CI.
 ## Human edits
 The human monitored the new CI run, reported both macOS jobs dead and
 directed the agent to continue diagnosis. No direct source-line edits
 were made by the human.
--- a/ai/prompt-io/opencode/20260820T023004Z_88a23449_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260820T023004Z_88a23449_prompt_io.raw.md
@ -0,0 +1,23 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-20T02:30:04Z
 git_ref: 88a23449
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Diagnose the remaining macOS PR #481 CI failures after the Linux
 debugger and transport fixes passed.
 > `git diff HEAD~1..HEAD -- tests/devx/test_debugger.py`
 Both macOS transports failed the same deeply nested crash-REPL test
 already tracked by issue #320: TCP omitted one actor-specific traceback
 record and UDS timed out waiting for a nested prompt. Apply an explicit
 Darwin-CI skip to this one node while retaining Linux TCP/UDS coverage.
 Verification:
 - debugger/tooling TCP: `39 passed, 6 skipped`
 - debugger/tooling UDS: `39 passed, 6 skipped`
 - Ruff, compilation and `git diff --check`: clean
--- a/ai/prompt-io/opencode/20260820T023005Z_88a23449_prompt_io.md
+++ b/ai/prompt-io/opencode/20260820T023005Z_88a23449_prompt_io.md
@ -0,0 +1,40 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-20T02:30:05Z
 git_ref: 88a23449
 scope: docs
 substantive: true
 raw_file: 20260820T023005Z_88a23449_prompt_io.raw.md
 ---
 ## Prompt
 Audit all documentation and executable examples once more, replacing
 prescriptive `run_in_actor()` usage with `to_actor.run()` or explicit
 actor/context lifetime APIs before PR #481 lands.
 ## Response summary
 Rewrote one-shot documentation around direct blocking result delivery,
 linked context execution and per-call reaping. Migrated all runnable
 examples, using daemon actors where reciprocal dialogs require longer
 lifetimes. Added API/guide cross-links and retained only three explicit
 legacy references.
 ## Files changed
 - `docs/` - update API, quickstart and subsystem guides to showcase
  `tractor.to_actor.run()` and link its underlying core APIs.
 - `examples/` - migrate one-shot calls and preserve explicit daemon
  lifetimes for reciprocal or long-lived actor dialogs.
 ## Human edits
 The human requested a final docs pass covering every place that should
 showcase `to_actor` over `.run_in_actor()`. Earlier review also required
 named target arguments to remain visible through `functools.partial()`
 and core API references to link to local guides/reference pages. These
 were human-directed agent edits; the human made no direct source-line
 edits.
--- a/ai/prompt-io/opencode/20260820T023005Z_88a23449_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260820T023005Z_88a23449_prompt_io.raw.md
@ -0,0 +1,27 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-20T02:30:05Z
 git_ref: 88a23449
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Perform a final rendered-documentation and executable-example pass so
 PR #481 showcases `tractor.to_actor.run()` instead of the legacy
 `ActorNursery.run_in_actor()` API.
 > `git diff HEAD~1..HEAD -- docs examples`
 Migrate one-shot guides and examples to direct result delivery through
 `to_actor.run()`, preserving named target inputs with target partials.
 Use daemon actors and concurrent portal calls where reciprocal actor
 lifetimes require both peers to coexist. Add API and guide cross-links,
 and retain only explicit legacy/removal notes.
 Verification:
 - executable docs examples: `23 passed`
 - debugger/tooling TCP: `39 passed, 6 skipped`
 - debugger/tooling UDS: `39 passed, 6 skipped`
 - Ruff, compilation and `git diff --check`: clean
 - local Sphinx build unavailable because Sphinx is not installed
--- a/ai/prompt-io/opencode/20260820T135125Z_9f99043b_prompt_io.md
+++ b/ai/prompt-io/opencode/20260820T135125Z_9f99043b_prompt_io.md
@ -0,0 +1,35 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-20T13:51:25Z
 git_ref: 9f99043b
 scope: tests
 substantive: true
 raw_file: 20260820T135125Z_9f99043b_prompt_io.raw.md
 ---
 ## Prompt
 Continue preparing PR #481 for landing after the prior test and
 documentation commits were pushed. Follow CI and proceed with clear next
 steps without merging or changing remote content unasked.
 ## Response summary
 Followed CI through completion and found both macOS jobs failed because the
 new `skipif` expression returned the `CI=true` environment string. Corrected
 the condition to pass pytest a boolean before evaluating the marker. A
 simulated Darwin-CI run now skips cleanly, and the sequential TCP and UDS
 debugger/tooling suites each pass with 39 passed and 6 skipped.
 ## Files changed
 - `tests/devx/test_debugger.py` - coerce the Darwin-CI skip condition to a
  boolean.
 ## Human edits
 The human pushed the preceding commits, directed the agent to continue, and
 approved recording this test-only follow-up in Prompt-IO. No direct
 source-line edits were made by the human.
--- a/ai/prompt-io/opencode/20260820T135125Z_9f99043b_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260820T135125Z_9f99043b_prompt_io.raw.md
@ -0,0 +1,22 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-20T13:51:25Z
 git_ref: 9f99043b
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Continue preparing PR #481 for landing after the test and documentation
 commits were pushed. Follow the new CI run to completion and diagnose any
 failures.
 > `git diff HEAD~1..HEAD -- tests/devx/test_debugger.py`
 Both macOS jobs failed while evaluating the new `skipif` marker. The
 expression returned the `CI=true` environment string instead of a boolean,
 so pytest evaluated `true` as Python source and raised `NameError` during
 test setup. Coerce `_ci_env` to `bool` so pytest receives a boolean marker
 condition on Darwin CI.
 Verification should exercise the condition with `CI=true` and a simulated
 Darwin platform, then rerun the debugger/tooling TCP and UDS suites.
--- a/ai/prompt-io/opencode/20260820T143845Z_559fd0f1_prompt_io.md
+++ b/ai/prompt-io/opencode/20260820T143845Z_559fd0f1_prompt_io.md
@ -0,0 +1,43 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-20T14:38:50Z
 git_ref: 559fd0f1
 scope: code
 substantive: true
 raw_file: 20260820T143845Z_559fd0f1_prompt_io.raw.md
 ---
 ## Prompt
 Continue preparing PR #481 after the latest fix was pushed. Follow CI and
 proceed with clear next steps toward a green landing candidate.
 ## Response summary
 Traced the remaining macOS UDS failure to cancellation racing transport
 teardown inside the shielded framed-send path. Preserve pending cancellation
 over a transport error caused by concurrent teardown, and add a deterministic
 regression for that ordering. A follow-up A/B run showed the corrected
 cancellation precedence changes which nested debugger intermediary is
 rendered as the immediate source versus relay, so retain coverage for both
 actor levels without pinning those racy roles. The adjusted UDS node passes
 three consecutive runs, and both debugger/tooling transport suites pass with
 39 passed and 6 skipped.
 ## Files changed
 - `tractor/ipc/_transport.py` - deliver pending cancellation before
  translating a shielded send's transport error.
 - `tests/ipc/test_each_tpt.py` - reproduce cancellation followed by local
  stream closure during shielded frame publication.
 - `tests/devx/test_debugger.py` - accept either valid source/relay role for
  each nested intermediary while retaining the actor and error assertions.
 ## Human edits
 The human pushed the preceding fix, ran the proposed verification plan, and
 reported a repeated UDS debugger failure. That report prompted the A/B
 comparison and role-insensitive assertion. No direct source-line edits were
 made by the human.
--- a/ai/prompt-io/opencode/20260820T143845Z_559fd0f1_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260820T143845Z_559fd0f1_prompt_io.raw.md
@ -0,0 +1,26 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-20T14:38:50Z
 git_ref: 559fd0f1
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Continue preparing PR #481 after pushing the macOS debugger skip fix.
 Follow the replacement CI run and address any remaining PR-specific
 failure.
 > `git diff HEAD~1..HEAD -- tractor/ipc/_transport.py`
 > `git diff HEAD~1..HEAD -- tests/ipc/test_each_tpt.py`
 macOS UDS failed `test_reqresp_ontopof_streaming` when its two-second
 `move_on_after()` scope cancelled during `stream.send('ping')`. Commit
 `88a23449` shields framed `send_all()` and checks pending cancellation only
 after a successful write. Concurrent transport teardown instead closed the
 socket, causing `ClosedResourceError` to escape as `TransportClosed` before
 the pending cancellation could be delivered.
 Preserve structured cancellation precedence on the shielded send's
 transport-error path, and add a deterministic regression that cancels the
 sender before making the fake stream raise `ClosedResourceError`.
--- a/ai/prompt-io/opencode/20260820T150250Z_9afda1c6_prompt_io.md
+++ b/ai/prompt-io/opencode/20260820T150250Z_9afda1c6_prompt_io.md
@ -0,0 +1,33 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 7b9c97c4-fff7-4ac4-97fb-35720453308e
 timestamp: 2026-08-20T15:02:50Z
 git_ref: pformat_caller_frame_render_guard
 scope: code
 substantive: true
 raw_file: 20260820T150250Z_9afda1c6_prompt_io.raw.md
 ---
 ## Prompt
 Fix both newly exposed send-side `MsgTypeError` formatting failures
 and pin them with an end-to-end regression in PR #503.
 ## Response summary
 Corrected codec-spec formatting and default error-message assembly so
 `_mk_send_mte()` returns a printable error instead of raising another
 formatter exception.
 ## Files changed
 - `tractor/msg/_codec.py` - pass the codec to its supported formatter.
 - `tractor/_exceptions.py` - assemble the default message as `str`.
 - `tests/devx/test_pformat.py` - render the complete default error.
 ## Human edits
 The human selected both one-line fixes and the single end-to-end test
 as coherent additions to PR #503, while leaving broader formatter
 cleanup out of scope.
--- a/ai/prompt-io/opencode/20260820T150250Z_9afda1c6_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260820T150250Z_9afda1c6_prompt_io.raw.md
@ -0,0 +1,25 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-20T15:02:50Z
 git_ref: pformat_caller_frame_render_guard
 diff_cmd: git diff HEAD~1..HEAD
 ---
 ## Prompt
 After reviewing additional `tractor.devx.pformat` work suitable for
 PR #503, the user approved fixing both send-side `MsgTypeError`
 formatting failures and adding an end-to-end regression.
 ## Response
 The generated code corrects the `MsgCodec.msg_spec_str` formatter
 input, keeps `_mk_send_mte()`'s assembled default message a string,
 and tests that the resulting `MsgTypeError` can be rendered:
 > `git diff HEAD~1..HEAD -- tractor/msg/_codec.py tractor/_exceptions.py tests/devx/test_pformat.py`
 These failures were hidden behind the original
 `pformat_caller_frame()` keyword error addressed by the first two
 commits on the branch.
--- a/ai/prompt-io/opencode/20260821T023537Z_ae6f2ac3_prompt_io.md
+++ b/ai/prompt-io/opencode/20260821T023537Z_ae6f2ac3_prompt_io.md
@ -0,0 +1,65 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-21T02:35:37Z
 git_ref: ae6f2ac3
 scope: code
 substantive: true
 raw_file: 20260821T023537Z_ae6f2ac3_prompt_io.raw.md
 ---
 ## Prompt
 Simplify bounded actor cancellation by passing an explicit absolute
 deadline from `Portal.cancel_actor()` through `_run_from_ns()`,
 `Actor.start_remote_task()`, and `Channel.send()` into
 `MsgpackTransport.send()`. Avoid a `ContextVar`, watcher tasks, shared
 status, coalescing, and waiter state. After tracing the current
 `Start -> StartAck -> CancelAck` transaction, rename the local result to
 `cancel_ack_received`, document its exact semantics, and link a focused
 follow-up for a dedicated `Cancel -> CancelAck` protocol.
 ## Response summary
 Threaded one absolute Trio deadline through the existing private
 actor-cancel RPC path. The transport retains complete-frame shielding
 for ordinary sends, while a cancel-control send that overruns its
 deadline force-closes the potentially corrupted stream before releasing
 the send lock. The outer actor-cancel scope uses the same deadline for
 ack waiting and redelivers pending caller cancellation afterward.
 Renamed the completion flag to `cancel_ack_received` and documented that
 the current private call consumes `StartAck`, then receives a real
 `CancelAck` after `Actor.cancel()` completes; this does not establish
 that the OS process exited. Added a source TODO linking issue #506 for
 the future first-class `Cancel -> CancelAck` transaction.
 Focused transport and actor-cancel verification passed all four tests.
 ## Files changed
 - `tractor/runtime/_portal.py` - own the absolute deadline, accurately
  record ack receipt, and link the dedicated cancellation protocol.
 - `tractor/runtime/_runtime.py` - forward the optional deadline for the
  exact private `Start` publication.
 - `tractor/ipc/_chan.py` - pass the operation-specific deadline to the
  transport without changing ordinary sends.
 - `tractor/ipc/_transport.py` - bound the shielded frame publication and
  close a partial-frame stream before unlocking it.
 - `tests/ipc/test_each_tpt.py` - cover deadline expiry after a partial
  frame prefix reaches the stream.
 - `tests/test_to_actor.py` - prove actor-cancel publication and ack
  waiting share one absolute timeout budget.
 ## Human edits
 The human rejected the initial watcher-task, shared `_SendStatus`, cancel
 coalescing, and per-waiter design as unnecessary complexity. They also
 rejected `ContextVar` propagation in favor of explicit functional
 threading, selected a single absolute deadline for publication and ack
 waiting, and required item 2 to remain separate from the item-3 child
 reaping work. After reviewing the result, they requested the precise
 `cancel_ack_received` name, a detailed protocol-trace comment, a focused
 follow-up issue, and a linked source TODO. No direct source-line edits
 were made by the human.
--- a/ai/prompt-io/opencode/20260821T023537Z_ae6f2ac3_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260821T023537Z_ae6f2ac3_prompt_io.raw.md
@ -0,0 +1,41 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-21T02:35:37Z
 git_ref: ae6f2ac3
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Replace the actor-cancel timeout watcher/status experiment with one
 explicit absolute deadline threaded through the existing private call
 path. Do not use a `ContextVar`, shared result state, waiter
 coalescing, or polling tasks.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_portal.py`
 `Portal.cancel_actor()` computes one absolute deadline and uses it for
 both `Start` frame publication and the subsequent cancel-ack wait.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_runtime.py`
 > `git diff HEAD~1..HEAD -- tractor/ipc/_chan.py`
 The private RPC path forwards the operation-specific deadline. Lower
 layers preserve the ordinary infinite-deadline call shape.
 > `git diff HEAD~1..HEAD -- tractor/ipc/_transport.py`
 `MsgpackTransport.send()` applies the deadline inside its complete-frame
 shield. If the deadline expires after partial publication, it closes
 the unusable stream before releasing the send lock.
 > `git diff HEAD~1..HEAD -- tests/ipc/test_each_tpt.py`
 > `git diff HEAD~1..HEAD -- tests/test_to_actor.py`
 Focused regressions prove a partial-frame timeout closes the stream and
 that actor-cancel publication and acknowledgement share one budget.
 The implementation removes the earlier `_SendStatus`, watcher task,
 coalescing, shared cancel result, and per-waiter state. Four focused
 transport and actor-cancel tests pass.
--- a/ai/prompt-io/opencode/20260821T040803Z_3c1bbe73_prompt_io.md
+++ b/ai/prompt-io/opencode/20260821T040803Z_3c1bbe73_prompt_io.md
@ -0,0 +1,57 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-21T04:08:03Z
 git_ref: 3c1bbe73
 scope: code
 substantive: true
 raw_file: 20260821T040803Z_3c1bbe73_prompt_io.raw.md
 ---
 ## Prompt
 Continue PR #481 review cleanup one item at a time. Compare the
 remaining child-registration/reaping experiment against PR #484,
 identify the next valid behavior, and generate an exact commit plan for
 that boundary without committing automatically.
 ## Response summary
 Separated late-child admission from the broader bounded-reap rewrite.
 Added one synchronous `ActorNursery._register_child()` publication step
 that stores the child and its reap events before sampling nursery
 cancellation. This closes both scheduler orderings around
 `ActorNursery.cancel()`'s child snapshot.
 The MP backend registers immediately before synchronous process startup
 and refuses to start when cancellation already owns the child. The Trio
 backend registers immediately after `open_process()` and kills that
 already-created process when registration observes cancellation. An
 early `start_actor()` guard rejects calls begun after cancellation is
 already visible.
 Deterministic tests cover the nursery registration ordering and the MP
 no-start invariant. Comparison with PR #484 confirmed that its retained
 generic nursery/backends do not close this race.
 ## Files changed
 - `tractor/runtime/_supervise.py` - atomically publish child ownership
  and reject actor starts after nursery cancellation.
 - `tractor/spawn/_mp.py` - register before synchronous process startup
  and abort a cancellation-owned child.
 - `tractor/spawn/_trio.py` - register immediately after process creation,
  kill a cancellation-owned child, and remove its stale unused import.
 - `tests/test_to_actor.py` - cover late registration and MP startup
  suppression.
 ## Human edits
 The human required review extras to be handled one item and one
 behavioral commit at a time, with each item compared against PR #484
 before acceptance. That direction split this late-registration fix from
 the original broad experiment's bounded post-ack reaping,
 `ActorNursery.cancel()` hard-reap rewrite, and debugger/error behavior.
 The human accepted the narrower late-registration boundary by requesting
 its commit plan. No direct source-line edits were made by the human.
--- a/ai/prompt-io/opencode/20260821T040803Z_3c1bbe73_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260821T040803Z_3c1bbe73_prompt_io.raw.md
@ -0,0 +1,48 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-21T04:08:03Z
 git_ref: 3c1bbe73
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Compare the remaining child-registration and reaping experiment with
 PR #484, then identify the next review item without changing code.
 The next item is the late-child admission race. A spawn can pass
 `ActorNursery.start_actor()`'s early cancellation check, then be absent
 from `ActorNursery.cancel()`'s child snapshot and register afterward.
 The existing reap-request latch releases its monitor but does not send
 runtime cancellation, so the monitor can wait forever for a still-live
 process.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_supervise.py`
 `ActorNursery._register_child()` publishes the child, installs its reap
 events, and samples `ActorNursery._cancel_called` without a checkpoint.
 The two scheduler orderings are then complete: registration first puts
 the child in the cancel snapshot, while cancellation first makes the
 backend abort the late registration.
 > `git diff HEAD~1..HEAD -- tractor/spawn/_mp.py`
 The multiprocessing backend registers immediately before `proc.start()`
 and refuses to start a process already owned by nursery cancellation.
 There is no Trio checkpoint between registration and process startup.
 > `git diff HEAD~1..HEAD -- tractor/spawn/_trio.py`
 The Trio backend registers immediately after `open_process()` and kills
 the newly opened process if cancellation won the registration race. Its
 stale unused `get_runtime_vars` import is removed so the touched module
 remains lint-clean.
 > `git diff HEAD~1..HEAD -- tests/test_to_actor.py`
 Deterministic regressions prove late registration observes cancellation
 and that the MP backend never starts a process after cancellation owns
 its registration.
 PR #484 retains the affected generic nursery and spawn-backend paths and
 does not close this race. Keep this fix in PR #481 as its own commit;
 review bounded post-`CancelAck` reaping separately.
--- a/ai/prompt-io/opencode/20260822T022526Z_5562fd9a_prompt_io.md
+++ b/ai/prompt-io/opencode/20260822T022526Z_5562fd9a_prompt_io.md
@ -0,0 +1,42 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: 76c5d31c-5a2f-4503-9b16-410ee7f4fab3
 timestamp: 2026-08-22T02:25:26Z
 git_ref: 5562fd9a
 scope: config
 substantive: true
 raw_file: 20260822T022526Z_5562fd9a_prompt_io.raw.md
 ---
 ## Prompt
 Perform a full Tractor repository scan for related `ai.skillz` work,
 then correct the run-tests landing branch, prune unrelated `.gitignore`
 additions, preserve only the focused migration, and provide canonical
 deployment commands.
 ## Response summary
 Audited all local branches, worktrees, affected-path history, deployment
 state, canonical skill dependencies, and current Tractor harness behavior.
 Corrected the local test reference where it overstated cleanup safety or
 omitted current environment, platform, debugger, timeout, and CI details.
 Narrowed `.gitignore` to the three managed `run-tests` deployment blocks.
 ## Files changed
 - `.claude/skills/run-tests/test-harness-reference.md` - correct the
  project-specific test and cleanup contract.
 - `.gitignore` - remove unrelated deployment ignores from this migration.
 - `ai/prompt-io/opencode/20260822T022526Z_5562fd9a_prompt_io.md` - record
  the migration review provenance.
 - `ai/prompt-io/opencode/20260822T022526Z_5562fd9a_prompt_io.raw.md` -
  preserve the unedited response record.
 ## Human edits
 The human required an existing-work scan after duplicate implementation
 was discovered, approved correcting the landing branch during PR #481
 review, and directed removal or reconciliation of unrelated ignore rules.
 No direct source-line edits were made by the human.
--- a/ai/prompt-io/opencode/20260822T022526Z_5562fd9a_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260822T022526Z_5562fd9a_prompt_io.raw.md
@ -0,0 +1,24 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-22T02:25:26Z
 git_ref: 5562fd9a
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Audit Tractor's repository-wide `ai.skillz` state and correct the
 `wkt/ai_skillz_run_tests_landing` migration before landing it.
 > `git diff HEAD~1..HEAD -- .claude/skills/run-tests/test-harness-reference.md`
 The harness reference is corrected against current Tractor behavior:
 environment overrides, CI/platform matrices, randomized registry
 addresses, interactive debugger capture, timeout mechanisms, stackscope
 artifacts, reaper platform limits, dry-run expansion, and exact
 change-to-test mappings.
 > `git diff HEAD~1..HEAD -- .gitignore`
 Unrelated Taken and broad OpenCode command ignore additions are removed;
 only the managed canonical `run-tests` link and command blocks remain in
 this migration.
--- a/ai/prompt-io/opencode/20260824T222033Z_ce38cb6f_prompt_io.md
+++ b/ai/prompt-io/opencode/20260824T222033Z_ce38cb6f_prompt_io.md
@ -0,0 +1,37 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: d9d7df2c-7044-463f-8768-ec024718eac9
 timestamp: 2026-08-24T22:20:33Z
 git_ref: ce38cb6f
 scope: code
 substantive: true
 raw_file: 20260824T222033Z_ce38cb6f_prompt_io.raw.md
 ---
 ## Prompt
 Continue the PR #481 review after triage. The human explicitly accepted
 the proposed merge-blocking `Context.cancel()` deadline update with
 "keep" and required the work to remain limited to that review item.
 ## Response summary
 Update `Context.cancel()` so one absolute deadline bounds both shielded
 cancel-request publication and acknowledgement waiting. Add a focused
 mocked-clock regression for the blocked-publication failure mode and run
 the narrow cancellation tests.
 ## Files changed
 - `tractor/_context.py` - forward the cancel transaction's absolute
  deadline to frame publication.
 - `tests/test_to_actor.py` - prove blocked context-cancel publication is
  bounded by the shared deadline.
 ## Human edits
 The human retained ownership of review scope and explicitly selected
 "keep" for this item after receiving keep/defer/drop options. The human
 required no unrelated cancellation changes and did not directly edit
 source lines.
--- a/ai/prompt-io/opencode/20260824T222033Z_ce38cb6f_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260824T222033Z_ce38cb6f_prompt_io.raw.md
@ -0,0 +1,26 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-24T22:20:33Z
 git_ref: ce38cb6f
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Implement the approved PR #481 review update for `Context.cancel()`.
 Use one absolute deadline for both cancellation-request frame
 publication and acknowledgement waiting, without broadening the change
 to unrelated cancellation behavior.
 > `git diff HEAD~1..HEAD -- tractor/_context.py`
 `Context.cancel()` computes one absolute cancellation deadline, uses it
 for the outer bounded wait, and forwards it through
 `Portal._run_from_ns()` to shielded frame publication.
 > `git diff HEAD~1..HEAD -- tests/test_to_actor.py`
 A deterministic mocked-clock regression arranges a shielded blocked
 publication and proves that `Context.cancel()` forwards the same deadline
 which bounds the complete cancel transaction.
 Run the focused cancellation deadline regressions after the edit.
--- a/ai/prompt-io/opencode/20260824T223614Z_88d538e3_prompt_io.md
+++ b/ai/prompt-io/opencode/20260824T223614Z_88d538e3_prompt_io.md
@ -0,0 +1,35 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: d9d7df2c-7044-463f-8768-ec024718eac9
 timestamp: 2026-08-24T22:36:14Z
 git_ref: 88d538e3
 scope: code
 substantive: true
 raw_file: 20260824T223614Z_88d538e3_prompt_io.raw.md
 ---
 ## Prompt
 Continue PR #481 review remediation after committing the shared
 `Context.cancel()` deadline fix. The human accepted the proposed
 child-reap bookkeeping invariant, asking only that the first fix receive
 its own commit plan and commit before this update began.
 ## Response summary
 Check that `ActorNursery` removes its paired reap-coordination entries
 together while preserving valid pre-registration and immediate-cancel
 paths. Extend the existing real-runtime reap tests to prove all three
 child bookkeeping mappings are empty before `to_actor.run()` returns.
 ## Files changed
 - `tractor/runtime/_supervise.py` - assert paired reap-map cleanup.
 - `tests/test_to_actor.py` - verify graceful and hard-reap bookkeeping.
 ## Human edits
 The human explicitly accepted this invariant update but directed the
 preceding cancellation fix to be planned and committed as a separate
 boundary first. No direct source-line edits were made by the human.
--- a/ai/prompt-io/opencode/20260824T223614Z_88d538e3_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260824T223614Z_88d538e3_prompt_io.raw.md
@ -0,0 +1,26 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-24T22:36:14Z
 git_ref: 88d538e3
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Implement the approved PR #481 child-reap bookkeeping update after the
 preceding `Context.cancel()` fix was committed separately.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_supervise.py`
 `ActorNursery._mark_child_reaped()` captures both reap-coordination
 entries and asserts that they are either both present or both absent.
 It intentionally does not require the reap-request event to be set,
 because backend cancellation can reap immediately after registration.
 > `git diff HEAD~1..HEAD -- tests/test_to_actor.py`
 Existing real-runtime graceful and hard-reap tests verify that
 `ActorNursery._children`, `ActorNursery._child_reap_requests`, and
 `ActorNursery._child_reaped` are all empty before the one-shot call
 returns.
 Run focused bookkeeping and real-runtime reap tests after the edit.
--- a/ai/prompt-io/opencode/20260824T225356Z_2f86dd1a_prompt_io.md
+++ b/ai/prompt-io/opencode/20260824T225356Z_2f86dd1a_prompt_io.md
@ -0,0 +1,39 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: d9d7df2c-7044-463f-8768-ec024718eac9
 timestamp: 2026-08-24T22:53:56Z
 git_ref: 2f86dd1a
 scope: code
 substantive: true
 raw_file: 20260824T225356Z_2f86dd1a_prompt_io.raw.md
 ---
 ## Prompt
 Continue PR #481 review remediation after committing the paired
 `ActorNursery` reap-state invariant. The human selected "keep" for the
 reviewer's request to factor a duplicated debugger predicate in
 `_try_cancel_then_kill()`.
 ## Response summary
 Factor the child/tree debugger predicate into a local sampler used both
 before and after the cancel-RPC checkpoint. Preserve dynamic debugger
 lock re-evaluation and its distinction from root-wide debug mode.
 ## Files changed
 - `tractor/runtime/_supervise.py` - factor the duplicated debugger
  predicate without changing cancellation behavior.
 ## Human edits
 The human explicitly selected "keep" after receiving keep/defer/drop
 options for this isolated review item. During commit-plan review, the
 agent found that a single pre-checkpoint snapshot could become stale;
 the human selected a local helper which re-evaluates the lock after the
 cancel RPC. The human then considered moving the predicate into
 `.devx.debug` and accepted keeping it local after confirming that no
 existing helper shares its supervisor-owned semantics. No direct
 source-line edits were made by the human.
--- a/ai/prompt-io/opencode/20260824T225356Z_2f86dd1a_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260824T225356Z_2f86dd1a_prompt_io.raw.md
@ -0,0 +1,18 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-24T22:53:56Z
 git_ref: 2f86dd1a
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Implement the approved PR #481 review refactor in
 `_try_cancel_then_kill()` without changing debugger behavior.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_supervise.py`
 Compute the child/tree debugger predicate once, reuse it in the broader
 hard-kill protection predicate, and pass it directly to
 `debug.maybe_wait_for_debugger()`.
 Run focused debugger/cancellation coverage and lint after the edit.
--- a/ai/prompt-io/opencode/20260824T233957Z_5327b25e_prompt_io.md
+++ b/ai/prompt-io/opencode/20260824T233957Z_5327b25e_prompt_io.md
@ -0,0 +1,36 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: d9d7df2c-7044-463f-8768-ec024718eac9
 timestamp: 2026-08-24T23:39:57Z
 git_ref: 5327b25e
 scope: code
 substantive: true
 raw_file: 20260824T233957Z_5327b25e_prompt_io.raw.md
 ---
 ## Prompt
 Continue PR #481 review remediation after committing the debugger-state
 sampler. The human selected "keep" for the paired review request to use
 `Aid` objects as keys in the newly added reap-coordination maps.
 ## Response summary
 Migrate only `ActorNursery._child_reap_requests` and
 `ActorNursery._child_reaped` to `Aid` keys. Preserve the legacy
 `ActorNursery._children` `.uid` key and pass full actor identities
 through the narrow process-monitor bookkeeping path.
 ## Files changed
 - `tractor/runtime/_supervise.py` - key fresh reap maps by `Aid`.
 - `tractor/spawn/_spawn.py` - pass `Aid` into completed-reap cleanup.
 - `tests/test_to_actor.py` - exercise `Aid` registration keys.
 ## Human edits
 The human explicitly selected "keep" after reviewing the scope,
 performance, and mutability tradeoffs. The human retained the legacy
 tuple key for `_children` and accepted `Aid` for only the two fresh
 private mappings. No direct source-line edits were made by the human.
--- a/ai/prompt-io/opencode/20260824T233957Z_5327b25e_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260824T233957Z_5327b25e_prompt_io.raw.md
@ -0,0 +1,27 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-24T23:39:57Z
 git_ref: 5327b25e
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Implement the approved PR #481 review update which uses `Aid` keys for
 the two fresh `ActorNursery` reap-coordination maps while preserving the
 legacy `.uid` key for `ActorNursery._children`.
 > `git diff HEAD~1..HEAD -- tractor/runtime/_supervise.py`
 Type and access `_child_reap_requests` and `_child_reaped` by `Aid`.
 Pass full actor identities through registration, cancellation, and
 completed-reap bookkeeping, deriving `.uid` only for `_children`.
 > `git diff HEAD~1..HEAD -- tractor/spawn/_spawn.py`
 Forward `subactor.aid` when publishing completed process teardown.
 > `git diff HEAD~1..HEAD -- tests/test_to_actor.py`
 Update deterministic registration tests to exercise `Aid` map keys.
 Run focused registration/reaping tests and the full `to_actor` suite.
--- a/ai/prompt-io/opencode/20260825T015742Z_e42ecb55_prompt_io.md
+++ b/ai/prompt-io/opencode/20260825T015742Z_e42ecb55_prompt_io.md
@ -0,0 +1,38 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: d9d7df2c-7044-463f-8768-ec024718eac9
 timestamp: 2026-08-25T01:57:42Z
 git_ref: e42ecb55
 scope: code
 substantive: true
 raw_file: 20260825T015742Z_e42ecb55_prompt_io.raw.md
 ---
 ## Prompt
 Continue PR #481 review remediation after committing the `Aid` reap-map
 migration. The human selected "keep" for comments explaining why both
 spawn backends provisionally register children with `portal=None`.
 ## Response summary
 Document that a child has no `Portal` until its IPC handshake yields a
 `Channel`, and make `portal=None` explicit at both registration calls.
 Identify the later replacement of each provisional entry with
 `Portal(chan)`. Update the MP registration test double to accept and
 assert the explicit provisional portal state. Name every registration
 argument consistently in both backends.
 ## Files changed
 - `tractor/spawn/_mp.py` - clarify provisional MP registration.
 - `tractor/spawn/_trio.py` - clarify provisional Trio registration.
 - `tests/test_to_actor.py` - model explicit provisional registration.
 ## Human edits
 The human explicitly selected "keep" after receiving keep/defer/drop
 options for this paired clarification. During local review, the human
 then requested that `subactor` and `proc` also be passed by name in both
 backend calls. No direct source-line edits were made by the human.
--- a/ai/prompt-io/opencode/20260825T015742Z_e42ecb55_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260825T015742Z_e42ecb55_prompt_io.raw.md
@ -0,0 +1,21 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-25T01:57:42Z
 git_ref: e42ecb55
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Implement the approved PR #481 clarification for provisional child
 registration in both process-spawn backends.
 > `git diff HEAD~1..HEAD -- tractor/spawn/_mp.py`
 > `git diff HEAD~1..HEAD -- tractor/spawn/_trio.py`
 Explain that `portal=None` is provisional because no `Portal` can exist
 until the child completes its IPC handshake and returns a `Channel`.
 Use an explicit keyword argument and identify the later replacement with
 `Portal(chan)`.
 Run lint and the full `to_actor` runtime suite.
--- a/ai/prompt-io/opencode/20260825T021319Z_ce430fca_prompt_io.md
+++ b/ai/prompt-io/opencode/20260825T021319Z_ce430fca_prompt_io.md
@ -0,0 +1,32 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 session: d9d7df2c-7044-463f-8768-ec024718eac9
 timestamp: 2026-08-25T02:13:19Z
 git_ref: ce430fca
 scope: code
 substantive: true
 raw_file: 20260825T021319Z_ce430fca_prompt_io.raw.md
 ---
 ## Prompt
 Continue PR #481 review remediation after committing provisional child
 registration clarifications. The human selected "keep" for inlining the
 guarded `functools.Placeholder` lookup with a walrus assignment.
 ## Response summary
 Remove the standalone placeholder assignment and bind the optional
 Python 3.14 sentinel directly in the existing conditional while
 preserving compatibility behavior.
 ## Files changed
 - `tractor/to_actor/_api.py` - inline placeholder feature detection.
 ## Human edits
 The human explicitly selected "keep" after receiving keep/defer/drop
 options for this isolated cleanup. No direct source-line edits were made
 by the human.
--- a/ai/prompt-io/opencode/20260825T021319Z_ce430fca_prompt_io.raw.md
+++ b/ai/prompt-io/opencode/20260825T021319Z_ce430fca_prompt_io.raw.md
@ -0,0 +1,19 @@
 ---
 model: openai/gpt-5.6-sol
 service: opencode
 timestamp: 2026-08-25T02:13:19Z
 git_ref: ce430fca
 diff_cmd: git diff HEAD~1..HEAD
 ---
 Implement the approved PR #481 review cleanup for Python 3.14 partial
 placeholder detection.
 > `git diff HEAD~1..HEAD -- tractor/to_actor/_api.py`
 Inline the guarded `functools.Placeholder` lookup into the existing
 condition with a walrus assignment, preserving fallback behavior when
 the attribute is unavailable.
 Run partial/placeholder normalization tests and the full `to_actor`
 suite.
--- a/ai/prompt-io/prompts/issue_477.md
+++ b/ai/prompt-io/prompts/issue_477.md
@ -0,0 +1,7 @@
 NOTE: you MUST pause this work at 12:50PM EST (BEFORE your weekly
 limit reset) for review by a human!
 ---
 attempt to resolve https://github.com/goodboy/tractor/issues/477
 do it with /open-wkt.
--- a/docs/api/core.rst
+++ b/docs/api/core.rst
@ -37,7 +37,6 @@ Spawning actors
 .. autoclass:: ActorNursery
   :members: start_actor,
             run_in_actor,
             cancel,
             cancel_called,
             cancelled_caught
@ -46,11 +45,25 @@ Spawning actors
   :meth:`ActorNursery.start_actor` (daemon actor + portal) is the
   blessed spawning primitive; pair it with
-   ``Portal.open_context()`` for SC-linked remote tasks.
+   :meth:`Portal.open_context` for SC-linked remote tasks.
-   :meth:`ActorNursery.run_in_actor` is a *convenience* one-shot —
+
-   spawn, run a single task, auto-cancel after the result — slated
+One-shot task actors
-   to be rebuilt as a high-level wrapper, so don't design around
+--------------------
-   it as the core model.
+
 .. autofunction:: tractor.to_actor.run
 .. note::
   Without ``portal=``, :func:`tractor.to_actor.run` (parlance of
   ``trio.to_thread.run_sync()`` and friends) is the convenience
   one-shot: spawn, run one task, block on its result and reap. It
   combines :meth:`ActorNursery.start_actor`, a linked
   :meth:`Portal.open_context` call and per-child reaping. With
   ``portal=`` it owns only the linked task and leaves the existing
   actor's lifetime to the portal owner; that actor must expose both
   the target module and ``tractor.to_actor.MODULE``. It supersedes
   the removed (legacy, non-blocking)
   ``ActorNursery.run_in_actor()``.
 .. deprecated:: 0.1.0a6
@ -71,14 +84,12 @@ flowing back `exactly like trio`_.
   :members: run,
             run_from_ns,
             open_stream_from,
             wait_for_result,
             cancel_actor,
             chan
 .. deprecated:: 0.1.0a6
-   ``Portal.result()`` warns; use :meth:`Portal.wait_for_result`.
+   The str-form ``Portal.run('mod.path', 'fn_name')`` warns;
   The str-form ``Portal.run('mod.path', 'fn_name')`` also warns;
   pass a function *object* whose module is listed in the target's
   ``enable_modules``. ``Portal.channel`` is the legacy spelling
   of :attr:`Portal.chan`.
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@ -5,8 +5,9 @@ This is the curated reference for ``tractor``'s public surface: the
 names you can import and lean on without reading runtime internals.
 Everything below is re-exported at the top level (``import
 tractor``) unless a page says otherwise; subsystems like
-``tractor.msg``, ``tractor.trionics``, ``tractor.to_asyncio``,
+``tractor.msg``, ``tractor.trionics``, ``tractor.to_actor``,
-``tractor.devx`` and ``tractor.log`` are importable as submodules.
+``tractor.to_asyncio``, ``tractor.devx`` and ``tractor.log`` are
 importable as submodules.
 ``tractor`` is "just trio_" extended across processes: every API
 here is designed to keep the structured concurrency (SC) rules you
@ -23,6 +24,7 @@ Most-used names at a glance:
   open_root_actor
   open_nursery
   to_actor.run
   run_daemon
   ActorNursery
   Portal
--- a/docs/api/to_asyncio.rst
+++ b/docs/api/to_asyncio.rst
@ -30,11 +30,12 @@ Starting asyncio tasks from trio
 .. note::
   :func:`open_channel_from` mirrors the
-   ``Portal.open_context()`` handshake: the asyncio side calls
+   :meth:`tractor.Portal.open_context` handshake: the asyncio side calls
   ``chan.started_nowait(value)`` and that value pops out as
   ``first`` on the trio side. :func:`run_task` is the one-shot
   form — run a single asyncio-compatible coroutine fn and return
-   its result to trio.
+   its result to trio; :func:`tractor.to_actor.run` is its
   cross-process sibling.
 The inter-loop channel
 ----------------------
--- a/docs/explain/architecture.rst
+++ b/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
+runtime dir: ``$XDG_RUNTIME_DIR/tractor/`` on linux, a short
-``platformdirs`` equivalent elsewhere). Two perks over tcp on a
+owner-only ``/tmp/tractor-<uid>`` dir on Darwin, and the
-single host:
+``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
--- a/docs/guide/asyncio.rst
+++ b/docs/guide/asyncio.rst
@ -76,8 +76,8 @@ Just flip the flag on :meth:`tractor.ActorNursery.start_actor`:
            infect_asyncio=True,
        )
-The one-shot convenience ``ActorNursery.run_in_actor()`` accepts
+The one-shot convenience ``tractor.to_actor.run()`` accepts the
-the same flag. The ``to_asyncio`` APIs may **only** be called from
+same flag. The ``to_asyncio`` APIs may **only** be called from
 tasks inside an infected actor; calling them anywhere else raises
 a loud ``RuntimeError``. You can introspect at runtime with
 ``tractor.current_actor().is_infected_aio()``.
@ -229,7 +229,7 @@ dialog, skip the channel ceremony and use
 It schedules the fn as an ``asyncio.Task``, waits for completion
 and hands the return value back to ``trio``; think of it as the
-cross-loop sibling of ``ActorNursery.run_in_actor()``. Errors and
+cross-loop sibling of ``tractor.to_actor.run()``. Errors and
 cancellation are translated exactly as for channels.
 Cross-loop errors and cancellation
--- a/docs/guide/cancellation.rst
+++ b/docs/guide/cancellation.rst
@ -64,11 +64,13 @@ What's going on here?
 - three healthy actors are spawned as daemons via
  :meth:`tractor.ActorNursery.start_actor`; left alone they'd
  happily idle forever,
- a fourth actor runs ``assert_err()`` via ``.run_in_actor()`` and
+- a fourth actor runs ``assert_err()`` via a blocking
-  promptly trips its ``assert 0``,
+  ``tractor.to_actor.run()`` one-shot and promptly trips its
  ``assert 0``,
 - the resulting ``AssertionError`` ships back over IPC as a
-  serialized error msg and re-raises *boxed* inside the nursery
+  serialized error msg and re-raises *boxed* right at the call
-  block as a :class:`tractor.RemoteActorError`,
+  inside the nursery block as a
  :class:`tractor.RemoteActorError`,
 - the nursery reacts like any ``trio`` nursery would: it cancels
  the three healthy siblings (graceful runtime-cancel requests,
  acks awaited), reaps all four processes, then re-raises,
@ -228,22 +230,23 @@ Graceful first, hard as a last resort
   The hard-kill path is *skipped* whenever an actor in the tree
   holds the debug-REPL lock (``debug_mode=True`` flavors):
-   SIGTERM raining down on a tree mid-``pdb`` session would
+   Process signals raining down on a tree mid-``pdb`` session would
   clobber your prompt. See :doc:`/guide/debugging`.
-Every process teardown in ``tractor`` walks the same escalation
+Owned-child teardown in ``tractor`` begins with the same graceful
-ladder, top rung first,
+steps, then selects the escalation path used by its supervisor,
 1. **graceful cancel request**: a runtime-cancel msg over IPC; the
   target actor cancels its tasks, closes its channels and exits
   its :func:`trio.run` cleanly,
 2. **soft wait**: the parent waits (bounded) for the child process
   to exit on its own,
-3. **SIGTERM**: no ack within the bounded wait (internally an
+3. **actor-nursery hard reap**: no cancel ack within the bounded wait
-   ``ActorTooSlowError``) escalates to ``proc.terminate()``,
+   (internally an ``ActorTooSlowError``) escalates directly to
-4. **SIGKILL ultimatum**: still alive after the hard-kill timeout
+   ``proc.kill()`` before the child monitor joins the process,
-   (~1.6s)? The runtime logs that the "T-800" has been deployed to
+4. **legacy soft-kill path**: older teardown callers may first issue
-   collect the zombie and issues ``proc.kill()``. No survivors.
+   ``proc.terminate()`` and then deploy the "T-800" ``proc.kill()``
   ultimatum if the process survives that additional bounded wait.
 The result is the **no-zombies guarantee**: ``tractor`` tries to
 protect you from zombies, no matter what. Quoting the project
--- a/docs/guide/clustering.rst
+++ b/docs/guide/clustering.rst
@ -62,7 +62,10 @@ one kwarg away,
 .. code:: python
    async with tractor.open_actor_cluster(
-        modules=['mylib.workers'],
+        modules=[
            'mylib.workers',
            tractor.to_actor.MODULE,
        ],
        count=4,
        names=['scout', 'miner', 'smelter', 'smith'],
        debug_mode=True,    # whole-fleet crash-to-REPL
@ -70,9 +73,12 @@ one kwarg away,
        ...
 From here the composition patterns are the usual ``tractor`` fare:
-``portal.run()`` for one-shot calls (as in the demo), or — for a
+``portal.run()`` for bare one-shot RPCs (as in the demo),
-persistent bidirectional dialog per worker — concurrently enter N
+``tractor.to_actor.run(..., portal=portal)`` for cancellation-linked
-``portal.open_context()`` blocks with
+one-shot tasks in an existing worker (include
 ``tractor.to_actor.MODULE`` in ``modules``; the cluster still owns
 the worker's lifetime), or — for a persistent bidirectional dialog
 per worker — concurrently enter N ``portal.open_context()`` blocks with
 ``tractor.trionics.gather_contexts()``; see :doc:`/guide/context`
 for that whole layer.
@ -87,8 +93,8 @@ Clusters vs. nurseries
 ``open_actor_cluster()`` is sugar, not a new primitive: under the
 hood it's just :func:`tractor.open_nursery` plus N concurrent
-``start_actor()`` calls plus a ``.cancel()`` on the way out. Reach
+:meth:`~tractor.ActorNursery.start_actor` calls plus a ``.cancel()``
-for it when,
+on the way out. Reach for it when,
 - you want a *flat*, homogeneous fleet (classic worker-pool or
  map-style fan-out shapes),
--- a/docs/guide/context.rst
+++ b/docs/guide/context.rst
@ -15,12 +15,12 @@ a single `structured concurrency`_ (SC) scope over IPC.
   :alt: sequence diagram of the context handshake msg flow
 Pretty much everything else is (or is slated to be) built on this
-one primitive: ``ActorNursery.run_in_actor()`` is a convenience
+one primitive: ``tractor.to_actor.run()`` uses it for a linked
-for "spawn, open a context, await the result, tear down"; plain
+one-shot task, spawning and reaping an actor only when no ``portal=``
-``Portal.run()`` RPC is planned to be re-implemented on top of it;
+is supplied; plain ``Portal.run()`` RPC is planned to be
-the multi-process debugger's tree-wide REPL lock rides one. Grok
+re-implemented on top of it; the multi-process debugger's tree-wide
-this page and the rest of the library reads as convenience
+REPL lock rides one. Grok this page and the rest of the library reads
-wrappers B)
+as convenience wrappers B)
 The endpoint contract
 ---------------------
--- a/docs/guide/discovery.rst
+++ b/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
+- on boot, probe every addr in ``registry_addrs`` with a bounded
-  are passed the per-transport defaults are used: for TCP the
+  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
+- if every address is absent, congratulations: you just became the
-  registrar**. Your transport server binds the registry addrs
+  registrar. Your transport server binds the registry addrs
-  themselves and you start serving lookups for everyone else.
+  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
+Per the bootstrap rules above, if those addrs are absent this process
-*not* reachable this process simply becomes its own (registrar)
+becomes its own registrar root, so the same code works standalone and
-root — so the same code works standalone and as a tree-joiner.
+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
 -------------------------------
--- a/docs/guide/index.rst
+++ b/docs/guide/index.rst
@ -9,8 +9,8 @@ docs; what you read is what CI runs).
 Roughly in "first date to long term relationship"
 order,
- :doc:`spawning` — actor nurseries, daemons +
+- :doc:`spawning` — actor nurseries, daemons,
-  one-shot workers, process lifetimes.
+  ``to_actor.run()`` one-shots and process lifetimes.
 - :doc:`rpc` — portals: calling into another
  process like it's a local ``await``.
 - :doc:`context` — the cross-actor task-pair
--- a/docs/guide/parallelism.rst
+++ b/docs/guide/parallelism.rst
@ -119,15 +119,16 @@ Run a func in a process
 Even a pool can be overkill; "run this one async func in a
 subprocess and give me the result" is a one-liner via
-:meth:`tractor.ActorNursery.run_in_actor`,
+:func:`tractor.to_actor.run`,
 .. literalinclude:: ../../examples/parallelism/single_func.py
   :caption: examples/parallelism/single_func.py
   :language: python
-``run_in_actor()`` is a *convenience wrapper* — spawn an actor, run
+``to_actor.run()`` is a *convenience wrapper* — spawn an actor,
-exactly one task in it, reap on result — not the core spawning
+run exactly one task in it, block on and return its result, reap
-model (that's :meth:`tractor.ActorNursery.start_actor` plus
+— not the core spawning model (that's
 :meth:`tractor.ActorNursery.start_actor` plus
 :meth:`tractor.Portal.open_context`; see :doc:`/guide/context`).
 But for this fire-and-collect shape it's exactly the right amount
 of typing.
--- a/docs/guide/rpc.rst
+++ b/docs/guide/rpc.rst
@ -80,28 +80,56 @@ One special namespace exists: ``'self'`` resolves to the remote
 how internal machinery (cancel requests, registry ops) travels;
 don't build your app on it.
-One-shot results: ``wait_for_result()``
+One-shot subactors: ``to_actor.run()``
---------------------------------------
+--------------------------------------
-A portal returned from
+When the call should own a fresh subactor whose entire job is one
-:meth:`~tractor.ActorNursery.run_in_actor` has exactly one
+function call, :func:`tractor.to_actor.run` spawns it, runs the task,
-"main" task running remotely; that task's ``return`` value is
+returns its result and reaps the process — all in one blocking call:
 delivered as the portal's *final result*:
 .. code:: python
-    portal = await an.run_in_actor(fib, n=10)
+    from functools import partial
-    final = await portal.wait_for_result()
+
    final = await tractor.to_actor.run(
        partial(fib, n=10),
        an=an,
    )
 Semantics worth knowing:
 - it blocks until the remote task returns, re-raising any
-  remote error in the usual boxed form.
+  remote error in the usual boxed form right in the calling
- once resolved it's idempotent: later calls return the same
+  task.
-  cached value.
+- lifetime mode also determines process ownership: ``an=`` spawns and
- a *daemon* portal (from ``start_actor()``) has no main task,
+  reaps a fresh child in an existing actor nursery, while passing
-  so there's no final result to wait for: you'll get a warning
+  neither does the same in a private call-scoped nursery (booting
-  plus a ``NoResult`` sentinel. Results of individual daemon
+  the runtime if needed). ``portal=`` instead runs one linked task
-  calls come straight back from each ``await portal.run()``.
+  in an existing actor; it neither spawns nor reaps that actor, so
  the portal's owner remains responsible for its lifetime.
 - concurrency composes the plain ``trio`` way: schedule
  multiple ``run()`` calls into a local task nursery (see
  ``examples/parallelism/concurrent_toactor_primes.py``).
 A reused actor must expose both the target module and the
 ``to_actor`` context trampoline:
 .. code:: python
    async with tractor.open_nursery() as an:
        portal = await an.start_actor(
            'worker',
            enable_modules=[
                __name__,
                tractor.to_actor.MODULE,
            ],
        )
        try:
            final = await tractor.to_actor.run(
                partial(fib, n=10),
                portal=portal,
            )
        finally:
            await portal.cancel_actor()
 Pure RPC daemons: ``run_daemon()``
 ----------------------------------
@ -147,7 +175,8 @@ call tears down the entire sub-tree — SC, transitively.
 When to graduate to ``Context``
 -------------------------------
-``portal.run()`` is great for one-shot, request-response calls.
+The :meth:`~tractor.Portal.run` method is great for one-shot,
 request-response calls.
 Reach for :meth:`~tractor.Portal.open_context` with an
 ``@tractor.context`` endpoint as soon as you want:
@ -160,10 +189,15 @@ Reach for :meth:`~tractor.Portal.open_context` with an
  :meth:`~tractor.Portal.cancel_actor` nukes the **entire**
  remote runtime and its process.
-In fact the source plans for ``Portal.run()`` itself to be
+:func:`tractor.to_actor.run` already enters the full
-rebuilt on top of ``open_context()`` — contexts *are* the core
+:meth:`~tractor.Portal.open_context` lifecycle. The older
-inter-actor protocol. Take the full tour in
+:meth:`~tractor.Portal.run` path instead uses the ``Context`` returned
-:doc:`/guide/context`.
+by the lower-level ``Actor.start_remote_task()`` directly, avoiding a
 ``Started`` handshake but owning less lifecycle machinery. A follow-up
 should factor their shared linked-task lifecycle without requiring
 ``Portal.run()`` to delegate through the public context API or add
 another wire message. Take the full tour in
 :doc:`the context guide </guide/context>`.
 .. seealso::
--- a/docs/guide/spawning.rst
+++ b/docs/guide/spawning.rst
@ -91,31 +91,34 @@ somebody-ing:
 What's going on here?
- ``start_actor('frank', enable_modules=[__name__])`` forks off
+- :meth:`~tractor.ActorNursery.start_actor` forks off
  a new process, boots a ``tractor`` runtime inside it, and
  allows it to serve functions from the current module (see the
  allowlist section below).
- each ``await portal.run(...)`` schedules a *new* task in
+- each :meth:`~tractor.Portal.run` call schedules a *new* task in
  frank's task tree and waits on its result — the full RPC story
  lives in :doc:`/guide/rpc`.
 - frank has no main task to complete, so without the final
-  ``await portal.cancel_actor()`` the nursery block would wait
+  :meth:`~tractor.Portal.cancel_actor` call the nursery block would
-  on him **forever**. Daemon lifetimes are *yours* to end; that
+  wait on him **forever**. Daemon lifetimes are *yours* to end;
-  explicitness is the point.
+  that explicitness is the point.
-``run_in_actor()``: quick one-shot parallelism
+``to_actor.run()``: quick one-shot parallelism
 ----------------------------------------------
-:meth:`~tractor.ActorNursery.run_in_actor` is the convenience
+Without ``portal=``, :func:`tractor.to_actor.run` is the convenience
-wrapper: spawn an actor, run exactly one async function in it,
+wrapper: spawn an actor, run exactly one async function in it, block
-then reap the process as soon as the result arrives.
+on the result, then reap the process — the distributed sibling of
 ``trio.to_thread.run_sync()``.
 .. code:: python
-    async with tractor.open_nursery() as an:
+    async with (
-        portal = await an.run_in_actor(burn_cpu)
+        tractor.open_nursery() as an,
        trio.open_nursery() as tn,
    ):
        # burn rubber in the parent too...
-        await burn_cpu()
+        tn.start_soon(burn_cpu)
-        total = await portal.wait_for_result()
+        total = await tractor.to_actor.run(burn_cpu, an=an)
 A few details worth knowing:
@ -123,43 +126,61 @@ A few details worth knowing:
  ``name='something_cuter'``.
 - the function's module is auto-added to the child's
  ``enable_modules`` allowlist.
- extra ``**kwargs`` are forwarded to the function itself.
+- targets cross IPC as ``module:name`` references, so portable calls
- the child is *auto-cancelled* once its "main" result lands;
+  use module-global async functions or ``functools.partial`` objects
-  at nursery exit these run-once children are always reaped
+  wrapping them. Nested functions, methods and callable objects do not
-  first (causality_ is paramount!).
+  provide that stable address.
 - target arguments are positional; use ``functools.partial()``
  to bind target keyword arguments. Keywords passed directly to
  ``run()`` configure actor placement and spawning.
 - the call blocks until the result (or error) lands and the
  child is *auto-cancelled* (reaped) right after — so remote
  errors raise directly in your calling task (causality_ is
  paramount!).
 - "placement" composes: ``an=`` spawns a call-owned child from an
  existing actor nursery, while passing neither opens a private
  call-scoped nursery. ``portal=`` instead reuses an existing actor:
  the call scopes only its linked remote task, neither spawns nor
  reaps the actor, and leaves its lifetime with the portal's owner.
  That actor must expose both the target module and
  ``tractor.to_actor.MODULE``.
 .. note::
-   ``run_in_actor()`` is a convenience, **not** the core model.
+   :func:`tractor.to_actor.run` is a convenience, **not** the core
-   The source literally marks it for an eventual rebuild as
+   model. For actor-owning placements it combines
-   a thin "hilevel" wrapper on top of
+   :meth:`~tractor.ActorNursery.start_actor`, a linked
-   :meth:`~tractor.Portal.open_context` (the modern inter-actor
+   :meth:`~tractor.Portal.open_context` call, and per-child
-   task API). Teach your fingers to use it for quick
+   cancellation/reaping. With ``portal=`` it uses only the linked
-   fire-and-collect parallelism — think a per-function
+   context call and leaves the existing actor's lifetime untouched.
-   trio-parallel_ style one-shot — and reach for
+   Teach your fingers to use it for quick
-   ``start_actor()`` + ``open_context()`` for anything
+   fire-and-collect parallelism — think a per-function trio-parallel_
-   long-lived, stateful or streaming
+   style one-shot — and reach for
-   (:doc:`/guide/context`).
+   :meth:`~tractor.ActorNursery.start_actor` plus
   :meth:`~tractor.Portal.open_context` for anything long-lived,
   stateful or streaming; see :doc:`/guide/context`.
 Actor lifetimes and teardown order
 ----------------------------------
-So we have two lifetime flavors:
+There are two actor-lifetime flavors:
- **run-once** (``run_in_actor()``): lives exactly as long as
+- **call-owned one-shot** (``to_actor.run()`` without ``portal=``):
-  its single task; reaped the moment its result (or error)
+  spawned for one task, then cancelled and joined before ``run()``
-  arrives.
+  returns its result or raises its error.
- **daemon** (``start_actor()``): lives until *someone* cancels
+- **caller-owned daemon** (:meth:`~tractor.ActorNursery.start_actor`),
-  it — an explicit ``await portal.cancel_actor()``, a bulk
+  including an actor later reused through
-  ``await an.cancel()``, or the one-cancels-all strategy kicking
+  ``to_actor.run(..., portal=portal)``: lives until *someone*
-  in on error.
+  cancels it via an explicit
  :meth:`~tractor.Portal.cancel_actor`, a bulk
  :meth:`~tractor.ActorNursery.cancel`, or the one-cancels-all
  strategy kicking in on error.
 On a clean exit of the nursery block the teardown order is:
-1. the nursery waits on every run-once actor's final result;
+1. call-owned actors do not survive their own ``to_actor.run()``
-   any errors from these are raised immediately so your code
+   calls; each is reaped before its call returns.
-   (acting as supervisor) gets first crack at handling them.
+2. the nursery waits on caller-owned daemon actors
-2. then it waits on daemon actors — **indefinitely**. If you
+   **indefinitely**. If you spawned one, you own its lifetime.
   spawned a daemon, you own its lifetime.
 When a child *is* cancelled, teardown is graceful-first per SC
 discipline: the runtime sends an IPC cancel request and gives
--- a/docs/guide/testing.rst
+++ b/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``
+your dev venv, to check live mappings and fds) and ``--uds`` clears
-clears socket files whose binder pid is dead.
+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
 --------------------------------
--- a/docs/start/quickstart.rst
+++ b/docs/start/quickstart.rst
@ -43,24 +43,21 @@ Run it::
 What's going on here?
 - ``trio.run(main)`` starts the **root actor**; the ``tractor``
-  runtime boots *implicitly* inside ``tractor.open_nursery()``
+  runtime boots *implicitly* inside this ``tractor.to_actor.run()``
-  whenever it isn't already up. No special entrypoint, no
+  call because neither ``an=`` nor ``portal=`` was supplied. No
-  framework takeover - it's just a ``trio`` app,
+  special entrypoint, no framework takeover - it's just a ``trio``
  app,
 - inside ``main()`` a *subactor* is spawned via
-  ``ActorNursery.run_in_actor()`` and told to run exactly one
+  ``tractor.to_actor.run()`` and told to run exactly one
  function: ``cellar_door()``,
 - you get back a ``Portal``: your handle for invoking tasks in
  the new process's (separate!) memory domain. We lean on it
  much harder in the next section,
 - the subactor, *some_linguist*, boots a fresh ``trio.run()`` in
-  a **new process** and executes ``cellar_door()`` as its *main
+  a **new process** and executes ``cellar_door()`` as its linked
-  task* (note the child proving it is *not* the root with
+  one-shot task (note the child proving it is *not* the root with
  ``tractor.is_root_process()``), then ships the return value
  back over IPC,
- the parent grabs that *final result* with
+- the call *blocks* until that final result arrives, then
-  ``await portal.wait_for_result()``, much like you'd expect
+  returns it - causality is preserved: your task only proceeds
-  from a "future" - except causality is preserved: the nursery
+  once the child is *done*, dead, and reaped.
  block only exits once the child is *done*, dead, and reaped.
 .. margin:: Just need a worker pool?
@ -71,17 +68,20 @@ What's going on here?
 .. note::
-   ``run_in_actor()`` is the *convenience* wrapper: one-shot
+   Without ``portal=``, ``to_actor.run()`` (parlance of
-   spawn-run-reap semantics for when a subactor's entire job is
+   ``trio.to_thread`` and friends) is the *convenience* wrapper:
-   a single function call. The core primitives are
+   one-shot spawn-run-reap semantics for when a subactor's entire
-   ``ActorNursery.start_actor()`` (next up) paired with
+   job is a single function call. The core primitives are
-   ``Portal.open_context()`` for full, SC-linked cross-actor
+   :meth:`~tractor.ActorNursery.start_actor` (next up) — which
-   dialogs - see :doc:`/guide/context`.
+   hands you a ``Portal``, your handle for invoking tasks in the
   new process's (separate!) memory domain — paired with
   :meth:`~tractor.Portal.open_context` for full, SC-linked
   cross-actor dialogs; see :doc:`/guide/context`.
 Daemon actors and RPC
 ---------------------
-A ``run_in_actor()``-spawned actor terminates when its main task
+A subactor spawned by ``to_actor.run()`` terminates after its lone
-returns. But often you want long-lived *daemon* actors instead:
+task returns. But often you want long-lived *daemon* actors instead:
 spawned once, then serving (allowlisted) RPC requests until told
 otherwise. That's ``start_actor()``:
@ -91,14 +91,17 @@ otherwise. That's ``start_actor()``:
 Two lifetime rules to internalize:
- a ``run_in_actor()`` actor lives exactly as long as its main
+- a subactor spawned and owned by ``to_actor.run()`` is cancelled
-  task; the nursery waits for that function (and thus the
+  and reaped before the call returns its result or raises its error,
  process) to complete before unblocking,
 - a ``start_actor()`` actor *lives forever* - an RPC daemon the
  nursery will happily wait on **indefinitely** - until some
  task explicitly cancels it via ``Portal.cancel_actor()`` (as
  above), or its parent nursery is cancelled wholesale.
 Passing ``portal=`` is different: the call owns only the linked
 remote task. It neither spawns nor reaps the existing actor; the
 portal's owner must end that actor's lifetime.
 .. tip::
   Want your *entire program* to just be a long-lived RPC
@ -208,16 +211,20 @@ The script of the scene (runtime ``INFO`` log lines trimmed)::
 The new tricks in play:
- two subactors, *donny* and *gretchen*, are each told to run
+- *donny* and *gretchen* start as daemon actors so each remains alive
-  ``say_hello()`` targeting the *other* by name,
+  while the other discovers it and completes its line,
 - a local ``trio`` nursery runs both ``Portal.run(say_hello)`` calls
  concurrently; starting both actors first avoids either reciprocal
  dialog racing one-shot process reaping,
 - ``tractor.wait_for_actor()`` blocks until the named peer has
  registered with the tree's *registrar* (every actor announces
  itself at boot), then yields a ``Portal`` connected
  **directly** to that peer,
 - each actor invokes its partner's ``hi()`` over that portal:
-  actor-to-actor RPC with the root merely *directing* - and both
+  actor-to-actor RPC with the root merely *directing* - and each
-  final lines flow back to ``main()`` via
+  ``Portal.run()`` returns its final line directly to ``main()``,
-  ``await portal.wait_for_result()``,
+- the actor nursery explicitly cancels both daemons only after both
  dialogs complete,
 - ``tractor.log.get_console_log("INFO")`` cranks up runtime
  logging so you can watch the spawn/register/cancel machinery
  narrate itself; remove it for a quiet set.
--- a/examples/a_trynamic_first_scene.py
+++ b/examples/a_trynamic_first_scene.py
@ -21,22 +21,38 @@ async def main():
    """Main tractor entry point, the "master" process (for now
    acts as the "director").
    """
-    async with tractor.open_nursery() as n:
+    async with tractor.open_nursery() as an:
        print("Alright... Action!")
-        donny = await n.run_in_actor(
+        # both actors wait on (then dial!) the *other*, so each
-            say_hello,
+        # must outlive both hellos: spawn as daemons, run the
-            name='donny',
+        # hellos concurrently, reap only once both complete.
-            # arguments are always named
+        portals: dict[str, tractor.Portal] = {
-            other_actor='gretchen',
+            name: await an.start_actor(
                name,
                enable_modules=[__name__],
            )
-        gretchen = await n.run_in_actor(
+            for name in ('donny', 'gretchen')
        }
        async def run_and_print(
            name: str,
            other_actor: str,
        ) -> None:
            print(
                # RPC through an existing actor's `Portal`.
                await portals[name].run(
                    say_hello,
-            name='gretchen',
+                    other_actor=other_actor,
            other_actor='donny',
                )
-        print(await gretchen.wait_for_result())
+            )
-        print(await donny.wait_for_result())
+
        async with trio.open_nursery() as tn:
            tn.start_soon(run_and_print, 'donny', 'gretchen')
            tn.start_soon(run_and_print, 'gretchen', 'donny')
        await an.cancel()
    print("CUTTTT CUUTT CUT!!! Donny!! You're supposed to say...")
--- a/examples/actor_spawning_and_causality.py
+++ b/examples/actor_spawning_and_causality.py
@ -10,17 +10,14 @@ async def cellar_door():
 async def main():
    """The main ``tractor`` routine.
    """
-    async with tractor.open_nursery() as n:
+    # spawn a subactor, run ``cellar_door()`` as its lone task,
-
+    # block until its result arrives and the subactor is reaped.
-        portal = await n.run_in_actor(
+    print(
        await tractor.to_actor.run(
            cellar_door,
            name='some_linguist',
        )
-
+    )
    # The ``async with`` will unblock here since the 'some_linguist'
    # actor has completed its main task ``cellar_door``.
    print(await portal.wait_for_result())
 if __name__ == '__main__':
--- a/examples/actor_spawning_and_causality_with_daemon.py
+++ b/examples/actor_spawning_and_causality_with_daemon.py
@ -12,9 +12,9 @@ async def movie_theatre_question():
 async def main():
    """The main ``tractor`` routine.
    """
-    async with tractor.open_nursery() as n:
+    async with tractor.open_nursery() as an:
-        portal = await n.start_actor(
+        portal = await an.start_actor(
            'frank',
            # enable the actor to run funcs from this current module
            enable_modules=[__name__],
--- a/examples/asynchronous_generators.py
+++ b/examples/asynchronous_generators.py
@ -15,9 +15,9 @@ async def stream_forever() -> AsyncIterator[int]:
 async def main():
-    async with tractor.open_nursery() as n:
+    async with tractor.open_nursery() as an:
-        portal = await n.start_actor(
+        portal = await an.start_actor(
            'donny',
            enable_modules=[__name__],
        )
--- a/examples/debugging/multi_nested_subactors_error_up_through_nurseries.py
+++ b/examples/debugging/multi_nested_subactors_error_up_through_nurseries.py
@ -1,3 +1,5 @@
 from functools import partial
 import trio
 import tractor
@ -21,26 +23,41 @@ async def breakpoint_forever():
 async def spawn_until(depth=0):
    """"A nested nursery that triggers another ``NameError``.
    """
-    async with tractor.open_nursery() as n:
+    async with (
        tractor.open_nursery() as an,
        trio.open_nursery() as tn,
    ):
        if depth < 1:
-            await n.run_in_actor(breakpoint_forever)
+            tn.start_soon(
-
+                partial(
-            p = await n.run_in_actor(
+                    tractor.to_actor.run,
-                name_error,
+                    breakpoint_forever,
-                name='name_error'
+                    an=an,
                )
            )
            # Let the background one-shot enter `breakpoint_forever()`
            # before its sibling raises and cancellation propagates.
            await trio.sleep(0.5)
            # rx and propagate error from child
-            await p.result()
+            await tractor.to_actor.run(
                name_error,
                an=an,
                name='name_error',
            )
        else:
            # recusrive call to spawn another process branching layer of
-            # the tree
+            # the tree; blocks (up) each level until the leaf's
            # `name_error` relays through.
            depth -= 1
-            await n.run_in_actor(
+            await tractor.to_actor.run(
                partial(
                    spawn_until,
                    depth=depth,
                ),
                an=an,
                name=f'spawn_until_{depth}',
            )
@ -65,34 +82,37 @@ async def main():
             └─ python -m tractor._child --uid ('spawn_until_0', 'de918e6d ...)
    """
-    async with tractor.open_nursery(
+    async with (
        tractor.open_nursery(
            debug_mode=True,
            loglevel='pdb',
-    ) as n:
+        ) as an,
-
+        trio.open_nursery() as tn,
-        # spawn both actors
+    ):
-        portal = await n.run_in_actor(
+        # spawn both spawner trees as concurrent one-shots; the
        # first tree's (relayed) error cancels the other.
        tn.start_soon(
            partial(
                tractor.to_actor.run,
                partial(
                    spawn_until,
                    depth=3,
                ),
                an=an,
                name='spawner0',
            )
-        portal1 = await n.run_in_actor(
+        )
        tn.start_soon(
            partial(
                tractor.to_actor.run,
                partial(
                    spawn_until,
                    depth=4,
                ),
                an=an,
                name='spawner1',
            )
-
+        )
        # TODO: test this case as well where the parent don't see
        # the sub-actor errors by default and instead expect a user
        # ctrl-c to kill the root.
        with trio.move_on_after(3):
            await trio.sleep_forever()
        # gah still an issue here.
        await portal.result()
        # should never get here
        await portal1.result()
 if __name__ == '__main__':
--- a/examples/debugging/multi_subactor_root_errors.py
+++ b/examples/debugging/multi_subactor_root_errors.py
@ -15,12 +15,12 @@ async def name_error():
 async def spawn_error():
    """"A nested nursery that triggers another ``NameError``.
    """
-    async with tractor.open_nursery() as n:
+    async with tractor.open_nursery() as an:
-        portal = await n.run_in_actor(
+        return await tractor.to_actor.run(
            name_error,
            an=an,
            name='name_error_1',
        )
        return await portal.result()
 async def main():
@ -38,29 +38,36 @@ async def main():
        - root actor should then fail on assert
        - program termination
    """
-    async with tractor.open_nursery(
+    async with (
        tractor.open_nursery(
            debug_mode=True,
            loglevel='devx',
-    ) as n:
+        ) as an,
        trio.open_nursery() as tn,
    ):
        # spawn both actors..
        portal = await an.start_actor(
            'name_error',
            enable_modules=[__name__],
        )
        portal1 = await an.start_actor(
            'spawn_error',
            enable_modules=[__name__],
        )
-        # spawn both actors
+        # ..and bg-schedule their erroring tasks.
-        portal = await n.run_in_actor(
+        tn.start_soon(portal.run, name_error)
-            name_error,
+        tn.start_soon(portal1.run, spawn_error)
-            name='name_error',
+
-        )
+        # yield to the bg tasks so both RPC requests are
-        portal1 = await n.run_in_actor(
+        # submitted (and start crashing) before the root's own
-            spawn_error,
+        # error below (the legacy `run_in_actor()` submitted
-            name='spawn_error',
+        # in-line with each spawn).
-        )
+        await trio.sleep(0.5)
        # trigger a root actor error
        assert 0
        # attempt to collect results (which raises error in parent)
        # still has some issues where the parent seems to get stuck
        await portal.result()
        await portal1.result()
 if __name__ == '__main__':
    trio.run(main)
--- a/examples/debugging/multi_subactors.py
+++ b/examples/debugging/multi_subactors.py
@ -17,12 +17,12 @@ async def name_error():
 async def spawn_error():
    """"A nested nursery that triggers another ``NameError``.
    """
-    async with tractor.open_nursery() as n:
+    async with tractor.open_nursery() as an:
-        portal = await n.run_in_actor(
+        return await tractor.to_actor.run(
            name_error,
            an=an,
            name='name_error_1',
        )
        return await portal.result()
 async def main():
@ -36,17 +36,39 @@ async def main():
    `-python -m tractor._child --uid ('spawn_error', '52ee14a5 ...)
       `-python -m tractor._child --uid ('name_error', '3391222c ...)
    """
    errors: list[BaseException] = []
    async with tractor.open_nursery(
        debug_mode=True,
        # loglevel='runtime',
-    ) as n:
+    ) as an:
-        # Spawn both actors, don't bother with collecting results
+        async def run_and_collect(fn):
-        # (would result in a different debugger outcome due to parent's
+            '''
-        # cancellation).
+            One-shot whose (boxed) error is stashed instead of
-        await n.run_in_actor(breakpoint_forever)
+            raised so a sibling's crash never cancels the others
-        await n.run_in_actor(name_error)
+            before they've had their own debugger sessions (the
-        await n.run_in_actor(spawn_error)
+            "collect all errors" the legacy `run_in_actor()` API
            did implicitly at nursery teardown).
            '''
            try:
                await tractor.to_actor.run(fn, an=an)
            except tractor.RemoteActorError as rae:
                errors.append(rae)
        # Spawn all one-shot task actors, collecting (vs.
        # raising) their errors.
        async with trio.open_nursery() as tn:
            tn.start_soon(run_and_collect, breakpoint_forever)
            tn.start_soon(run_and_collect, name_error)
            tn.start_soon(run_and_collect, spawn_error)
        if errors:
            raise BaseExceptionGroup(
                'multi_subactors errored!',
                errors,
            )
 if __name__ == '__main__':
--- a/examples/debugging/open_ctx_modnofound.py
+++ b/examples/debugging/open_ctx_modnofound.py
@ -21,8 +21,8 @@ async def main() -> None:
    async with tractor.open_nursery(
        debug_mode=True,
-    ) as n:
+    ) as an:
-        portal = await n.start_actor(
+        portal = await an.start_actor(
            'ctx_child',
            # XXX: we don't enable the current module in order
--- a/examples/debugging/per_actor_debug.py
+++ b/examples/debugging/per_actor_debug.py
@ -6,14 +6,14 @@ async def die():
 async def main():
-    async with tractor.open_nursery() as tn:
+    async with tractor.open_nursery() as an:
-        debug_actor = await tn.start_actor(
+        debug_actor = await an.start_actor(
            'debugged_boi',
            enable_modules=[__name__],
            debug_mode=True,
        )
-        crash_boi = await tn.start_actor(
+        crash_boi = await an.start_actor(
            'crash_boi',
            enable_modules=[__name__],
            # debug_mode=True,
--- a/examples/debugging/root_cancelled_but_child_is_in_tty_lock.py
+++ b/examples/debugging/root_cancelled_but_child_is_in_tty_lock.py
@ -1,3 +1,5 @@
 from functools import partial
 import trio
 import tractor
@ -10,15 +12,17 @@ async def name_error():
 async def spawn_until(depth=0):
    """"A nested nursery that triggers another ``NameError``.
    """
-    async with tractor.open_nursery() as n:
+    async with tractor.open_nursery() as an:
        if depth < 1:
-            # await n.run_in_actor('breakpoint_forever', breakpoint_forever)
+            await tractor.to_actor.run(name_error, an=an)
            await n.run_in_actor(name_error)
        else:
            depth -= 1
-            await n.run_in_actor(
+            await tractor.to_actor.run(
                partial(
                    spawn_until,
                    depth=depth,
                ),
                an=an,
                name=f'spawn_until_{depth}',
            )
@ -37,28 +41,37 @@ async def main():
       └─ python -m tractor._child --uid ('name_error', '6c2733b8 ...)
    '''
-    async with tractor.open_nursery(
+    async with (
        tractor.open_nursery(
            debug_mode=True,
-        enable_transports=['uds'],  # TODO, apss this via osenv?
+            enable_transports=['uds'],  # TODO, pass this via osenv?
            loglevel='devx',  # XXX, required for test!
-    ) as n:
+        ) as an,
-
+        trio.open_nursery() as tn,
-        # spawn both actors
+    ):
-        portal = await n.run_in_actor(
+        # spawn the deeper tree in the bg..
-            spawn_until,
+        tn.start_soon(
-            depth=0,
+            partial(
-            name='spawner0',
+                tractor.to_actor.run,
-        )
+                partial(
        portal1 = await n.run_in_actor(
                    spawn_until,
                    depth=1,
                ),
                an=an,
                name='spawner1',
            )
        )
-        # nursery cancellation should be triggered due to propagated
+        # ..while blocking on the shallow (faster to fail) tree
-        # error from child.
+        # whose propagated error triggers nursery cancellation.
-        await portal.result()
+        await tractor.to_actor.run(
-        await portal1.result()
+            partial(
                spawn_until,
                depth=0,
            ),
            an=an,
            name='spawner0',
        )
 if __name__ == '__main__':
--- a/examples/debugging/root_timeout_while_child_crashed.py
+++ b/examples/debugging/root_timeout_while_child_crashed.py
@ -13,17 +13,24 @@ async def main():
    simultaneously.
    '''
-    async with tractor.open_nursery(
+    async with (
        tractor.open_nursery(
            debug_mode=True,
            # loglevel='debug'  # ?XXX required?
-    ) as n:
+        ) as an,
-
+        trio.open_nursery() as tn,
-        # spawn both actors
+    ):
-        portal = await n.run_in_actor(key_error)
+        # spawn the actor..
        portal = await an.start_actor(
            'key_error',
            enable_modules=[__name__],
        )
        print(
            f'Child is up @ {portal.chan.aid.reprol()}'
        )
-
+        # ..then schedule its erroring task in the bg while the
        # root blocks below.
        tn.start_soon(portal.run, key_error)
        # XXX: originally a bug caused by this is where root would enter
        # the debugger and clobber the tty used by the repl even though
--- a/examples/debugging/shielded_pause.py
+++ b/examples/debugging/shielded_pause.py
@ -74,11 +74,11 @@ async def cancelled_before_pause(
 async def main():
    async with tractor.open_nursery(
        debug_mode=True,
-    ) as n:
+    ) as an:
-        portal: tractor.Portal = await n.run_in_actor(
+        await tractor.to_actor.run(
            cancelled_before_pause,
            an=an,
        )
        await portal.wait_for_result()
        # ensure the same works in the root actor!
        await pm_on_cancelled()
--- a/examples/debugging/subactor_bp_in_ctx.py
+++ b/examples/debugging/subactor_bp_in_ctx.py
@ -58,8 +58,8 @@ async def main():
        debug_mode=True,
        enable_transports=[tpt],
        loglevel='devx',
-    ) as n:
+    ) as an:
-        p = await n.start_actor(
+        p = await an.start_actor(
            'bp_boi',
            enable_modules=[__name__],
        )
--- a/examples/debugging/subactor_breakpoint.py
+++ b/examples/debugging/subactor_breakpoint.py
@ -17,12 +17,14 @@ async def main():
    async with tractor.open_nursery(
        debug_mode=True,
        loglevel='cancel',
-    ) as n:
+    ) as an:
-        portal = await n.run_in_actor(
+        # parks awaiting a result which only arrives once the
        # user quits (`BdbQuit`s) the child's REPL loop.
        await tractor.to_actor.run(
            breakpoint_forever,
            an=an,
        )
        await portal.wait_for_result()
 if __name__ == '__main__':
--- a/examples/debugging/subactor_error.py
+++ b/examples/debugging/subactor_error.py
@ -12,16 +12,12 @@ async def main():
    ) as an:
        # TODO: ideally the REPL arrives at this frame in the parent,
-        # ABOVE the @api_frame of `Portal.run_in_actor()` (which
+        # ABOVE the @api_frame of `to_actor.run()` ..
        # should eventually not even be a portal method ... XD)
        # await tractor.pause()
        p: tractor.Portal = await an.run_in_actor(name_error)
-        # with this style, should raise on this line
+        # the one-shot blocks on the subactor's result so the
-        await p.wait_for_result()
+        # boxed `NameError` raises right here.
-
+        await tractor.to_actor.run(name_error, an=an)
        # with this alt style should raise at `open_nusery()`
        # return await p.wait_for_result()
 if __name__ == '__main__':
--- a/examples/debugging/sync_bp.py
+++ b/examples/debugging/sync_bp.py
@ -90,7 +90,7 @@ async def main() -> None:
        # TODO: 3 sub-actor usage cases:
        # -[x] via a `.open_context()`
-        # -[ ] via a `.run_in_actor()` call
+        # -[ ] via a `to_actor.run()` call
        # -[ ] via a `.run()`
        # -[ ] via a `.to_thread.run_sync()` in subactor
        async with p.open_context(
--- a/examples/infected_asyncio_echo_server.py
+++ b/examples/infected_asyncio_echo_server.py
@ -50,8 +50,8 @@ async def trio_to_aio_echo_server(
 async def main():
-    async with tractor.open_nursery() as n:
+    async with tractor.open_nursery() as an:
-        p = await n.start_actor(
+        p = await an.start_actor(
            'aio_server',
            enable_modules=[__name__],
            infect_asyncio=True,
--- a/Show More
+++ b/Show More