Bind named `to_actor.run()` inputs with partials

PR #481 made target inputs positional and reserved keywords for
actor placement/runtime controls. PR #484 still forwarded target
kwargs, so tests and examples failed local signature binding after
the rebase.

Deats,
- bind named target inputs with `functools.partial()`
- keep placement, naming and runtime controls as direct keywords
- reject invalid target calls locally before actor startup
- require linked one-shots to raise one direct `RemoteActorError`
- doc linked context execution and per-child process reaping

Prompt-IO: ai/prompt-io/opencode/20260819T184640Z_481ba003_prompt_io.md

(this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))

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

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

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

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

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

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

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

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

ai/prompt-io/opencode/20260820T023004Z_88a23449_prompt_io.md

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

ai/prompt-io/opencode/20260820T023004Z_88a23449_prompt_io.raw.md

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

ai/prompt-io/opencode/20260820T023005Z_88a23449_prompt_io.md

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

ai/prompt-io/opencode/20260820T023005Z_88a23449_prompt_io.raw.md

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

ai/prompt-io/opencode/20260820T135125Z_9f99043b_prompt_io.md

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

ai/prompt-io/opencode/20260820T135125Z_9f99043b_prompt_io.raw.md

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

ai/prompt-io/opencode/20260820T143845Z_559fd0f1_prompt_io.md

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

ai/prompt-io/opencode/20260820T143845Z_559fd0f1_prompt_io.raw.md

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

ai/prompt-io/opencode/20260820T150250Z_9afda1c6_prompt_io.md

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

ai/prompt-io/opencode/20260820T150250Z_9afda1c6_prompt_io.raw.md

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

ai/prompt-io/opencode/20260821T023537Z_ae6f2ac3_prompt_io.md

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

ai/prompt-io/opencode/20260821T023537Z_ae6f2ac3_prompt_io.raw.md

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

ai/prompt-io/opencode/20260821T040803Z_3c1bbe73_prompt_io.md

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

ai/prompt-io/opencode/20260821T040803Z_3c1bbe73_prompt_io.raw.md

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

ai/prompt-io/opencode/20260824T222033Z_ce38cb6f_prompt_io.md

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

ai/prompt-io/opencode/20260824T222033Z_ce38cb6f_prompt_io.raw.md

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

ai/prompt-io/opencode/20260824T223614Z_88d538e3_prompt_io.md

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

ai/prompt-io/opencode/20260824T223614Z_88d538e3_prompt_io.raw.md

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

ai/prompt-io/opencode/20260824T225356Z_2f86dd1a_prompt_io.md

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

ai/prompt-io/opencode/20260824T225356Z_2f86dd1a_prompt_io.raw.md

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

ai/prompt-io/opencode/20260824T233957Z_5327b25e_prompt_io.md

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

ai/prompt-io/opencode/20260824T233957Z_5327b25e_prompt_io.raw.md

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

ai/prompt-io/opencode/20260825T015742Z_e42ecb55_prompt_io.md

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

ai/prompt-io/opencode/20260825T015742Z_e42ecb55_prompt_io.raw.md

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

ai/prompt-io/opencode/20260825T021319Z_ce430fca_prompt_io.md

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

ai/prompt-io/opencode/20260825T021319Z_ce430fca_prompt_io.raw.md

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

docs/api/core.rst

@@ -45,7 +45,7 @@ Spawning actors
 
    :meth:`ActorNursery.start_actor` (daemon actor + portal) is the
    blessed spawning primitive; pair it with
-   :meth:`Portal.open_context` for SC-linked remote tasks.
+   ``Portal.open_context()`` for SC-linked remote tasks.
 
 One-shot task actors
 --------------------
@@ -54,16 +54,14 @@ One-shot task actors
 
 .. 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()``.
+   :func:`tractor.to_actor.run` (parlance of
+   ``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:`Portal.open_context` call and per-child cancellation/reaping,
+   so don't design around it as the core model. It supersedes the
+   removed (legacy, non-blocking) ``ActorNursery.run_in_actor()``.
 
 .. deprecated:: 0.1.0a6
 

docs/api/index.rst

@@ -5,9 +5,8 @@ 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_actor``,
-``tractor.to_asyncio``, ``tractor.devx`` and ``tractor.log`` are
-importable as submodules.
+``tractor.msg``, ``tractor.trionics``, ``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
@@ -24,7 +23,6 @@ Most-used names at a glance:
 
    open_root_actor
    open_nursery
-   to_actor.run
    run_daemon
    ActorNursery
    Portal

docs/api/to_asyncio.rst

@@ -30,12 +30,11 @@ Starting asyncio tasks from trio
 .. note::
 
    :func:`open_channel_from` mirrors the
-   :meth:`tractor.Portal.open_context` handshake: the asyncio side calls
+   ``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; :func:`tractor.to_actor.run` is its
-   cross-process sibling.
+   its result to trio.
 
 The inter-loop channel
 ----------------------

docs/guide/cancellation.rst

@@ -230,23 +230,22 @@ 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):
-   Process signals raining down on a tree mid-``pdb`` session would
+   SIGTERM raining down on a tree mid-``pdb`` session would
    clobber your prompt. See :doc:`/guide/debugging`.
 
-Owned-child teardown in ``tractor`` begins with the same graceful
-steps, then selects the escalation path used by its supervisor,
+Every process teardown in ``tractor`` walks the same escalation
+ladder, top rung first,
 
 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. **actor-nursery hard reap**: no cancel ack within the bounded wait
-   (internally an ``ActorTooSlowError``) escalates directly to
-   ``proc.kill()`` before the child monitor joins the process,
-4. **legacy soft-kill path**: older teardown callers may first issue
-   ``proc.terminate()`` and then deploy the "T-800" ``proc.kill()``
-   ultimatum if the process survives that additional bounded wait.
+3. **SIGTERM**: no ack within the bounded wait (internally an
+   ``ActorTooSlowError``) escalates to ``proc.terminate()``,
+4. **SIGKILL ultimatum**: still alive after the hard-kill timeout
+   (~1.6s)? The runtime logs that the "T-800" has been deployed to
+   collect the zombie and issues ``proc.kill()``. No survivors.
 
 The result is the **no-zombies guarantee**: ``tractor`` tries to
 protect you from zombies, no matter what. Quoting the project

docs/guide/clustering.rst

@@ -62,10 +62,7 @@ one kwarg away,
 .. code:: python
 
     async with tractor.open_actor_cluster(
-        modules=[
-            'mylib.workers',
-            tractor.to_actor.MODULE,
-        ],
+        modules=['mylib.workers'],
         count=4,
         names=['scout', 'miner', 'smelter', 'smith'],
         debug_mode=True,    # whole-fleet crash-to-REPL
@@ -73,12 +70,9 @@ one kwarg away,
         ...
 
 From here the composition patterns are the usual ``tractor`` fare:
-``portal.run()`` for bare one-shot RPCs (as in the demo),
-``tractor.to_actor.run(..., portal=portal)`` for cancellation-linked
-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
+``portal.run()`` for one-shot calls (as in the demo), 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.
 
@@ -93,8 +87,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
-:meth:`~tractor.ActorNursery.start_actor` calls plus a ``.cancel()``
-on the way out. Reach for it when,
+``start_actor()`` calls plus a ``.cancel()`` on the way out. Reach
+for it when,
 
 - you want a *flat*, homogeneous fleet (classic worker-pool or
   map-style fan-out shapes),

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: ``tractor.to_actor.run()`` uses it for a linked
-one-shot task, spawning and reaping an actor only when no ``portal=``
-is supplied; plain ``Portal.run()`` RPC is planned to be
-re-implemented on top of it; the multi-process debugger's tree-wide
-REPL lock rides one. Grok this page and the rest of the library reads
-as convenience wrappers B)
+one primitive: ``tractor.to_actor.run()`` is a convenience for
+"spawn, run the lone task, await the result, tear down"; plain
+``Portal.run()`` RPC is planned to be re-implemented on top of it;
+the multi-process debugger's tree-wide REPL lock rides one. Grok
+this page and the rest of the library reads as convenience
+wrappers B)
 
 The endpoint contract
 ---------------------

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,
-  ``to_actor.run()`` one-shots and process lifetimes.
+- :doc:`spawning` — actor nurseries, daemons +
+  one-shot workers, process lifetimes.
 - :doc:`rpc` — portals: calling into another
   process like it's a local ``await``.
 - :doc:`context` — the cross-actor task-pair

docs/guide/rpc.rst

@@ -82,9 +82,10 @@ don't build your app on it.
 
 One-shot subactors: ``to_actor.run()``
 --------------------------------------
-When the call should own a fresh subactor whose entire job is one
-function call, :func:`tractor.to_actor.run` spawns it, runs the task,
-returns its result and reaps the process — all in one blocking call:
+When a subactor's *entire job* is a single function call, skip
+the portal plumbing with :func:`tractor.to_actor.run`: spawn,
+run the lone task, return its result and reap the process — all
+in one blocking call:
 
 .. code:: python
 
@@ -100,36 +101,15 @@ Semantics worth knowing:
 - it blocks until the remote task returns, re-raising any
   remote error in the usual boxed form right in the calling
   task.
-- lifetime mode also determines process ownership: ``an=`` spawns and
-  reaps a fresh child in an existing actor nursery, while passing
-  neither does the same in a private call-scoped nursery (booting
-  the runtime if needed). ``portal=`` instead runs one linked task
-  in an existing actor; it neither spawns nor reaps that actor, so
-  the portal's owner remains responsible for its lifetime.
+- "placement" is composable: ``an=`` spawns from an existing
+  actor-nursery, ``portal=`` reuses an already-running actor
+  (no spawn/reap, just a linked
+  :meth:`~tractor.Portal.open_context` call; see the
+  :doc:`context guide </guide/context>`), and passing neither
+  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/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()
+  ``examples/parallelism/to_actor_one_shots.py``).
 
 Pure RPC daemons: ``run_daemon()``
 ----------------------------------

docs/guide/spawning.rst

@@ -105,9 +105,9 @@ What's going on here?
 
 ``to_actor.run()``: quick one-shot parallelism
 ----------------------------------------------
-Without ``portal=``, :func:`tractor.to_actor.run` is the convenience
-wrapper: spawn an actor, run exactly one async function in it, block
-on the result, then reap the process — the distributed sibling of
+:func:`tractor.to_actor.run` is the convenience wrapper: spawn
+an actor, run exactly one async function in it, block on the
+result, then reap the process — the distributed sibling of
 ``trio.to_thread.run_sync()``.
 
 .. code:: python
@@ -126,10 +126,6 @@ A few details worth knowing:
   ``name='something_cuter'``.
 - the function's module is auto-added to the child's
   ``enable_modules`` allowlist.
-- targets cross IPC as ``module:name`` references, so portable calls
-  use module-global async functions or ``functools.partial`` objects
-  wrapping them. Nested functions, methods and callable objects do not
-  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.
@@ -137,23 +133,18 @@ A few details worth knowing:
   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``.
+- "placement" composes: ``an=`` spawns from a caller-managed
+  actor-nursery, ``portal=`` reuses an already-running actor
+  (no spawn/reap), and passing neither opens a private
+  call-scoped nursery (booting the runtime if needed).
 
 .. note::
 
    :func:`tractor.to_actor.run` is a convenience, **not** the core
-   model. For actor-owning placements it combines
-   :meth:`~tractor.ActorNursery.start_actor`, a linked
-   :meth:`~tractor.Portal.open_context` call, and per-child
-   cancellation/reaping. With ``portal=`` it uses only the linked
-   context call and leaves the existing actor's lifetime untouched.
-   Teach your fingers to use it for quick
+   model — it's built *entirely* on
+   :meth:`~tractor.ActorNursery.start_actor` plus a linked
+   :meth:`~tractor.Portal.open_context` call and per-child
+   cancellation/reaping. Teach your fingers to use it for quick
    fire-and-collect parallelism — think a per-function trio-parallel_
    style one-shot — and reach for
    :meth:`~tractor.ActorNursery.start_actor` plus
@@ -162,25 +153,25 @@ A few details worth knowing:
 
 Actor lifetimes and teardown order
 ----------------------------------
-There are two actor-lifetime flavors:
+So we have two lifetime flavors:
 
-- **call-owned one-shot** (``to_actor.run()`` without ``portal=``):
-  spawned for one task, then cancelled and joined before ``run()``
-  returns its result or raises its error.
-- **caller-owned daemon** (:meth:`~tractor.ActorNursery.start_actor`),
-  including an actor later reused through
-  ``to_actor.run(..., portal=portal)``: lives until *someone*
-  cancels it via an explicit
+- **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
+  until *someone* cancels it — 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. call-owned actors do not survive their own ``to_actor.run()``
-   calls; each is reaped before its call returns.
-2. the nursery waits on caller-owned daemon actors
-   **indefinitely**. If you spawned one, you own its lifetime.
+1. one-shot actors never make it to nursery exit: each is
+   reaped inside its own ``to_actor.run()`` call, any error
+   raising immediately in the calling task so your code
+   (acting as supervisor) gets first crack at handling it.
+2. the nursery then waits on daemon actors — **indefinitely**.
+   If you 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

