The 8-page docs sweep of the #477 removal, ahead of the API's
excision,
- `start/quickstart.rst`: the first-actor-tree walkthrough now
narrates the (migrated) `to_actor.run()` example — no portal
in hand until the daemon section introduces `start_actor()`.
- `guide/spawning.rst`: the one-shot section becomes
`to_actor.run()` (blocking call, placement opts, "built on the
primitives" note); lifetime/teardown rules update — one-shots
never make it to nursery exit since each is reaped inside its
own call.
- `guide/rpc.rst`: the `wait_for_result()` section (an API that
dies with the reap cluster, incl. the `NoResult` sentinel)
becomes a `to_actor.run()` one-shot section.
- `api/core.rst`: drop `run_in_actor`/`wait_for_result` from the
autodoc member lists, drop the `Portal.result()` deprecation
note, add a "One-shot task actors" `tractor.to_actor.run`
autodoc section.
- `guide/{asyncio,context,cancellation,parallelism}.rst`:
mention swaps to the successor API.
Gate: `make -C docs html` builds clean; `to_actor.run` autodoc
renders in `api/core.html`.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The 8 `examples/debugging/` scripts driven by the pexpect'd
`test_debugger.py` REPL-flows (#477 removal),
- blocking one-shots (`subactor_error`, `subactor_breakpoint`,
`shielded_pause`): straight `to_actor.run(fn, an=an)` — the
boxed error/`BdbQuit` raises in the root's task.
- `multi_subactors`: introduces the "collect all errors" pattern
— each one-shot catches + stashes its `RemoteActorError` (vs
raising) so no child's crash cancels its siblings before
they've had their own REPL sessions, then a
`BaseExceptionGroup` of the lot raises at the end; preserves
the legacy teardown-reap REPL flow exactly (28/28 debugger
suite unchanged).
- `multi_nested_subactors_error_up_through_nurseries` +
`root_cancelled_but_child_is_in_tty_lock`: recursive
`spawn_until` levels each block on their one-shot child; the
parallel spawner-trees run as bg task-nursery one-shots where
the first tree's error cancels the other.
- `multi_subactor_root_errors` +
`root_timeout_while_child_crashed`: `start_actor()` + bg
`Portal.run()` tasks so the root's own error/timeout races the
already-crashed children, same as before.
- `sync_bp`: TODO-comment x-ref update only.
`test_debugger.py`: the nested-nurseries test's final-output
patterns update to the new relay shape — the LAST-released leaf
REPL's error chain wins each level's relay-vs-cancel race and
relays as a `collapse_eg()`-annotated collapsed chain, while the
sibling tree is cancelled + absorbed. (The legacy teardown-reap
grouped BOTH the `name_error` and bp-quit chains — explaining
the previously-mysterious "extra" `src_uid`/`relay_uid` patterns
noted in the old TODO.)
Gate: `tests/devx/test_debugger.py` = 28 passed, 6 skipped —
identical to the pre-migration baseline.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
4 example scripts of the #477 removal sweep, each exercised by
`test_docs_examples.py`,
- `actor_spawning_and_causality.py`: the simplest possible
`to_actor.run()` demo — private call-scoped nursery, block on
and print the one-shot's result.
- `remote_error_propagation.py`: blocking `to_actor.run(an=n)`
raises the boxed `AssertionError` in the caller's task,
cancelling the sibling daemons.
- `parallelism/single_func.py`: bg-burn a core in the parent via
a local task-nursery while the one-shot burns (and returns
from) a subactor.
- `a_trynamic_first_scene.py`: donny + gretchen wait on each
*other* so their one-shots run concurrently in a local
task-nursery against a shared `an` (mirrors the migrated
`test_trynamic_trio`).
Gate: all 4 green via the example-runner suite.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The known-flaky dynamic pubsub test's 3 fire-and-forget spawn
sites (#477 removal),
- the forever-streaming `publisher` + N `consumer` one-shots now
bg-schedule as `to_actor.run(fn, an=n)` tasks in a local `trio`
task-nursery (`publisher`'s rendezvous name still derives from
`fn.__name__`).
- the simulated user-cancel raise (`KeyboardInterrupt` /
`TooSlowError` params) cancels the task-nursery, each one-shot
reaping its subactor via `to_actor.run()`'s shielded
`Portal.cancel_actor()`; `_run_and_match()`'s existing
`BaseExceptionGroup.split()` walk covers the (possibly nested)
relay shapes unchanged.
- spawns now issue concurrently rather than sequentially —
comment on the fork-backend budget updated to match.
Gate: both params x4 runs green on `trio` + x1 on `mp_spawn`;
full module green.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Final `test_cancellation.py` group of the `run_in_actor` removal
(#477) — cancel-mechanics tests, so clean conversions,
- `test_cancel_via_SIGINT_other_task`: the 3 keep-alive
`run_in_actor(sleep_forever)` one-shots become plain
`start_actor()` daemons (an idle daemon needs no "main" task,
and no longer shares a single dup'd `namesucka` name).
- `spawn_sub_with_sync_blocking_task`: the middle layer's spawn
becomes a blocking `to_actor.run(spin_for, an=an)` which parks
awaiting the sync-sleeping grandchild's result until cancelled
from above.
- `test_cancel_while_childs_child_in_sync_sleep`: the
fire-and-forget middle-actor spawn becomes a bg
`to_actor.run()` task in a local task-nursery; the root's
`assert 0` cancels it, driving the same
graceful-cancel-then-zombie-reap cascade on the sync-blocked
grandchild. The `man_cancel_outer` xfail param is unchanged.
Zero live `run_in_actor()` call-sites remain in this suite.
Gate: full `test_cancellation.py` module green on both `trio`
(18p/1xf) + `mp_spawn` (18p/1xf).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Third `test_cancellation.py` group of the `run_in_actor` removal
(#477),
- `spawn_and_error` fans out each level's erroring one-shots as
concurrent `to_actor.run(fn, an=an)` tasks in a local `trio`
task-nursery (recursing per spawner subactor), as does the
test-body's top-level spawner loop.
- the deterministic exact-breadth nested-BEG shape dies with the
legacy teardown-reap: each level now groups whatever subset of
sub-tree errors relay before the first one's cancel wins, and
a single-member group gets unwrapped by the runtime's own
`collapse_eg()` at every actor boundary — so a fully-raced
tree relays a bare `RemoteActorError` chain.
- loosen the shape walk accordingly: accept a lone
`RemoteActorError` or a 1..breadth group whose members box
`ExceptionGroup` (multi-relay), `AssertionError` (collapsed
leaf chain), `RemoteActorError` (re-boxed collapsed chain) or
`BaseExceptionGroup` (runtime reap-deadline `Cancelled`
upgrade); fold the windows-only tolerances into the same walk.
- raced sibling `trio.Cancelled`s are now ABSORBED by the
task-nursery instead of landing in the group, so the MTF
shape-mismatch xfail should consistently xpass — note added to
drop the marker once CI confirms.
- add an `else: pytest.fail()` so a silently-clean tree can no
longer pass.
Gate: both depths green on `trio` (10 consecutive runs) +
`mp_spawn`.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`test_nested_multierrors`'s backend/depth budget `match` only
carries arms for the `trio` + `main_thread_forkserver` spawn
backends, so running under any other (e.g. `mp_spawn`) leaves
`timeout` unbound and crashes with an `UnboundLocalError` at the
headroom-scaling below. Add default per-depth arms riding the MTF
budgets (same per-spawn round-trip cost class).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Second `test_cancellation.py` group of the `run_in_actor` removal
(#477),
- one-shot subactors now run as concurrent `to_actor.run(fn,
an=an)` tasks in a local `trio` task-nursery, so their errors
raise WHILE the actor-nursery block is open (vs the legacy
teardown-reap) and the first error cancels sibling one-shots.
- wrap the task-nursery in `collapse_eg()` so the deterministic
single-error cases still surface a bare `RemoteActorError`.
- loosen the group-shape assertion: the relay-vs-cancel race
populates anywhere from 1 to `num_actors` `RemoteActorError`s
(the exact-`num_actors` BEG was `run_in_actor`'s
reap-all-at-teardown); group members are always
`RemoteActorError` now since sibling `trio.Cancelled`s are
absorbed by the task-nursery.
- move the daemon-portal call loop inside the task-nursery body
so the sleep-forever one-shot case is cancelled by the daemon
error raise.
- rename the `*run_in_actor*` param ids to `*one_shot*`.
Gate: 6 passed on both `trio` + `mp_spawn` backends.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Append two sections to the ria-removal plan capturing the
2026-07-02 hang episode + the resulting design pivot.
Regression writeup: the full-suite hang on
`test_tractor_cancels_aio` root-caused to the step-A reaper
hoist (`5cd190c5`), not the B2 handler merge. The happy-path
`_reap_ria_portals()` parks unbounded on `wait_for_result()`
after a user `portal.cancel_actor()`; the old spawn-backend
reaper raced `soft_kill()`'s scope-cancel, the hoist dropped
it. Records the `proc.poll()` death-watch fix + why poll (not
the event `wait_func`) bc `soft_kill` already awaits
`proc.sentinel` (a 2nd `wait_readable` -> `BusyResourceError`).
Pause writeup: user's insight that the hoist landed in the
wrong scope — result-waiting belongs in the `to_actor`
one-shot scope (`_invoke_in_subactor()`), beside `an` + a
local task-nursery + cancel-scope, where bounding the wait is
trivial + the hang dissolves. So the poll fix is likely
SUPERSEDED (flagged do-not-land); the anti-hang guard commit
(`d1fb4a1a`) stays red-first per the failing-test convention.
(this patch was generated in some part by `claude-code` using
`claude-opus-4-8` (`anthropic`))
First group of the `test_cancellation.py` `run_in_actor` removal
(#477),
- `test_remote_error` -> blocking `to_actor.run()` (single erroring
one-shot; a bad-arg `TypeError` still relays as a
`RemoteActorError`).
- `test_multierror` -> concurrent fan-out via
`gather_contexts([p.open_context(assert_err_ctx) ...])` over
`start_actor()` portals. NB `gather_contexts` is cancel-on-first
so the 2nd errorer is usually cancelled before relaying its own
exc and the pair collapses to a single `RemoteActorError` (vs the
legacy reap-all-at-teardown `BEG`-of-N) — the assertion now
accepts either shape.
- delete `test_multierror_fast_nursery` — a 25-actor stress test of
`run_in_actor`'s teardown-reap; no analogous surface under the
`to_actor` fan-out.
- add an `assert_err_ctx` `@context` shim for the `open_context`
fan-out.
Remaining `test_cancellation` groups (some_cancels_all, nested,
SIGINT, sync-blocking) still on `run_in_actor` — ported next.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Two sites migrated (#477 removal),
- `test_trynamic_trio`: donny + gretchen each wait on the *other*
to register, so they must run CONCURRENTLY — was two
non-blocking `run_in_actor()`s awaited after; now two
`to_actor.run()` one-shots scheduled into a local `trio`
task-nursery.
- the unregister-on-cancel cluster test: its non-streaming branch
spawned `run_in_actor(trio.sleep_forever)` purely to keep each
subactor alive + registered — a `start_actor()` daemon does that
without a "main" task, so the spawn loop collapses to the same
`start_actor()` the streaming branch already used.
Suite: 16 passed.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`test_multi_actor_subs_arbiter_pub` used `run_in_actor()` to spawn
two forever-ish subscriber actors and hold their portals for a
later `cancel_actor()` (its `.result()` was commented out exactly
because `subs()` never cleanly returns). That deferred-spawn +
cancel shape isn't a blocking `to_actor.run()`, so convert to the
successor primitives (#477 removal),
- `start_actor()` per subscriber — keeps the portal for the
existing `cancel_actor()` teardown,
- run `subs()` on each via a background `Portal.run()` task in a
local `trio` nursery so both subscribe concurrently with the
test's `wait_for_actor` / topic checks,
- each bg runner swallows the `RemoteActorError`/`ContextCancelled`
that `cancel_actor()` relays; a trailing `tn.cancel_scope.cancel()`
drops any lingering runner.
Suite: 8 passed.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Migrate all 4 sites to blocking `tractor.to_actor.run()` (#477
removal),
- rename the two API-named tests to `test_to_actor_run_*`
(`same_func_in_child`, `can_skip_parent_main_inheritance`) —
they exercise the same spawn / `inherit_parent_main` path via
the successor API.
- the recursive `spawn()` helper drops its white-box
`an._children` / portal-`_peers` asserts (which probed
`run_in_actor`'s portal + nursery-tracking internals);
`to_actor.run()` returns the result and reaps internally, so
keep the user-facing `result == 10` check.
- `test_most_beautiful_word` drops the 2nd `wait_for_result()`
(the legacy result-cache re-fetch) — `to_actor.run()` delivers
the value once, no cache.
Suite: 9 passed.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Sole call-site: `run_in_actor(sleep_back_actor, ...)` ->
blocking `tractor.to_actor.run(..., an=n, ...)` (#477 removal).
The RPC-callback subactor is awaited in-caller instead of
reaped at nursery teardown; `name=`/`enable_modules=` map to
`to_actor.run()`'s same-named params, the rest to `**fn_kwargs`.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Sole call-site: an inlined `run_in_actor(...).result()` ->
blocking `tractor.to_actor.run(fn, an=an, ...)` (#477 removal).
Behaviour identical — the one-shot's result/error is awaited
in the caller's task rather than reaped at nursery teardown;
the enclosing `move_on_after` still cancels the sub in the
`error_in_child=False` case.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
First test-file of the #477 `.run_in_actor()` removal (blocking
`to_actor.run()` is the successor; the legacy non-blocking one-shot
is dropped, not replaced). All 9 call-sites migrated,
- blocking result/error/streaming-result tests -> `to_actor.run(fn,
an=an, ...)`; the "streaming" ones stream aio<->trio INSIDE the
subactor so the caller only awaits the final result.
- forever-task + cancel tests (`test_tractor_cancels_aio`,
`test_trio_cancels_aio`) -> `start_actor()` +
`Portal.open_context()` + cancel — can't block on a
never-returning task. Adds a small `sleep_forever_aio_ctx`
`@context` shim.
- greens the red `test_tractor_cancels_aio` anti-hang guard from
the prior commit: under the correctly-scoped API the wait is
bounded by the caller's cancel scope, so the hang is structurally
gone — not patched.
Suite: 34 passed, 2 xfailed (trio backend).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Wrap `test_tractor_cancels_aio`'s `main()` in a
`trio.fail_after(9 * cpu_perf_headroom())` so a wedged remote
runtime can't hang the test forever. This is the blessed
anti-hang guard here bc `pytest-timeout`'s global cap is
intentionally off (it breaks `trio` under the fork backends,
per the `pyproject` NOTE).
The cap is generous + CPU-headroom-scaled bc it's an anti-hang
guard, not a perf assertion. Motivated by the
`._ria_nursery`-removal regression where a wedged ria-reaper
once hung this exact test indefinitely.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Step B2 of the `._ria_nursery` removal (issue #477; see
`ai/conc-anal/ria_nursery_removal_plan.md`). With the 2ndary
nursery gone (step B), the two nested error handlers in
`_open_and_supervise_one_cancels_all_nursery` collapse to one,
- the outer `except (Exception, BaseExceptionGroup,
trio.Cancelled)` existed to catch errors bubbling from the
old `._ria_nursery.__aexit__` reaper-group; that nursery no
longer exists.
- trace shows the outer handler's `raise` was already DEAD: the
inner handler records `errors[uid]` as its first action, so
`errors` is always non-empty by the time anything could reach
the outer handler, and the `finally`'s raise-from-`errors`
always superseded the outer `raise`.
- so fold both into a single `except BaseException as
_scope_err` guarding the lone daemon nursery; the `finally`
(unchanged) still raises the collected `errors` as a single
exc or `BaseExceptionGroup`.
- drop the now-unused `outer_err`/`inner_err` locals.
Behaviour-preserving (net ~30 lines lighter); the big diff is
the one-level de-indent of the handler body. The two remaining
`maybe_wait_for_debugger()` guards collapse to the single
pre-teardown wait.
Prompt-IO: ai/prompt-io/claude/20260702T222544Z_9201a2ed_prompt_io.md
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Split from the step-B2 code commit to keep the runtime diff
free of `ai/` meta noise,
- `ai/conc-anal/ria_nursery_removal_plan.md`: add a "Step-B2
outcome" section — the dead-outer-`raise` trace, why the
merge is behavior-preserving, and the gate results.
- `ai/prompt-io/claude/20260702T222544Z_9201a2ed_*`: NLNet
provenance (log + unedited raw) for the step-B2 work.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Step B of the `._ria_nursery` removal (issue #477; see
`ai/conc-anal/ria_nursery_removal_plan.md`). With step A having
rerouted `.run_in_actor()` children onto the daemon nursery,
the 2ndary "run-in-actor" nursery spawns nothing and its stored
ref is never read — pure dead weight,
- collapse the inner `async with trio.open_nursery() as
ria_nursery` layer in
`_open_and_supervise_one_cancels_all_nursery`; `da_nursery` is
now the single nursery for ALL subactors.
- `ActorNursery.__init__` loses the `ria_nursery` param + the
`self._ria_nursery` attr; `start_actor()` loses its `nursery=`
escape-hatch (spawns via `self._da_nursery` directly).
- `._cancel_after_result_on_exit` stays — still the ria-child
discriminator for `_reap_ria_portals()`.
Behavior-preserving: a zero-task `trio.open_nursery()` only adds
a checkpoint. The two error handlers are KEPT (now nested under
the single nursery); merging them changes error/cancel
propagation and is deferred to its own PR (TODO left at the
outer `except`).
Prompt-IO: ai/prompt-io/claude/20260702T172233Z_5cd190c5_prompt_io.md
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Split from the step-B code commit to keep the runtime diff
free of `ai/` meta noise,
- `ai/conc-anal/ria_nursery_removal_plan.md`: add a "Step-B
outcome" section — the empty-nursery collapse, why it's
behavior-preserving, the deliberate handler-merge deferral,
and the targeted-gate result.
- `ai/prompt-io/claude/20260702T172233Z_5cd190c5_*`: NLNet
provenance (log + unedited raw) for the step-B work.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Step A of the `._ria_nursery` removal (issue #477 follow-up, see
`ai/conc-anal/ria_nursery_removal_plan.md`): `.run_in_actor()`
children now spawn via the default daemon nursery and their
result-reaping moves up into the `ActorNursery` machinery,
- new `_supervise._reap_ria_portals()`: one
`_spawn.cancel_on_completion()` task per ria child, run AFTER
`._join_procs` is set — replacing the per-child reaper task the
backends formerly spawned (keyed off
`._cancel_after_result_on_exit` membership) which required
routing such children into `._ria_nursery`.
- happy path: reap awaited right after `._join_procs.set()`,
preserving "collect ria results before daemon join" sequencing.
- error path: snapshot ria `(portal, subactor)` pairs (backend
`finally`s pop `._children` as procs reap), `await an.cancel()`,
THEN a 0.5s-bounded reap over the snapshot; anything collectable
is already queued in the local ctx and a parked reaper
self-cleans (`trio.Cancelled` results are never stashed). NB: a
concurrent reap+cancel variant deadlocked `test_multierror` and
a 3s bound blew `test_cancel_while_childs_child_in_sync_sleep`'s
deadline — deats in the plan doc's probe history.
- `spawn/_trio.py` + `spawn/_mp.py`: drop the membership branch,
per-child reaper nursery + now-unused `cancel_on_completion`
imports; the join phase is a bare `soft_kill()`.
`._ria_nursery` is now vestigial (zero spawn users): step B
deletes it + `start_actor()`'s `nursery=` escape hatch and merges
the supervisor's two error handlers.
Prompt-IO: ai/prompt-io/claude/20260702T165806Z_a34aaf98_prompt_io.md
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Split from the step-A code commit to keep the runtime diff
free of `ai/` meta noise,
- `ai/conc-anal/ria_nursery_removal_plan.md`: agent-verified
machinery map + 3-step (A/B/C) design + probe history
(reap-relocation deadlock -> sequencing fix -> bound
tighten) + risk register for the `._ria_nursery` excision.
- `ai/prompt-io/claude/20260702T165806Z_a34aaf98_*`: NLNet
provenance (log + unedited raw) for the step-A work.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Demo both flavors of the new API in a runnable script
(auto-collected by `test_docs_examples.py`),
- the fully-implicit one-shot which boots (and tears down) the
actor-runtime around a single `to_actor.run()` call,
- the concurrent "worker-pool-ish" prime-check pattern: a local
`trio` task nursery scheduling one-shots against a shared
caller-managed `an`, mirroring (in miniature) the neighboring
`concurrent_actors_primes.py` example per issue #477.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Cover every placement variant + failure mode of the new
`to_actor.run()`,
- private-nursery one-shot + implicit runtime boot via pass-through
`runtime_kwargs`,
- remote-error relay to the caller's task (bare and inside a
caller-managed `an`) as boxed `RemoteActorError`s,
- caller-nursery spawn + portal-reuse w/o implicit reap,
- the concurrent "worker-pool-ish" pattern: a local `trio` task
nursery scheduling one-shots against a shared `an`,
- the 4 pre-spawn validation rejections (sync fn, async-gen fn,
`portal`+`an` combo, `runtime_kwargs`+placement combo).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
First cut at the `to_thread`/`to_process`-style "run it over there"
wrapper layer from issue #477: a single-remote-task invocation API
decoupled from the `ActorNursery` spawn machinery, composed purely
from the lower level daemon-actor + portal primitives,
- `to_actor.run(fn, **fn_kwargs)` spawns a subactor via
`ActorNursery.start_actor()`, schedules `fn` as its lone task
with `Portal.run()` and ALWAYS reaps it via a `finally`-scoped
`Portal.cancel_actor()` (whose bounded cancel-req wait is
internally shielded so the reap also runs under caller-scope
cancellation).
- remote errors raise directly in the caller's task as boxed
`RemoteActorError`s, moving error collection/propagation up into
whatever local `trio` scope encloses the call.
- "placement" opts: `portal=` reuses a running actor (no
spawn/reap), `an=` spawns from a caller-managed actor-nursery,
neither opens a private call-scoped `open_nursery()` (implicitly
booting the runtime, tunable via pass-through `runtime_kwargs`).
- fail-fast validation BEFORE any spawn: non-streaming async fn
only (same constraint as `Portal.run()`), `portal=`/`an=` mutual
exclusion and no `runtime_kwargs` alongside a placement opt.
Also,
- x-ref the successor API from `.run_in_actor()`'s deprecation TODO
+ docstring; emitting a formal `DeprecationWarning` waits on
migrating in-repo usage.
- log prompt-io provenance per NLNet policy incl. the driver prompt
file.
Prompt-IO: ai/prompt-io/claude/20260702T154255Z_65bf9df5_prompt_io.md
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Bring the transport helpers back in line with project style:
- restore single-quote strings and docstrings;
- drop the oversized helper divider and simplify comments;
- keep guarded `match` dispatch so a missing `socket.AF_UNIX`
remains safe when `HAS_UDS` is false.
Also, format the `HAS_UDS` conjunction with the project's
multiline branch convention.
Review: PR #475 (goodboy)
https://github.com/goodboy/tractor/pull/475
Prompt-IO: ai/prompt-io/opencode/20260817T231825Z_359fe75c_prompt_io.md
(this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))
Job-level `continue-on-error` made setup and import-smoke failures
non-blocking even though the smoke is the hard Windows support
signal.
Move tolerance to the `pytest` step so the incomplete suite remains
informational while install, dependency, and `HAS_UDS` smoke
failures fail the job. When only the known suite fails, the job and
PR rollup remain green with the failed step still visible.
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
Modern Windows Python can expose `AF_UNIX`, so `trio.has_unix`
alone can register the UDS backend even though its credential and
lifecycle paths remain POSIX-only.
Gate `HAS_UDS` on `sys.platform` and make the Windows import smoke
step assert the TCP-only capability contract.
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
`test_parent_writer_child_reader` deadlocks on Windows (the
parent/child shared-mem transfer hangs at the larger frame size),
so the `windows-latest` CI leg ran to the 16-min job cap instead
of completing. It's a genuine nascent-Windows shm bug, not a
clean "unsupported", so it's `skipif`'d (not removed) and tracked
under #404; `test_child_attaches_alot` still runs on Windows.
- `@pytest.mark.skipif(platform.system() == 'Windows', ...)` on
the parametrized `test_parent_writer_child_reader` so the leg
completes + reports. linux/macOS unaffected (all 6 variants
still run).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The five transport/address lookup maps each hand-guarded `uds`
with its own `if HAS_UDS:` block (3 in `ipc/_types`, 2 in
`discovery/_addr`) — easy to let drift so a backend half-registers
(known by address but not by key, listed but unroutable, &c).
- build one `_msg_transports` / `_address_protos` list per module
(TCP always, UDS only when `HAS_UDS`), then DERIVE every map
from it via each backend's ClassVars (`codec_key`,
`address_type`, `proto_key`). Adding a backend now touches one
list, and the maps can't disagree.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`tractor`'s infect-asyncio mode runs an `asyncio` loop under
`trio` guest-mode; on Windows the default `ProactorEventLoop` is
incompatible and the suite hangs/crashes mid-run (orphaned py
procs), so the `windows-latest` CI leg never finishes reporting.
- add a module-level `pytest.skip(allow_module_level=True)` gated
on `platform.system() == 'Windows'` to `test_infected_asyncio`
and `test_root_infect_asyncio`, before their asyncio-interop
imports. macOS/linux are unaffected (they run these fine).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`test_lifetime_stack_wipes_tmpfile` guards spawn+teardown with a
hard-coded `trio.move_on_after()` (1.6s / 1s) that isn't scaled
for slow CI. On a noisy macOS runner the `error_in_child=True`
case times out before the child error propagates, so the scope
cancels and `assert not cs.cancel_called` flips — reddening the
(required) macOS leg. Same unscaled-deadline class `main` already
fixed for `test_dynamic_pub_sub`.
- multiply the budget by `cpu_perf_headroom()` (`tests/conftest`),
the established deadline-headroom helper (3x on macOS CI, a
1.0 no-op locally / on un-throttled linux).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`tests/test_ringbuf.py` imports `tractor.ipc._ringbuf` at module
top, which pulls in `tractor.ipc._linux` whose module-level
`ffi.dlopen(None)` raises `OSError` on Windows (and any non-linux
host). That fires at COLLECTION, before the module's existing
`pytestmark = pytest.mark.skip` can apply, so it aborts the whole
pytest session — the new `windows-latest` CI leg never gets past
collection.
- guard the module with `pytest.skip(allow_module_level=True)`
gated on `platform.system() != 'Linux'`, placed before the
crashing import — same idiom as `tests/devx/test_debugger.py`.
- the `eventfd`-based ringbuf backend is linux-only by design, so
macOS skips cleanly too (previously it only skipped incidentally
via the absent `cffi` optional dep).
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
The prior round gated UDS in four modules but `import tractor`
still crashed on Windows: `tractor.ipc._uds` does `from socket
import AF_UNIX` at module top, and several modules in the import
graph (`discovery._api`, `spawn._reap`, `discovery._multiaddr`,
`_testing.addr`) import `_uds` unconditionally. Instead of
guarding every importer, fix the root and collapse the per-module
probes to one capability flag.
- in `ipc/_uds.py`, guard the lone `AF_UNIX` import so the module
stays importable everywhere; expose `HAS_UDS = trio.has_unix`
as the single source of truth (the same predicate that gates
`trio.open_unix_socket()`).
- `ipc/_types.py`, `discovery/_addr.py` and `ipc/_server.py` now
import `UDSAddress`/`MsgpackUDSStream`/`HAS_UDS` directly and
gate the transport + address registries on `HAS_UDS`; drop the
duplicated `getattr(socket,'AF_UNIX')` / `platform.system()`
probes, the dead `HAS_AF_UNIX` conjunct, and the import-time
`log.warning()` spam.
- `devx/_stackscope.py` `enable_stack_on_sig()` early-returns
when `sig is None`, so a missing `SIGUSR1` (Windows) degrades
to a no-op instead of a `TypeError` from `getsignal()` /
`signal()`.
- add a `windows-latest` CI leg (UDS excluded; informational via
`continue-on-error` while support matures) plus an `import
tractor` smoke step as the hard signal for the import fix.
Because `_uds` is importable everywhere `UDSAddress` stays a real
class, so `isinstance()` checks and `wrap_address()` no longer
`AttributeError` on no-UDS hosts; actual socket use stays gated
on `has_unix`.
Review: https://github.com/goodboy/tractor/pull/475
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Windows (and any CPython that doesn't expose `socket.AF_UNIX`)
can't import the UDS transport backend nor `signal.SIGUSR1`, so
the unconditional imports break `import tractor` outright on
those hosts. Guard the platform-specific bits behind capability
probes and fall back to a TCP-only runtime when the UDS backend
is unavailable.
- across `discovery/_addr.py`, `ipc/_server.py` and
`ipc/_types.py`, gate on `getattr(socket, 'AF_UNIX', None)` +
`platform.system()` and import `UDSAddress` /
`MsgpackUDSStream` only when supported, leaving the names as
`None` otherwise.
- register the `'uds'` key in `_address_types`, its
default-loopback addr, and the transport lookup maps only when
the backend actually loads, so TCP keeps working standalone.
- in `devx/_stackscope.py`, import `SIGUSR1` conditionally and
set it to `None` on Windows.
Rebased onto the post-reorg tree where `_addr.py` now lives
under `tractor/discovery/`; adapt the relocated imports to the
package's `..ipc._uds` / `..ipc._tcp` paths (the original
single-dot paths would silently disable UDS on POSIX) and drop a
duplicated `TYPE_CHECKING` block and dead `import logging` left
by the move.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
`_peer_closed_errno()` followed cause and context links but did not
descend through grouped exceptions. A reset below a group could
therefore escape as `trio.BrokenResourceError` instead of the
normalized `TransportClosed` boundary.
Walk the exception tree with cycle protection, requiring every
group branch to represent peer closure before normalization. Extend
the `MsgpackTransport.send()` regression to prove all-transport and
mixed-failure behavior.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
Registrar election and multi-address probing are discovery-protocol
concerns, but their implementation lived in root-runtime ignition.
Move the bounded handshake probe and its concurrent address
classifier into `discovery._api`, leaving `open_root_actor()` to
consume the classified results.
Update probe tests for the canonical module and clarify that the
daemon-fixture regressions directly exercise their sibling
`conftest` plugin.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
Linux previously accepted a pre-existing runtime bindspace without
checking its owner or mode, even though Darwin enforced both. Share
the POSIX directory guard so every managed root and subdir rejects
non-directories and foreign UIDs before changing permissions.
Normalize owner-controlled bindspaces to `0o700` and add Linux
regressions for mode repair, foreign ownership, and non-directory
paths.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
The `@context` debugger E2E intentionally closes its channel.
Teardown can surface from either local error shipment or the peer
receive task.
The RPC response fix makes local close win under CI, while the test
required both scheduler-dependent diagnostics.
Keep the common debugger and cancellation assertions, then accept
either transport-close report. This preserves real actor-tree
teardown coverage without depending on task scheduling order.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
An RPC caller can close its channel after the callee creates the
endpoint coro but before its `StartAck` or final response lands.
Treat those response-send failures as terminal delivery failures so
the accepted endpoint still runs and application errors stay local
instead of cancelling the shared service nursery.
Register each cancellable RPC in `Actor._rpc_tasks` before
publishing its `Context` through `TaskStatus.started()`.
This closes the checkpoint-free completion race without a
cross-task handoff and keeps `Actor._ongoing_rpc_tasks` balanced
through existing cleanup.
Add regressions for caller disconnects at `StartAck` and error
shipment, plus registration-before-execution and cleanup checks.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
Darwin's pytest `tmp_path` can already exceed the 104-byte AF_UNIX
budget before appending either synthetic socket filename. That made
the new sentinel-policy regression fail identically in both macOS
matrix legs without exercising reaper behavior.
Allocate the test's real socket files under a short
`/tmp/tractor-reap-*` directory and retain scoped cleanup.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
The remediation grew beyond the original no-autobind fix, leaving
public docs and nearby comments describing connect-only discovery,
XDG-only socket paths, raw readiness probes, and old cleanup naming.
Document typed registrar probing, occupied-address rejection, Darwin's
short runtime directory, platform-aware socket cleanup, sentinel
readiness, and subprocess output draining. Add the GH #473 bugfix
fragment and update regression rationale without changing task states.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
Moving Darwin sockets to `/tmp/tractor-<uid>` left pytest and the
standalone reaper searching only `XDG_RUNTIME_DIR`. Enabling that
shared bindspace naively would also let automatic session cleanup
unlink an independent live `registry@1616.sock`.
Resolve the runtime's actual default UDS bindspace on every platform.
Exclude the pid-less registry sentinel from automatic cleanup while
retaining explicit CLI removal, and document that destructive choice.
Cover bindspace resolution and automatic-vs-explicit sentinel policy.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
Registry probes need short retry deadlines, but applying their
one-second budget to every portal and child connection can terminate a
valid delayed actor with no client retry path.
Give ordinary pre-registration handshakes an independent ten-second
deadline. Normalize raw `msgspec.DecodeError` frames to
`TransportClosed` so malformed peers cannot cancel the shared IPC
nursery with decoder internals.
Cover malformed frames and the ordinary-vs-probe timeout distinction.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
A loaded runner can accept a registry transport while delaying its
actor handshake beyond the first one-second attempt. Treating that
timeout as final classifies a healthy daemon as occupied and cascades
into unrelated discovery failures.
Retry connected handshake failures on fresh channels under a shared
three-second budget, while returning immediately for truly absent
listeners. Bound every connect-plus-handshake attempt, use incremental
backoff, and retain the one-second unauthenticated server limit.
Also bound shielded probe-channel cleanup to 200ms and cover the real
timeout, reconnection, backoff, fresh-channel, and stalled-close paths.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
The discovery `daemon` fixture probed UDS readiness by connecting and
immediately closing. That entered Tractor's actor handshake without an
`Aid` payload and destabilized the remote registrar on macOS before
test roots attempted discovery.
Run the child through a small `open_root_actor()` wrapper and publish a
filesystem sentinel only after runtime startup completes. Poll that
sentinel with process-liveness checks and guaranteed setup-failure
cleanup, without touching the transport socket.
Cover transport-free readiness and deterministic polling backoff.
Caught-during: review remediation
Found-via: `/run-tests` discovery daemon fixture consumers
Cause: initial sentinel drafts mishandled `pytest.Testdir`, emitted
invalid `python -c` syntax, and misplaced return-code logging.
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
Transport connect alone can select a foreign, stalled, or ordinary
actor endpoint as the registry. On macOS UDS this also exercises a
fragile connect-and-bail path before every root election.
Extend `Aid` with backward-compatible probe and registrar capability
fields, require a bounded typed handshake, and classify addresses as
absent, occupied, or confirmed registrars. Reject occupied endpoints
instead of binding over them.
Also,
- close `_connect_chan()` in `finally`
- bypass normal peer tracking for election probes
- preserve legacy registrar handshakes with unknown capability
- cover foreign listeners and idle registrar peer state
Review: PR #480 (goodboy)
https://github.com/goodboy/tractor/pull/480
(this patch was generated in some part by `opencode` using
`gpt-5.6-sol` (`openai`))
Gud Boi
Bd