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

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

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

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

ai/prompt-io/opencode/20260819T184640Z_481ba003_prompt_io.md

@@ -1,56 +0,0 @@
----
-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.

ai/prompt-io/opencode/20260819T184640Z_481ba003_prompt_io.raw.md

@@ -1,30 +0,0 @@
----
-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

docs/api/core.rst

@@ -58,10 +58,10 @@ One-shot task actors
    ``trio.to_thread.run_sync()`` and friends) is the
    *convenience* one-shot — spawn, run a single task, block on
    its result, reap — built entirely on
-   :meth:`ActorNursery.start_actor`, a linked
+   :meth:`ActorNursery.start_actor` + :meth:`Portal.run` +
-   :meth:`Portal.open_context` call and per-child cancellation/reaping,
+   :meth:`Portal.cancel_actor`, so don't design around it as the
-   so don't design around it as the core model. It supersedes the
+   core model. It supersedes the removed (legacy, non-blocking)
-   removed (legacy, non-blocking) ``ActorNursery.run_in_actor()``.
+   ``ActorNursery.run_in_actor()``.
 
 .. deprecated:: 0.1.0a6
 

docs/guide/rpc.rst

@@ -89,12 +89,7 @@ in one blocking call:
 
 .. code:: python
 
-    from functools import partial
+    final = await tractor.to_actor.run(fib, an=an, n=10)
-
-    final = await tractor.to_actor.run(
-        partial(fib, n=10),
-        an=an,
-    )
 
 Semantics worth knowing:
 
@@ -103,10 +98,9 @@ Semantics worth knowing:
   task.
 - "placement" is composable: ``an=`` spawns from an existing
   actor-nursery, ``portal=`` reuses an already-running actor
-  (no spawn/reap, just a linked
+  (no spawn/reap, just a ``Portal.run()``), and passing
-  :meth:`~tractor.Portal.open_context` call; see the
+  neither opens a private call-scoped nursery (booting the
-  :doc:`context guide </guide/context>`), and passing neither
+  runtime if needed).
-  opens a private call-scoped nursery (booting the runtime if needed).
 - concurrency composes the plain ``trio`` way: schedule
   multiple ``run()`` calls into a local task nursery (see
   ``examples/parallelism/to_actor_one_shots.py``).
@@ -155,8 +149,7 @@ call tears down the entire sub-tree — SC, transitively.
 
 When to graduate to ``Context``
 -------------------------------
-The :meth:`~tractor.Portal.run` method is great for one-shot,
+``portal.run()`` is great for one-shot, request-response calls.
-request-response calls.
 Reach for :meth:`~tractor.Portal.open_context` with an
 ``@tractor.context`` endpoint as soon as you want:
 
@@ -169,15 +162,10 @@ Reach for :meth:`~tractor.Portal.open_context` with an
   :meth:`~tractor.Portal.cancel_actor` nukes the **entire**
   remote runtime and its process.
 
-:func:`tractor.to_actor.run` already enters the full
+In fact the source plans for ``Portal.run()`` itself to be
-:meth:`~tractor.Portal.open_context` lifecycle. The older
+rebuilt on top of ``open_context()`` — contexts *are* the core
-:meth:`~tractor.Portal.run` path instead uses the ``Context`` returned
+inter-actor protocol. Take the full tour in
-by the lower-level ``Actor.start_remote_task()`` directly, avoiding a
+:doc:`/guide/context`.
-``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::
 

docs/guide/spawning.rst

@@ -91,17 +91,17 @@ somebody-ing:
 
 What's going on here?
 
-- :meth:`~tractor.ActorNursery.start_actor` forks off
+- ``start_actor('frank', enable_modules=[__name__])`` 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 :meth:`~tractor.Portal.run` call schedules a *new* task in
+- each ``await portal.run(...)`` 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
-  :meth:`~tractor.Portal.cancel_actor` call the nursery block would
+  ``await portal.cancel_actor()`` the nursery block would wait
-  wait on him **forever**. Daemon lifetimes are *yours* to end;
+  on him **forever**. Daemon lifetimes are *yours* to end; that
-  that explicitness is the point.
+  explicitness is the point.
 
 ``to_actor.run()``: quick one-shot parallelism
 ----------------------------------------------
@@ -126,9 +126,7 @@ A few details worth knowing:
   ``name='something_cuter'``.
 - the function's module is auto-added to the child's
   ``enable_modules`` allowlist.