docs/start/quickstart.rst

@@ -43,16 +43,15 @@ Run it::
 What's going on here?
 
 - ``trio.run(main)`` starts the **root actor**; the ``tractor``
-  runtime boots *implicitly* inside this ``tractor.to_actor.run()``
-  call because neither ``an=`` nor ``portal=`` was supplied. No
-  special entrypoint, no framework takeover - it's just a ``trio``
-  app,
+  runtime boots *implicitly* inside ``tractor.to_actor.run()``
+  whenever it isn't already up. No special entrypoint, no
+  framework takeover - it's just a ``trio`` app,
 - inside ``main()`` a *subactor* is spawned via
   ``tractor.to_actor.run()`` and told to run exactly one
   function: ``cellar_door()``,
 - the subactor, *some_linguist*, boots a fresh ``trio.run()`` in
-  a **new process** and executes ``cellar_door()`` as its linked
-  one-shot task (note the child proving it is *not* the root with
+  a **new process** and executes ``cellar_door()`` as its *main
+  task* (note the child proving it is *not* the root with
   ``tractor.is_root_process()``), then ships the return value
   back over IPC,
 - the call *blocks* until that final result arrives, then
@@ -68,22 +67,22 @@ What's going on here?
 
 .. note::
 
-   Without ``portal=``, ``to_actor.run()`` (parlance of
-   ``trio.to_thread`` and friends) is the *convenience* wrapper:
-   one-shot spawn-run-reap semantics for when a subactor's entire
-   job is a single function call. The core primitives are
-   :meth:`~tractor.ActorNursery.start_actor` (next up) — which
-   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`.
+   ``to_actor.run()`` (parlance of ``trio.to_thread`` and
+   friends) is the *convenience* wrapper: one-shot
+   spawn-run-reap semantics for when a subactor's entire job is
+   a single function call. The core primitives are
+   ``ActorNursery.start_actor()`` (next up) — which hands you
+   a ``Portal``, your handle for invoking tasks in the new
+   process's (separate!) memory domain — paired with
+   ``Portal.open_context()`` for full, SC-linked cross-actor
+   dialogs - see :doc:`/guide/context`.
 
 Daemon actors and RPC
 ---------------------
-A subactor spawned by ``to_actor.run()`` terminates after its lone
-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()``:
+A ``to_actor.run()`` one-shot subactor terminates when its lone
+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()``:
 
 .. literalinclude:: ../../examples/actor_spawning_and_causality_with_daemon.py
    :caption: examples/actor_spawning_and_causality_with_daemon.py
@@ -91,17 +90,14 @@ otherwise. That's ``start_actor()``:
 
 Two lifetime rules to internalize:
 
-- a subactor spawned and owned by ``to_actor.run()`` is cancelled
-  and reaped before the call returns its result or raises its error,
+- a ``to_actor.run()`` one-shot actor lives exactly as long as
+  its lone task; the call blocks until that function (and thus
+  the process) completes,
 - 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
@@ -211,20 +207,16 @@ The script of the scene (runtime ``INFO`` log lines trimmed)::
 
 The new tricks in play:
 
-- *donny* and *gretchen* start as daemon actors so each remains alive
-  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,
+- two subactors, *donny* and *gretchen*, are each told to run
+  ``say_hello()`` targeting the *other* by name,
 - ``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 each
-  ``Portal.run()`` returns its final line directly to ``main()``,
-- the actor nursery explicitly cancels both daemons only after both
-  dialogs complete,
+  actor-to-actor RPC with the root merely *directing* - and both
+  final lines flow back to ``main()`` via
+  ``await portal.wait_for_result()``,
 - ``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.

examples/a_trynamic_first_scene.py

@@ -35,12 +35,8 @@ async def main():
             for name in ('donny', 'gretchen')
         }
 
-        async def run_and_print(
-            name: str,
-            other_actor: str,
-        ) -> None:
+        async def run_and_print(name: str, other_actor: str):
             print(
-                # RPC through an existing actor's `Portal`.
                 await portals[name].run(
                     say_hello,
                     other_actor=other_actor,

examples/debugging/multi_nested_subactors_error_up_through_nurseries.py

@@ -37,8 +37,6 @@ async def spawn_until(depth=0):
                 )
             )
 
-            # 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 tractor.to_actor.run(

examples/debugging/root_cancelled_but_child_is_in_tty_lock.py

@@ -44,7 +44,7 @@ async def main():
     async with (
         tractor.open_nursery(
             debug_mode=True,
-            enable_transports=['uds'],  # TODO, pass this via osenv?
+            enable_transports=['uds'],  # TODO, apss this via osenv?
             loglevel='devx',  # XXX, required for test!
         ) as an,
         trio.open_nursery() as tn,

examples/parallelism/single_func.py

@@ -20,7 +20,7 @@ async def burn_cpu():
     for _ in range(50000):
         await trio.sleep(1/50000/50)
 
-    return pid
+    return os.getpid()
 
 
 async def main():
@@ -31,7 +31,7 @@ async def main():
         tn.start_soon(burn_cpu)
 
         # run the same func as the lone task in a subactor,
-        # block on and collect its PID as the caller-side result
+        # block on (and collect) its result
         pid = await tractor.to_actor.run(burn_cpu)
 
     print(f"Collected subproc {pid}")

examples/parallelism/to_actor_one_shots.py

@@ -1,5 +1,5 @@
 '''
-`tractor.to_actor.run()`: concurrent one-shot prime checks
+`tractor.to_actor.run()`: one-shot single-task subactor
 invocation, the SC-parallelism sibling of
 `trio.to_thread.run_sync()` (and `anyio.to_process`).
 

nooz/477.feature.rst

@@ -1,3 +0,0 @@
-Add ``tractor.to_actor.run()`` for Trio-style one-shot async calls in
-new or existing actors, with caller-scoped result/error propagation,
-linked cancellation, and deterministic reaping of call-owned children.

tests/_helpers.py

@@ -1,53 +0,0 @@
-'''
-Shared helpers for actor-runtime test suites.
-
-'''
-from pathlib import Path
-from types import TracebackType
-
-import tractor
-import trio
-
-
-class CancellationMarkers:
-    '''
-    Mark a test endpoint and require cancellation-driven teardown.
-
-    '''
-    def __init__(
-        self,
-        started_path: str,
-        cancelled_path: str,
-    ) -> None:
-        self.started_path = started_path
-        self.cancelled_path = cancelled_path
-
-    def __enter__(self) -> None:
-        Path(self.started_path).touch()
-
-    def __exit__(
-        self,
-        exc_type: type[BaseException]|None,
-        exc_value: BaseException|None,
-        traceback: TracebackType|None,
-    ) -> None:
-        assert exc_type is trio.Cancelled
-        assert isinstance(exc_value, trio.Cancelled)
-        Path(self.cancelled_path).touch()
-
-
-def non_registration_contexts(
-    actor: tractor.Actor,
-) -> dict[tuple, str]:
-    '''
-    Snapshot application contexts without registrar-service traffic.
-
-    '''
-    return {
-        key: str(ctx._nsf)
-        for key, ctx in actor._contexts.items()
-        if str(ctx._nsf) != (
-            'tractor.discovery._registry:'
-            'Registrar.register_actor'
-        )
-    }

tests/devx/test_debugger.py

@@ -27,7 +27,6 @@ from pexpect.exceptions import (
 import tractor
 
 from .conftest import (
-    ansi_strip,
     do_ctlc,
     PROMPT,
     _pause_msg,
@@ -769,15 +768,6 @@ def test_multi_subactors_root_errors(
 
 
 @has_nested_actors
-@pytest.mark.skipif(
-    platform.system() == 'Darwin'
-    and
-    bool(_ci_env),
-    reason=(
-        'Nested crash-REPL ordering is unreliable on macOS CI; '
-        'see https://github.com/goodboy/tractor/issues/320'
-    ),
-)
 def test_multi_nested_subactors_error_through_nurseries(
     ci_env: bool,
     spawn: PexpectSpawner,
@@ -804,7 +794,6 @@ def test_multi_nested_subactors_error_through_nurseries(
         loglevel='pdb',
     )
     last_send_char: str|None = None
-    transcript_parts: list[str] = []
 
     # inflate pexpect waits under CPU throttle — incl. the
     # sustained-load power-cap invisible to static freq reads — so
@@ -844,9 +833,6 @@ def test_multi_nested_subactors_error_through_nurseries(
                 PROMPT,
                 timeout=timeout,
             )
-            transcript_parts.append(
-                ansi_strip(child.before.decode())
-            )
             delay: float = 0.1
             test_log.info('Sleeping {delay!r} before next send-chart..')
             time.sleep(delay)
@@ -856,9 +842,6 @@ def test_multi_nested_subactors_error_through_nurseries(
 
         # script finally exited with tb on console.
         except EOF:
-            transcript_parts.append(
-                ansi_strip(child.before.decode())
-            )
             test_log.info(
                 f'Breaking from send-char loop'
                 f'last_send_char: {last_send_char!r}\n'
@@ -866,59 +849,43 @@ def test_multi_nested_subactors_error_through_nurseries(
             break
 
     # boxed source errors
+    #
+    # NB post-#477 (`to_actor.run()` one-shots in local
+    # task-nurseries) the final relay is the LAST-released
+    # (leaf) REPL's error chain: it wins each level's
+    # relay-vs-cancel race so every level's single-member
+    # group gets unwrapped by the runtime's `collapse_eg()`
+    # (annotated at each actor boundary) while the sibling
+    # tree ('spawner1') is cancelled + absorbed. The legacy
+    # `run_in_actor()` teardown-reap instead grouped BOTH the
+    # `name_error` and bp-quit chains into the final dump
+    # (the previously-unexplained "extra" patterns).
     expect_patts: list[str] = [
-        "NameError: name 'doggypants' is not defined",
         "tractor._exceptions.RemoteActorError:",
-        "('name_error'",
 
-        # first level subtrees
-        # "tractor._exceptions.RemoteActorError: ('spawner0'",
-        "src_uid=('spawner0'",
-
-        # "tractor._exceptions.RemoteActorError: ('spawner1'",
-
-        # propagation of errors up through nested subtrees
-        # "tractor._exceptions.RemoteActorError: ('spawn_until_0'",
-        # "tractor._exceptions.RemoteActorError: ('spawn_until_1'",
-        # "tractor._exceptions.RemoteActorError: ('spawn_until_2'",
-        # ^-NOTE-^ old RAE repr, new one is below with a field
-        # showing the src actor's uid.
-        "src_uid=('spawn_until_2'",
+        # each level's unwrapped-single-member-group
+        # annotation + the first-level subtree's boundary
+        # footer.
+        "( ^^^ this exc was collapsed from a group ^^^ )",
+        "------ ('spawner0'",
     ]
-    # XXX, I HAVE NO IDEA why these patts only show on the
-    # `trio`-spawner but it seems to have something to do with
-    # what gets dumped in prior-prompt latches somehow??
-    # TODO for claude, explain and or work through how this is
-    # happening but ONLY WHEN RUN FROM THE TEST, bc when i try to
-    # run the test script manually the correct output ALWAYS seems
-    # to be in the last `str(child.before.decode())` output !?!?
-    transcript: str = '\n'.join(transcript_parts)
     if (
         not is_forking_spawner
         and
         last_send_char == 'q'
     ):
-        # Cancellation can swap which intermediary is rendered as
-        # the immediate source vs. relay. Require both actor levels
-        # below without pinning those racy roles.
-        expect_patts.append('bdb.BdbQuit')
-        for uid in (
-            'spawn_until_0',
-            'spawn_until_1',
-        ):
-            assert any(
-                role in transcript
-                for role in (
-                    f"src_uid=('{uid}'",
-                    f"relay_uid=('{uid}'",
-                )
-            )
+        expect_patts += [
+            # expect the pdb-quit exc relayed from the leaf's
+            # bp-loop child.
+            "bdb.BdbQuit",
+            "src_uid=('breakpoint_forever'",
+        ]
 
-    for part in expect_patts:
-        assert part in transcript
-
-    assert child.flag_eof
-    assert not child.isalive()
+    assert_before(
+        child,
+        expect_patts,
+    )
+    expect(child, EOF)
 
 
 # @pytest.mark.timeout(15)
@@ -1309,8 +1276,13 @@ def test_ctxep_pauses_n_maybe_ipc_breaks(
             )
             child.sendline('c')
             child.expect(EOF)
-            assert child.flag_eof
-            assert not child.isalive()
+            assert_before(
+                child,
+                ["tractor._exceptions.RemoteActorError: remote task raised a 'BdbQuit'",
+                 "bdb.BdbQuit",
+                 "('bp_boi'",
+                ]
+            )
             break  # end-of-test
 
         child.sendline('c')
@@ -1359,10 +1331,10 @@ def test_ctxep_pauses_n_maybe_ipc_breaks(
                 expect_prompt=False,
             )
             child.expect(EOF)
-            before += ansi_strip(child.before.decode())
-            assert 'KeyboardInterrupt' in before
-            assert child.flag_eof
-            assert not child.isalive()
+            assert_before(
+                child,
+                ['KeyboardInterrupt'],
+            )
 
 
 def test_crash_handling_within_cancelled_root_actor(

tests/devx/test_pformat.py

@@ -1,84 +0,0 @@
-'''
-Unit tests for the `tractor.devx.pformat` render helpers.
-
-'''
-from __future__ import annotations
-
-import pytest
-
-from tractor._exceptions import _mk_send_mte
-from tractor.devx.pformat import (
-    pformat_boxed_tb,
-    pformat_caller_frame,
-)
-from tractor.msg._codec import _def_tractor_codec
-
-
-@pytest.mark.parametrize(
-    'box_tb',
-    [True, False],
-    ids=['boxed', 'bare'],
-)
-def test_pformat_caller_frame_renders(box_tb: bool):
-    '''
-    `pformat_caller_frame()` must render, not raise.
-
-    XXX the `box_tb=True` branch was passing an `indent=''` kwarg
-    that `pformat_boxed_tb()` never accepted, so it blew up with
-    a `TypeError`. Nothing in the test suite covered it, and the
-    only caller is `_mk_send_mte()` — i.e. EVERY send-side
-    `MsgTypeError` died while formatting itself, masking the real
-    msg-spec violation behind a bogus `TypeError`.
-
-    '''
-    report: str = pformat_caller_frame(
-        stack_limit=3,
-        box_tb=box_tb,
-    )
-    assert isinstance(report, str)
-    assert 'test_pformat_caller_frame_renders' in report
-
-
-def test_pformat_boxed_tb_rejects_unknown_kwargs():
-    '''
-    Pin the signature so a future typo'd kwarg fails loudly at the
-    call site rather than only when some rare error path runs.
-
-    '''
-    assert pformat_boxed_tb(tb_str='doggy\n')
-
-    with pytest.raises(TypeError):
-        pformat_boxed_tb(
-            tb_str='doggy\n',
-            indent='',
-        )
-
-
-def test_send_mte_default_message_renders():
-    '''
-    The default send-side `MsgTypeError` must remain printable.
-
-    Once `pformat_caller_frame()` stopped failing first, this path
-    exposed two more formatter errors: `MsgCodec.msg_spec_str` passed
-    a type union where `pformat_msgspec()` requires a codec/decoder,
-    then `_mk_send_mte()` wrapped its message in a one-element tuple.
-
-    Construct the error without an override message to execute that
-    complete default path. Requiring a `str` message with the bad
-    value and valid spec, then rendering the exception, proves the
-    original IPC violation survives every formatter layer.
-
-    '''
-    bad_msg: dict[str, bool] = {'bad': True}
-    mte = _mk_send_mte(
-        msg=bad_msg,
-        codec=_def_tractor_codec,
-    )
-
-    assert isinstance(mte.message, str)
-    assert f'invalid msg -> {bad_msg}' in mte.message
-    assert 'Valid IPC msgs are:' in mte.message
-
-    report: str = repr(mte)
-    assert 'MsgTypeError' in report
-    assert f'invalid msg -> {bad_msg}' in report

tests/devx/test_tooling.py

@@ -191,8 +191,9 @@ def test_shield_pause(
     ]
     if not no_capfd:
         expect_on_teardown += [
-            'Cancel-ack TIMED OUT for sub-actor',
-            '-> escalating to `proc.kill()` (hard-reap)',
+            # 'Shutting down actor runtime',
+            '#T-800 deployed to collect zombie B0',
+            "'--uid', \"('hanger',",
         ]
     assert_before(
         child,

tests/discovery/test_multi_program.py

@@ -207,7 +207,7 @@ def test_dup_name_cancel_cascade_escalates_to_hard_kill(
 
     Post-fix, `Portal.cancel_actor()` raises `ActorTooSlowError` on
     the bounded-wait timeout, and `ActorNursery.cancel()`'s
-    per-child wrapper escalates directly to `proc.kill()` (hard-reap).
+    per-child wrapper escalates to `proc.terminate()` (hard-kill).
     The full nursery teardown therefore stays bounded even under
     pathological timing.
 
@@ -266,7 +266,7 @@ def test_dup_name_cancel_cascade_escalates_to_hard_kill(
 
         # post-teardown sanity: every child proc must be reaped.
         # If escalation worked, even timed-out cancel-RPCs would
-        # have triggered `proc.kill()` and the procs are dead.
+        # have triggered `proc.terminate()` and the procs are dead.
         for p in portals:
             # `Portal.channel.connected()` -> False once the
             # underlying chan disconnected (clean exit OR

tests/ipc/test_each_tpt.py

@@ -7,7 +7,6 @@ import os
 from pathlib import Path
 import socket
 import stat
-import struct
 import sys
 import tempfile
 from types import SimpleNamespace
@@ -15,10 +14,6 @@ from unittest.mock import Mock
 
 import pytest
 import trio
-from trio.testing import (
-    MockClock,
-    wait_all_tasks_blocked,
-)
 import tractor
 from tractor import Actor
 from tractor.discovery import _addr
@@ -27,259 +22,56 @@ from tractor.runtime import _state
 
 
 
-def test_cancelled_transport_send_completes_frame():
+def test_cancelled_transport_send_closes_stream():
     '''
-    Finish an in-flight frame before delivering sender cancellation.
+    Discard a transport after cancellation interrupts a framed send.
 
-    A cancelled `send_all()` may leave an arbitrary frame prefix on the
-    wire. Closing the actor-wide stream avoids decoder corruption but
-    also destroys unrelated contexts using that channel. On its first
-    call, the fake stream publishes two header bytes and blocks until
-    the parent test releases it. This lets the parent cancel the sender
-    while frame publication is suspended. The sender must remain inside
-    `send_first()` until the complete frame is written, then observe
-    pending cancellation; a second sender proves sibling contexts can
-    safely reuse the still frame-aligned stream.
+    Trio's `SendStream.send_all()` may write an arbitrary frame prefix
+    before raising `Cancelled`. Sending another IPC msg afterward
+    would append a second frame and desynchronize the peer decoder.
+    The fake stream checkpoints after recording send entry; cancelling
+    its nursery deterministically interrupts that unknown-publication
+    window. Its close assertion proves the transport is made unusable
+    before another framed msg can be attempted.
 
     '''
     class PartialSendStream:
         def __init__(self) -> None:
-            self.send_all_entered = trio.Event()
-            self.send_all_release = trio.Event()
+            self.send_entered = trio.Event()
             self.closed = False
-            self.wire = bytearray()
 
         async def send_all(
             self,
             data: bytes,
         ) -> None:
             assert data
-            if not self.wire:
-                self.wire.extend(data[:2])
-                self.send_all_entered.set()
-                await self.send_all_release.wait()
-                self.wire.extend(data[2:])
-            else:
-                self.wire.extend(data)
-
-        async def aclose(self) -> None:
-            self.closed = True
-
-    def count_frames(wire: bytearray) -> int:
-        offset: int = 0
-        count: int = 0
-        while offset < len(wire):
-            header_end: int = offset + 4
-            assert header_end <= len(wire)
-            size, = struct.unpack('<I', wire[offset:header_end])
-            offset = header_end + size
-            assert offset <= len(wire)
-            count += 1
-
-        assert offset == len(wire)
-        return count
-
-    async def main() -> None:
-        stream = PartialSendStream()
-        transport = object.__new__(MsgpackTransport)
-        transport.stream = stream
-        transport._send_lock = trio.StrictFIFOLock()
-        sender_done = trio.Event()
-        sender_scopes: list[trio.CancelScope] = []
-        cancelled_caught: bool = False
-
-        first_msg = tractor.msg.Start(
-            ns=__name__,
-            func='add_one',
-            kwargs={'n': 1},
-            uid=('root', 'test'),
-            cid='partial-send',
-        )
-        second_msg = tractor.msg.Start(
-            ns=__name__,
-            func='add_one',
-            kwargs={'n': 2},
-            uid=('root', 'test'),
-            cid='second-send',
-        )
-
-        async def send_first() -> None:
-            nonlocal cancelled_caught
-            with trio.CancelScope() as cs:
-                sender_scopes.append(cs)
-                await transport.send(first_msg)
-
-            cancelled_caught = cs.cancelled_caught
-            sender_done.set()
-
-        async with trio.open_nursery() as tn:
-            tn.start_soon(
-                send_first,
-            )
-            await stream.send_all_entered.wait()
-            sender_scopes[0].cancel()
-            await wait_all_tasks_blocked()
-
-            assert not stream.closed
-            # Cancellation is pending, but complete-frame shielding
-            # keeps `send_first()` suspended in `.send_all()`.
-            assert not sender_done.is_set()
-
-            # Let the underlying frame write finish after the parent
-            # has requested sender cancellation.
-            stream.send_all_release.set()
-            await sender_done.wait()
-
-            assert cancelled_caught
-            assert not stream.closed
-            # The initial two-byte prefix was completed into one valid
-            # frame before cancellation reached `send_first()`.
-            assert count_frames(stream.wire) == 1
-
-            await transport.send(second_msg)
-            # A sibling sender can append and decode another frame only
-            # because the first cancellation preserved stream alignment.
-            assert count_frames(stream.wire) == 2
-
-            tn.cancel_scope.cancel()
-
-    trio.run(main)
-
-
-def test_transport_send_deadline_closes_partial_frame():
-    '''
-    Destroy a stalled partial frame before another sender can append.
-
-    Ordinary cancellation cannot interrupt complete-frame publication.
-    Bounded actor/context cancellation instead passes its absolute
-    deadline into this operation. The fake stream writes a partial
-    header and stalls; when the send's own deadline fires, the transport
-    must close the stream before releasing its shared send lock. This
-    prevents the next sender from appending bytes which a decoder would
-    treat as the remainder of the corrupt first frame.
-
-    '''
-    class StalledStream:
-        def __init__(self) -> None:
-            self.closed = False
-            self.wire = bytearray()
-
-        async def send_all(
-            self,
-            data: bytes,
-        ) -> None:
-            self.wire.extend(data[:2])
+            self.send_entered.set()
             await trio.sleep_forever()
 
         async def aclose(self) -> None:
             self.closed = True
 
     async def main() -> None:
-        stream = StalledStream()
+        stream = PartialSendStream()
         transport = object.__new__(MsgpackTransport)
         transport.stream = stream
         transport._send_lock = trio.StrictFIFOLock()
-        msg = tractor.msg.Start(
-            ns=__name__,
-            func='add_one',
-            kwargs={'n': 1},
-            uid=('root', 'test'),
-            cid='deadline-send',
-        )
-
-        with pytest.raises(
-            tractor.TransportClosed,
-            match='frame publication exceeded',
-        ):
-            await transport.send(
-                msg,
-                send_deadline=1,
-            )
-
-        assert stream.closed  # partial-frame timeout destroys stream
-        assert len(stream.wire) == 2  # only a header fragment was sent
-        assert not transport._send_lock.locked()  # cleanup released lock
-
-    trio.run(
-        main,
-        clock=MockClock(autojump_threshold=0),
-    )
-
-
-def test_cancelled_transport_send_preserves_cancellation():
-    '''
-    Prefer sender cancellation when teardown closes the stream.
-
-    `MsgpackTransport.send()` shields frame publication at
-    `tractor.ipc._transport:MsgpackTransport.send`. Before this fix, an
-    outer `move_on_after()`/cancel scope could cancel `Channel.send()`
-    while actor teardown closed the shared stream. The resulting
-    `ClosedResourceError` escaped from the transport handler instead of
-    its `checkpoint_if_cancelled()` redelivering pending cancellation.
-
-    The fake stream blocks inside the shield until the test cancels the
-    sender. Parent-controlled release then simulates actor teardown
-    closing the socket and raises the `ClosedResourceError` observed on
-    macOS UDS. `CancelScope.cancelled_caught` proves the handler's
-    checkpoint preserved cancellation as the primary outcome instead of
-    leaking that secondary close error.
-
-    '''
-    class ClosingStream:
-        def __init__(self) -> None:
-            self.send_all_entered = trio.Event()
-            self.send_all_release = trio.Event()
-
-        async def send_all(
-            self,
-            data: bytes,
-        ) -> None:
-            assert data
-            self.send_all_entered.set()
-            await self.send_all_release.wait()
-            # Model actor teardown closing the shared transport while
-            # this sender is still inside the complete-frame shield.
-            raise trio.ClosedResourceError(
-                'this socket was already closed'
-            )
-
-    async def main() -> None:
-        stream = ClosingStream()
-        transport = object.__new__(MsgpackTransport)
-        transport.stream = stream
-        transport._send_lock = trio.StrictFIFOLock()
-        sender_done = trio.Event()
-        sender_scopes: list[trio.CancelScope] = []
-        cancelled_caught: bool = False
-
-        msg = tractor.msg.Start(
-            ns=__name__,
-            func='add_one',
-            kwargs={'n': 1},
-            uid=('root', 'test'),
-            cid='close-during-cancelled-send',
-        )
-
-        async def send() -> None:
-            nonlocal cancelled_caught
-            with trio.CancelScope() as cs:
-                sender_scopes.append(cs)
-                await transport.send(msg)
-
-            cancelled_caught = cs.cancelled_caught
-            sender_done.set()
 
         async with trio.open_nursery() as tn:
-            tn.start_soon(send)
-            await stream.send_all_entered.wait()
-            sender_scopes[0].cancel()
-            await wait_all_tasks_blocked()
+            tn.start_soon(
+                transport.send,
+                tractor.msg.Start(
+                    ns=__name__,
+                    func='add_one',
+                    kwargs={'n': 1},
+                    uid=('root', 'test'),
+                    cid='partial-send',
+                ),
+            )
+            await stream.send_entered.wait()
+            tn.cancel_scope.cancel()
 
-            assert not sender_done.is_set()
-            stream.send_all_release.set()
-            await sender_done.wait()
-
-        assert cancelled_caught
+        assert stream.closed
 
     trio.run(main)
 

tests/msg/test_namespace_path.py

@@ -1,43 +0,0 @@
-'''
-`NamespacePath` Python-object reference tests.
-
-'''
-import pytest
-
-from tractor.msg import ptr as msgptr
-from tractor.msg.ptr import NamespacePath
-
-
-def example_target() -> None:
-    '''
-    Provide a module-addressable reference for pointer tests.
-
-    '''
-
-
-def test_retains_target_ref(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    '''
-    Reuse a retained target ref when splitting its namespace path.
-
-    `NamespacePath.from_ref()` previously discarded `example_target`,
-    so `to_tuple()` imported and resolved the just-created string again.
-    Replacing `resolve_name()` with a failure proves the retained ref
-    supplies the tuple without a redundant lookup.
-
-    '''
-    target = NamespacePath.from_ref(example_target)
-
-    def fail_resolve(name: str) -> object:
-        raise AssertionError(f'unexpected lookup for {name!r}')
-
-    monkeypatch.setattr(
-        msgptr,
-        'resolve_name',
-        fail_resolve,
-    )
-    assert target.to_tuple() == (
-        example_target.__module__,
-        example_target.__name__,
-    )

tests/test_advanced_streaming.py

@@ -25,7 +25,6 @@ _registry: dict[str, set[tractor.MsgStream]] = {
     'even': set(),
     'odd': set(),
 }
-_publisher_started: bool = False
 
 
 async def publisher(
@@ -34,13 +33,11 @@ async def publisher(
 
 ) -> None:
 
-    global _publisher_started, _registry
+    global _registry
 
     def is_even(i):
         return i % 2 == 0
 
-    _publisher_started = True
-    try:
     for val in itertools.count(seed):
 
         sub = 'even' if is_even(val) else 'odd'
@@ -52,26 +49,6 @@ async def publisher(
         # making it readable to a human user
         await trio.sleep(1/1000)
 
-    finally:
-        _publisher_started = False
-
-
-async def pubsub_active(
-    expected_subs: int,
-) -> bool:
-    '''
-    Report whether the publisher and all subscriber tasks are active.
-
-    Runs as an RPC task in the publisher actor, where `_registry` is
-    mutated by each `subscribe()` context after its consumer sends the
-    first subscription.
-
-    '''
-    return (
-        _publisher_started
-        and sum(map(len, _registry.values())) >= expected_subs
-    )
-
 
 @tractor.context
 async def subscribe(
@@ -293,16 +270,8 @@ def test_dynamic_pub_sub(
                             )
                         )
 
-                        expected_subs: int = max(cpus - 2, 0) + 1
-                        async with tractor.wait_for_actor(
-                            'publisher',
-                        ) as portal:
-                            while not await portal.run(
-                                pubsub_active,
-                                expected_subs=expected_subs,
-                            ):
-                                await trio.sleep(0.01)
-
+                        # block until "cancelled by user"
+                        await trio.sleep(3)
                         test_log.warning(
                             f'Raising user cancel exc: '
                             f'{expect_cancel_exc!r}'

tests/test_context_stream_semantics.py

@@ -11,14 +11,9 @@ from pathlib import Path
 import platform
 from pprint import pformat
 import sys
-from types import SimpleNamespace
 from typing import (
     Callable,
 )
-from unittest.mock import (
-    AsyncMock,
-    Mock,
-)
 
 import pytest
 import trio
@@ -31,7 +26,6 @@ from tractor import (
 from tractor._exceptions import (
     StreamOverrun,
     ContextCancelled,
-    TransportClosed,
 )
 from tractor.runtime._state import current_ipc_ctx
 
@@ -40,11 +34,6 @@ from tractor._testing import (
     expect_ctxc,
 )
 
-from ._helpers import (
-    CancellationMarkers,
-    non_registration_contexts,
-)
-
 # ``Context`` semantics are as follows,
 #  ------------------------------------
 
@@ -84,106 +73,34 @@ from ._helpers import (
 #   with implicit stream closure on the cancelling end.
 
 
-def test_overrun_error_send_tolerates_transport_close(
-    monkeypatch: pytest.MonkeyPatch,
-) -> None:
-    '''
-    Preserve a stream overrun when its error can not be shipped.
-
-    A full local stream buffer makes `Context._deliver_msg()` package
-    `StreamOverrun` for the remote sender. On Darwin, a concurrently
-    closing socket is wrapped as `TransportClosed`; allowing that
-    secondary error to escape replaces the primary overrun and crashes
-    the actor-wide RPC loop. This fake context forces that ordering and
-    proves failed error shipment reports non-delivery without raising.
-
-    '''
-    error_msg = tractor.msg.Error(
-        src_uid=('local', 'test'),
-        src_type_str='StreamOverrun',
-        boxed_type_str='StreamOverrun',
-        relay_path=[],
-        sender=('peer', 'test'),
-        cid='overrun',
-    )
-    packed: dict[str, object] = {}
-
-    # Spy on the generated `StreamOverrun` and return a stable wire
-    # `Error`; the real packer adds traceback/relay details unrelated to
-    # this test's secondary transport-close contract.
-    def pack_overrun(
-        local_err: BaseException,
-        cid: str,
-        **kwargs: object,
-    ) -> tractor.msg.Error:
-        packed['local_err'] = local_err
-        packed['cid'] = cid
-        packed['kwargs'] = kwargs
-        return error_msg
-
-    monkeypatch.setattr(
-        'tractor._context.pack_from_raise',
-        pack_overrun,
-    )
-
-    async def main() -> None:
-        send_chan = Mock()
-        send_chan.send_nowait.side_effect = trio.WouldBlock
-        chan = SimpleNamespace(
-            aid=SimpleNamespace(uid=('peer', 'test')),
-            send=AsyncMock(
-                side_effect=TransportClosed('peer closed'),
-            ),
-        )
-        local_aid = SimpleNamespace(
-            name='local',
-            reprol=lambda: 'local@test',
-        )
-        ctx = SimpleNamespace(
-            cid='overrun',
-            chan=chan,
-            _send_chan=send_chan,
-            _nsf='tests:overrun',
-            side='parent',
-            peer_side='child',
-            _portal=object(),
-            _task=None,
-            repr_api='Context',
-            repr_caller='test',
-            _in_overrun=False,
-            _actor=SimpleNamespace(aid=local_aid),
-            _stream_opened=True,
-            _allow_overruns=False,
-        )
-        msg = tractor.msg.Yield(
-            cid=ctx.cid,
-            pld='payload',
-        )
-
-        delivered: bool = await Context._deliver_msg(ctx, msg)
-
-        assert delivered is False
-        assert isinstance(packed['local_err'], StreamOverrun)
-        assert packed['cid'] == ctx.cid
-        chan.send.assert_awaited_once_with(error_msg)
-
-    trio.run(main)
-
 _state: bool = False
 
 
+def _non_registration_contexts(
+    actor: Actor,
+) -> dict[tuple, str]:
+    return {
+        key: str(ctx._nsf)
+        for key, ctx in actor._contexts.items()
+        if str(ctx._nsf) != (
+            'tractor.discovery._registry:'
+            'Registrar.register_actor'
+        )
+    }
+
+
 @tractor.context
 async def startup_cancel_target(
     ctx: Context,
     started_path: str,
     cancelled_path: str,
 ) -> None:
-    with CancellationMarkers(
-        started_path,
-        cancelled_path,
-    ):
+    Path(started_path).touch()
+    try:
         await ctx.started()
         await trio.sleep_forever()
+    finally:
+        Path(cancelled_path).touch()
 
 
 async def return_one() -> int:
@@ -278,7 +195,7 @@ async def simple_setup_teardown(
         _state = False
 
 
-async def assert_state(value: bool) -> None:
+async def assert_state(value: bool):
     global _state
     assert _state == value
 
@@ -289,7 +206,7 @@ async def test_cancel_during_context_startup(
     tmp_path: Path,
     start_method: str,
     debug_mode: bool,
-) -> None:
+):
     '''
     Cancel a context after sending `Start` but before its ack.
 
@@ -306,26 +223,19 @@ async def test_cancel_during_context_startup(
     started_path = tmp_path / 'startup_started'
     cancelled_path = tmp_path / 'startup_cancelled'
     start_sent = trio.Event()
-    start_funcs: list[str] = []
     original_send = tractor.Channel.send
 
     async def delay_after_start(
         chan: tractor.Channel,
         payload: object,
         hide_tb: bool = False,
-        send_deadline: float = float('inf'),
     ) -> None:
         await original_send(
             chan,
             payload,
             hide_tb=hide_tb,
-            send_deadline=send_deadline,
         )
-        # The patched method keeps `Channel.send()`'s broad message
-        # contract. It sees both the requested endpoint `Start` and the
-        # internal `self._cancel_task` startup RPC used for cleanup.
         if isinstance(payload, tractor.msg.Start):
-            start_funcs.append(payload.func)
             if payload.func == 'startup_cancel_target':
                 start_sent.set()
             await trio.sleep_forever()
@@ -341,12 +251,12 @@ async def test_cancel_during_context_startup(
             raise AssertionError('context startup should be cancelled')
 
     async with tractor.open_nursery() as an:
-        actor: Actor = tractor.current_actor()
+        actor = tractor.current_actor()
         portal: tractor.Portal = await an.start_actor(
             'startup_cancel_worker',
             enable_modules=[__name__],
         )
-        contexts_before = non_registration_contexts(actor)
+        contexts_before = _non_registration_contexts(actor)
         monkeypatch.setattr(
             tractor.Channel,
             'send',
@@ -367,16 +277,12 @@ async def test_cancel_during_context_startup(
             original_send,
         )
         assert cancelled_path.exists()
-        assert non_registration_contexts(actor) == contexts_before
+        assert _non_registration_contexts(actor) == contexts_before
         assert await portal.run_from_ns(
             __name__,
             'return_one',
         ) == 1
-        assert non_registration_contexts(actor) == contexts_before
-        assert start_funcs == [
-            'startup_cancel_target',
-            '_cancel_task',
-        ]
+        assert _non_registration_contexts(actor) == contexts_before
         await portal.cancel_actor()
 
 
@@ -384,7 +290,7 @@ async def test_cancel_during_context_startup(
 async def test_start_serialization_error_cleans_context(
     start_method: str,
     debug_mode: bool,
-) -> None:
+):
     '''
     Deallocate caller state when `Start` can not be serialized.
 
@@ -397,12 +303,12 @@ async def test_start_serialization_error_cleans_context(
 
     '''
     async with tractor.open_nursery() as an:
-        actor: Actor = tractor.current_actor()
+        actor = tractor.current_actor()
         portal: tractor.Portal = await an.start_actor(
             'serialization_error_worker',
             enable_modules=[__name__],
         )
-        contexts_before = non_registration_contexts(actor)
+        contexts_before = _non_registration_contexts(actor)
         with pytest.raises(tractor.MsgTypeError):
             async with portal.open_context(
                 simple_setup_teardown,
@@ -410,7 +316,7 @@ async def test_start_serialization_error_cleans_context(
             ):
                 raise AssertionError('invalid `Start` was accepted')
 
-        assert non_registration_contexts(actor) == contexts_before
+        assert _non_registration_contexts(actor) == contexts_before
         async with portal.open_context(
             simple_setup_teardown,
             data=1,
@@ -418,7 +324,7 @@ async def test_start_serialization_error_cleans_context(
             assert started == 2
             assert await ctx.wait_for_result() == 'yo'
 
-        assert non_registration_contexts(actor) == contexts_before
+        assert _non_registration_contexts(actor) == contexts_before
         await portal.cancel_actor()
 
 
@@ -426,7 +332,7 @@ async def test_start_serialization_error_cleans_context(
 async def test_start_module_error_cleans_context(
     start_method: str,
     debug_mode: bool,
-) -> None:
+):
     '''
     Deallocate caller state after a remote startup rejection.
 
@@ -439,11 +345,11 @@ async def test_start_module_error_cleans_context(
 
     '''
     async with tractor.open_nursery() as an:
-        actor: Actor = tractor.current_actor()
+        actor = tractor.current_actor()
         portal: tractor.Portal = await an.start_actor(
             'module_error_worker',
         )
-        contexts_before = non_registration_contexts(actor)
+        contexts_before = _non_registration_contexts(actor)
         with pytest.raises(tractor.RemoteActorError) as excinfo:
             async with portal.open_context(
                 simple_setup_teardown,
@@ -452,7 +358,7 @@ async def test_start_module_error_cleans_context(
                 raise AssertionError('unexposed context was started')
 
         assert excinfo.value.boxed_type is tractor.ModuleNotExposed
-        assert non_registration_contexts(actor) == contexts_before
+        assert _non_registration_contexts(actor) == contexts_before
         await portal.cancel_actor()
 
 

tests/test_pubsub.py

@@ -194,18 +194,14 @@ def test_multi_actor_subs_arbiter_pub(
                 )
                 name = 'streamer'
 
-            root_uid = tractor.current_actor().aid.uid
-
             # spawn the two subscriber actors as daemons and run
             # `subs()` on each as a background task (was the legacy
             # `run_in_actor()`); keep the portals for the explicit
             # `cancel_actor()` teardown below. Each runner swallows
-            # only the cancellation relayed after its own teardown
-            # starts; every earlier or unrelated failure propagates.
+            # the teardown error that `cancel_actor()` relays.
             async def _run_subs(
                 portal: tractor.Portal,
                 which: list[str],
-                teardown_started: trio.Event,
             ) -> None:
                 try:
                     await portal.run(
@@ -213,16 +209,11 @@ def test_multi_actor_subs_arbiter_pub(
                         which=which,
                         pub_actor_name=name,
                     )
-                except tractor.ContextCancelled as ctxc:
-                    if not (
-                        teardown_started.is_set()
-                        and
-                        ctxc.canceller == root_uid
+                except (
+                    tractor.RemoteActorError,
+                    tractor.ContextCancelled,
                 ):
-                        raise
-
-            even_teardown_started = trio.Event()
-            odd_teardown_started = trio.Event()
+                    pass  # expected once we `cancel_actor()` below
 
             even_portal = await an.start_actor(
                 'evens',
@@ -232,18 +223,8 @@ def test_multi_actor_subs_arbiter_pub(
                 'odds',
                 enable_modules=[__name__],
             )
-            tn.start_soon(
-                _run_subs,
-                even_portal,
-                ['even'],
-                even_teardown_started,
-            )
-            tn.start_soon(
-                _run_subs,
-                odd_portal,
-                ['odd'],
-                odd_teardown_started,
-            )
+            tn.start_soon(_run_subs, even_portal, ['even'])
+            tn.start_soon(_run_subs, odd_portal, ['odd'])
 
             async with tractor.wait_for_actor('evens'):
                 # block until 2nd actor is initialized
@@ -282,14 +263,12 @@ def test_multi_actor_subs_arbiter_pub(
             # await even_portal.result()
 
             await trio.sleep(0.5)
-            even_teardown_started.set()
             await even_portal.cancel_actor()
             await trio.sleep(1)
 
             if pub_actor == 'arbiter':
                 assert 'even' not in get_topics()
 
-            odd_teardown_started.set()
             await odd_portal.cancel_actor()
 
             if pub_actor == 'arbiter':

tests/test_to_actor.py

@@ -8,38 +8,23 @@ https://github.com/goodboy/tractor/issues/477
 '''
 from functools import partial
 from pathlib import Path
-from types import SimpleNamespace
 
 import pytest
 import trio
-from trio.testing import MockClock
 import tractor
 from tractor import (
     RemoteActorError,
     to_actor,
 )
 from tractor._testing import tractor_test
-from tractor._exceptions import ActorTooSlowError
+from tractor.msg import ptr as msgptr
 from tractor.msg.ptr import NamespacePath
-from tractor.spawn import _mp as mp_spawn
 from tractor.to_actor import _api as to_actor_api
 
-from ._helpers import (
-    CancellationMarkers,
-    non_registration_contexts,
-)
-
 
 async def add_one(
     n: int,
 ) -> int:
-    '''
-    Increment within an active actor runtime.
-
-    '''
-    assert tractor.current_actor(
-        err_on_no_runtime=False,
-    ) is not None
     return n + 1
 
 
@@ -69,17 +54,17 @@ async def mark_task_cancellation(
     started_path: str,
     cancelled_path: str,
 ) -> None:
-    with CancellationMarkers(
-        started_path,
-        cancelled_path,
-    ):
+    Path(started_path).touch()
+    try:
         await trio.sleep_forever()
+    finally:
+        Path(cancelled_path).touch()
 
 
 async def echo_startup_control(
-    cancel_on_startup: str,
+    _cancel_on_startup: str,
 ) -> str:
-    return cancel_on_startup
+    return _cancel_on_startup
 
 
 async def collect_args(
@@ -88,15 +73,53 @@ async def collect_args(
     return args
 
 
-def test_public_module_alias() -> None:
-    '''
-    Keep the public trampoline alias separate from its private module.
+async def collect_call(
+    *args: object,
+    **kwargs: object,
+) -> tuple[tuple[object, ...], dict[str, object]]:
+    return args, kwargs
 
-    Callers use `to_actor.MODULE` to configure an existing actor's RPC
-    allowlist, while `_api.__name__` remains the authoritative module
-    path and does not re-export the alias internally.
+
+def _non_registration_contexts(
+    actor: tractor.Actor,
+) -> dict[tuple, str]:
+    return {
+        key: str(ctx._nsf)
+        for key, ctx in actor._contexts.items()
+        if str(ctx._nsf) != (
+            'tractor.discovery._registry:'
+            'Registrar.register_actor'
+        )
+    }
+
+
+def test_namespace_path_retains_target_ref(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    '''
+    Reuse the client-side target ref when splitting its namespace path.
+
+    `NamespacePath.from_ref()` previously discarded `add_one`, so
+    `to_tuple()` imported and resolved the just-created string again.
+    Replacing `resolve_name()` with a failure proves the retained ref
+    supplies the tuple without a redundant lookup. The public module
+    alias assertion also keeps internal `_api.__name__` authoritative.
 
     '''
+    target = NamespacePath.from_ref(add_one)
+
+    def fail_resolve(name: str) -> object:
+        raise AssertionError(f'unexpected lookup for {name!r}')
+
+    monkeypatch.setattr(
+        msgptr,
+        'resolve_name',
+        fail_resolve,
+    )
+    assert target.to_tuple() == (
+        add_one.__module__,
+        add_one.__name__,
+    )
     assert to_actor.MODULE == to_actor_api.__name__
     assert not hasattr(to_actor_api, 'MODULE')
 
@@ -125,9 +148,7 @@ def test_one_shot_boots_implicit_runtime(
     '''
     Outside any actor-runtime `to_actor.run()` boots one
     implicitly (just like bare `open_nursery()` usage)
-    configured via pass-through `runtime_kwargs`. The remote target
-    asserts its runtime exists; the caller then verifies the private
-    runtime is fully torn down before `to_actor.run()` returns.
+    configured via pass-through `runtime_kwargs`.
 
     '''
     async def main() -> None:
@@ -144,9 +165,6 @@ def test_one_shot_boots_implicit_runtime(
             ),
         )
         assert result == 42
-        assert tractor.current_actor(
-            err_on_no_runtime=False,
-        ) is None
 
     trio.run(main)
 
@@ -179,10 +197,10 @@ async def test_spawn_from_caller_nursery(
 
     Previously `to_actor.run()` treated an actor-runtime cancel ack
     as process reaping, so the call returned while the child monitor
-    and its `ActorNursery` child/reap bookkeeping remained alive until
-    the entire nursery exited. The assertions inside the still-open
-    nursery prove child-process joining and removal from all three
-    mappings complete before the one-shot call returns.
+    and its `ActorNursery._children` record remained alive until the
+    entire nursery exited. The assertion inside the still-open
+    nursery proves child-process joining and record removal now
+    complete before the one-shot call returns.
 
     '''
     async with tractor.open_nursery() as an:
@@ -192,8 +210,6 @@ async def test_spawn_from_caller_nursery(
             an=an,
         ) == 11
         assert not an._children
-        assert not an._child_reap_requests
-        assert not an._child_reaped
 
 
 @tractor_test
@@ -205,18 +221,13 @@ async def test_cancel_ack_failure_hard_reaps_child(
     '''
     Escalate a failed cancel acknowledgement and reap the child.
 
-    `Portal.cancel_actor()` catches `TransportClosed` and returns
-    `False` when it can not confirm runtime cancellation. The mock
-    represents that public post-transport-failure result, so no
-    underlying exception remains to bubble through `to_actor.run()`.
-
-    The old one-shot path ignored `False`, released the nursery-wide
-    join gate and then waited forever for a still-running process.
-    `_cancel_and_reap_child()` must instead hard-kill and join the child.
-    The five-second scope is only a generous CI hang ceiling: normal
-    teardown returns much sooner, while expiry fails the test. Final
-    assertions prove the child monitor removes every `ActorNursery`
-    child/reap entry before returning.
+    `Portal.cancel_actor()` can return `False` when its transport is
+    already closed without confirming runtime cancellation. The old
+    one-shot path ignored that result, released the nursery-wide join
+    gate and then waited forever for a still-running process. This
+    test forces that exact result without cancelling the actor, caps
+    the call to detect the former hang and verifies the child monitor
+    removes its `ActorNursery._children` record before returning.
 
     '''
     async def cancel_without_ack(
@@ -227,8 +238,6 @@ async def test_cancel_ack_failure_hard_reaps_child(
         assert raise_on_timeout
         return False
 
-    # Model `Portal.cancel_actor()` after it catches `TransportClosed`;
-    # there is no transport exception left for `run()` to re-raise.
     monkeypatch.setattr(
         tractor.Portal,
         'cancel_actor',
@@ -236,8 +245,6 @@ async def test_cancel_ack_failure_hard_reaps_child(
     )
 
     async with tractor.open_nursery() as an:
-        # Expiry means hard reaping hung; five seconds is not the
-        # expected duration of the successful path.
         with trio.fail_after(5):
             assert await to_actor.run(
                 add_one,
@@ -245,280 +252,6 @@ async def test_cancel_ack_failure_hard_reaps_child(
                 an=an,
             ) == 21
         assert not an._children
-        assert not an._child_reap_requests
-        assert not an._child_reaped
-
-
-def test_cancel_actor_shares_request_and_ack_deadline():
-    '''
-    Share one cancel deadline across request publication and ack waiting.
-
-    The cancel RPC's outer timeout cannot penetrate a complete-frame
-    shield. The fake private RPC applies the forwarded send deadline to
-    its own shielded wait, then checkpoints into the outer scope. A
-    bounded `ActorTooSlowError` and the recorded absolute deadline prove
-    publication and acknowledgement share one timeout budget.
-
-    A real subactor can not deterministically stall the caller's
-    outbound frame at this exact boundary. Actual partial-frame stream
-    closure is covered by
-    `test_transport_send_deadline_closes_partial_frame()`.
-
-    '''
-    class ConnectedChannel:
-        def __init__(self) -> None:
-            self._cancel_called = False
-            self.aid = tractor.msg.Aid(
-                name='blocked_peer',
-                uuid='test',
-            )
-
-        def connected(self) -> bool:
-            return True
-
-    async def main() -> None:
-        channel = ConnectedChannel()
-        # `Portal.__init__()` requires live actor-runtime state; this
-        # unit seam needs only its channel and private RPC method.
-        portal = object.__new__(tractor.Portal)
-        portal._chan = channel
-        deadlines: list[float] = []
-
-        async def blocked_cancel(
-            namespace: str,
-            function: str,
-            kwargs: dict[str, object],
-            cancel_on_startup: bool,
-            send_deadline: float,
-        ) -> None:
-            assert (namespace, function) == ('self', 'cancel')
-            assert kwargs == {}
-            assert not cancel_on_startup
-            deadlines.append(send_deadline)
-            with trio.CancelScope(
-                deadline=send_deadline,
-                shield=True,
-            ):
-                await trio.sleep_forever()
-            await trio.lowlevel.checkpoint_if_cancelled()
-
-        portal._run_from_ns = blocked_cancel
-        with pytest.raises(ActorTooSlowError):
-            await portal.cancel_actor(
-                timeout=1,
-                raise_on_timeout=True,
-            )
-
-        assert deadlines == [1.]
-
-    trio.run(
-        main,
-        clock=MockClock(autojump_threshold=0),
-    )
-
-
-def test_context_cancel_shares_request_and_ack_deadline():
-    '''
-    Bound context-cancel publication and acknowledgement together.
-
-    `Context.cancel()` shields its transaction from outer cancellation,
-    while `MsgpackTransport.send()` separately shields complete frame
-    publication. Previously the context's timeout was not forwarded to
-    that inner shield, so a peer which stopped reading could leave the
-    cancel task blocked forever instead of respecting `timeout`.
-
-    The fake private RPC records the forwarded absolute deadline and
-    blocks under a send-like shield until that deadline. The mock clock
-    advances directly to it; completion and the exact recorded value
-    prove that publication shares the context's one-second budget.
-    The transport suite separately proves that deadline expiry closes
-    a stream after partial frame publication.
-
-    '''
-    async def main() -> None:
-        deadlines: list[float] = []
-
-        async def blocked_cancel(
-            namespace: str,
-            function: str,
-            kwargs: dict[str, object],
-            cancel_on_startup: bool,
-            send_deadline: float,
-        ) -> None:
-            assert (namespace, function) == ('self', '_cancel_task')
-            assert kwargs == {'cid': 'blocked-context'}
-            assert not cancel_on_startup
-            deadlines.append(send_deadline)
-            with trio.CancelScope(
-                deadline=send_deadline,
-                shield=True,
-            ):
-                await trio.sleep_forever()
-            await trio.lowlevel.checkpoint_if_cancelled()
-
-        peer_aid = tractor.msg.Aid(
-            name='blocked_peer',
-            uuid='test',
-        )
-
-        def connected() -> bool:
-            return True
-
-        # `Context.__init__()` requires live actor/channel registration;
-        # this unit seam supplies only state consumed by `.cancel()`.
-        ctx = object.__new__(tractor.Context)
-        ctx.chan = SimpleNamespace(
-            aid=peer_aid,
-            connected=connected,
-            transport=SimpleNamespace(maddr='test://blocked'),
-        )
-        ctx.cid = 'blocked-context'
-        ctx._portal = SimpleNamespace(_run_from_ns=blocked_cancel)
-        ctx._nsf = NamespacePath.from_ref(add_one)
-
-        await ctx.cancel(timeout=1)
-
-        assert deadlines == [1.]
-
-    trio.run(
-        main,
-        clock=MockClock(autojump_threshold=0),
-    )
-
-
-def _mock_actor_nursery() -> tractor.ActorNursery:
-    an = object.__new__(tractor.ActorNursery)
-    an._children = {}
-    an._join_procs = trio.Event()
-    an._child_reap_requests = {}
-    an._child_reaped = {}
-    an._at_least_one_child_in_debug = False
-    an._cancel_called = False
-    return an
-
-
-def test_late_child_registration_observes_cancel():
-    '''
-    Make registration atomically observe nursery cancellation.
-
-    `ActorNursery.cancel()` previously snapshotted `_children` before
-    its next checkpoint. A process monitor registering after that
-    snapshot received a reap request but no runtime cancellation, then
-    waited forever for natural exit. Publishing the child and its reap
-    events together returns cancellation ownership to the late monitor.
-
-    '''
-    an = _mock_actor_nursery()
-    # `ActorNursery.cancel()` has set its sticky flag after taking the
-    # old `_children` snapshot but before backend registration resumes.
-    an._cancel_called = True
-    aid = tractor.msg.Aid(
-        name='late_child',
-        uuid='test',
-    )
-    subactor = SimpleNamespace(aid=aid)
-    proc = object()
-
-    (
-        reap_request,
-        reaped,
-        cancel_during_registration,
-    ) = an._register_child(
-        subactor,
-        proc,
-        None,
-    )
-
-    assert cancel_during_registration
-    assert an._children[aid.uid] == (
-        subactor,
-        proc,
-        None,
-    )
-    assert an._child_reap_requests[aid] is reap_request
-    assert an._child_reaped[aid] is reaped
-
-
-def test_mp_late_registration_never_starts_process(
-    monkeypatch: pytest.MonkeyPatch,
-):
-    '''
-    Refuse to start an MP child already owned by nursery cancellation.
-
-    A concurrent `ActorNursery.cancel()` can publish cancellation after
-    `start_actor()` checks its flag but before the MP backend registers
-    its process. The fake registration reports that exact schedule.
-    Proving `FakeProcess.start()` is never called prevents a child from
-    starting after it was omitted from the cancellation snapshot.
-
-    '''
-    class FakeProcess:
-        started: bool = False
-
-        def start(self) -> None:
-            self.started = True
-
-    process = FakeProcess()
-
-    def register_child(
-        subactor: object,
-        proc: object,
-        portal: object|None,
-    ) -> tuple[trio.Event, trio.Event, bool]:
-        '''
-        Simulate provisional MP registration before child startup.
-
-        '''
-        assert subactor
-        assert proc is process
-        assert portal is None
-        return (
-            trio.Event(),
-            trio.Event(),
-            True,
-        )
-
-    class FakeContext:
-        def get_start_method(self) -> str:
-            return 'spawn'
-
-        def Process(self, **kwargs: object) -> FakeProcess:
-            assert kwargs
-            return process
-
-    nursery = SimpleNamespace(
-        _register_child=register_child,
-    )
-    subactor = SimpleNamespace(
-        aid=tractor.msg.Aid(
-            name='late_mp_child',
-            uuid='test',
-        ),
-    )
-    monkeypatch.setattr(
-        mp_spawn._spawn,
-        '_ctx',
-        FakeContext(),
-    )
-
-    with pytest.raises(
-        RuntimeError,
-        match='nursery began cancelling',
-    ):
-        trio.run(
-            partial(
-                mp_spawn.mp_proc,
-                name='late_mp_child',
-                actor_nursery=nursery,
-                subactor=subactor,
-                errors={},
-                bind_addrs=[],
-                parent_addr=SimpleNamespace(),
-                _runtime_vars={},
-            )
-        )
-
-    assert not process.started
 
 
 def test_late_child_reap_registration_is_released():
@@ -538,14 +271,10 @@ def test_late_child_reap_registration_is_released():
     an._child_reap_requests = {}
     an._child_reaped = {}
 
-    # Nursery teardown publishes its reap request while the child
-    # monitor is checkpointed before per-child event registration.
     an._join_procs.set()
-    aid = tractor.msg.Aid(
-        name='late_child',
-        uuid='uid',
+    reap_request, _ = an._register_child_reap(
+        ('late_child', 'uid'),
     )
-    reap_request, _ = an._register_child_reap(aid)
 
     assert reap_request.is_set()
 
@@ -580,12 +309,9 @@ async def test_reuse_existing_actor_via_portal(
     Pass `portal=` to schedule the one-shot task in an
     already-running actor; no spawn, no implicit reap.
 
-    The low-level call uses `__name__` to select the remote module and
-    `'echo_startup_control'` to select its function. Public
-    `Portal.run_from_ns()` packages `cancel_on_startup` inside the
-    target `kwargs` passed to private `Portal._run_from_ns()`. Receiving
-    `'target_value'` back proves the value reached the target instead of
-    binding the private Boolean startup-cancellation policy parameter.
+    The low-level `Portal.run_from_ns()` assertion also proves its
+    target kwargs remain separate from the private startup-cancel
+    policy used by context cleanup.
 
     '''
     async with tractor.open_nursery() as an:
@@ -597,7 +323,7 @@ async def test_reuse_existing_actor_via_portal(
                 to_actor.MODULE,
             ],
         )
-        contexts_before = non_registration_contexts(actor)
+        contexts_before = _non_registration_contexts(actor)
         for i in range(3):
             assert await to_actor.run(
                 add_one,
@@ -608,9 +334,9 @@ async def test_reuse_existing_actor_via_portal(
         assert await portal.run_from_ns(
             __name__,
             'echo_startup_control',
-            cancel_on_startup='target_value',
+            _cancel_on_startup='target_value',
         ) == 'target_value'
-        assert non_registration_contexts(actor) == contexts_before
+        assert _non_registration_contexts(actor) == contexts_before
 
         # still alive: caller owns the actor's lifetime.
         await portal.cancel_actor()
@@ -627,8 +353,6 @@ async def test_concurrent_one_shots_from_task_nursery(
     nursery scheduling multiple one-shot calls against
     a shared caller-managed actor-nursery; error
     collection thus lives entirely in caller-code.
-    A proposed distilled task-manager API is tracked in #485:
-    https://github.com/goodboy/tractor/issues/485
 
     '''
     results: dict[int, int] = {}
@@ -656,7 +380,7 @@ async def test_concurrent_one_shots_from_task_nursery(
     }
 
 
-def test_rejects_sync_fn() -> None:
+def test_rejects_sync_fn():
     '''
     Non-async callables error BEFORE any spawn (or even
     runtime-boot) happens.
@@ -665,10 +389,7 @@ def test_rejects_sync_fn() -> None:
     def not_async() -> None:
         ...
 
-    with pytest.raises(
-        TypeError,
-        match='must be a non-streaming async function',
-    ):
+    with pytest.raises(TypeError):
         trio.run(
             partial(
                 to_actor.run,
@@ -677,7 +398,7 @@ def test_rejects_sync_fn() -> None:
         )
 
 
-def test_rejects_streaming_fn() -> None:
+def test_rejects_streaming_fn():
     '''
     Async-gen (streaming) fns are not one-shot-able,
     same constraint as `Portal.run()`.
@@ -686,10 +407,7 @@ def test_rejects_streaming_fn() -> None:
     async def agen():
         yield 1
 
-    with pytest.raises(
-        TypeError,
-        match='must be a non-streaming async function',
-    ):
+    with pytest.raises(TypeError):
         trio.run(
             partial(
                 to_actor.run,
@@ -742,7 +460,7 @@ def test_partial_placeholder_normalization(
         )
 
 
-def test_nested_partial_normalization() -> None:
+def test_nested_partial_normalization():
     '''
     Flatten every retained `functools.partial` layer before RPC.
 
@@ -754,12 +472,6 @@ def test_nested_partial_normalization() -> None:
     direct nested-partial call.
 
     '''
-    async def collect_call(
-        *args: object,
-        **kwargs: object,
-    ) -> tuple[tuple[object, ...], dict[str, object]]:
-        return args, kwargs
-
     inner = partial(
         collect_call,
         1,
@@ -781,15 +493,13 @@ def test_nested_partial_normalization() -> None:
     assert kwargs == {'label': 'outer'}
 
 
-def test_rejects_portal_and_an_combo() -> None:
+def test_rejects_portal_and_an_combo():
     '''
-    `portal=` and `an=` are mutually exclusive actor-lifetime handles.
+    `portal=` and `an=` are mutually exclusive
+    placement options.
 
     '''
-    with pytest.raises(
-        ValueError,
-        match='Pass at most ONE of `portal` or `an`',
-    ):
+    with pytest.raises(ValueError):
         trio.run(
             partial(
                 to_actor.run,
@@ -802,7 +512,7 @@ def test_rejects_portal_and_an_combo() -> None:
 
 
 @pytest.mark.parametrize(
-    'lifetime_mode',
+    'placement',
     ['an', 'portal'],
 )
 @pytest.mark.parametrize(
@@ -813,31 +523,28 @@ def test_rejects_portal_and_an_combo() -> None:
     ],
     ids=['empty', 'configured'],
 )
-def test_rejects_runtime_kwargs_with_lifetime_mode(
-    lifetime_mode: str,
+def test_rejects_runtime_kwargs_with_placement(
+    placement: str,
     runtime_kwargs: dict,
-) -> None:
+):
     '''
     `runtime_kwargs` only applies when the call opens
     its own private actor-nursery; passing it alongside
-    an actor-lifetime handle is an error, never silently
+    a placement opt is an error, never silently
     ignored. In particular, an empty dict still means the
     caller provided this mutually exclusive option; testing
-    both lifetime modes prevents truthiness checks from
+    both placement modes prevents truthiness checks from
     accepting it before any actor runtime is started.
 
     '''
-    with pytest.raises(
-        ValueError,
-        match='`runtime_kwargs` only applies',
-    ):
+    with pytest.raises(ValueError):
         trio.run(
             partial(
                 to_actor.run,
                 add_one,
                 1,
                 **{
-                    lifetime_mode: object(),
+                    placement: object(),
                     'runtime_kwargs': runtime_kwargs,
                 },
             )
@@ -895,13 +602,12 @@ async def test_portal_task_cancelled_with_local_caller(
     Couple a reused portal's remote task to its local caller.
 
     The former `Portal.run()` path abandoned its remote task when the
-    local `to_actor.run()` caller was cancelled. `CancellationMarkers`
-    writes one file after entry and writes the second only after its
-    synchronous exit verifies the remote task received `trio.Cancelled`.
-    Cancelling the local task nursery and observing that marker proves
-    `Portal.open_context()` propagated cancellation before the caller
-    exited. A subsequent call proves the caller-owned actor was not
-    cancelled with that task.
+    local `to_actor.run()` caller was cancelled. The target writes
+    one file after starting and another from its cancellation
+    `finally`. Cancelling the local task nursery and observing the
+    second file proves `Portal.open_context()` propagated
+    cancellation before the caller exited. A subsequent call proves
+    the caller-owned actor was not cancelled with that task.
 
     '''
     started_path = tmp_path / 'started'
@@ -916,7 +622,7 @@ async def test_portal_task_cancelled_with_local_caller(
                 to_actor.MODULE,
             ],
         )
-        contexts_before = non_registration_contexts(actor)
+        contexts_before = _non_registration_contexts(actor)
 
         async with trio.open_nursery() as tn:
             tn.start_soon(
@@ -934,17 +640,13 @@ async def test_portal_task_cancelled_with_local_caller(
             tn.cancel_scope.cancel()
 
         assert cancelled_path.exists()
-        # Remote-task cancellation must restore the exact application
-        # context snapshot captured before the one-shot call.
-        assert non_registration_contexts(actor) == contexts_before
+        assert _non_registration_contexts(actor) == contexts_before
         assert await to_actor.run(
             add_one,
             1,
             portal=portal,
         ) == 2
-        # Reusing the actor for a later successful call must also leave
-        # no local or remote context registry entries behind.
-        assert non_registration_contexts(actor) == contexts_before
+        assert _non_registration_contexts(actor) == contexts_before
 
         await portal.cancel_actor()
 
@@ -970,7 +672,7 @@ async def test_context_trampoline_preserves_module_allowlist(
             'restricted_context_worker',
             enable_modules=[to_actor.MODULE],
         )
-        contexts_before = non_registration_contexts(actor)
+        contexts_before = _non_registration_contexts(actor)
         with pytest.raises(RemoteActorError) as excinfo:
             await to_actor.run(
                 add_one,
@@ -978,11 +680,8 @@ async def test_context_trampoline_preserves_module_allowlist(
                 portal=portal,
             )
 
-        err = excinfo.value
-        assert err.boxed_type is tractor.ModuleNotExposed
-        assert add_one.__module__ in str(err)
-        assert 'Make sure you exposed the target module' in str(err)
-        assert non_registration_contexts(actor) == contexts_before
+        assert excinfo.value.boxed_type is tractor.ModuleNotExposed
+        assert _non_registration_contexts(actor) == contexts_before
         await portal.cancel_actor()
 
 
@@ -1006,7 +705,7 @@ async def test_portal_requires_context_trampoline(
             'no_context_trampoline_worker',
             enable_modules=[__name__],
         )
-        contexts_before = non_registration_contexts(actor)
+        contexts_before = _non_registration_contexts(actor)
         with pytest.raises(RemoteActorError) as excinfo:
             await to_actor.run(
                 add_one,
@@ -1017,5 +716,5 @@ async def test_portal_requires_context_trampoline(
         err = excinfo.value
         assert err.boxed_type is tractor.ModuleNotExposed
         assert to_actor.MODULE in str(err)
-        assert non_registration_contexts(actor) == contexts_before
+        assert _non_registration_contexts(actor) == contexts_before
         await portal.cancel_actor()

tractor/_context.py

@@ -1097,12 +1097,7 @@ class Context:
                 )
 
             cid: str = self.cid
-            cancel_deadline: float = (
-                trio.current_time()
-                +
-                timeout
-            )
-            with trio.move_on_at(cancel_deadline) as cs:
+            with trio.move_on_after(timeout) as cs:
                 cs.shield = True
                 log.cancel(
                     header
@@ -1113,16 +1108,11 @@ class Context:
                 # NOTE: we're telling the far end actor to cancel a task
                 # corresponding to *this actor*. The far end local channel
                 # instance is passed to `Actor._cancel_task()` implicitly.
-                # Use private `Portal._run_from_ns()` because cancellation
-                # needs its internal `cancel_on_startup=False` policy and
-                # the transaction's shared absolute `send_deadline`; public
-                # `run_from_ns()` exposes neither control.
                 await self._portal._run_from_ns(
                     'self',
                     '_cancel_task',
                     kwargs={'cid': cid},
                     cancel_on_startup=False,
-                    send_deadline=cancel_deadline,
                 )
 
             if cs.cancelled_caught:
@@ -1959,9 +1949,6 @@ class Context:
         # the sender; the main motivation is that using bp can block the
         # msg handling loop which calls into this method!
         except trio.WouldBlock:
-            # `send_chan.send_nowait(msg)` found the local receive feeder
-            # full. With overruns disabled below, report that primary
-            # local overflow to the far-end sender as `StreamOverrun`.
 
             # XXX: always push an error even if the local receiver
             # is in overrun state - i.e. if an 'error' msg is
@@ -2034,17 +2021,9 @@ class Context:
                     await chan.send(err_msg)
                     return True
 
-                # The `StreamOverrun` shipment can fail secondarily when
-                # context/channel teardown has already closed shared IPC.
-                # Local stream closure may surface as
-                # `BrokenResourceError`; either peer closing the transport
-                # can surface as `TransportClosed`. In both cases teardown
-                # owns far-end cancellation and the primary overrun can no
-                # longer be delivered.
-                except (
-                    TransportClosed,
-                    trio.BrokenResourceError,
-                ):
+                # XXX: local consumer has closed their side of
+                # the IPC so cancel the far end streaming task
+                except trio.BrokenResourceError:
                     log.warning(
                         'Channel for ctx is already closed?\n'
                         f'|_{chan}\n'

tractor/_exceptions.py

@@ -1505,7 +1505,7 @@ def _mk_send_mte(
             f'invalid msg -> {msg}: {type(msg)}\n\n'
             f'{tb_fmt}\n'
             f'Valid IPC msgs are:\n\n'
-            f'{codec.msg_spec_str}\n'
+            f'{codec.msg_spec_str}\n',
         )
     elif src_type_error:
         src_message: str = str(src_type_error)

tractor/devx/pformat.py

@@ -215,6 +215,7 @@ def pformat_caller_frame(
         tb_str: str = pformat_boxed_tb(
             tb_str=tb_str,
             field_prefix='  ',
+            indent='',
         )
     return tb_str
 

tractor/experimental/_pubsub.py

@@ -217,6 +217,7 @@ def pub(
 
     .. code:: python
 
+        from functools import partial
         import tractor
 
         async with tractor.open_nursery() as n:
@@ -224,16 +225,15 @@ def pub(
                 'publisher',  # actor name
                 enable_modules=[__name__],
             )
-            try:
             async with portal.open_stream_from(
-                    pub_service,  # func to execute in it
+                partial(  # func to execute in it
+                    pub_service,
                     topics=('clicks', 'users'),
                     task_name='source1',
+                )
             ) as stream:
                 async for value in stream:
                     print(f"Subscriber received {value}")
-            finally:
-                await portal.cancel_actor()
 
 
     Here, you don't need to provide the ``ctx`` argument since the

tractor/ipc/_chan.py

@@ -310,7 +310,6 @@ class Channel:
         payload: Any,
 
         hide_tb: bool = False,
-        send_deadline: float = float('inf'),
 
     ) -> None:
         '''
@@ -321,9 +320,6 @@ class Channel:
         expected-graceful cases, normally ephemercal
         (re/dis)connects.
 
-        `send_deadline` is an absolute Trio clock deadline forwarded
-        only to transports that support bounded frame publication.
-
         '''
         __tracebackhide__: bool = hide_tb
         try:
@@ -334,17 +330,10 @@ class Channel:
                     f'{pformat(payload)}\n'
                 )
             # assert self._transport  # but why typing?
-            if send_deadline == float('inf'):
             await self._transport.send(
                 payload,
                 hide_tb=hide_tb,
             )
-            else:
-                await self._transport.send(
-                    payload,
-                    hide_tb=hide_tb,
-                    send_deadline=send_deadline,
-                )
         except (
             BaseException,
             MsgTypeError,

tractor/ipc/_transport.py

@@ -439,7 +439,6 @@ class MsgpackTransport(MsgTransport):
 
         strict_types: bool = True,
         hide_tb: bool = True,
-        send_deadline: float = float('inf'),
 
     ) -> None:
         '''
@@ -448,12 +447,6 @@ class MsgpackTransport(MsgTransport):
         If `strict_types == True` then a `MsgTypeError` will be raised on any
         invalid msg type
 
-        `send_deadline` bounds publication of one complete
-        length-prefixed frame. If it expires after a prefix or payload
-        fragment reaches the wire, a later sender would append bytes the
-        peer decoder treats as the remainder of that corrupt frame. The
-        stream is therefore destroyed before releasing `._send_lock`.
-
         '''
         __tracebackhide__: bool = hide_tb
 
@@ -505,56 +498,17 @@ class MsgpackTransport(MsgTransport):
             # https://stackoverflow.com/a/54027962
             size: bytes = struct.pack("<I", len(bytes_data))
             try:
-                # Every IPC msg is length-prefixed and all contexts
-                # on this actor pair share one transport stream. If
-                # the send deadline interrupts `send_all()`, an unknown
-                # frame prefix may already be on the wire; allowing the
-                # next sender to append would corrupt framing.
-                #
-                # The enclosing `async with self._send_lock` retains the
-                # lock through shielded publication and any forced-close
-                # cleanup. Context-manager exit releases it only after a
-                # complete frame or destruction of the corrupt stream.
-                # Ordinary outer cancellation remains shielded until
-                # complete publication; only expiry of `send_deadline`
-                # intentionally closes a partial stream here.
-                #
-                # Ordinary sends may delay cancellation while the remote
-                # peer actor is not reading. Bounded actor/context cancel
-                # requests pass an absolute deadline so this operation
-                # can close a stalled stream.
-                with trio.CancelScope(
-                    deadline=send_deadline,
-                    shield=True,
-                ) as send_cs:
-                    await self.stream.send_all(size + bytes_data)
-
-                if send_cs.cancelled_caught:
-                    # This frame may be partial. Destroy the stream
-                    # before releasing `_send_lock` so no later sender
-                    # can append bytes to a corrupted frame.
-                    await trio.aclose_forcefully(self.stream)
-                    await trio.lowlevel.checkpoint_if_cancelled()
-                    raise TransportClosed(
-                        'IPC frame publication exceeded its '
-                        f'deadline of {send_deadline!r}'
-                    )
-
-                # The frame is complete and still aligned. Redeliver any
-                # pending outer cancellation before normal lock release.
-                await trio.lowlevel.checkpoint_if_cancelled()
-                return None
-
+                return await self.stream.send_all(size + bytes_data)
+            except trio.Cancelled:
+                # `send_all()` may have written a partial frame. The
+                # stream can not safely carry another framed msg.
+                with trio.CancelScope(shield=True):
+                    await self.stream.aclose()
+                raise
             except (
                 trio.BrokenResourceError,
                 trio.ClosedResourceError,
             ) as _re:
-                # A shielded send can race outer cancellation with
-                # stream teardown. If teardown closes the stream, let
-                # the pending cancellation retain precedence instead
-                # of converting that close into `TransportClosed`.
-                await trio.lowlevel.checkpoint_if_cancelled()
-
                 trans_err = _re
                 tpt_name: str = f'{type(self).__name__!r}'
 

tractor/msg/_codec.py

@@ -430,7 +430,7 @@ class MsgCodec(Struct):
     # wrapped field over the `.msg_spec` one?
     @property
     def msg_spec_str(self) -> str:
-        return pformat_msgspec(self)
+        return pformat_msgspec(self.msg_spec)
 
     lib: ModuleType = msgspec
 

tractor/msg/ptr.py

@@ -123,15 +123,6 @@ class NamespacePath(str):
         ref: type|object,
 
     ) -> NamespacePath:
-        '''
-        Build a path while retaining its process-local object reference.
-
-        The originating process already holds `ref`; caching it prevents
-        `to_tuple()` from immediately importing and resolving the same
-        object again. Serialized paths carry only the `str` value and
-        therefore resolve lazily through `load_ref()` after decoding.
-
-        '''
 
         fqnp: tuple[str, str] = cls._mk_fqnp(ref)
         nsp = cls(':'.join(fqnp))

tractor/runtime/_portal.py

@@ -186,7 +186,7 @@ class Portal:
         - `True`: on bounded-wait expiry, raise `ActorTooSlowError`
           so the caller MUST handle the failure explicitly.
           `ActorNursery.cancel()` opts in so it can escalate via
-          direct `proc.kill()` hard-reaping per SC-discipline.
+          `proc.terminate()` per SC-discipline.
 
         '''
         __runtimeframe__: int = 1  # noqa
@@ -213,53 +213,39 @@ class Portal:
             or
             self.cancel_timeout
         )
-        cancel_deadline: float = (
-            trio.current_time()
-            +
-            cancel_timeout
-        )
-        # NOTE: Actor-runtime cancellation currently rides the normal
-        # RPC envelope:
-        #
-        # `Start(self.cancel)` -> `StartAck` -> `CancelAck`.
-        #
-        # `Actor.start_remote_task()` consumes the `StartAck`, then
-        # `._run_from_ns()` returns only after `PldRx.recv_pld()`
-        # decodes the final `CancelAck`. Thus this flag means that ack
-        # reached this portal after the peer's `Actor.cancel()` routine
-        # completed; it does not prove the peer OS process has exited.
-        # A dedicated `Cancel` request msg can eventually replace the
-        # internal `Start` RPC envelope and its extra `StartAck`.
-        cancel_ack_received: bool = False
         try:
-            with trio.move_on_at(cancel_deadline) as cs:
+            # send cancel cmd - might not get response
+            # XXX: sure would be nice to make this work with
+            # a proper shield
+            with trio.move_on_after(cancel_timeout) as cs:
                 cs.shield: bool = True
-                await self._run_from_ns(
+                await self.run_from_ns(
                     'self',
                     'cancel',
-                    kwargs={},
-                    cancel_on_startup=False,
-                    send_deadline=cancel_deadline,
                 )
-                cancel_ack_received = True
+                return True
 
-            # Preserve shielded actor teardown, then immediately
-            # redeliver any cancellation pending from an outer scope.
-            await trio.lowlevel.checkpoint_if_cancelled()
-
-            # `move_on_at` fired — peer didn't ack within
+            # `move_on_after` fired — peer didn't ack within
             # bounded window. Behaviour depends on
             # `raise_on_timeout`:
-            if cs.cancelled_caught:
-                if raise_on_timeout:
+            if (
+                cs.cancelled_caught
+                and
+                raise_on_timeout
+            ):
                 raise ActorTooSlowError(
                     f'Peer {peer_id} did not ack its '
                     f'`Actor.cancel()` RPC within bounded wait '
                     f'of {cancel_timeout!r}s'
                 )
 
-                # Legacy fire-and-forget callers decide whether to
-                # escalate the missed acknowledgement themselves.
+            # legacy fire-and-forget path: log + return False so
+            # the caller can decide whether to escalate.
+            #
+            # NOTE, we also land here in the (unexpected) case where
+            # the shielded `move_on_after` block exits WITHOUT
+            # `return True` and WITHOUT the deadline firing — prefer
+            # a soft `False` over an `assert`-crash mid-teardown.
             log.debug(
                 f'May have failed to cancel peer?\n'
                 f'\n'
@@ -267,8 +253,6 @@ class Portal:
             )
             return False
 
-            return cancel_ack_received
-
         except TransportClosed as tpt_err:
             ipc_borked_report: str = (
                 f'IPC for actor already closed/broken?\n\n'
@@ -289,24 +273,16 @@ class Portal:
 
             return False
 
-    # TODO: Replace actor-runtime cancellation's internal
-    # `Start -> StartAck -> CancelAck` RPC with a dedicated
-    # `Cancel -> CancelAck` transaction:
-    # https://github.com/goodboy/tractor/issues/506
     async def _run_from_ns(
         self,
         namespace_path: str,
         function_name: str,
         kwargs: dict[str, Any],
         cancel_on_startup: bool = True,
-        send_deadline: float = float('inf'),
     ) -> Any:
         '''
         Run a namespace target with local startup policy controls.
 
-        `send_deadline` bounds only publication of the `Start` frame;
-        the caller owns any larger RPC/acknowledgement deadline.
-
         '''
         nsf = NamespacePath(
             f'{namespace_path}:{function_name}'
@@ -317,7 +293,6 @@ class Portal:
             kwargs=kwargs,
             portal=self,
             cancel_on_startup=cancel_on_startup,
-            send_deadline=send_deadline,
         )
         try:
             return await ctx._pld_rx.recv_pld(

tractor/runtime/_runtime.py

@@ -793,12 +793,6 @@ class Actor:
         ack_timeout: float = float('inf'),
         cancel_on_startup: bool = True,
 
-        # Optional absolute deadline for publishing this exact `Start`
-        # frame. Used by bounded actor/context cancel RPCs whose outer
-        # timeout cannot penetrate `Channel.send()` forwarding into the
-        # shield in `MsgpackTransport.send()`.
-        send_deadline: float = float('inf'),
-
     ) -> Context:
         '''
         Send a `'cmd'` msg to a remote actor, which requests the
@@ -851,13 +845,7 @@ class Actor:
         )
         start_published: bool = False
         try:
-            if send_deadline == float('inf'):
             await chan.send(msg)
-            else:
-                await chan.send(
-                    msg,
-                    send_deadline=send_deadline,
-                )
             start_published = True
 
             # NOTE wait on first `StartAck` response msg and validate;
@@ -883,15 +871,12 @@ class Actor:
 
         except BaseException as startup_err:
             with trio.CancelScope(shield=True):
-                # `MsgpackTransport.send()` shields length-prefixed frame
-                # publication until complete, then checkpoints pending
-                # cancellation before returning. Thus `start_published`
-                # can remain false after a complete `Start` reached the
-                # wire. If the send's own deadline catches a partial
-                # frame, it closes the stream. A connected channel means
-                # cancellation happened before the write or after frame
-                # completion, so `_cancel_task` is protocol-safe (and
-                # a no-op when `Start` was unsent).
+                # `MsgpackTransport.send()` closes its stream when
+                # cancellation interrupts the length-prefixed write
+                # because an unknown prefix may already be sent. A
+                # connected channel means cancellation happened before
+                # that write or after it completed, so `_cancel_task`
+                # is protocol-safe (and a no-op if `Start` was unsent).
                 if (
                     cancel_on_startup
                     and

tractor/runtime/_supervise.py

@@ -45,7 +45,6 @@ from ..log import (
     get_logger,
     get_loglevel,
 )
-from ..msg import Aid
 from ._runtime import Actor
 from ._portal import Portal
 from ..trionics import (
@@ -130,21 +129,12 @@ 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.
-    def child_in_debug() -> bool:
-        '''
-        Sample child/tree debugger protection state.
-
-        '''
-        return (
-            debug_mode_active
-            or
-            debug.Lock.ctx_in_debug is not None
-        )
-
     debug_protected: bool = (
-        child_in_debug()
+        debug.Lock.ctx_in_debug is not None
         or
         _state._runtime_vars.get('_debug_mode', False)
+        or
+        debug_mode_active
     )
 
     try:
@@ -154,8 +144,11 @@ async def _try_cancel_then_kill(
         if not cancelled:
             if debug_protected:
                 await debug.maybe_wait_for_debugger(
-                    # Re-sample after the cancel-RPC checkpoint.
-                    child_in_debug=child_in_debug(),
+                    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'
@@ -245,11 +238,11 @@ class ActorNursery:
 
         self._join_procs = trio.Event()
         self._child_reap_requests: dict[
-            Aid,
+            tuple[str, str],
             trio.Event,
         ] = {}
         self._child_reaped: dict[
-            Aid,
+            tuple[str, str],
             trio.Event,
         ] = {}
         self._at_least_one_child_in_debug: bool = False
@@ -308,7 +301,7 @@ class ActorNursery:
 
     def _register_child_reap(
         self,
-        aid: Aid,
+        uid: tuple[str, str],
     ) -> tuple[trio.Event, trio.Event]:
         '''
         Register a child monitor's process-reap events.
@@ -316,36 +309,12 @@ class ActorNursery:
         '''
         reap_request = trio.Event()
         reaped = trio.Event()
-        self._child_reap_requests[aid] = reap_request
-        self._child_reaped[aid] = reaped
+        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 _register_child(
-        self,
-        subactor: Actor,
-        proc: 'ProcessType',
-        portal: Portal|None,
-    ) -> tuple[trio.Event, trio.Event, bool]:
-        '''
-        Atomically publish one child and its reap coordination.
-
-        '''
-        aid: Aid = subactor.aid
-        uid: tuple[str, str] = aid.uid
-        self._children[uid] = (
-            subactor,
-            proc,
-            portal,
-        )
-        reap_request, reaped = self._register_child_reap(aid)
-        return (
-            reap_request,
-            reaped,
-            self._cancel_called,
-        )
-
     def _request_reap_all(self) -> None:
         '''
         Release every child monitor into its process-join phase.
@@ -359,26 +328,18 @@ class ActorNursery:
 
     def _mark_child_reaped(
         self,
-        aid: Aid,
+        uid: tuple[str, str],
     ) -> None:
         '''
         Publish completed child-process teardown to its waiter.
 
         '''
-        uid: tuple[str, str] = aid.uid
         self._children.pop(uid, None)
-        reap_request: trio.Event|None = (
-            self._child_reap_requests.pop(aid, None)
-        )
+        self._child_reap_requests.pop(uid, None)
         reaped: trio.Event|None = self._child_reaped.pop(
-            aid,
+            uid,
             None,
         )
-        assert (
-            (reap_request is None)
-            ==
-            (reaped is None)
-        )
         if reaped is not None:
             reaped.set()
 
@@ -390,15 +351,14 @@ class ActorNursery:
         Cancel, join and unregister one nursery-owned child.
 
         '''
-        aid: Aid = portal.channel.aid
-        uid: tuple[str, str] = aid.uid
+        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[aid]
-        reaped: trio.Event = self._child_reaped[aid]
+        reap_request: trio.Event = self._child_reap_requests[uid]
+        reaped: trio.Event = self._child_reaped[uid]
 
         with trio.CancelScope(shield=True):
             try:
@@ -442,12 +402,6 @@ class ActorNursery:
 
         '''
         __runtimeframe__: int = 1  # noqa
-        if self._cancel_called:
-            raise RuntimeError(
-                'Cannot start an actor in a cancelling '
-                '`ActorNursery`'
-            )
-
         loglevel: str = (
             loglevel
             or self._actor.loglevel

tractor/spawn/_mp.py

@@ -137,24 +137,12 @@ async def mp_proc(
         # daemon=True,
         name=name,
     )
-    # `multiprocessing` only (since no async interface): publish the
-    # process and its reap coordination before start so cancellation
-    # can own every subsequently started child.
-    # No `Portal` exists until the IPC handshake returns `chan`.
-    # Replace this provisional entry with `Portal(chan)` below.
-    (
-        reap_request,
-        _,
-        cancel_during_registration,
-    ) = actor_nursery._register_child(
-        subactor=subactor,
-        proc=proc,
-        portal=None,
-    )
-    if cancel_during_registration:
-        raise RuntimeError(
-            'Actor registered after its nursery began cancelling'
-        )
+
+    # `multiprocessing` only (since no async interface):
+    # register the process before start in case we get a cancel
+    # request before the actor has fully spawned - then we can wait
+    # for it to fully come up before sending a cancel request
+    actor_nursery._children[subactor.aid.uid] = (subactor, proc, None)
 
     proc.start()
     if not proc.is_alive():
@@ -181,6 +169,9 @@ async def mp_proc(
         # any process we may have started.
 
         portal = Portal(chan)
+        reap_request, _ = actor_nursery._register_child_reap(
+            subactor.aid.uid,
+        )
         actor_nursery._children[subactor.aid.uid] = (subactor, proc, portal)
 
         # unblock parent task

tractor/spawn/_spawn.py

@@ -368,7 +368,7 @@ async def new_proc(
             proc_kwargs=proc_kwargs
         )
     finally:
-        actor_nursery._mark_child_reaped(subactor.aid)
+        actor_nursery._mark_child_reaped(subactor.aid.uid)
 
 
 # NOTE: bottom-of-module to avoid a circular import since the

tractor/spawn/_trio.py

@@ -39,6 +39,7 @@ from tractor.runtime._state import (
     current_actor,
     is_root_process,
     debug_mode,
+    get_runtime_vars,
 )
 from tractor.log import get_logger
 from tractor.discovery._addr import UnwrappedAddress
@@ -129,26 +130,6 @@ async def trio_proc(
                 f' |_{proc}\n'
             )
 
-            # No `Portal` exists until the IPC handshake returns
-            # `chan`. Replace this provisional entry with
-            # `Portal(chan)` below.
-            (
-                reap_request,
-                _,
-                cancel_during_registration,
-            ) = actor_nursery._register_child(
-                subactor=subactor,
-                proc=proc,
-                portal=None,
-            )
-            if cancel_during_registration:
-                cancelled_during_spawn = True
-                proc.kill()
-                raise RuntimeError(
-                    'Actor registered after its nursery began '
-                    'cancelling'
-                )
-
             # wait for actor to spawn and connect back to us
             # channel should have handshake completed by the
             # local actor by the time we get a ref to it
@@ -179,6 +160,9 @@ async def trio_proc(
         assert proc
 
         portal = Portal(chan)
+        reap_request, _ = actor_nursery._register_child_reap(
+            subactor.aid.uid,
+        )
         actor_nursery._children[subactor.aid.uid] = (
             subactor,
             proc,

tractor/to_actor/_api.py

@@ -116,14 +116,13 @@ def _normalize_call(
 
         # `functools.Placeholder` was added in Python 3.14. Drop
         # this `getattr()` guard once 3.14 is the minimum version.
-        if (
-            (
-                placeholder := getattr(
+        placeholder = getattr(
             functools,
             'Placeholder',
             None,
         )
-            ) is not None
+        if (
+            placeholder is not None
             and
             any(
                 arg is placeholder
@@ -240,8 +239,8 @@ async def run(
     fn: Callable[[Unpack[ArgsT]], Awaitable[RetT]],
     *args: Unpack[ArgsT],
 
-    # actor lifetime management: reuse an already-running peer
-    # via its `portal: Portal`, spawn a fresh subactor from
+    # actor "placement": reuse an already-running peer
+    # via its `portal`, spawn a fresh subactor from
     # a caller-managed `an: ActorNursery`, or, when
     # neither is provided, open a private actor-nursery
     # (implicitly booting the actor-runtime as needed)
@@ -275,10 +274,9 @@ async def run(
 
     As with Trio's API, target arguments are positional. Use
     `functools.partial()` to bind target keyword arguments; all
-    keyword arguments accepted here configure actor lifetime
-    management, including actor reuse and spawning. A caller-supplied
-    `portal` must address an actor started with both
-    `tractor.to_actor.MODULE` and the target function's
+    keyword arguments accepted here configure actor placement or
+    spawning. A caller-supplied `portal` must address an actor started
+    with both `tractor.to_actor.MODULE` and the target function's
     module in its `enable_modules` list. Calls that spawn their own
     actor add the trampoline module automatically.