-- target arguments are positional; use ``functools.partial()``
+- extra ``**kwargs`` are forwarded to the function itself.
-  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
@@ -140,16 +138,14 @@ A few details worth knowing:
 
 .. note::
 
-   :func:`tractor.to_actor.run` is a convenience, **not** the core
+   ``to_actor.run()`` is a convenience, **not** the core model —
-   model — it's built *entirely* on
+   it's built *entirely* on ``start_actor()`` + ``Portal.run()``
-   :meth:`~tractor.ActorNursery.start_actor` plus a linked
+   + ``Portal.cancel_actor()``. Teach your fingers to use it for
-   :meth:`~tractor.Portal.open_context` call and per-child
+   quick fire-and-collect parallelism — think a per-function
-   cancellation/reaping. Teach your fingers to use it for quick
+   trio-parallel_ style one-shot — and reach for
-   fire-and-collect parallelism — think a per-function trio-parallel_
+   ``start_actor()`` + ``open_context()`` for anything
-   style one-shot — and reach for
+   long-lived, stateful or streaming
-   :meth:`~tractor.ActorNursery.start_actor` plus
+   (:doc:`/guide/context`).
-   :meth:`~tractor.Portal.open_context` for anything long-lived,
-   stateful or streaming; see :doc:`/guide/context`.
 
 Actor lifetimes and teardown order
 ----------------------------------
@@ -158,11 +154,10 @@ So we have two lifetime flavors:
 - **one-shot** (``to_actor.run()``): lives exactly as long as
   its single task; reaped the moment its result (or error)
   arrives back in the (blocking) call.
-- **daemon** (:meth:`~tractor.ActorNursery.start_actor`): lives
+- **daemon** (``start_actor()``): lives until *someone* cancels
-  until *someone* cancels it — an explicit
+  it — an explicit ``await portal.cancel_actor()``, a bulk
-  :meth:`~tractor.Portal.cancel_actor`, a bulk
+  ``await an.cancel()``, or the one-cancels-all strategy kicking
-  :meth:`~tractor.ActorNursery.cancel`, or the one-cancels-all
+  in on error.
-  strategy kicking in on error.
 
 On a clean exit of the nursery block the teardown order is:
 

examples/debugging/multi_nested_subactors_error_up_through_nurseries.py

@@ -51,11 +51,9 @@ async def spawn_until(depth=0):
             # `name_error` relays through.
             depth -= 1
             await tractor.to_actor.run(
-                partial(
+                spawn_until,
-                    spawn_until,
-                    depth=depth,
-                ),
                 an=an,
+                depth=depth,
                 name=f'spawn_until_{depth}',
             )
 
@@ -92,22 +90,18 @@ async def main():
         tn.start_soon(
             partial(
                 tractor.to_actor.run,
-                partial(
+                spawn_until,
-                    spawn_until,
-                    depth=3,
-                ),
                 an=an,
+                depth=3,
                 name='spawner0',
             )
         )
         tn.start_soon(
             partial(
                 tractor.to_actor.run,
-                partial(
+                spawn_until,
-                    spawn_until,
-                    depth=4,
-                ),
                 an=an,
+                depth=4,
                 name='spawner1',
             )
         )

examples/debugging/root_cancelled_but_child_is_in_tty_lock.py

@@ -18,11 +18,9 @@ async def spawn_until(depth=0):
         else:
             depth -= 1
             await tractor.to_actor.run(
-                partial(
+                spawn_until,
-                    spawn_until,
-                    depth=depth,
-                ),
                 an=an,
+                depth=depth,
                 name=f'spawn_until_{depth}',
             )
 
@@ -53,11 +51,9 @@ async def main():
         tn.start_soon(
             partial(
                 tractor.to_actor.run,
-                partial(
+                spawn_until,
-                    spawn_until,
-                    depth=1,
-                ),
                 an=an,
+                depth=1,
                 name='spawner1',
             )
         )
@@ -65,11 +61,9 @@ async def main():
         # ..while blocking on the shallow (faster to fail) tree
         # whose propagated error triggers nursery cancellation.
         await tractor.to_actor.run(
-            partial(
+            spawn_until,
-                spawn_until,
-                depth=0,
-            ),
             an=an,
+            depth=0,
             name='spawner0',
         )
 

tests/test_advanced_streaming.py

@@ -248,12 +248,10 @@ def test_dynamic_pub_sub(
                             tn.start_soon(
                                 partial(
                                     tractor.to_actor.run,
-                                    partial(
+                                    consumer,
-                                        consumer,
-                                        subs=[sub],
-                                    ),
                                     an=an,
                                     name=f'consumer_{sub}',
+                                    subs=[sub],
                                 )
                             )
 
@@ -261,12 +259,10 @@ def test_dynamic_pub_sub(
                         tn.start_soon(
                             partial(
                                 tractor.to_actor.run,
-                                partial(
+                                consumer,
-                                    consumer,
-                                    subs=list(_registry.keys()),
-                                ),
                                 an=an,
                                 name='consumer_dynamic',
+                                subs=list(_registry.keys()),
                             )
                         )
 

tests/test_cancellation.py

@@ -104,7 +104,7 @@ async def do_nuthin():
     [
         # expected to be thrown in assert_err
         ({}, AssertionError),
-        # argument mismatch rejected locally before spawn
+        # argument mismatch raised in _invoke()
         ({'unexpected': 10}, TypeError)
     ],
     ids=['no_args', 'unexpected_args'],
@@ -130,34 +130,48 @@ def test_remote_error(
 
             # `to_actor.run()` blocks on the one-shot's result and
             # raises the remote error directly here in the caller's
-            # task. Invalid target args fail local signature binding
+            # task (a bad-arg `TypeError` likewise relays as a
-            # before any one-shot actor is spawned.
+            # `RemoteActorError`).
             try:
                 await tractor.to_actor.run(
-                    partial(assert_err, **args),
+                    assert_err,
                     an=an,
                     name='errorer',
+                    **args
                 )
             except tractor.RemoteActorError as err:
                 assert err.boxed_type == errtype
                 print("Look Maa that actor failed hard, hehh")
                 raise
 
-    # Invalid args never cross the process boundary.
+    # ensure boxed errors
     if args:
-        with pytest.raises(errtype):
+        with pytest.raises(tractor.RemoteActorError) as excinfo:
-            trio.run(main)
-
-    else:
-        # The linked one-shot raises the child's boxed error
-        # directly in this caller task.
-        with pytest.raises(
-            tractor.RemoteActorError,
-        ) as excinfo:
             trio.run(main)
 
         assert excinfo.value.boxed_type == errtype
 
+    else:
+        # the root task will also error on the `Portal.result()`
+        # call so we expect an error from there AND the child.
+        # |_ tho seems like on new `trio` this doesn't always
+        #    happen?
+        with pytest.raises((
+            BaseExceptionGroup,
+            tractor.RemoteActorError,
+        )) as excinfo:
+            trio.run(main)
+
+        # ensure boxed errors are `errtype`
+        err: BaseException = excinfo.value
+        if isinstance(err, BaseExceptionGroup):
+            suberrs: list[BaseException] = err.exceptions
+        else:
+            suberrs: list[BaseException] = [err]
+
+        for exc in suberrs:
+            assert exc.boxed_type == errtype
+
 
 def test_multierror(
     reg_addr: tuple[str, int],
@@ -377,9 +391,10 @@ async def test_some_cancels_all(
                     tn.start_soon(
                         partial(
                             tractor.to_actor.run,
-                            partial(func, **kwargs),
+                            func,
                             an=an,
                             name=f'actor_{i}',
+                            **kwargs,
                         )
                     )
 
@@ -454,14 +469,12 @@ async def spawn_and_error(
             if depth > 0:
 
                 args = (
-                    partial(
+                    spawn_and_error,
-                        spawn_and_error,
-                        breadth=breadth,
-                        depth=depth - 1,
-                    ),
                 )
                 kwargs = {
                     'name': f'spawner_{i}_depth_{depth}',
+                    'breadth': breadth,
+                    'depth': depth - 1,
                 }
             else:
                 args = (
@@ -692,13 +705,11 @@ async def test_nested_multierrors(
                     tn.start_soon(
                         partial(
                             tractor.to_actor.run,
-                            partial(
+                            spawn_and_error,
-                                spawn_and_error,
-                                breadth=subactor_breadth,
-                                depth=depth,
-                            ),
                             an=an,
                             name=f'spawner_{i}',
+                            breadth=subactor_breadth,
+                            depth=depth,
                         )
                     )
         except (

tests/test_infected_asyncio.py

@@ -5,7 +5,7 @@ The hipster way to force SC onto the stdlib's "async": 'infection mode'.
 import asyncio
 import builtins
 from contextlib import ExitStack
-from functools import partial
+# from functools import partial
 import itertools
 import importlib
 import os
@@ -209,12 +209,10 @@ def test_aio_simple_error(
             debug_mode=debug_mode,
         ) as an:
             await to_actor.run(
-                partial(
+                asyncio_actor,
-                    asyncio_actor,
-                    target='sleep_and_err',
-                    expect_err='AssertionError',
-                ),
                 an=an,
+                target='sleep_and_err',
+                expect_err='AssertionError',
                 infect_asyncio=True,
             )
 
@@ -457,14 +455,10 @@ def test_aio_cancelled_from_aio_causes_trio_cancelled(
             # relays the remote error here in the caller's task.
             with trio.fail_after(1 + delay):
                 await to_actor.run(
-                    partial(
+                    asyncio_actor,
-                        asyncio_actor,
-                        target='aio_cancel',
-                        expect_err=(
-                            'tractor.to_asyncio.AsyncioCancelled'
-                        ),
-                    ),
                     an=an,
+                    target='aio_cancel',
+                    expect_err='tractor.to_asyncio.AsyncioCancelled',
                     infect_asyncio=True,
                 )
 
@@ -669,12 +663,10 @@ def test_basic_interloop_channel_stream(
             ) as an:
                 # should raise RAE diectly
                 await to_actor.run(
-                    partial(
+                    stream_from_aio,
-                        stream_from_aio,
-                        fan_out=fan_out,
-                    ),
                     an=an,
                     infect_asyncio=True,
+                    fan_out=fan_out,
                 )
 
     trio.run(main)
@@ -690,11 +682,9 @@ def test_trio_error_cancels_intertask_chan(
         ) as an:
             # should trigger remote actor error
             await to_actor.run(
-                partial(
+                stream_from_aio,
-                    stream_from_aio,
-                    trio_raise_err=True,
-                ),
                 an=an,
+                trio_raise_err=True,
                 infect_asyncio=True,
             )
 
@@ -729,11 +719,9 @@ def test_trio_closes_early_causes_aio_checkpoint_raise(
                 # should raise RAE diectly
                 print('waiting on final infected subactor result..')
                 res: None = await to_actor.run(
-                    partial(
+                    stream_from_aio,
-                        stream_from_aio,
-                        trio_exit_early=True,
-                    ),
                     an=an,
+                    trio_exit_early=True,
                     infect_asyncio=True,
                 )
                 assert res is None
@@ -782,13 +770,11 @@ def test_aio_exits_early_relays_AsyncioTaskExited(
                 # should raise RAE diectly
                 print('waiting on final infected subactor result..')
                 res: None = await to_actor.run(
-                    partial(
+                    stream_from_aio,
-                        stream_from_aio,
-                        trio_exit_early=False,
-                        aio_exit_early=True,
-                    ),
                     an=an,
                     infect_asyncio=True,
+                    trio_exit_early=False,
+                    aio_exit_early=True,
                 )
                 assert res is None
                 print(f'infected subactor returned result: {res!r}\n')
@@ -823,11 +809,9 @@ def test_aio_errors_and_channel_propagates_and_closes(
         ) as an:
             # should trigger RAE directly, not an eg.
             await to_actor.run(
-                partial(
+                stream_from_aio,
-                    stream_from_aio,
-                    aio_raise_err=True,
-                ),
                 an=an,
+                aio_raise_err=True,
                 infect_asyncio=True,
             )
 

tests/test_rpc.py

@@ -4,7 +4,6 @@ related API and error checks.
 
 '''
 import itertools
-from functools import partial
 from unittest.mock import (
     AsyncMock,
     Mock,
@@ -240,21 +239,19 @@ def test_rpc_errors(
             actor = tractor.current_actor()
             assert actor.is_registrar
             await tractor.to_actor.run(
-                partial(
+                sleep_back_actor,
-                    sleep_back_actor,
-                    actor_name=subactor_requests_to,
-                    func_name=funcname,
-                    func_defined=bool(func_defined),
-                    exposed_mods=exposed_mods,
-                    reg_addr=reg_addr,
-                ),
                 an=an,
+                actor_name=subactor_requests_to,
 
                 name='subactor',
 
-                # Function from the local exposed module space the
+                # function from the local exposed module space
-                # subactor invokes when it RPCs back to this actor.
+                # the subactor will invoke when it RPCs back to this actor
+                func_name=funcname,
+                exposed_mods=exposed_mods,
+                func_defined=True if func_defined else False,
                 enable_modules=subactor_exposed_mods,
+                reg_addr=reg_addr,
             )
 
     def run():

tests/test_runtime.py

@@ -2,7 +2,6 @@
 Verifying internal runtime state and undocumented extras.
 
 """
-from functools import partial
 import os
 
 import pytest
@@ -85,12 +84,10 @@ async def test_lifetime_stack_wipes_tmpfile(
                 loglevel=loglevel,
             ) as an:
                 await tractor.to_actor.run(
-                    partial(
+                    crash_and_clean_tmpdir,
-                        crash_and_clean_tmpdir,
-                        tmp_file_path=path,
-                        error=error_in_child,
-                    ),
                     an=an,
+                    tmp_file_path=path,
+                    error=error_in_child,
                 )
     except (
         tractor.RemoteActorError,

tests/test_spawning.py

@@ -51,18 +51,18 @@ async def spawn(
             # recursively spawn this same `spawn()` fn as the lone
             # task of a one-shot child subactor and get its result.
             result = await tractor.to_actor.run(
-                partial(
+                spawn,
-                    spawn,
-                    should_be_root=False,
-                    data=data_to_pass_down,
-                    reg_addr=reg_addr,
-                ),
                 an=an,
 
                 # spawning args
                 name='sub-actor',
                 enable_modules=[__name__],
 
+                # passed to a subactor-recursive RPC invoke
+                # of this same `spawn()` fn.
+                should_be_root=False,
+                data=data_to_pass_down,
+                reg_addr=reg_addr,
             )
             assert result == 10
             return result
@@ -152,11 +152,9 @@ async def test_most_beautiful_word(
             debug_mode=debug_mode,
         ) as an:
             res: Any = await tractor.to_actor.run(
-                partial(
+                cellar_door,
-                    cellar_door,
-                    return_value=return_value,
-                ),
                 an=an,
+                return_value=return_value,
                 name='some_linguist',
             )
             assert res == return_value
@@ -206,12 +204,10 @@ def test_loglevel_propagated_to_subactor(
 
         ) as an:
             await tractor.to_actor.run(
-                partial(
+                check_loglevel,
-                    check_loglevel,
-                    level=level,
-                ),
                 an=an,
                 loglevel=level,
+                level=level,
             )
 
     trio.run(main)
@@ -277,23 +273,19 @@ def test_to_actor_run_can_skip_parent_main_inheritance(
 
             # Default: child receives parent __main__ bootstrap data
             await tractor.to_actor.run(
-                partial(
+                check_parent_main_inheritance,
-                    check_parent_main_inheritance,
-                    expect_inherited=True,
-                ),
                 an=an,
                 name='replaying-parent-main',
+                expect_inherited=True,
             )
 
             # Opt-out: child gets no parent __main__ data
             await tractor.to_actor.run(
-                partial(
+                check_parent_main_inheritance,
-                    check_parent_main_inheritance,
-                    expect_inherited=False,
-                ),
                 an=an,
                 name='isolated-parent-main',
                 inherit_parent_main=False,
+                expect_inherited=False,
             )
 
     trio.run(main)

tractor/runtime/_supervise.py

@@ -89,7 +89,7 @@ async def _try_cancel_then_kill(
     Sends a graceful actor-runtime cancel-RPC via
     `Portal.cancel_actor(raise_on_timeout=True)`. If the bounded-wait
     expires before the peer ack's, `ActorTooSlowError` is raised and
-    we escalate via `proc.kill()` per SC-discipline:
+    we escalate via `proc.terminate()` (SIGTERM) per SC-discipline:
 
       graceful cancel-req -> bounded wait -> hard-kill
 
@@ -101,9 +101,11 @@ async def _try_cancel_then_kill(
     the wider write-up.
 
     '''
-    # XXX, delay hard-kill escalation while any debugger guard
+    # XXX, do NOT escalate to `proc.terminate()` while ANY of
-    # below is active. Killing the sub immediately would tear down
+    # the following are true — SIGTERM-ing a sub would tear
-    # its tree and clobber an actor proxying a REPL session:
+    # down its sub-tree including any descendant proxying
+    # stdio to/from a REPL-locked actor, clobbering the user's
+    # debug session:
     #
     # - `Lock.ctx_in_debug is not None`: most precise — some
     #   actor in the tree is currently REPL-locked. Set in the
@@ -119,7 +121,7 @@ async def _try_cancel_then_kill(
     #   child.
     #
     # - `debug_mode_active`: this nursery has at least one
-    #   child started with an explicit `debug_mode=True` arg
+    #   child started with an explicit `debug_mode=` arg
     #   (`ActorNursery._at_least_one_child_in_debug`). Catches
     #   the case where root is NOT in debug-mode but a
     #   nursery-direct child opted in.
@@ -129,57 +131,36 @@ async def _try_cancel_then_kill(
     # mutated by per-child `debug_mode=True`). ORing covers
     # every flavor without false-positively skipping
     # legitimate hard-kill paths in non-debug trees.
-    debug_protected: bool = (
+    if (
         debug.Lock.ctx_in_debug is not None
         or
         _state._runtime_vars.get('_debug_mode', False)
         or
         debug_mode_active
-    )
+    ):
+        await portal.cancel_actor()
+        return
 
     try:
-        cancelled: bool = await portal.cancel_actor(
+        await portal.cancel_actor(raise_on_timeout=True)
-            raise_on_timeout=not debug_protected,
-        )
-        if not cancelled:
-            if debug_protected:
-                await debug.maybe_wait_for_debugger(
-                    child_in_debug=(
-                        debug_mode_active
-                        or
-                        debug.Lock.ctx_in_debug is not None
-                    ),
-                    header_msg=(
-                        'Delaying subproc hard-reap while '
-                        'debugger locked..\n'
-                    ),
-                )
-
-            peer_id: str = portal.channel.aid.reprol()
-            raise ActorTooSlowError(
-                f'Peer {peer_id} disconnected before '
-                f'acknowledging its `Actor.cancel()` RPC'
-            )
-
     except ActorTooSlowError as too_slow:
         log.error(
             f'Cancel-ack TIMED OUT for sub-actor\n'
             f'  uid: {subactor.aid.reprol()!r}\n'
             f'  reason: {too_slow}\n'
-            f'-> escalating to `proc.kill()` (hard-reap)\n'
+            f'-> escalating to `proc.terminate()` (hard-kill)\n'
         )
         # XXX, the `subint` backend stores an `int` interp-id in the
-        # `proc` slot (not a `Process`), so it has no `.kill()`.
+        # `proc` slot (not a `Process`), so it has no `.terminate()`.
         # Guard here so a cancel-ack timeout doesn't `AttributeError`
         # once that backend lands; its hard-kill path is a TODO.
-        if hasattr(proc, 'kill'):
+        if hasattr(proc, 'terminate'):
-            if proc.poll() is None:
+            proc.terminate()
-                proc.kill()
         else:
             log.error(
                 f'Cannot hard-kill sub-actor — backend proc-handle '
                 f'{proc!r} ({type(proc).__name__!r}) has no '
-                f'`.kill()`!\n'
+                f'`.terminate()`!\n'
                 f'  uid: {subactor.aid.reprol()!r}\n'
                 f'TODO: per-backend cancel-escalation.\n'
             )
@@ -237,14 +218,6 @@ class ActorNursery:
         ] = {}
 
         self._join_procs = trio.Event()
-        self._child_reap_requests: dict[
-            tuple[str, str],
-            trio.Event,
-        ] = {}
-        self._child_reaped: dict[
-            tuple[str, str],
-            trio.Event,
-        ] = {}
         self._at_least_one_child_in_debug: bool = False
         self.errors = errors
         self._scope_error: BaseException|None = None
@@ -299,79 +272,6 @@ class ActorNursery:
             # self._cancelled_caught
         )
 
-    def _register_child_reap(
-        self,
-        uid: tuple[str, str],
-    ) -> tuple[trio.Event, trio.Event]:
-        '''
-        Register a child monitor's process-reap events.
-
-        '''
-        reap_request = trio.Event()
-        reaped = trio.Event()
-        self._child_reap_requests[uid] = reap_request
-        self._child_reaped[uid] = reaped
-        if self._join_procs.is_set():
-            reap_request.set()
-        return reap_request, reaped
-
-    def _request_reap_all(self) -> None:
-        '''
-        Release every child monitor into its process-join phase.
-
-        '''
-        self._join_procs.set()
-        for reap_request in tuple(
-            self._child_reap_requests.values()
-        ):
-            reap_request.set()
-
-    def _mark_child_reaped(
-        self,
-        uid: tuple[str, str],
-    ) -> None:
-        '''
-        Publish completed child-process teardown to its waiter.
-
-        '''
-        self._children.pop(uid, None)
-        self._child_reap_requests.pop(uid, None)
-        reaped: trio.Event|None = self._child_reaped.pop(
-            uid,
-            None,
-        )
-        if reaped is not None:
-            reaped.set()
-
-    async def _cancel_and_reap_child(
-        self,
-        portal: Portal,
-    ) -> None:
-        '''
-        Cancel, join and unregister one nursery-owned child.
-
-        '''
-        uid: tuple[str, str] = portal.channel.aid.uid
-        child_entry = self._children.get(uid)
-        if child_entry is None:
-            return
-
-        subactor, proc, _ = child_entry
-        reap_request: trio.Event = self._child_reap_requests[uid]
-        reaped: trio.Event = self._child_reaped[uid]
-
-        with trio.CancelScope(shield=True):
-            try:
-                await _try_cancel_then_kill(
-                    portal,
-                    proc,
-                    subactor,
-                    self._at_least_one_child_in_debug,
-                )
-            finally:
-                reap_request.set()
-                await reaped.wait()
-
     async def start_actor(
         self,
         name: str,
@@ -416,7 +316,7 @@ class ActorNursery:
         # allow setting debug policy per actor
         if debug_mode is not None:
             _rtv['_debug_mode'] = debug_mode
-            self._at_least_one_child_in_debug |= debug_mode
+            self._at_least_one_child_in_debug = True
 
         enable_modules = list(enable_modules or [])
         proc_kwargs = dict(proc_kwargs or {})
@@ -485,7 +385,7 @@ class ActorNursery:
 
         # TODO: impl a repr for spawn more compact
         # then `._children`..
-        children: tuple = tuple(self._children.values())
+        children: dict = self._children
         child_count: int = len(children)
         msg: str = f'Cancelling actor nursery with {child_count} children\n'
 
@@ -504,7 +404,7 @@ class ActorNursery:
                     subactor,
                     proc,
                     portal,
-                ) in children:
+                ) in children.values():
 
                     # TODO: are we ever even going to use this or
                     # is the spawning backend responsible for such
@@ -524,9 +424,7 @@ class ActorNursery:
                             await event.wait()
 
                             # channel/portal should now be up
-                            _, _, portal = self._children[
+                            _, _, portal = children[subactor.aid.uid]
-                                subactor.aid.uid
-                            ]
 
                             # XXX should be impossible to get here
                             # unless method was called from within
@@ -573,14 +471,14 @@ class ActorNursery:
                 subactor,
                 proc,
                 portal,
-                ) in children:
+            ) in children.values():
                 log.warning(f"Hard killing process {proc}")
                 proc.terminate()
         else:
             self._cancelled_caught
 
         # mark ourselves as having (tried to have) cancelled all subactors
-        self._request_reap_all()
+        self._join_procs.set()
 
 
 @acm
@@ -748,13 +646,15 @@ async def open_nursery(
     Create and yield a new ``ActorNursery`` to be used for spawning
     structured concurrent subactors.
 
-    When an actor is spawned a new trio task invokes one of the
+    When an actor is spawned a new trio task is started which
-    process spawning backends to create and start a new subprocess.
+    invokes one of the process spawning backends to create and start
-    These tasks are started in the supervisor's process nursery.
+    a new subprocess. These tasks are started by one of two nurseries
-    Spawning from a task is required because ``trio_run_in_process``
+    detailed below. The reason for spawning processes from within
-    creates an internal nursery which the opening task **must** close;
+    a new task is because ``trio_run_in_process`` itself creates a new
-    this also makes each task's cancellation scope correspond to its
+    internal nursery and the same task that opens a nursery **must**
-    spawned subactor.
+    close it. It turns out this approach is probably more correct
+    anyway since it is more clear from the following nested nurseries
+    which cancellation scopes correspond to each spawned subactor set.
 
     '''
     __tracebackhide__: bool = hide_tb