Adjust `test_trio_prestarted_task_bubbles()` suite to expect non-eg raises

Was failing due to the `.fail_after()` timeout being *too short* and
somehow the new interplay of that with strict-exception groups resulting
in the `TooSlowError` never raising but instead an eg with the embedded
`AssertionError`?? I still don't really get it honestly..

I've written up lengthy notes around the different `delay` settings that
can be used to see the diff outcomes, the failing case being the one
i still don't really grok and think is justification for `trio` to
bubble inner `Cancelled`s differently possibly?

For now i've included the original failing case as an `xfail`
parametrization for now which will hopefully drive a follow lowlevel
`trio` test in `test_trioisms`!

.github/workflows/ci.yml

@@ -8,46 +8,70 @@ on:
   workflow_dispatch:
 
 jobs:
-
+  # ------ sdist ------
-  mypy:
-    name: 'MyPy'
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v2
-
-      - name: Setup python
-        uses: actions/setup-python@v2
-        with:
-          python-version: '3.11'
-
-      - name: Install dependencies
-        run: pip install -U . --upgrade-strategy eager -r requirements-test.txt
-
-      - name: Run MyPy check
-        run: mypy tractor/ --ignore-missing-imports --show-traceback
-
   # test that we can generate a software distribution and install it
   # thus avoid missing file issues after packaging.
+  #
+  # -[x] produce sdist with uv
+  # ------ - ------
   sdist-linux:
     name: 'sdist'
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
-      - name: Setup python
+      - name: Install latest uv
-        uses: actions/setup-python@v2
+        uses: astral-sh/setup-uv@v6
-        with:
-          python-version: '3.11'
 
-      - name: Build sdist
+      - name: Build sdist as tar.gz
-        run: python setup.py sdist --formats=zip
+        run: uv build --sdist --python=3.13
 
-      - name: Install sdist from .zips
+      - name: Install sdist from .tar.gz
-        run: python -m pip install dist/*.zip
+        run: python -m pip install dist/*.tar.gz
+
+  # ------ type-check ------
+  # mypy:
+  #   name: 'MyPy'
+  #   runs-on: ubuntu-latest
+
+  #   steps:
+  #     - name: Checkout
+  #       uses: actions/checkout@v4
+
+  #     - name: Install latest uv
+  #       uses: astral-sh/setup-uv@v6
+
+  #     # faster due to server caching?
+  #     # https://docs.astral.sh/uv/guides/integration/github/#setting-up-python
+  #     - name: "Set up Python"
+  #       uses: actions/setup-python@v6
+  #       with:
+  #         python-version-file: "pyproject.toml"
+
+  #     # w uv
+  #     # - name: Set up Python
+  #     #   run: uv python install
+
+  #     - name: Setup uv venv
+  #       run: uv venv .venv --python=3.13
+
+  #     - name: Install
+  #       run: uv sync --dev
+
+  #     # TODO, ty cmd over repo
+  #     # - name: type check with ty
+  #     #   run: ty ./tractor/
+
+  #     # - uses: actions/cache@v3
+  #     #     name: Cache uv virtenv as default .venv
+  #     #     with:
+  #     #       path: ./.venv
+  #     #       key: venv-${{ hashFiles('uv.lock') }}
+
+  #     - name: Run MyPy check
+  #       run: mypy tractor/ --ignore-missing-imports --show-traceback
 
 
   testing-linux:
@@ -59,32 +83,45 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python: ['3.11']
+        python-version: ['3.13']
         spawn_backend: [
           'trio',
-          'mp_spawn',
+          # 'mp_spawn',
-          'mp_forkserver',
+          # 'mp_forkserver',
         ]
 
     steps:
 
-      - name: Checkout
+      - uses: actions/checkout@v4
-        uses: actions/checkout@v2
 
-      - name: Setup python
+      - name: 'Install uv + py-${{ matrix.python-version }}'
-        uses: actions/setup-python@v2
+        uses: astral-sh/setup-uv@v6
         with:
-          python-version: '${{ matrix.python }}'
+          python-version: ${{ matrix.python-version }}
 
-      - name: Install dependencies
+      # GH way.. faster?
-        run: pip install -U . -r requirements-test.txt -r requirements-docs.txt --upgrade-strategy eager
+      # - name: setup-python@v6
+      #   uses: actions/setup-python@v6
+      #   with:
+      #     python-version: '${{ matrix.python-version }}'
 
-      - name: List dependencies
+      # consider caching for speedups?
-        run: pip list
+      # https://docs.astral.sh/uv/guides/integration/github/#caching
+
+      - name: Install the project w uv
+        run: uv sync --all-extras --dev
+
+      # - name: Install dependencies
+      #   run: pip install -U . -r requirements-test.txt -r requirements-docs.txt --upgrade-strategy eager
+
+      - name: List deps tree
+        run: uv tree
 
       - name: Run tests
-        run: pytest tests/ --spawn-backend=${{ matrix.spawn_backend }} -rsx
+        run: uv run pytest tests/ --spawn-backend=${{ matrix.spawn_backend }} -rsx
 
+  # XXX legacy NOTE XXX
+  #
   # We skip 3.10 on windows for now due to not having any collabs to
   # debug the CI failures. Anyone wanting to hack and solve them is very
   # welcome, but our primary user base is not using that OS.

docs/README.rst

@@ -1,8 +1,5 @@
 |logo| ``tractor``: distributed structurred concurrency
 
-|gh_actions|
-|docs|
-
 ``tractor`` is a `structured concurrency`_ (SC), multi-processing_ runtime built on trio_.
 
 Fundamentally, ``tractor`` provides parallelism via
@@ -66,6 +63,13 @@ Features
   - (WIP) a ``TaskMngr``: one-cancels-one style nursery supervisor.
 
 
+Status of `main` / infra
+------------------------
+
+- |gh_actions|
+- |docs|
+
+
 Install
 -------
 ``tractor`` is still in a *alpha-near-beta-stage* for many
@@ -689,9 +693,11 @@ channel`_!
 .. _msgspec: https://jcristharif.com/msgspec/
 .. _guest: https://trio.readthedocs.io/en/stable/reference-lowlevel.html?highlight=guest%20mode#using-guest-mode-to-run-trio-on-top-of-other-event-loops
 
-
+..
-.. |gh_actions| image:: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fgoodboy%2Ftractor%2Fbadge&style=popout-square
+   NOTE, on generating badge links from the UI
-    :target: https://actions-badge.atrox.dev/goodboy/tractor/goto
+   https://docs.github.com/en/actions/how-tos/monitoring-and-troubleshooting-workflows/monitoring-workflows/adding-a-workflow-status-badge?ref=gitguardian-blog-automated-secrets-detection#using-the-ui
+.. |gh_actions| image:: https://github.com/goodboy/tractor/actions/workflows/ci.yml/badge.svg?branch=main
+    :target: https://github.com/goodboy/tractor/actions/workflows/ci.yml
 
 .. |docs| image:: https://readthedocs.org/projects/tractor/badge/?version=latest
     :target: https://tractor.readthedocs.io/en/latest/?badge=latest

examples/debugging/root_cancelled_but_child_is_in_tty_lock.py

@@ -24,10 +24,9 @@ async def spawn_until(depth=0):
 
 
 async def main():
-    """The main ``tractor`` routine.
+    '''
-
+    The process tree should look as approximately as follows when the
-    The process tree should look as approximately as follows when the debugger
+    debugger first engages:
-    first engages:
 
     python examples/debugging/multi_nested_subactors_bp_forever.py
     ├─ python -m tractor._child --uid ('spawner1', '7eab8462 ...)
@@ -37,10 +36,11 @@ async def main():
     └─ python -m tractor._child --uid ('spawner0', '1d42012b ...)
        └─ python -m tractor._child --uid ('name_error', '6c2733b8 ...)
 
-    """
+    '''
     async with tractor.open_nursery(
         debug_mode=True,
-        loglevel='warning'
+        loglevel='devx',
+        enable_transports=['uds'],
     ) as n:
 
         # spawn both actors

examples/debugging/shield_hang_in_sub.py

@@ -37,6 +37,7 @@ async def main(
             enable_stack_on_sig=True,
             # maybe_enable_greenback=False,
             loglevel='devx',
+            enable_transports=['uds'],
         ) as an,
     ):
         ptl: tractor.Portal  = await an.start_actor(

examples/debugging/subactor_bp_in_ctx.py

@@ -33,8 +33,11 @@ async def just_bp(
 
 
 async def main():
+
     async with tractor.open_nursery(
         debug_mode=True,
+        enable_transports=['uds'],
+        loglevel='devx',
     ) as n:
         p = await n.start_actor(
             'bp_boi',

examples/trio/send_chan_aclose_masks_beg.py

@@ -0,0 +1,145 @@
+from contextlib import (
+    contextmanager as cm,
+    # TODO, any diff in async case(s)??
+    # asynccontextmanager as acm,
+)
+from functools import partial
+
+import tractor
+import trio
+
+
+log = tractor.log.get_logger(__name__)
+tractor.log.get_console_log('info')
+
+@cm
+def teardown_on_exc(
+    raise_from_handler: bool = False,
+):
+    '''
+    You could also have a teardown handler which catches any exc and
+    does some required teardown. In this case the problem is
+    compounded UNLESS you ensure the handler's scope is OUTSIDE the
+    `ux.aclose()`.. that is in the caller's enclosing scope.
+
+    '''
+    try:
+        yield
+    except BaseException as _berr:
+        berr = _berr
+        log.exception(
+            f'Handling termination teardown in child due to,\n'
+            f'{berr!r}\n'
+        )
+        if raise_from_handler:
+            # XXX teardown ops XXX
+            # on termination these steps say need to be run to
+            # ensure wider system consistency (like the state of
+            # remote connections/services).
+            #
+            # HOWEVER, any bug in this teardown code is also
+            # masked by the `tx.aclose()`!
+            # this is also true if `_tn.cancel_scope` is
+            # `.cancel_called` by the parent in a graceful
+            # request case..
+
+            # simulate a bug in teardown handler.
+            raise RuntimeError(
+                'woopsie teardown bug!'
+            )
+
+        raise  # no teardown bug.
+
+
+async def finite_stream_to_rent(
+    tx: trio.abc.SendChannel,
+    child_errors_mid_stream: bool,
+
+    task_status: trio.TaskStatus[
+        trio.CancelScope,
+    ] = trio.TASK_STATUS_IGNORED,
+):
+    async with (
+        # XXX without this unmasker the mid-streaming RTE is never
+        # reported since it is masked by the `tx.aclose()`
+        # call which in turn raises `Cancelled`!
+        #
+        # NOTE, this is WITHOUT doing any exception handling
+        # inside the child  task!
+        #
+        # TODO, uncomment next LoC to see the supprsessed beg[RTE]!
+        # tractor.trionics.maybe_raise_from_masking_exc(),
+
+        tx as tx,  # .aclose() is the guilty masker chkpt!
+        trio.open_nursery() as _tn,
+    ):
+        # pass our scope back to parent for supervision\
+        # control.
+        task_status.started(_tn.cancel_scope)
+
+        with teardown_on_exc(
+            raise_from_handler=not child_errors_mid_stream,
+        ):
+            for i in range(100):
+                log.info(
+                    f'Child tx {i!r}\n'
+                )
+                if (
+                    child_errors_mid_stream
+                    and
+                    i == 66
+                ):
+                    # oh wait but WOOPS there's a bug
+                    # in that teardown code!?
+                    raise RuntimeError(
+                        'woopsie, a mid-streaming bug!?'
+                    )
+
+                await tx.send(i)
+
+
+async def main(
+    # TODO! toggle this for the 2 cases!
+    # 1. child errors mid-stream while parent is also requesting
+    #   (graceful) cancel of that child streamer.
+    #
+    # 2. child contains a teardown handler which contains a
+    #   bug and raises.
+    #
+    child_errors_mid_stream: bool,
+):
+    tx, rx = trio.open_memory_channel(1)
+
+    async with (
+        trio.open_nursery() as tn,
+        rx as rx,
+    ):
+
+        _child_cs = await tn.start(
+            partial(
+                finite_stream_to_rent,
+                child_errors_mid_stream=child_errors_mid_stream,
+                tx=tx,
+            )
+        )
+        async for msg in rx:
+            log.info(
+                f'Rent rx {msg!r}\n'
+            )
+
+            # simulate some external cancellation
+            # request **JUST BEFORE** the child errors.
+            if msg == 65:
+                log.cancel(
+                    f'Cancelling parent on,\n'
+                    f'msg={msg}\n'
+                    f'\n'
+                    f'Simulates OOB cancel request!\n'
+                )
+                tn.cancel_scope.cancel()
+
+
+if __name__ == '__main__':
+
+    for case in [True, False]:
+        trio.run(main, case)

pyproject.toml

@@ -61,7 +61,9 @@ dev = [
   # `tractor.devx` tooling
   "greenback>=1.2.1,<2",
   "stackscope>=0.2.2,<0.3",
-  "typing-extensions>=4.13.2",  # needed for stackscope
+  # ^ requires this?
+  "typing-extensions>=4.14.1",
+
   "pyperclip>=1.9.0",
   "prompt-toolkit>=3.0.50",
   "xonsh>=0.19.2",

tests/devx/test_debugger.py

@@ -10,10 +10,14 @@ TODO:
     - wonder if any of it'll work on OS X?
 
 """
+from __future__ import annotations
 from functools import partial
 import itertools
 import platform
 import time
+from typing import (
+    TYPE_CHECKING,
+)
 
 import pytest
 from pexpect.exceptions import (
@@ -34,6 +38,9 @@ from .conftest import (
     assert_before,
 )
 
+if TYPE_CHECKING:
+    from ..conftest import PexpectSpawner
+
 # TODO: The next great debugger audit could be done by you!
 # - recurrent entry to breakpoint() from single actor *after* and an
 #   error in another task?
@@ -1062,6 +1069,88 @@ def test_shield_pause(
     child.expect(EOF)
 
 
+@pytest.mark.parametrize(
+    'quit_early', [False, True]
+)
+def test_ctxep_pauses_n_maybe_ipc_breaks(
+    spawn: PexpectSpawner,
+    quit_early: bool,
+):
+    '''
+    Audit generator embedded `.pause()`es from within a `@context`
+    endpoint with a chan close at the end, requiring that ctl-c is
+    mashed and zombie reaper kills sub with no hangs.
+
+    '''
+    child = spawn('subactor_bp_in_ctx')
+    child.expect(PROMPT)
+
+    # 3 iters for the `gen()` pause-points
+    for i in range(3):
+        assert_before(
+            child,
+            [
+                _pause_msg,
+                "('bp_boi'",  # actor name
+                "<Task 'just_bp'",  # task name
+            ]
+        )
+        if (
+            i == 1
+            and
+            quit_early
+        ):
+            child.sendline('q')
+            child.expect(PROMPT)
+            assert_before(
+                child,
+                ["tractor._exceptions.RemoteActorError: remote task raised a 'BdbQuit'",
+                 "bdb.BdbQuit",
+                 "('bp_boi'",
+                ]
+            )
+            child.sendline('c')
+            child.expect(EOF)
+            assert_before(
+                child,
+                ["tractor._exceptions.RemoteActorError: remote task raised a 'BdbQuit'",
+                 "bdb.BdbQuit",
+                 "('bp_boi'",
+                ]
+            )
+            break  # end-of-test
+
+        child.sendline('c')
+        try:
+            child.expect(PROMPT)
+        except TIMEOUT:
+            # no prompt since we hang due to IPC chan purposely
+            # closed so verify we see error reporting as well as
+            # a failed crash-REPL request msg and can CTL-c our way
+            # out.
+            assert_before(
+                child,
+                ['peer IPC channel closed abruptly?',
+                 'another task closed this fd',
+                 'Debug lock request was CANCELLED?',
+                 "TransportClosed: 'MsgpackUDSStream' was already closed locally ?",]
+
+                # XXX races on whether these show/hit?
+                 # 'Failed to REPl via `_pause()` You called `tractor.pause()` from an already cancelled scope!',
+                 # 'AssertionError',
+            )
+            # OSc(ancel) the hanging tree
+            do_ctlc(
+                child=child,
+                expect_prompt=False,
+            )
+            child.expect(EOF)
+            assert_before(
+                child,
+                ['KeyboardInterrupt'],
+            )
+
+
 # TODO: better error for "non-ideal" usage from the root actor.
 # -[ ] if called from an async scope emit a message that suggests
 #    using `await tractor.pause()` instead since it's less overhead

tests/devx/test_tooling.py

@@ -14,6 +14,9 @@ TODO:
 
 '''
 from __future__ import annotations
+from contextlib import (
+    contextmanager as cm,
+)
 import os
 import signal
 import time
@@ -28,6 +31,8 @@ from .conftest import (
     PROMPT,
     _pause_msg,
 )
+
+import pytest
 from pexpect.exceptions import (
     # TIMEOUT,
     EOF,
@@ -116,9 +121,11 @@ def test_shield_pause(
         child.pid,
         signal.SIGINT,
     )
+    from tractor._supervise import _shutdown_msg
     expect(
         child,
-        'Shutting down actor runtime',
+        # 'Shutting down actor runtime',
+        _shutdown_msg,
         timeout=6,
     )
     assert_before(
@@ -183,3 +190,117 @@ def test_breakpoint_hook_restored(
     )
     child.sendline('c')
     child.expect(EOF)
+
+
+
+_to_raise = Exception('Triggering a crash')
+
+
+@pytest.mark.parametrize(
+    'to_raise',
+    [
+        None,
+        _to_raise,
+        RuntimeError('Never crash handle this!'),
+    ],
+)
+@pytest.mark.parametrize(
+    'raise_on_exit',
+    [
+        True,
+        [type(_to_raise)],
+        False,
+    ]
+)
+def test_crash_handler_cms(
+    debug_mode: bool,
+    to_raise: Exception,
+    raise_on_exit: bool|list[Exception],
+):
+    '''
+    Verify the `.devx.open_crash_handler()` API(s) by also
+    (conveniently enough) tesing its `repl_fixture: ContextManager`
+    param support which for this suite allows use to avoid use of
+    a `pexpect`-style-test since we use the fixture to avoid actually
+    entering `PdbpREPL.iteract()` :smirk:
+
+    '''
+    import tractor
+    # import trio
+
+    # state flags
+    repl_acquired: bool = False
+    repl_released: bool = False
+
+    @cm
+    def block_repl_ux(
+        repl: tractor.devx.debug.PdbREPL,
+        maybe_bxerr: (
+            tractor.devx._debug.BoxedMaybeException
+            |None
+        ) = None,
+        enter_repl: bool = True,
+
+    ) -> bool:
+        '''
+        Set pre/post-REPL state vars and bypass actual conole
+        interaction.
+
+        '''
+        nonlocal repl_acquired, repl_released
+
+        # task: trio.Task = trio.lowlevel.current_task()
+        # print(f'pre-REPL active_task={task.name}')
+
+        print('pre-REPL')
+        repl_acquired = True
+        yield False  # never actually .interact()
+        print('post-REPL')
+        repl_released = True
+
+    try:
+        # TODO, with runtime's `debug_mode` setting
+        # -[ ] need to open runtime tho obvi..
+        #
+        # with tractor.devx.maybe_open_crash_handler(
+        #     pdb=True,
+
+        with tractor.devx.open_crash_handler(
+            raise_on_exit=raise_on_exit,
+            repl_fixture=block_repl_ux
+        ) as bxerr:
+            if to_raise is not None:
+                raise to_raise
+
+    except Exception as _exc:
+        exc = _exc
+        if (
+            raise_on_exit is True
+            or
+            type(to_raise) in raise_on_exit
+        ):
+            assert (
+                exc
+                is
+                to_raise
+                is
+                bxerr.value
+            )
+
+        else:
+            raise
+    else:
+        assert (
+            to_raise is None
+            or
+            not raise_on_exit
+            or
+            type(to_raise) not in raise_on_exit
+        )
+        assert bxerr.value is to_raise
+
+    assert bxerr.raise_on_exit == raise_on_exit
+
+    if to_raise is not None:
+        assert repl_acquired
+        assert repl_released

tests/ipc/test_multi_tpt.py

@@ -0,0 +1,95 @@
+'''
+Verify the `enable_transports` param drives various
+per-root/sub-actor IPC endpoint/server settings.
+
+'''
+from __future__ import annotations
+
+import pytest
+import trio
+import tractor
+from tractor import (
+    Actor,
+    Portal,
+    ipc,
+    msg,
+    _state,
+    _addr,
+)
+
+@tractor.context
+async def chk_tpts(
+    ctx: tractor.Context,
+    tpt_proto_key: str,
+):
+    rtvars = _state._runtime_vars
+    assert (
+        tpt_proto_key
+        in
+        rtvars['_enable_tpts']
+    )
+    actor: Actor = tractor.current_actor()
+    spec: msg.types.SpawnSpec = actor._spawn_spec
+    assert spec._runtime_vars == rtvars
+
+    # ensure individual IPC ep-addr types
+    serv: ipc._server.Server = actor.ipc_server
+    addr: ipc._types.Address
+    for addr in serv.addrs:
+        assert addr.proto_key == tpt_proto_key
+
+    # Actor delegate-props enforcement
+    assert (
+        actor.accept_addrs
+        ==
+        serv.accept_addrs
+    )
+
+    await ctx.started(serv.accept_addrs)
+
+
+# TODO, parametrize over mis-matched-proto-typed `registry_addrs`
+# since i seems to work in `piker` but not exactly sure if both tcp
+# & uds are being deployed then?
+#
+@pytest.mark.parametrize(
+    'tpt_proto_key',
+    ['tcp', 'uds'],
+    ids=lambda item: f'ipc_tpt={item!r}'
+)
+def test_root_passes_tpt_to_sub(
+    tpt_proto_key: str,
+    reg_addr: tuple,
+    debug_mode: bool,
+):
+    async def main():
+        async with tractor.open_nursery(
+            enable_transports=[tpt_proto_key],
+            registry_addrs=[reg_addr],
+            debug_mode=debug_mode,
+        ) as an:
+
+            assert (
+                tpt_proto_key
+                in
+                _state._runtime_vars['_enable_tpts']
+            )
+
+            ptl: Portal = await an.start_actor(
+                name='sub',
+                enable_modules=[__name__],
+            )
+            async with ptl.open_context(
+                chk_tpts,
+                tpt_proto_key=tpt_proto_key,
+            ) as (ctx, accept_addrs):
+
+                uw_addr: tuple
+                for uw_addr in accept_addrs:
+                    addr = _addr.wrap_address(uw_addr)
+                    assert addr.is_valid
+
+            # shudown sub-actor(s)
+            await an.cancel()
+
+    trio.run(main)

tests/ipc/test_server.py

@@ -49,7 +49,7 @@ def test_basic_ipc_server(
             )
             assert server._no_more_peers.is_set()
 
-            eps: list[ipc.IPCEndpoint] = await server.listen_on(
+            eps: list[ipc._server.Endpoint] = await server.listen_on(
                 accept_addrs=[rando_addr],
                 stream_handler_nursery=None,
             )

tests/test_cancellation.py

@@ -284,20 +284,32 @@ async def test_cancel_infinite_streamer(start_method):
     ],
 )
 @tractor_test
-async def test_some_cancels_all(num_actors_and_errs, start_method, loglevel):
+async def test_some_cancels_all(
-    """Verify a subset of failed subactors causes all others in
+    num_actors_and_errs: tuple,
+    start_method: str,
+    loglevel: str,
+):
+    '''
+    Verify a subset of failed subactors causes all others in
     the nursery to be cancelled just like the strategy in trio.
 
     This is the first and only supervisory strategy at the moment.
-    """
+
-    num_actors, first_err, err_type, ria_func, da_func = num_actors_and_errs
+    '''
+    (
+        num_actors,
+        first_err,
+        err_type,
+        ria_func,
+        da_func,
+    ) = num_actors_and_errs
     try:
-        async with tractor.open_nursery() as n:
+        async with tractor.open_nursery() as an:
 
             # spawn the same number of deamon actors which should be cancelled
             dactor_portals = []
             for i in range(num_actors):
-                dactor_portals.append(await n.start_actor(
+                dactor_portals.append(await an.start_actor(
                     f'deamon_{i}',
                     enable_modules=[__name__],
                 ))
@@ -307,7 +319,7 @@ async def test_some_cancels_all(num_actors_and_errs, start_method, loglevel):
             for i in range(num_actors):
                 # start actor(s) that will fail immediately
                 riactor_portals.append(
-                    await n.run_in_actor(
+                    await an.run_in_actor(
                         func,
                         name=f'actor_{i}',
                         **kwargs
@@ -337,7 +349,8 @@ async def test_some_cancels_all(num_actors_and_errs, start_method, loglevel):
 
         # should error here with a ``RemoteActorError`` or ``MultiError``
 
-    except first_err as err:
+    except first_err as _err:
+        err = _err
         if isinstance(err, BaseExceptionGroup):
             assert len(err.exceptions) == num_actors
             for exc in err.exceptions:
@@ -348,8 +361,8 @@ async def test_some_cancels_all(num_actors_and_errs, start_method, loglevel):
         elif isinstance(err, tractor.RemoteActorError):
             assert err.boxed_type == err_type
 
-        assert n.cancelled is True
+        assert an.cancelled is True
-        assert not n._children
+        assert not an._children
     else:
         pytest.fail("Should have gotten a remote assertion error?")
 
@@ -533,38 +546,123 @@ def test_cancel_via_SIGINT_other_task(
 
 async def spin_for(period=3):
     "Sync sleep."
+    print(f'sync sleeping in sub-sub for {period}\n')
     time.sleep(period)
 
 
-async def spawn():
+async def spawn_sub_with_sync_blocking_task():
-    async with tractor.open_nursery() as tn:
+    async with tractor.open_nursery() as an:
-        await tn.run_in_actor(
+        print('starting sync blocking subactor..\n')
+        await an.run_in_actor(
             spin_for,
             name='sleeper',
         )
+        print('exiting first subactor layer..\n')
 
 
+@pytest.mark.parametrize(
+    'man_cancel_outer',
+    [
+        False,  # passes if delay != 2
+
+        # always causes an unexpected eg-w-embedded-assert-err?
+        pytest.param(True,
+             marks=pytest.mark.xfail(
+                 reason=(
+                    'always causes an unexpected eg-w-embedded-assert-err?'
+                )
+            ),
+        ),
+    ],
+)
 @no_windows
 def test_cancel_while_childs_child_in_sync_sleep(
-    loglevel,
+    loglevel: str,
-    start_method,
+    start_method: str,
-    spawn_backend,
+    spawn_backend: str,
+    debug_mode: bool,
+    reg_addr: tuple,
+    man_cancel_outer: bool,
 ):
-    """Verify that a child cancelled while executing sync code is torn
+    '''
+    Verify that a child cancelled while executing sync code is torn
     down even when that cancellation is triggered by the parent
     2 nurseries "up".
-    """
+
+    Though the grandchild should stay blocking its actor runtime, its
+    parent should issue a "zombie reaper" to hard kill it after
+    sufficient timeout.
+
+    '''
     if start_method == 'forkserver':
         pytest.skip("Forksever sux hard at resuming from sync sleep...")
 
     async def main():
-        with trio.fail_after(2):
+        #
-            async with tractor.open_nursery() as tn:
+        # XXX BIG TODO NOTE XXX
-                await tn.run_in_actor(
+        #
-                    spawn,
+        # it seems there's a strange race that can happen
-                    name='spawn',
+        # where where the fail-after will trigger outer scope
+        # .cancel() which then causes the inner scope to raise,
+        #
+        # BaseExceptionGroup('Exceptions from Trio nursery', [
+        #   BaseExceptionGroup('Exceptions from Trio nursery',
+        #   [
+        #       Cancelled(),
+        #       Cancelled(),
+        #   ]
+        #   ),
+        #   AssertionError('assert 0')
+        # ])
+        #
+        # WHY THIS DOESN'T MAKE SENSE:
+        # ---------------------------
+        # - it should raise too-slow-error when too slow..
+        #  * verified that using simple-cs and manually cancelling
+        #    you get same outcome -> indicates that the fail-after
+        #    can have its TooSlowError overriden!
+        #  |_ to check this it's easy, simplly decrease the timeout
+        #     as per the var below.
+        #
+        # - when using the manual simple-cs the outcome is different
+        #   DESPITE the `assert 0` which means regardless of the
+        #   inner scope effectively failing in the same way, the
+        #   bubbling up **is NOT the same**.
+        #
+        # delays trigger diff outcomes..
+        # ---------------------------
+        # as seen by uncommenting various lines below there is from
+        # my POV an unexpected outcome due to the delay=2 case.
+        #
+        # delay = 1  # no AssertionError in eg, TooSlowError raised.
+        # delay = 2  # is AssertionError in eg AND no TooSlowError !?
+        delay = 4  # is AssertionError in eg AND no _cs cancellation.
+
+        with trio.fail_after(delay) as _cs:
+        # with trio.CancelScope() as cs:
+        # ^XXX^ can be used instead to see same outcome.
+
+            async with (
+                # tractor.trionics.collapse_eg(),  # doesn't help
+                tractor.open_nursery(
+                    hide_tb=False,
+                    debug_mode=debug_mode,
+                    registry_addrs=[reg_addr],
+                ) as an,
+            ):
+                await an.run_in_actor(
+                    spawn_sub_with_sync_blocking_task,
+                    name='sync_blocking_sub',
                 )
                 await trio.sleep(1)
+
+                if man_cancel_outer:
+                    print('Cancelling manually in root')
+                    _cs.cancel()
+
+                # trigger exc-srced taskc down
+                # the actor tree.
+                print('RAISING IN ROOT')
                 assert 0
 
     with pytest.raises(AssertionError):

tests/test_clustering.py

@@ -13,26 +13,24 @@ MESSAGE = 'tractoring at full speed'
 def test_empty_mngrs_input_raises() -> None:
 
     async def main():
-        with trio.fail_after(1):
+        with trio.fail_after(3):
             async with (
                 open_actor_cluster(
                     modules=[__name__],
 
                     # NOTE: ensure we can passthrough runtime opts
-                    loglevel='info',
+                    loglevel='cancel',
-                    # debug_mode=True,
+                    debug_mode=False,
 
                 ) as portals,
 
-                gather_contexts(
+                gather_contexts(mngrs=()),
-                    # NOTE: it's the use of inline-generator syntax
-                    # here that causes the empty input.
-                    mngrs=(
-                        p.open_context(worker) for p in portals.values()
-                    ),
-                ),
             ):
-                assert 0
+                # should fail before this?
+                assert portals
+
+                # test should fail if we mk it here!
+                assert 0, 'Should have raised val-err !?'
 
     with pytest.raises(ValueError):
         trio.run(main)

tests/test_legacy_one_way_streaming.py

@@ -235,10 +235,16 @@ async def cancel_after(wait, reg_addr):
 
 
 @pytest.fixture(scope='module')
-def time_quad_ex(reg_addr, ci_env, spawn_backend):
+def time_quad_ex(
+    reg_addr: tuple,
+    ci_env: bool,
+    spawn_backend: str,
+):
     if spawn_backend == 'mp':
-        """no idea but the  mp *nix runs are flaking out here often...
+        '''
-        """
+        no idea but the  mp *nix runs are flaking out here often...
+
+        '''
         pytest.skip("Test is too flaky on mp in CI")
 
     timeout = 7 if platform.system() in ('Windows', 'Darwin') else 4
@@ -249,12 +255,24 @@ def time_quad_ex(reg_addr, ci_env, spawn_backend):
     return results, diff
 
 
-def test_a_quadruple_example(time_quad_ex, ci_env, spawn_backend):
+def test_a_quadruple_example(
-    """This also serves as a kind of "we'd like to be this fast test"."""
+    time_quad_ex: tuple,
+    ci_env: bool,
+    spawn_backend: str,
+):
+    '''
+    This also serves as a kind of "we'd like to be this fast test".
 
+    '''
     results, diff = time_quad_ex
     assert results
-    this_fast = 6 if platform.system() in ('Windows', 'Darwin') else 3
+    this_fast = (
+        6 if platform.system() in (
+            'Windows',
+            'Darwin',
+        )
+        else 3
+    )
     assert diff < this_fast
 
 

tests/test_root_infect_asyncio.py

@@ -147,8 +147,7 @@ def test_trio_prestarted_task_bubbles(
         await trio.sleep_forever()
 
     async def _trio_main():
-        # with trio.fail_after(2):
+        with trio.fail_after(2 if not debug_mode else 999):
-        with trio.fail_after(999):
             first: str
             chan: to_asyncio.LinkedTaskChannel
             aio_ev = asyncio.Event()
@@ -217,32 +216,25 @@ def test_trio_prestarted_task_bubbles(
                         ):
                             aio_ev.set()
 
-    with pytest.raises(
-        expected_exception=ExceptionGroup,
-    ) as excinfo:
-        tractor.to_asyncio.run_as_asyncio_guest(
-            trio_main=_trio_main,
-        )
-
-    eg = excinfo.value
-    rte_eg, rest_eg = eg.split(RuntimeError)
-
     # ensure the trio-task's error bubbled despite the aio-side
     # having (maybe) errored first.
     if aio_err_trigger in (
         'after_trio_task_starts',
         'after_start_point',
     ):
-        assert len(errs := rest_eg.exceptions) == 1
+        patt: str = 'trio-side'
-        typerr = errs[0]
+        expect_exc = TypeError
-        assert (
-            type(typerr) is TypeError
-            and
-            'trio-side' in typerr.args
-        )
 
     # when aio errors BEFORE (last) trio task is scheduled, we should
     # never see anythinb but the aio-side.
     else:
-        assert len(rtes := rte_eg.exceptions) == 1
+        patt: str = 'asyncio-side'
-        assert 'asyncio-side' in rtes[0].args[0]
+        expect_exc = RuntimeError
+
+    with pytest.raises(expect_exc) as excinfo:
+        tractor.to_asyncio.run_as_asyncio_guest(
+            trio_main=_trio_main,
+        )
+
+    caught_exc = excinfo.value
+    assert patt in caught_exc.args

tractor/_clustering.py

@@ -55,10 +55,17 @@ async def open_actor_cluster(
         raise ValueError(
             'Number of names is {len(names)} but count it {count}')
 
-    async with tractor.open_nursery(
+    async with (
-        **runtime_kwargs,
+        # tractor.trionics.collapse_eg(),
-    ) as an:
+        tractor.open_nursery(
-        async with trio.open_nursery() as n:
+            **runtime_kwargs,
+        ) as an
+    ):
+        async with (
+            # tractor.trionics.collapse_eg(),
+            trio.open_nursery() as tn,
+            tractor.trionics.maybe_raise_from_masking_exc()
+        ):
             uid = tractor.current_actor().uid
 
             async def _start(name: str) -> None:
@@ -69,9 +76,8 @@ async def open_actor_cluster(
                 )
 
             for name in names:
-                n.start_soon(_start, name)
+                tn.start_soon(_start, name)
 
         assert len(portals) == count
         yield portals
-
         await an.cancel(hard_kill=hard_kill)

tractor/_context.py

@@ -743,6 +743,8 @@ class Context:
             # cancelled, NOT their reported canceller. IOW in the
             # latter case we're cancelled by someone else getting
             # cancelled.
+            #
+            # !TODO, switching to `Actor.aid` here!
             if (canc := error.canceller) == self._actor.uid:
                 whom: str = 'us'
                 self._canceller = canc
@@ -2258,7 +2260,7 @@ async def open_context_from_portal(
         # await debug.pause()
         # log.cancel(
         match scope_err:
-            case trio.Cancelled:
+            case trio.Cancelled():
                 logmeth = log.cancel
 
             # XXX explicitly report on any non-graceful-taskc cases

tractor/_discovery.py

@@ -51,7 +51,6 @@ from ._state import (
 
 if TYPE_CHECKING:
     from ._runtime import Actor
-    from .ipc._server import IPCServer
 
 
 log = get_logger(__name__)
@@ -83,7 +82,7 @@ async def get_registry(
         )
     else:
         # TODO: try to look pre-existing connection from
-        # `IPCServer._peers` and use it instead?
+        # `Server._peers` and use it instead?
         async with (
             _connect_chan(addr) as chan,
             open_portal(chan) as regstr_ptl,
@@ -114,18 +113,23 @@ def get_peer_by_name(
 ) -> list[Channel]|None:  # at least 1
     '''
     Scan for an existing connection (set) to a named actor
-    and return any channels from `IPCServer._peers: dict`.
+    and return any channels from `Server._peers: dict`.
 
     This is an optimization method over querying the registrar for
     the same info.
 
     '''
     actor: Actor = current_actor()
-    server: IPCServer = actor.ipc_server
+    to_scan: dict[tuple, list[Channel]] = actor.ipc_server._peers.copy()
-    to_scan: dict[tuple, list[Channel]] = server._peers.copy()
+
-    pchan: Channel|None = actor._parent_chan
+    # TODO: is this ever needed? creates a duplicate channel on actor._peers
-    if pchan:
+    # when multiple find_actor calls are made to same actor from a single ctx
-        to_scan[pchan.uid].append(pchan)
+    # which causes actor exit to hang waiting forever on
+    # `actor._no_more_peers.wait()` in `_runtime.async_main`
+
+    # pchan: Channel|None = actor._parent_chan
+    # if pchan and pchan.uid not in to_scan:
+    #     to_scan[pchan.uid].append(pchan)
 
     for aid, chans in to_scan.items():
         _, peer_name = aid

tractor/_entry.py

@@ -21,7 +21,7 @@ Sub-process entry points.
 from __future__ import annotations
 from functools import partial
 import multiprocessing as mp
-import os
+# import os
 from typing import (
     Any,
     TYPE_CHECKING,
@@ -38,6 +38,7 @@ from .devx import (
     _frame_stack,
     pformat,
 )
+# from .msg import pretty_struct
 from .to_asyncio import run_as_asyncio_guest
 from ._addr import UnwrappedAddress
 from ._runtime import (
@@ -127,20 +128,13 @@ def _trio_main(
 
     if actor.loglevel is not None:
         get_console_log(actor.loglevel)
-        actor_info: str = (
-            f'|_{actor}\n'
-            f'  uid: {actor.uid}\n'
-            f'  pid: {os.getpid()}\n'
-            f'  parent_addr: {parent_addr}\n'
-            f'  loglevel: {actor.loglevel}\n'
-        )
         log.info(
-            'Starting new `trio` subactor:\n'
+            f'Starting `trio` subactor from parent @ '
+            f'{parent_addr}\n'
             +
             pformat.nest_from_op(
                 input_op='>(',  # see syntax ideas above
-                tree_str=actor_info,
+                text=f'{actor}',
-                back_from_op=2,  # since "complete"
             )
         )
     logmeth = log.info
@@ -149,8 +143,8 @@ def _trio_main(
         +
         pformat.nest_from_op(
             input_op=')>',  # like a "closed-to-play"-icon from super perspective
-            tree_str=actor_info,
+            text=f'{actor}',
-            back_from_op=1,
+            nest_indent=1,
         )
     )
     try:
@@ -167,7 +161,7 @@ def _trio_main(
             +
             pformat.nest_from_op(
                 input_op='c)>',  # closed due to cancel (see above)
-                tree_str=actor_info,
+                text=f'{actor}',
             )
         )
     except BaseException as err:
@@ -177,7 +171,7 @@ def _trio_main(
             +
             pformat.nest_from_op(
                 input_op='x)>',  # closed by error
-                tree_str=actor_info,
+                text=f'{actor}',
             )
         )
         # NOTE since we raise a tb will already be shown on the

tractor/_portal.py

@@ -118,6 +118,10 @@ class Portal:
 
     @property
     def chan(self) -> Channel:
+        '''
+        Ref to this ctx's underlying `tractor.ipc.Channel`.
+
+        '''
         return self._chan
 
     @property
@@ -177,10 +181,17 @@ class Portal:
 
         # not expecting a "main" result
         if self._expect_result_ctx is None:
+            peer_id: str = f'{self.channel.aid.reprol()!r}'
             log.warning(
-                f"Portal for {self.channel.aid} not expecting a final"
+                f'Portal to peer {peer_id} will not deliver a final result?\n'
-                " result?\nresult() should only be called if subactor"
+                f'\n'
-                " was spawned with `ActorNursery.run_in_actor()`")
+                f'Context.result() can only be called by the parent of '
+                f'a sub-actor when it was spawned with '
+                f'`ActorNursery.run_in_actor()`'
+                f'\n'
+                f'Further this `ActorNursery`-method-API will deprecated in the'
+                f'near fututre!\n'
+            )
             return NoResult
 
         # expecting a "main" result
@@ -213,6 +224,7 @@ class Portal:
         typname: str = type(self).__name__
         log.warning(
             f'`{typname}.result()` is DEPRECATED!\n'
+            f'\n'
             f'Use `{typname}.wait_for_result()` instead!\n'
         )
         return await self.wait_for_result(
@@ -224,8 +236,10 @@ class Portal:
         # terminate all locally running async generator
         # IPC calls
         if self._streams:
-            log.cancel(
+            peer_id: str = f'{self.channel.aid.reprol()!r}'
-                f"Cancelling all streams with {self.channel.aid}")
+            report: str = (
+                f'Cancelling all msg-streams with {peer_id}\n'
+            )
             for stream in self._streams.copy():
                 try:
                     await stream.aclose()
@@ -234,10 +248,18 @@ class Portal:
                     # (unless of course at some point down the road we
                     # won't expect this to always be the case or need to
                     # detect it for respawning purposes?)
-                    log.debug(f"{stream} was already closed.")
+                    report += (
+                        f'->) {stream!r} already closed\n'
+                    )
+
+            log.cancel(report)
 
     async def aclose(self):
-        log.debug(f"Closing {self}")
+        log.debug(
+            f'Closing portal\n'
+            f'>}}\n'
+            f'|_{self}\n'
+        )
         # TODO: once we move to implementing our own `ReceiveChannel`
         # (including remote task cancellation inside its `.aclose()`)
         # we'll need to .aclose all those channels here
@@ -263,19 +285,18 @@ class Portal:
         __runtimeframe__: int = 1  # noqa
 
         chan: Channel = self.channel
+        peer_id: str = f'{self.channel.aid.reprol()!r}'
         if not chan.connected():
             log.runtime(
-                'This channel is already closed, skipping cancel request..'
+                'Peer {peer_id} is already disconnected\n'
+                '-> skipping cancel request..\n'
             )
             return False
 
-        reminfo: str = (
-            f'c)=> {self.channel.aid}\n'
-            f'  |_{chan}\n'
-        )
         log.cancel(
-            f'Requesting actor-runtime cancel for peer\n\n'
+            f'Sending actor-runtime-cancel-req to peer\n'
-            f'{reminfo}'
+            f'\n'
+            f'c)=> {peer_id}\n'
         )
 
         # XXX the one spot we set it?
@@ -300,8 +321,9 @@ class Portal:
                 # may timeout and we never get an ack (obvi racy)
                 # but that doesn't mean it wasn't cancelled.
                 log.debug(
-                    'May have failed to cancel peer?\n'
+                    f'May have failed to cancel peer?\n'
-                    f'{reminfo}'
+                    f'\n'
+                    f'c)=?> {peer_id}\n'
                 )
 
             # if we get here some weird cancellation case happened
@@ -319,22 +341,22 @@ class Portal:
 
             TransportClosed,
         ) as tpt_err:
-            report: str = (
+            ipc_borked_report: str = (
-                f'IPC chan for actor already closed or broken?\n\n'
+                f'IPC for actor already closed/broken?\n\n'
-                f'{self.channel.aid}\n'
+                f'\n'
-                f' |_{self.channel}\n'
+                f'c)=x> {peer_id}\n'
             )
             match tpt_err:
                 case TransportClosed():
-                    log.debug(report)
+                    log.debug(ipc_borked_report)
                 case _:
-                    report += (
+                    ipc_borked_report += (
                         f'\n'
                         f'Unhandled low-level transport-closed/error during\n'
                         f'Portal.cancel_actor()` request?\n'
                         f'<{type(tpt_err).__name__}( {tpt_err} )>\n'
                     )
-                    log.warning(report)
+                    log.warning(ipc_borked_report)
 
             return False
 
@@ -491,10 +513,13 @@ class Portal:
                 with trio.CancelScope(shield=True):
                     await ctx.cancel()
 
-            except trio.ClosedResourceError:
+            except trio.ClosedResourceError as cre:
                 # if the far end terminates before we send a cancel the
                 # underlying transport-channel may already be closed.
-                log.cancel(f'Context {ctx} was already closed?')
+                log.cancel(
+                    f'Context.cancel() -> {cre!r}\n'
+                    f'cid: {ctx.cid!r} already closed?\n'
+                )
 
             # XXX: should this always be done?
             # await recv_chan.aclose()

tractor/_root.py

@@ -97,7 +97,7 @@ async def maybe_block_bp(
     ):
         logger.info(
             f'Found `greenback` installed @ {maybe_mod}\n'
-            'Enabling `tractor.pause_from_sync()` support!\n'
+            f'Enabling `tractor.pause_from_sync()` support!\n'
         )
         os.environ['PYTHONBREAKPOINT'] = (
             'tractor.devx.debug._sync_pause_from_builtin'
@@ -202,7 +202,9 @@ async def open_root_actor(
 
     '''
     # XXX NEVER allow nested actor-trees!
-    if already_actor := _state.current_actor(err_on_no_runtime=False):
+    if already_actor := _state.current_actor(
+        err_on_no_runtime=False,
+    ):
         rtvs: dict[str, Any] = _state._runtime_vars
         root_mailbox: list[str, int] = rtvs['_root_mailbox']
         registry_addrs: list[list[str, int]] = rtvs['_registry_addrs']
@@ -224,11 +226,16 @@ async def open_root_actor(
     ):
         if enable_transports is None:
             enable_transports: list[str] = _state.current_ipc_protos()
+        else:
+            _state._runtime_vars['_enable_tpts'] = enable_transports
 
-            # TODO! support multi-tpts per actor! Bo
+        # TODO! support multi-tpts per actor!
-            assert (
+        # Bo
-                len(enable_transports) == 1
+        if not len(enable_transports) == 1:
-            ), 'No multi-tpt support yet!'
+            raise RuntimeError(
+                f'No multi-tpt support yet!\n'
+                f'enable_transports={enable_transports!r}\n'
+            )
 
         _frame_stack.hide_runtime_frames()
         __tracebackhide__: bool = hide_tb
@@ -267,14 +274,20 @@ async def open_root_actor(
                 DeprecationWarning,
                 stacklevel=2,
             )
-            registry_addrs = [arbiter_addr]
+            uw_reg_addrs = [arbiter_addr]
 
-        if not registry_addrs:
+        uw_reg_addrs = registry_addrs
-            registry_addrs: list[UnwrappedAddress] = default_lo_addrs(
+        if not uw_reg_addrs:
+            uw_reg_addrs: list[UnwrappedAddress] = default_lo_addrs(
                 enable_transports
             )
 
-        assert registry_addrs
+        # must exist by now since all below code is dependent
+        assert uw_reg_addrs
+        registry_addrs: list[Address] = [
+            wrap_address(uw_addr)
+            for uw_addr in uw_reg_addrs
+        ]
 
         loglevel = (
             loglevel
@@ -323,10 +336,10 @@ async def open_root_actor(
             enable_stack_on_sig()
 
         # closed into below ping task-func
-        ponged_addrs: list[UnwrappedAddress] = []
+        ponged_addrs: list[Address] = []
 
         async def ping_tpt_socket(
-            addr: UnwrappedAddress,
+            addr: Address,
             timeout: float = 1,
         ) -> None:
             '''
@@ -346,17 +359,22 @@ async def open_root_actor(
                 # be better to eventually have a "discovery" protocol
                 # with basic handshake instead?
                 with trio.move_on_after(timeout):
-                    async with _connect_chan(addr):
+                    async with _connect_chan(addr.unwrap()):
                         ponged_addrs.append(addr)
 
             except OSError:
-                # TODO: make this a "discovery" log level?
+                # ?TODO, make this a "discovery" log level?
                 logger.info(
-                    f'No actor registry found @ {addr}\n'
+                    f'No root-actor registry found @ {addr!r}\n'
                 )
 
+        # !TODO, this is basically just another (abstract)
+        # happy-eyeballs, so we should try for formalize it somewhere
+        # in a `.[_]discovery` ya?
+        #
         async with trio.open_nursery() as tn:
-            for addr in registry_addrs:
+            for uw_addr in uw_reg_addrs:
+                addr: Address = wrap_address(uw_addr)
                 tn.start_soon(
                     ping_tpt_socket,
                     addr,
@@ -385,24 +403,28 @@ async def open_root_actor(
                 loglevel=loglevel,
                 enable_modules=enable_modules,
             )
-            # DO NOT use the registry_addrs as the transport server
+            # **DO NOT** use the registry_addrs as the
-            # addrs for this new non-registar, root-actor.
+            # ipc-transport-server's bind-addrs as this is
+            # a new NON-registrar, ROOT-actor.
+            #
+            # XXX INSTEAD, bind random addrs using the same tpt
+            # proto.
             for addr in ponged_addrs:
-                waddr: Address = wrap_address(addr)
                 trans_bind_addrs.append(
-                    waddr.get_random(bindspace=waddr.bindspace)
+                    addr.get_random(
+                        bindspace=addr.bindspace,
+                    )
                 )
 
         # Start this local actor as the "registrar", aka a regular
         # actor who manages the local registry of "mailboxes" of
         # other process-tree-local sub-actors.
         else:
-
             # NOTE that if the current actor IS THE REGISTAR, the
             # following init steps are taken:
             # - the tranport layer server is bound to each addr
             #   pair defined in provided registry_addrs, or the default.
-            trans_bind_addrs = registry_addrs
+            trans_bind_addrs = uw_reg_addrs
 
             # - it is normally desirable for any registrar to stay up
             #   indefinitely until either all registered (child/sub)
@@ -426,6 +448,16 @@ async def open_root_actor(
             # `.trio.run()`.
             actor._infected_aio = _state._runtime_vars['_is_infected_aio']
 
+        # NOTE, only set the loopback addr for the
+        # process-tree-global "root" mailbox since all sub-actors
+        # should be able to speak to their root actor over that
+        # channel.
+        raddrs: list[Address] = _state._runtime_vars['_root_addrs']
+        raddrs.extend(trans_bind_addrs)
+        # TODO, remove once we have also removed all usage;
+        # eventually all (root-)registry apis should expect > 1 addr.
+        _state._runtime_vars['_root_mailbox'] = raddrs[0]
+
         # Start up main task set via core actor-runtime nurseries.
         try:
             # assign process-local actor
@@ -433,20 +465,26 @@ async def open_root_actor(
 
             # start local channel-server and fake the portal API
             # NOTE: this won't block since we provide the nursery
-            ml_addrs_str: str = '\n'.join(
+            report: str = f'Starting actor-runtime for {actor.aid.reprol()!r}\n'
-                f'@{addr}' for addr in trans_bind_addrs
+            if reg_addrs := actor.registry_addrs:
-            )
+                report += (
-            logger.info(
+                    '-> Opening new registry @ '
-                f'Starting local {actor.uid} on the following transport addrs:\n'
+                    +
-                f'{ml_addrs_str}'
+                    '\n'.join(
-            )
+                        f'{addr}' for addr in reg_addrs
+                    )
+                )
+            logger.info(f'{report}\n')
 
             # start runtime in a bg sub-task, yield to caller.
             async with (
                 collapse_eg(),
                 trio.open_nursery() as root_tn,
-            ):
 
+                # XXX, finally-footgun below?
+                # -> see note on why shielding.
+                # maybe_raise_from_masking_exc(),
+            ):
                 # `_runtime.async_main()` creates an internal nursery
                 # and blocks here until any underlying actor(-process)
                 # tree has terminated thereby conducting so called
@@ -505,7 +543,7 @@ async def open_root_actor(
                     raise
 
                 finally:
-                    # NOTE: not sure if we'll ever need this but it's
+                    # NOTE/TODO?, not sure if we'll ever need this but it's
                     # possibly better for even more determinism?
                     # logger.cancel(
                     #     f'Waiting on {len(nurseries)} nurseries in root..')
@@ -516,14 +554,19 @@ async def open_root_actor(
 
                     op_nested_actor_repr: str = _pformat.nest_from_op(
                         input_op='>) ',
-                        tree_str=actor.pformat(),
+                        text=actor.pformat(),
                         nest_prefix='|_',
                     )
                     logger.info(
                         f'Closing down root actor\n'
-                        f'{op_nested_actor_repr}\n'
+                        f'{op_nested_actor_repr}'
                     )
-                    await actor.cancel(None)  # self cancel
+                    # XXX, THIS IS A *finally-footgun*!
+                    # -> though already shields iternally it can
+                    # taskc here and mask underlying errors raised in
+                    # the try-block above?
+                    with trio.CancelScope(shield=True):
+                        await actor.cancel(None)  # self cancel
         finally:
             # revert all process-global runtime state
             if (
@@ -536,10 +579,16 @@ async def open_root_actor(
             _state._current_actor = None
             _state._last_actor_terminated = actor
 
-            logger.runtime(
+            sclang_repr: str = _pformat.nest_from_op(
+                input_op=')>',
+                text=actor.pformat(),
+                nest_prefix='|_',
+                nest_indent=1,
+            )
+
+            logger.info(
                 f'Root actor terminated\n'
-                f')>\n'
+                f'{sclang_repr}'
-                f' |_{actor}\n'
             )
 
 

tractor/_rpc.py

@@ -64,6 +64,7 @@ from .trionics import (
 from .devx import (
     debug,
     add_div,
+    pformat as _pformat,
 )
 from . import _state
 from .log import get_logger
@@ -72,7 +73,7 @@ from .msg import (
     MsgCodec,
     PayloadT,
     NamespacePath,
-    # pretty_struct,
+    pretty_struct,
     _ops as msgops,
 )
 from tractor.msg.types import (
@@ -220,11 +221,18 @@ async def _invoke_non_context(
             task_status.started(ctx)
             result = await coro
             fname: str = func.__name__
+
+            op_nested_task: str = _pformat.nest_from_op(
+                input_op=f')> cid: {ctx.cid!r}',
+                text=f'{ctx._task}',
+                nest_indent=1,  # under >
+            )
             log.runtime(
-                'RPC complete:\n'
+                f'RPC task complete\n'
-                f'task: {ctx._task}\n'
+                f'\n'
-                f'|_cid={ctx.cid}\n'
+                f'{op_nested_task}\n'
-                f'|_{fname}() -> {pformat(result)}\n'
+                f'\n'
+                f')> {fname}() -> {pformat(result)}\n'
             )
 
             # NOTE: only send result if we know IPC isn't down
@@ -255,7 +263,7 @@ async def _errors_relayed_via_ipc(
     ctx: Context,
     is_rpc: bool,
 
-    hide_tb: bool = False,
+    hide_tb: bool = True,
     debug_kbis: bool = False,
     task_status: TaskStatus[
         Context | BaseException
@@ -380,9 +388,9 @@ async def _errors_relayed_via_ipc(
     # they can be individually ccancelled.
     finally:
 
-        # if the error is not from user code and instead a failure
+        # if the error is not from user code and instead a failure of
-        # of a runtime RPC or transport failure we do prolly want to
+        # an internal-runtime-RPC or IPC-connection, we do (prolly) want
-        # show this frame
+        # to show this frame!
         if (
             rpc_err
             and (
@@ -664,7 +672,8 @@ async def _invoke(
                 ctx._result = res
                 log.runtime(
                     f'Sending result msg and exiting {ctx.side!r}\n'
-                    f'{return_msg}\n'
+                    f'\n'
+                    f'{pretty_struct.pformat(return_msg)}\n'
                 )
                 await chan.send(return_msg)
 
@@ -831,12 +840,12 @@ async def _invoke(
                 else:
                     descr_str += f'\n{merr!r}\n'
             else:
-                descr_str += f'\nand final result {ctx.outcome!r}\n'
+                descr_str += f'\nwith final result {ctx.outcome!r}\n'
 
             logmeth(
-                message
+                f'{message}\n'
-                +
+                f'\n'
-                descr_str
+                f'{descr_str}\n'
             )
 
 
@@ -1003,8 +1012,6 @@ async def process_messages(
                         cid=cid,
                         kwargs=kwargs,
                     ):
-                        kwargs |= {'req_chan': chan}
-
                         # XXX NOTE XXX don't start entire actor
                         # runtime cancellation if this actor is
                         # currently in debug mode!
@@ -1023,14 +1030,14 @@ async def process_messages(
                                 cid,
                                 chan,
                                 actor.cancel,
-                                kwargs,
+                                kwargs | {'req_chan': chan},
                                 is_rpc=False,
                                 return_msg_type=CancelAck,
                             )
 
                         log.runtime(
-                            'Cancelling IPC transport msg-loop with peer:\n'
+                            'Cancelling RPC-msg-loop with peer\n'
-                            f'|_{chan}\n'
+                            f'->c}} {chan.aid.reprol()}@[{chan.maddr}]\n'
                         )
                         loop_cs.cancel()
                         break
@@ -1043,7 +1050,7 @@ async def process_messages(
                     ):
                         target_cid: str = kwargs['cid']
                         kwargs |= {
-                            'requesting_uid': chan.uid,
+                            'requesting_aid': chan.aid,
                             'ipc_msg': msg,
 
                             # XXX NOTE! ONLY the rpc-task-owning
@@ -1079,21 +1086,34 @@ async def process_messages(
                         ns=ns,
                         func=funcname,
                         kwargs=kwargs,  # type-spec this? see `msg.types`
-                        uid=actorid,
+                        uid=actor_uuid,
                     ):
+                        if actor_uuid != chan.aid.uid:
+                            raise RuntimeError(
+                                f'IPC <Start> msg <-> chan.aid mismatch!?\n'
+                                f'Channel.aid = {chan.aid!r}\n'
+                                f'Start.uid = {actor_uuid!r}\n'
+                            )
+                        # await debug.pause()
+                        op_repr: str = 'Start <=) '
+                        req_repr: str = _pformat.nest_from_op(
+                            input_op=op_repr,
+                            op_suffix='',
+                            nest_prefix='',
+                            text=f'{chan}',
+
+                            nest_indent=len(op_repr)-1,
+                            rm_from_first_ln='<',
+                            # ^XXX, subtract -1 to account for
+                            # <Channel
+                            # ^_chevron to be stripped
+                        )
                         start_status: str = (
-                            'Handling RPC `Start` request\n'
+                            'Handling RPC request\n'
-                            f'<= peer: {actorid}\n\n'
+                            f'{req_repr}\n'
-                            f'  |_{chan}\n'
+                            f'\n'
-                            f'  |_cid: {cid}\n\n'
+                            f'->{{ ipc-context-id: {cid!r}\n'
-                            # f'  |_{ns}.{funcname}({kwargs})\n'
+                            f'->{{ nsp for fn: `{ns}.{funcname}({kwargs})`\n'
-                            f'>> {actor.uid}\n'
-                            f'  |_{actor}\n'
-                            f'   -> nsp: `{ns}.{funcname}({kwargs})`\n'
-
-                            # f'  |_{ns}.{funcname}({kwargs})\n\n'
-
-                            # f'{pretty_struct.pformat(msg)}\n'
                         )
 
                         # runtime-internal endpoint: `Actor.<funcname>`
@@ -1122,10 +1142,6 @@ async def process_messages(
                                 await chan.send(err_msg)
                                 continue
 
-                        start_status += (
-                            f'   -> func: {func}\n'
-                        )
-
                         # schedule a task for the requested RPC function
                         # in the actor's main "service nursery".
                         #
@@ -1133,7 +1149,7 @@ async def process_messages(
                         # supervision isolation? would avoid having to
                         # manage RPC tasks individually in `._rpc_tasks`
                         # table?
-                        start_status += '   -> scheduling new task..\n'
+                        start_status += '->( scheduling new task..\n'
                         log.runtime(start_status)
                         try:
                             ctx: Context = await actor._service_n.start(
@@ -1217,12 +1233,24 @@ async def process_messages(
             # END-OF `async for`:
             # IPC disconnected via `trio.EndOfChannel`, likely
             # due to a (graceful) `Channel.aclose()`.
+
+            chan_op_repr: str = '<=x] '
+            chan_repr: str = _pformat.nest_from_op(
+                input_op=chan_op_repr,
+                op_suffix='',
+                nest_prefix='',
+                text=chan.pformat(),
+                nest_indent=len(chan_op_repr)-1,
+                rm_from_first_ln='<',
+            )
             log.runtime(
-                f'channel for {chan.uid} disconnected, cancelling RPC tasks\n'
+                f'IPC channel disconnected\n'
-                f'|_{chan}\n'
+                f'{chan_repr}\n'
+                f'\n'
+                f'->c) cancelling RPC tasks.\n'
             )
             await actor.cancel_rpc_tasks(
-                req_uid=actor.uid,
+                req_aid=actor.aid,
                 # a "self cancel" in terms of the lifetime of the
                 # IPC connection which is presumed to be the
                 # source of any requests for spawned tasks.
@@ -1294,13 +1322,37 @@ async def process_messages(
     finally:
         # msg debugging for when he machinery is brokey
         if msg is None:
-            message: str = 'Exiting IPC msg loop without receiving a msg?'
+            message: str = 'Exiting RPC-loop without receiving a msg?'
         else:
+            task_op_repr: str = ')>'
+            task: trio.Task = trio.lowlevel.current_task()
+
+            # maybe add cancelled opt prefix
+            if task._cancel_status.effectively_cancelled:
+                task_op_repr = 'c' + task_op_repr
+
+            task_repr: str = _pformat.nest_from_op(
+                input_op=task_op_repr,
+                text=f'{task!r}',
+                nest_indent=1,
+            )
+            # chan_op_repr: str = '<=} '
+            # chan_repr: str = _pformat.nest_from_op(
+            #     input_op=chan_op_repr,
+            #     op_suffix='',
+            #     nest_prefix='',
+            #     text=chan.pformat(),
+            #     nest_indent=len(chan_op_repr)-1,
+            #     rm_from_first_ln='<',
+            # )
             message: str = (
-                'Exiting IPC msg loop with final msg\n\n'
+                f'Exiting RPC-loop with final msg\n'
-                f'<= peer: {chan.uid}\n'
+                f'\n'
-                f'  |_{chan}\n\n'
+                # f'{chan_repr}\n'
-                # f'{pretty_struct.pformat(msg)}'
+                f'{task_repr}\n'
+                f'\n'
+                f'{pretty_struct.pformat(msg)}'
+                f'\n'
             )
 
         log.runtime(message)

tractor/_runtime.py

@@ -213,7 +213,7 @@ class Actor:
         *,
         enable_modules: list[str] = [],
         loglevel: str|None = None,
-        registry_addrs: list[UnwrappedAddress]|None = None,
+        registry_addrs: list[Address]|None = None,
         spawn_method: str|None = None,
 
         # TODO: remove!
@@ -234,7 +234,7 @@ class Actor:
 
         # state
         self._cancel_complete = trio.Event()
-        self._cancel_called_by_remote: tuple[str, tuple]|None = None
+        self._cancel_called_by: tuple[str, tuple]|None = None
         self._cancel_called: bool = False
 
         # retreive and store parent `__main__` data which
@@ -256,11 +256,12 @@ class Actor:
         if arbiter_addr is not None:
             warnings.warn(
                 '`Actor(arbiter_addr=<blah>)` is now deprecated.\n'
-                'Use `registry_addrs: list[tuple]` instead.',
+                'Use `registry_addrs: list[Address]` instead.',
                 DeprecationWarning,
                 stacklevel=2,
             )
-            registry_addrs: list[UnwrappedAddress] = [arbiter_addr]
+
+            registry_addrs: list[Address] = [wrap_address(arbiter_addr)]
 
         # marked by the process spawning backend at startup
         # will be None for the parent most process started manually
@@ -299,8 +300,10 @@ class Actor:
         # input via the validator.
         self._reg_addrs: list[UnwrappedAddress] = []
         if registry_addrs:
-            self.reg_addrs: list[UnwrappedAddress] = registry_addrs
+            _state._runtime_vars['_registry_addrs'] = self.reg_addrs = [
-            _state._runtime_vars['_registry_addrs'] = registry_addrs
+                addr.unwrap()
+                for addr in registry_addrs
+            ]
 
     @property
     def aid(self) -> msgtypes.Aid:
@@ -346,69 +349,118 @@ class Actor:
     def pid(self) -> int:
         return self._aid.pid
 
+    @property
+    def repr_state(self) -> str:
+        if self.cancel_complete:
+            return 'cancelled'
+
+        elif canceller := self.cancel_caller:
+                return f' and cancel-called by {canceller}'
+
+        else:
+            return 'running'
+
     def pformat(
         self,
         ds: str = ': ',
         indent: int = 0,
+        privates: bool = False,
     ) -> str:
-        fields_sect_prefix: str = ' |_'
+
-        parent_uid: tuple|None = None
+        fmtstr: str = f'|_id: {self.aid.reprol()!r}\n'
+        if privates:
+            aid_nest_prefix: str = '|_aid='
+            aid_field_repr: str = _pformat.nest_from_op(
+                input_op='',
+                text=pretty_struct.pformat(
+                    struct=self.aid,
+                    field_indent=2,
+                ),
+                op_suffix='',
+                nest_prefix=aid_nest_prefix,
+                nest_indent=0,
+            )
+            fmtstr: str = f'{aid_field_repr}'
+
         if rent_chan := self._parent_chan:
-            parent_uid = rent_chan.uid
+            fmtstr += (
+                f"|_parent{ds}{rent_chan.aid.reprol()}\n"
+            )
 
-        peers: list = []
         server: _server.IPCServer = self.ipc_server
-        ipc_server_sect: str = ''
         if server:
-            peers: list[tuple] = list(server._peer_connected)
+            if privates:
+                server_repr: str = self._ipc_server.pformat(
+                    privates=privates,
+                )
+                # create field ln as a key-header indented under
+                # and up to the section's key prefix.
+                # ^XXX if we were to indent `repr(Server)` to
+                # '<key>: '
+                #  _here_^
+                server_repr: str = _pformat.nest_from_op(
+                    input_op='',  # nest as sub-obj
+                    op_suffix='',
+                    text=server_repr,
+                )
+                fmtstr += (
+                    f"{server_repr}"
+                )
+            else:
+                fmtstr += (
+                    f'|_ipc: {server.repr_state!r}\n'
+                )
 
-            # create field ln as a key-header indented under
+        fmtstr += (
-            # and up to the section's key prefix.
+            f'|_rpc: {len(self._rpc_tasks)} active tasks\n'
-            # field_ln_header: str = textwrap.indent(
-            #     text=f"ipc_server{ds}",
-            #     prefix=' '*len(fields_sect_prefix),
-            # )
-            # ^XXX if we were to indent `repr(Server)` to
-            # '<key>: '
-            #  _here_^
-            server_repr: str = textwrap.indent(
-                text=self._ipc_server.pformat(),
-                # prefix=' '*len(field_ln_header),
-                prefix=' '*len(fields_sect_prefix),
-            )
-            ipc_server_sect: str = (
-                # f'{field_ln_header}\n'
-                f'{server_repr}'
-            )
-
-        fmtstr: str = (
-            f' |_id: {self.aid!r}\n'
-            # f"   aid{ds}{self.aid!r}\n"
-            f"   parent{ds}{parent_uid}\n"
-            # f'\n'
-            f' |_ipc: {len(peers)!r} connected peers\n'
-            f"   peers{ds}{peers!r}\n"
-            f"{ipc_server_sect}"
-            # f'\n'
-            f' |_rpc: {len(self._rpc_tasks)} tasks\n'
-            f"   ctxs{ds}{len(self._contexts)}\n"
-            # f'\n'
-            f' |_runtime: ._task{ds}{self._task!r}\n'
-            f'   _spawn_method{ds}{self._spawn_method}\n'
-            f'   _actoruid2nursery{ds}{self._actoruid2nursery}\n'
-            f'   _forkserver_info{ds}{self._forkserver_info}\n'
-            # f'\n'
-            f' |_state: "TODO: .repr_state()"\n'
-            f'   _cancel_complete{ds}{self._cancel_complete}\n'
-            f'   _cancel_called_by_remote{ds}{self._cancel_called_by_remote}\n'
-            f'   _cancel_called{ds}{self._cancel_called}\n'
         )
+
+        # TODO, actually fix the .repr_state impl/output?
+        # append ipc-ctx state summary
+        # ctxs: dict = self._contexts
+        # if ctxs:
+        #     ctx_states: dict[str, int] = {}
+        #     for ctx in self._contexts.values():
+        #         ctx_state: str = ctx.repr_state
+        #         cnt = ctx_states.setdefault(ctx_state, 0)
+        #         ctx_states[ctx_state] = cnt + 1
+
+        #     fmtstr += (
+        #         f"  ctxs{ds}{ctx_states}\n"
+        #     )
+
+        # runtime-state
+        task_name: str = '<dne>'
+        if task := self._task:
+            task_name: str = task.name
+        fmtstr += (
+            # TODO, this just like ctx?
+            f'|_state: {self.repr_state!r}\n'
+            f'  task: {task_name}\n'
+            f'  loglevel: {self.loglevel!r}\n'
+            f'  subactors_spawned: {len(self._actoruid2nursery)}\n'
+        )
+        if not _state.is_root_process():
+            fmtstr += f'  spawn_method: {self._spawn_method!r}\n'
+
+        if privates:
+            fmtstr += (
+                # f'  actoruid2nursery{ds}{self._actoruid2nursery}\n'
+                f'  cancel_complete{ds}{self._cancel_complete}\n'
+                f'  cancel_called_by_remote{ds}{self._cancel_called_by}\n'
+                f'  cancel_called{ds}{self._cancel_called}\n'
+            )
+
+        if fmtstr:
+            fmtstr: str = textwrap.indent(
+                text=fmtstr,
+                prefix=' '*(1 + indent),
+            )
+
         _repr: str = (
-            '<Actor(\n'
+            f'<{type(self).__name__}(\n'
-            +
+            f'{fmtstr}'
-            fmtstr
+            f')>\n'
-            +
-            ')>\n'
         )
         if indent:
             _repr: str = textwrap.indent(
@@ -423,7 +475,11 @@ class Actor:
     def reg_addrs(self) -> list[UnwrappedAddress]:
         '''
         List of (socket) addresses for all known (and contactable)
-        registry actors.
+        registry-service actors in "unwrapped" (i.e. IPC interchange
+        wire-compat) form.
+
+        If you are looking for the "wrapped" address form, use
+        `.registry_addrs` instead.
 
         '''
         return self._reg_addrs
@@ -442,8 +498,14 @@ class Actor:
 
         self._reg_addrs = addrs
 
+    @property
+    def registry_addrs(self) -> list[Address]:
+        return [wrap_address(uw_addr)
+                for uw_addr in self.reg_addrs]
+
     def load_modules(
         self,
+
     ) -> None:
         '''
         Load explicitly enabled python modules from local fs after
@@ -533,11 +595,11 @@ class Actor:
         queue.
 
         '''
-        uid: tuple[str, str] = chan.uid
+        aid: msgtypes.Aid = chan.aid
-        assert uid, f"`chan.uid` can't be {uid}"
+        assert aid, f"`chan.aid` can't be {aid}"
         try:
             ctx: Context = self._contexts[(
-                uid,
+                aid.uid,
                 cid,
 
                 # TODO: how to determine this tho?
@@ -548,7 +610,7 @@ class Actor:
                 'Ignoring invalid IPC msg!?\n'
                 f'Ctx seems to not/no-longer exist??\n'
                 f'\n'
-                f'<=? {uid}\n'
+                f'<=? {aid.reprol()!r}\n'
                 f'  |_{pretty_struct.pformat(msg)}\n'
             )
             match msg:
@@ -597,6 +659,7 @@ class Actor:
           msging session's lifetime.
 
         '''
+        # ?TODO, use Aid here as well?
         actor_uid = chan.uid
         assert actor_uid
         try:
@@ -914,9 +977,7 @@ class Actor:
             return (
                 chan,
                 accept_addrs,
-                None,
+                _state._runtime_vars['_enable_tpts']
-                # ^TODO, preferred tpts list from rent!
-                # -[ ] need to extend the `SpawnSpec` tho!
             )
 
         # failed to connect back?
@@ -947,6 +1008,22 @@ class Actor:
             None,  # self cancel all rpc tasks
         )
 
+    @property
+    def cancel_complete(self) -> bool:
+        return self._cancel_complete.is_set()
+
+    @property
+    def cancel_called(self) -> bool:
+        '''
+        Was this actor requested to cancel by a remote peer actor.
+
+        '''
+        return self._cancel_called_by is not None
+
+    @property
+    def cancel_caller(self) -> msgtypes.Aid|None:
+        return self._cancel_called_by
+
     async def cancel(
         self,
 
@@ -971,20 +1048,18 @@ class Actor:
 
         '''
         (
-            requesting_uid,
+            requesting_aid,  # Aid
-            requester_type,
+            requester_type,  # str
             req_chan,
             log_meth,
         ) = (
-            req_chan.uid,
+            req_chan.aid,
             'peer',
             req_chan,
             log.cancel,
-
         ) if req_chan else (
-
             # a self cancel of ALL rpc tasks
-            self.uid,
+            self.aid,
             'self',
             self,
             log.runtime,
@@ -992,14 +1067,14 @@ class Actor:
         # TODO: just use the new `Context.repr_rpc: str` (and
         # other) repr fields instead of doing this all manual..
         msg: str = (
-            f'Actor-runtime cancel request from {requester_type}\n\n'
+            f'Actor-runtime cancel request from {requester_type!r}\n'
-            f'<=c) {requesting_uid}\n'
-            f'  |_{self}\n'
             f'\n'
+            f'<=c)\n'
+            f'{self}'
         )
 
         # TODO: what happens here when we self-cancel tho?
-        self._cancel_called_by_remote: tuple = requesting_uid
+        self._cancel_called_by: tuple = requesting_aid
         self._cancel_called = True
 
         # cancel all ongoing rpc tasks
@@ -1027,7 +1102,7 @@ class Actor:
 
             # self-cancel **all** ongoing RPC tasks
             await self.cancel_rpc_tasks(
-                req_uid=requesting_uid,
+                req_aid=requesting_aid,
                 parent_chan=None,
             )
 
@@ -1056,8 +1131,7 @@ class Actor:
         self,
         cid: str,
         parent_chan: Channel,
-        requesting_uid: tuple[str, str]|None,
+        requesting_aid: msgtypes.Aid|None,
-        # ^^TODO! use the `Aid` directly here!
 
         ipc_msg: dict|None|bool = False,
 
@@ -1095,7 +1169,7 @@ class Actor:
             log.runtime(
                 'Cancel request for invalid RPC task.\n'
                 'The task likely already completed or was never started!\n\n'
-                f'<= canceller: {requesting_uid}\n'
+                f'<= canceller: {requesting_aid}\n'
                 f'=> {cid}@{parent_chan.uid}\n'
                 f'  |_{parent_chan}\n'
             )
@@ -1103,7 +1177,7 @@ class Actor:
 
         log.cancel(
             'Rxed cancel request for RPC task\n'
-            f'{ctx._task!r} <=c) {requesting_uid}\n'
+            f'{ctx._task!r} <=c) {requesting_aid}\n'
             f'|_>> {ctx.repr_rpc}\n'
 
             # f'|_{ctx._task}\n'
@@ -1129,9 +1203,9 @@ class Actor:
         )
         if (
             ctx._canceller is None
-            and requesting_uid
+            and requesting_aid
         ):
-            ctx._canceller: tuple = requesting_uid
+            ctx._canceller: tuple = requesting_aid.uid
 
         # TODO: pack the RPC `{'cmd': <blah>}` msg into a ctxc and
         # then raise and pack it here?
@@ -1157,7 +1231,7 @@ class Actor:
 
         # wait for _invoke to mark the task complete
         flow_info: str = (
-            f'<= canceller: {requesting_uid}\n'
+            f'<= canceller: {requesting_aid}\n'
             f'=> ipc-parent: {parent_chan}\n'
             f'|_{ctx}\n'
         )
@@ -1174,7 +1248,7 @@ class Actor:
 
     async def cancel_rpc_tasks(
         self,
-        req_uid: tuple[str, str],
+        req_aid: msgtypes.Aid,
 
         # NOTE: when None is passed we cancel **all** rpc
         # tasks running in this actor!
@@ -1191,7 +1265,7 @@ class Actor:
         if not tasks:
             log.runtime(
                 'Actor has no cancellable RPC tasks?\n'
-                f'<= canceller: {req_uid}\n'
+                f'<= canceller: {req_aid.reprol()}\n'
             )
             return
 
@@ -1231,7 +1305,7 @@ class Actor:
         )
         log.cancel(
             f'Cancelling {descr} RPC tasks\n\n'
-            f'<=c) {req_uid} [canceller]\n'
+            f'<=c) {req_aid} [canceller]\n'
             f'{rent_chan_repr}'
             f'c)=> {self.uid} [cancellee]\n'
             f'  |_{self} [with {len(tasks)} tasks]\n'
@@ -1259,7 +1333,7 @@ class Actor:
             await self._cancel_task(
                 cid,
                 task_caller_chan,
-                requesting_uid=req_uid,
+                requesting_aid=req_aid,
             )
 
         if tasks:
@@ -1304,7 +1378,7 @@ class Actor:
         Return all IPC channels to the actor with provided `uid`.
 
         '''
-        return self._peers[uid]
+        return self._ipc_server._peers[uid]
 
     def is_infected_aio(self) -> bool:
         '''
@@ -1359,6 +1433,8 @@ async def async_main(
         # establish primary connection with immediate parent
         actor._parent_chan: Channel|None = None
 
+        # is this a sub-actor?
+        # get runtime info from parent.
         if parent_addr is not None:
             (
                 actor._parent_chan,
@@ -1403,10 +1479,8 @@ async def async_main(
 
             ipc_server: _server.IPCServer
             async with (
-                trio.open_nursery(
+                collapse_eg(),
-                    strict_exception_groups=False,
+                trio.open_nursery() as service_nursery,
-                ) as service_nursery,
-
                 _server.open_ipc_server(
                     parent_tn=service_nursery,
                     stream_handler_tn=service_nursery,
@@ -1457,9 +1531,6 @@ async def async_main(
 
                 # TODO: why is this not with the root nursery?
                 try:
-                    log.runtime(
-                        'Booting IPC server'
-                    )
                     eps: list = await ipc_server.listen_on(
                         accept_addrs=accept_addrs,
                         stream_handler_nursery=service_nursery,
@@ -1491,16 +1562,6 @@ async def async_main(
                 # TODO, just read direct from ipc_server?
                 accept_addrs: list[UnwrappedAddress] = actor.accept_addrs
 
-                # NOTE: only set the loopback addr for the 
-                # process-tree-global "root" mailbox since
-                # all sub-actors should be able to speak to
-                # their root actor over that channel.
-                if _state._runtime_vars['_is_root']:
-                    for addr in accept_addrs:
-                        waddr: Address = wrap_address(addr)
-                        if waddr == waddr.get_root():
-                            _state._runtime_vars['_root_mailbox'] = addr
-
                 # Register with the arbiter if we're told its addr
                 log.runtime(
                     f'Registering `{actor.name}` => {pformat(accept_addrs)}\n'
@@ -1518,6 +1579,7 @@ async def async_main(
                     except AssertionError:
                         await debug.pause()
 
+                    # !TODO, get rid of the local-portal crap XD
                     async with get_registry(addr) as reg_portal:
                         for accept_addr in accept_addrs:
                             accept_addr = wrap_address(accept_addr)
@@ -1554,8 +1616,9 @@ async def async_main(
                     # 'Blocking on service nursery to exit..\n'
                 )
             log.runtime(
-                "Service nursery complete\n"
+                'Service nursery complete\n'
-                "Waiting on root nursery to complete"
+                '\n'
+                '->} waiting on root nursery to complete..\n'
             )
 
         # Blocks here as expected until the root nursery is
@@ -1610,6 +1673,7 @@ async def async_main(
     finally:
         teardown_report: str = (
             'Main actor-runtime task completed\n'
+            '\n'
         )
 
         # ?TODO? should this be in `._entry`/`._root` mods instead?
@@ -1651,7 +1715,8 @@ async def async_main(
         # Unregister actor from the registry-sys / registrar.
         if (
             is_registered
-            and not actor.is_registrar
+            and
+            not actor.is_registrar
         ):
             failed: bool = False
             for addr in actor.reg_addrs:
@@ -1686,7 +1751,8 @@ async def async_main(
             ipc_server.has_peers(check_chans=True)
         ):
             teardown_report += (
-                f'-> Waiting for remaining peers {ipc_server._peers} to clear..\n'
+                f'-> Waiting for remaining peers to clear..\n'
+                f'   {pformat(ipc_server._peers)}'
             )
             log.runtime(teardown_report)
             await ipc_server.wait_for_no_more_peers(
@@ -1694,20 +1760,23 @@ async def async_main(
             )
 
         teardown_report += (
-            '-> All peer channels are complete\n'
+            '-]> all peer channels are complete.\n'
         )
 
-    op_nested_actor_repr: str = _pformat.nest_from_op(
+    # op_nested_actor_repr: str = _pformat.nest_from_op(
-        input_op=')> ',
+    #     input_op=')>',
-        tree_str=actor.pformat(),
+    #     text=actor.pformat(),
-        nest_prefix='|_',
+    #     nest_prefix='|_',
-        back_from_op=2,
+    #     nest_indent=1,  # under >
-    )
+    # )
     teardown_report += (
-        'Actor runtime exited\n'
+        '-)> actor runtime main task exit.\n'
-        f'{op_nested_actor_repr}\n'
+        # f'{op_nested_actor_repr}'
     )
-    log.info(teardown_report)
+    # if _state._runtime_vars['_is_root']:
+    #     log.info(teardown_report)
+    # else:
+    log.runtime(teardown_report)
 
 
 # TODO: rename to `Registry` and move to `.discovery._registry`!

tractor/_spawn.py

@@ -34,9 +34,9 @@ from typing import (
 import trio
 from trio import TaskStatus
 
-from .devx.debug import (
+from .devx import (
-    maybe_wait_for_debugger,
+    debug,
-    acquire_debug_lock,
+    pformat as _pformat
 )
 from tractor._state import (
     current_actor,
@@ -51,14 +51,17 @@ from tractor._portal import Portal
 from tractor._runtime import Actor
 from tractor._entry import _mp_main
 from tractor._exceptions import ActorFailure
-from tractor.msg.types import (
+from tractor.msg import (
-    Aid,
+    types as msgtypes,
-    SpawnSpec,
+    pretty_struct,
 )
 
 
 if TYPE_CHECKING:
-    from ipc import IPCServer
+    from ipc import (
+        _server,
+        Channel,
+    )
     from ._supervise import ActorNursery
     ProcessType = TypeVar('ProcessType', mp.Process, trio.Process)
 
@@ -233,10 +236,6 @@ async def hard_kill(
     # whilst also hacking on it XD
     # terminate_after: int = 99999,
 
-    # NOTE: for mucking with `.pause()`-ing inside the runtime
-    # whilst also hacking on it XD
-    # terminate_after: int = 99999,
-
 ) -> None:
     '''
     Un-gracefully terminate an OS level `trio.Process` after timeout.
@@ -328,20 +327,21 @@ async def soft_kill(
     see `.hard_kill()`).
 
     '''
-    peer_aid: Aid = portal.channel.aid
+    chan: Channel = portal.channel
+    peer_aid: msgtypes.Aid = chan.aid
     try:
         log.cancel(
             f'Soft killing sub-actor via portal request\n'
             f'\n'
-            f'(c=> {peer_aid}\n'
+            f'c)=> {peer_aid.reprol()}@[{chan.maddr}]\n'
-            f'  |_{proc}\n'
+            f'   |_{proc}\n'
         )
         # wait on sub-proc to signal termination
         await wait_func(proc)
 
     except trio.Cancelled:
         with trio.CancelScope(shield=True):
-            await maybe_wait_for_debugger(
+            await debug.maybe_wait_for_debugger(
                 child_in_debug=_runtime_vars.get(
                     '_debug_mode', False
                 ),
@@ -465,7 +465,7 @@ async def trio_proc(
         "--uid",
         # TODO, how to pass this over "wire" encodings like
         # cmdline args?
-        # -[ ] maybe we can add an `Aid.min_tuple()` ?
+        # -[ ] maybe we can add an `msgtypes.Aid.min_tuple()` ?
         str(subactor.uid),
         # Address the child must connect to on startup
         "--parent_addr",
@@ -483,13 +483,14 @@ async def trio_proc(
 
     cancelled_during_spawn: bool = False
     proc: trio.Process|None = None
-    ipc_server: IPCServer = actor_nursery._actor.ipc_server
+    ipc_server: _server.Server = actor_nursery._actor.ipc_server
     try:
         try:
             proc: trio.Process = await trio.lowlevel.open_process(spawn_cmd, **proc_kwargs)
             log.runtime(
-                'Started new child\n'
+                f'Started new child subproc\n'
-                f'|_{proc}\n'
+                f'(>\n'
+                f' |_{proc}\n'
             )
 
             # wait for actor to spawn and connect back to us
@@ -507,10 +508,10 @@ async def trio_proc(
                 with trio.CancelScope(shield=True):
                     # don't clobber an ongoing pdb
                     if is_root_process():
-                        await maybe_wait_for_debugger()
+                        await debug.maybe_wait_for_debugger()
 
                     elif proc is not None:
-                        async with acquire_debug_lock(subactor.uid):
+                        async with debug.acquire_debug_lock(subactor.uid):
                             # soft wait on the proc to terminate
                             with trio.move_on_after(0.5):
                                 await proc.wait()
@@ -528,14 +529,19 @@ async def trio_proc(
 
         # send a "spawning specification" which configures the
         # initial runtime state of the child.
-        sspec = SpawnSpec(
+        sspec = msgtypes.SpawnSpec(
             _parent_main_data=subactor._parent_main_data,
             enable_modules=subactor.enable_modules,
             reg_addrs=subactor.reg_addrs,
             bind_addrs=bind_addrs,
             _runtime_vars=_runtime_vars,
         )
-        log.runtime(f'Sending spawn spec: {str(sspec)}')
+        log.runtime(
+            f'Sending spawn spec to child\n'
+            f'{{}}=> {chan.aid.reprol()!r}\n'
+            f'\n'
+            f'{pretty_struct.pformat(sspec)}\n'
+        )
         await chan.send(sspec)
 
         # track subactor in current nursery
@@ -563,7 +569,7 @@ async def trio_proc(
             # condition.
             await soft_kill(
                 proc,
-                trio.Process.wait,
+                trio.Process.wait,  # XXX, uses `pidfd_open()` below.
                 portal
             )
 
@@ -571,8 +577,7 @@ async def trio_proc(
             # tandem if not done already
             log.cancel(
                 'Cancelling portal result reaper task\n'
-                f'>c)\n'
+                f'c)> {subactor.aid.reprol()!r}\n'
-                f' |_{subactor.uid}\n'
             )
             nursery.cancel_scope.cancel()
 
@@ -581,21 +586,24 @@ async def trio_proc(
         # allowed! Do this **after** cancellation/teardown to avoid
         # killing the process too early.
         if proc:
+            reap_repr: str = _pformat.nest_from_op(
+                input_op='>x)',
+                text=subactor.pformat(),
+            )
             log.cancel(
                 f'Hard reap sequence starting for subactor\n'
-                f'>x)\n'
+                f'{reap_repr}'
-                f' |_{subactor}@{subactor.uid}\n'
             )
 
             with trio.CancelScope(shield=True):
                 # don't clobber an ongoing pdb
                 if cancelled_during_spawn:
                     # Try again to avoid TTY clobbering.
-                    async with acquire_debug_lock(subactor.uid):
+                    async with debug.acquire_debug_lock(subactor.uid):
                         with trio.move_on_after(0.5):
                             await proc.wait()
 
-                await maybe_wait_for_debugger(
+                await debug.maybe_wait_for_debugger(
                     child_in_debug=_runtime_vars.get(
                         '_debug_mode', False
                     ),
@@ -624,7 +632,7 @@ async def trio_proc(
                 #     acquire the lock and get notified of who has it,
                 #     check that uid against our known children?
                 # this_uid: tuple[str, str] = current_actor().uid
-                # await acquire_debug_lock(this_uid)
+                # await debug.acquire_debug_lock(this_uid)
 
                 if proc.poll() is None:
                     log.cancel(f"Attempting to hard kill {proc}")
@@ -727,7 +735,7 @@ async def mp_proc(
 
     log.runtime(f"Started {proc}")
 
-    ipc_server: IPCServer = actor_nursery._actor.ipc_server
+    ipc_server: _server.Server = actor_nursery._actor.ipc_server
     try:
         # wait for actor to spawn and connect back to us
         # channel should have handshake completed by the

tractor/_state.py

@@ -37,6 +37,13 @@ if TYPE_CHECKING:
     from ._context import Context
 
 
+# default IPC transport protocol settings
+TransportProtocolKey = Literal[
+    'tcp',
+    'uds',
+]
+_def_tpt_proto: TransportProtocolKey = 'tcp'
+
 _current_actor: Actor|None = None  # type: ignore # noqa
 _last_actor_terminated: Actor|None = None
 
@@ -47,6 +54,10 @@ _runtime_vars: dict[str, Any] = {
     # root of actor-process tree info
     '_is_root': False,  # bool
     '_root_mailbox': (None, None),  # tuple[str|None, str|None]
+    '_root_addrs': [],  # tuple[str|None, str|None]
+
+    # parent->chld ipc protocol caps
+    '_enable_tpts': [_def_tpt_proto],
 
     # registrar info
     '_registry_addrs': [],
@@ -180,14 +191,6 @@ def get_rt_dir(
     return rtdir
 
 
-# default IPC transport protocol settings
-TransportProtocolKey = Literal[
-    'tcp',
-    'uds',
-]
-_def_tpt_proto: TransportProtocolKey = 'tcp'
-
-
 def current_ipc_protos() -> list[str]:
     '''
     Return the list of IPC transport protocol keys currently
@@ -197,4 +200,4 @@ def current_ipc_protos() -> list[str]:
     concrete-backend sub-types defined throughout `tractor.ipc`.
 
     '''
-    return [_def_tpt_proto]
+    return _runtime_vars['_enable_tpts']

tractor/_supervise.py

@@ -21,7 +21,6 @@
 from contextlib import asynccontextmanager as acm
 from functools import partial
 import inspect
-from pprint import pformat
 from typing import (
     TYPE_CHECKING,
 )
@@ -31,7 +30,10 @@ import warnings
 import trio
 
 
-from .devx.debug import maybe_wait_for_debugger
+from .devx import (
+    debug,
+    pformat as _pformat,
+)
 from ._addr import (
     UnwrappedAddress,
     mk_uuid,
@@ -200,7 +202,7 @@ class ActorNursery:
             loglevel=loglevel,
 
             # verbatim relay this actor's registrar addresses
-            registry_addrs=current_actor().reg_addrs,
+            registry_addrs=current_actor().registry_addrs,
         )
         parent_addr: UnwrappedAddress = self._actor.accept_addr
         assert parent_addr
@@ -454,7 +456,7 @@ async def _open_and_supervise_one_cancels_all_nursery(
                     # the "hard join phase".
                     log.runtime(
                         'Waiting on subactors to complete:\n'
-                        f'{pformat(an._children)}\n'
+                        f'>}} {len(an._children)}\n'
                     )
                     an._join_procs.set()
 
@@ -468,7 +470,7 @@ async def _open_and_supervise_one_cancels_all_nursery(
                     # will make the pdb repl unusable.
                     # Instead try to wait for pdb to be released before
                     # tearing down.
-                    await maybe_wait_for_debugger(
+                    await debug.maybe_wait_for_debugger(
                         child_in_debug=an._at_least_one_child_in_debug
                     )
 
@@ -544,7 +546,7 @@ async def _open_and_supervise_one_cancels_all_nursery(
 
             # XXX: yet another guard before allowing the cancel
             # sequence in case a (single) child is in debug.
-            await maybe_wait_for_debugger(
+            await debug.maybe_wait_for_debugger(
                 child_in_debug=an._at_least_one_child_in_debug
             )
 
@@ -593,6 +595,11 @@ async def _open_and_supervise_one_cancels_all_nursery(
     # final exit
 
 
+_shutdown_msg: str = (
+    'Actor-runtime-shutdown'
+)
+
+
 @acm
 # @api_frame
 async def open_nursery(
@@ -680,17 +687,26 @@ async def open_nursery(
         ):
             __tracebackhide__: bool = False
 
-        msg: str = (
+
-            'Actor-nursery exited\n'
+        op_nested_an_repr: str = _pformat.nest_from_op(
-            f'|_{an}\n'
+            input_op=')>',
+            text=f'{an}',
+            # nest_prefix='|_',
+            nest_indent=1,  # under >
         )
+        an_msg: str = (
+            f'Actor-nursery exited\n'
+            f'{op_nested_an_repr}\n'
+        )
+        # keep noise low during std operation.
+        log.runtime(an_msg)
 
         if implicit_runtime:
             # shutdown runtime if it was started and report noisly
             # that we're did so.
-            msg += '=> Shutting down actor runtime <=\n'
+            msg: str = (
+                '\n'
+                '\n'
+                f'{_shutdown_msg} )>\n'
+            )
             log.info(msg)
-
-        else:
-            # keep noise low during std operation.
-            log.runtime(msg)

tractor/devx/_stackscope.py

@@ -237,9 +237,9 @@ def enable_stack_on_sig(
     try:
         import stackscope
     except ImportError:
-        log.error(
+        log.warning(
-            '`stackscope` not installed for use in debug mode!\n'
+            'The `stackscope` lib is not installed!\n'
-            '`Ignoring {enable_stack_on_sig!r} call!\n'
+            '`Ignoring enable_stack_on_sig() call!\n'
         )
         return None
 

tractor/devx/debug/_post_mortem.py

@@ -148,59 +148,61 @@ def _post_mortem(
         repl_fixture=repl_fixture,
         boxed_maybe_exc=boxed_maybe_exc,
     )
-    if not enter_repl:
-        return
     try:
-        actor: Actor = current_actor()
+        if not enter_repl:
-        actor_repr: str = str(actor.uid)
+            # XXX, trigger `.release()` below immediately!
-        # ^TODO, instead a nice runtime-info + maddr + uid?
+            return
-        # -[ ] impl a `Actor.__repr()__`??
+        try:
-        #  |_ <task>:<thread> @ <actor>
+            actor: Actor = current_actor()
+            actor_repr: str = str(actor.uid)
+            # ^TODO, instead a nice runtime-info + maddr + uid?
+            # -[ ] impl a `Actor.__repr()__`??
+            #  |_ <task>:<thread> @ <actor>
 
-    except NoRuntime:
+        except NoRuntime:
-        actor_repr: str = '<no-actor-runtime?>'
+            actor_repr: str = '<no-actor-runtime?>'
 
-    try:
+        try:
-        task_repr: Task = trio.lowlevel.current_task()
+            task_repr: Task = trio.lowlevel.current_task()
-    except RuntimeError:
+        except RuntimeError:
-        task_repr: str = '<unknown-Task>'
+            task_repr: str = '<unknown-Task>'
 
-    # TODO: print the actor supervion tree up to the root
+        # TODO: print the actor supervion tree up to the root
-    # here! Bo
+        # here! Bo
-    log.pdb(
+        log.pdb(
-        f'{_crash_msg}\n'
+            f'{_crash_msg}\n'
-        f'x>(\n'
+            f'x>(\n'
-        f' |_ {task_repr} @ {actor_repr}\n'
+            f' |_ {task_repr} @ {actor_repr}\n'
 
-    )
+        )
 
-    # XXX NOTE(s) on `pdbp.xpm()` version..
+        # XXX NOTE(s) on `pdbp.xpm()` version..
-    #
+        #
-    # - seems to lose the up-stack tb-info?
+        # - seems to lose the up-stack tb-info?
-    # - currently we're (only) replacing this from `pdbp.xpm()`
+        # - currently we're (only) replacing this from `pdbp.xpm()`
-    #   to add the `end=''` to the print XD
+        #   to add the `end=''` to the print XD
-    #
+        #
-    print(traceback.format_exc(), end='')
+        print(traceback.format_exc(), end='')
-    caller_frame: FrameType = api_frame.f_back
+        caller_frame: FrameType = api_frame.f_back
 
-    # NOTE, see the impl details of these in the lib to
+        # NOTE, see the impl details of these in the lib to
-    # understand usage:
+        # understand usage:
-    # - `pdbp.post_mortem()`
+        # - `pdbp.post_mortem()`
-    # - `pdbp.xps()`
+        # - `pdbp.xps()`
-    # - `bdb.interaction()`
+        # - `bdb.interaction()`
-    repl.reset()
+        repl.reset()
-    repl.interaction(
+        repl.interaction(
-        frame=caller_frame,
+            frame=caller_frame,
-        # frame=None,
+            # frame=None,
-        traceback=tb,
+            traceback=tb,
-    )
+        )
-
+    finally:
-    # XXX NOTE XXX: this is abs required to avoid hangs!
+        # XXX NOTE XXX: this is abs required to avoid hangs!
-    #
+        #
-    # Since we presume the post-mortem was enaged to
+        # Since we presume the post-mortem was enaged to
-    # a task-ending error, we MUST release the local REPL request
+        # a task-ending error, we MUST release the local REPL request
-    # so that not other local task nor the root remains blocked!
+        # so that not other local task nor the root remains blocked!
-    DebugStatus.release()
+        DebugStatus.release()
 
 
 async def post_mortem(

tractor/devx/debug/_tty_lock.py

@@ -846,9 +846,9 @@ class DebugStatus:
 
         '''
         if not (
-            repl_fixture
-            or
             (rt_repl_fixture := _state._runtime_vars.get('repl_fixture'))
+            or
+            repl_fixture
         ):
             return True  # YES always enter
 

tractor/devx/pformat.py

@@ -15,8 +15,10 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 '''
-Pretty formatters for use throughout the code base.
+Pretty formatters for use throughout our internals.
-Mostly handy for logging and exception message content.
+
+Handy for logging and exception message content but also for `repr()`
+in REPL(s).
 
 '''
 import sys
@@ -224,8 +226,8 @@ def pformat_cs(
     field_prefix: str = ' |_',
 ) -> str:
     '''
-    Pretty format info about a `trio.CancelScope` including most
+    Pretty format info about a `trio.CancelScope` including most of
-    of its public state and `._cancel_status`.
+    its public state and `._cancel_status`.
 
     The output can be modified to show a "var name" for the
     instance as a field prefix, just a simple str before each
@@ -249,14 +251,33 @@ def pformat_cs(
     )
 
 
-# TODO: move this func to some kinda `.devx.pformat.py` eventually
-# as we work out our multi-domain state-flow-syntax!
 def nest_from_op(
-    input_op: str,
+    input_op: str,  # TODO, Literal of all op-"symbols" from below?
+    text: str,
+    prefix_op: bool = True,  # unset is to suffix the first line
+    # optionally suffix `text`, by def on a newline
+    op_suffix='\n',
+
+    nest_prefix: str = '|_',
+    nest_indent: int|None = None,
+    # XXX indent `next_prefix` "to-the-right-of" `input_op`
+    # by this count of whitespaces (' ').
+    rm_from_first_ln: str|None = None,
+
+) -> str:
+    '''
+    Depth-increment the input (presumably hierarchy/supervision)
+    input "tree string" below the provided `input_op` execution
+    operator, so injecting a `"\n|_{input_op}\n"`and indenting the
+    `tree_str` to nest content aligned with the ops last char.
+
+    '''
+    # `sclang` "structurred-concurrency-language": an ascii-encoded
+    # symbolic alphabet to describe concurrent systems.
     #
-    # ?TODO? an idea for a syntax to the state of concurrent systems
+    # ?TODO? aa more fomal idea for a syntax to the state of
-    # as a "3-domain" (execution, scope, storage) model and using
+    # concurrent systems as a "3-domain" (execution, scope, storage)
-    # a minimal ascii/utf-8 operator-set.
+    # model and using a minimal ascii/utf-8 operator-set.
     #
     # try not to take any of this seriously yet XD
     #
@@ -322,38 +343,185 @@ def nest_from_op(
     #
     # =>{  recv-req to open
     # <={  send-status that it closed
+    #
+    if (
+        nest_prefix
+        and
+        nest_indent != 0
+    ):
+        if nest_indent is not None:
+            nest_prefix: str = textwrap.indent(
+                nest_prefix,
+                prefix=nest_indent*' ',
+            )
+        nest_indent: int = len(nest_prefix)
 
-    tree_str: str,
+    # determine body-text indent either by,
+    # - using wtv explicit indent value is provided,
+    # OR
+    # - auto-calcing the indent to embed `text` under
+    #   the `nest_prefix` if provided, **IFF** `nest_indent=None`.
+    tree_str_indent: int = 0
+    if nest_indent not in {0, None}:
+        tree_str_indent = nest_indent
+    elif (
+        nest_prefix
+        and
+        nest_indent != 0
+    ):
+        tree_str_indent = len(nest_prefix)
 
-    # NOTE: so move back-from-the-left of the `input_op` by
+    indented_tree_str: str = text
-    # this amount.
+    if tree_str_indent:
-    back_from_op: int = 0,
+        indented_tree_str: str = textwrap.indent(
-    nest_prefix: str = ''
+            text,
+            prefix=' '*tree_str_indent,
+        )
 
-) -> str:
-    '''
-    Depth-increment the input (presumably hierarchy/supervision)
-    input "tree string" below the provided `input_op` execution
-    operator, so injecting a `"\n|_{input_op}\n"`and indenting the
-    `tree_str` to nest content aligned with the ops last char.
-
-    '''
-    indented_tree_str: str = textwrap.indent(
-        tree_str,
-        prefix=' ' *(
-            len(input_op)
-            -
-            (back_from_op + 1)
-        ),
-    )
     # inject any provided nesting-prefix chars
     # into the head of the first line.
     if nest_prefix:
         indented_tree_str: str = (
-            f'{nest_prefix}'
+            f'{nest_prefix}{indented_tree_str[tree_str_indent:]}'
-            f'{indented_tree_str[len(nest_prefix):]}'
         )
-    return (
+
-        f'{input_op}\n'
+    if (
-        f'{indented_tree_str}'
+        not prefix_op
+        or
+        rm_from_first_ln
+    ):
+        tree_lns: list[str] = indented_tree_str.splitlines()
+        first: str = tree_lns[0]
+        if rm_from_first_ln:
+            first = first.strip().replace(
+                rm_from_first_ln,
+                '',
+            )
+        indented_tree_str: str = '\n'.join(tree_lns[1:])
+
+        if prefix_op:
+            indented_tree_str = (
+                f'{first}\n'
+                f'{indented_tree_str}'
+            )
+
+    if prefix_op:
+        return (
+            f'{input_op}{op_suffix}'
+            f'{indented_tree_str}'
+        )
+    else:
+        return (
+            f'{first}{input_op}{op_suffix}'
+            f'{indented_tree_str}'
+        )
+
+
+# ------ modden.repr ------
+# XXX originally taken verbaatim from `modden.repr`
+'''
+More "multi-line" representation then the stdlib's `pprint` equivs.
+
+'''
+from inspect import (
+    FrameInfo,
+    stack,
+)
+import pprint
+import reprlib
+from typing import (
+    Callable,
+)
+
+
+def mk_repr(
+    **repr_kws,
+) -> Callable[[str], str]:
+    '''
+    Allocate and deliver a `repr.Repr` instance with provided input
+    settings using the std-lib's `reprlib` mod,
+     * https://docs.python.org/3/library/reprlib.html
+
+    ------ Ex. ------
+    An up to 6-layer-nested `dict` as multi-line:
+    - https://stackoverflow.com/a/79102479
+    - https://docs.python.org/3/library/reprlib.html#reprlib.Repr.maxlevel
+
+    '''
+    def_kws: dict[str, int] = dict(
+        indent=3,  # indent used for repr of recursive objects
+        maxlevel=616,  # recursion levels
+        maxdict=616,  # max items shown for `dict`
+        maxlist=616,  # max items shown for `dict`
+        maxstring=616,  # match editor line-len limit
+        maxtuple=616,  # match editor line-len limit
+        maxother=616,  # match editor line-len limit
     )
+    def_kws |= repr_kws
+    reprr = reprlib.Repr(**def_kws)
+    return reprr.repr
+
+
+def ppfmt(
+    obj: object,
+    do_print: bool = False,
+) -> str:
+    '''
+    The `pprint.pformat()` version of `pprint.pp()`, namely
+    a default `sort_dicts=False`.. (which i think should be
+    the normal default in the stdlib).
+
+    '''
+    pprepr: Callable = mk_repr()
+    repr_str: str = pprepr(obj)
+
+    if do_print:
+        return pprint.pp(repr_str)
+
+    return repr_str
+
+
+pformat = ppfmt
+
+
+def pfmt_frame_info(fi: FrameInfo) -> str:
+    '''
+    Like a std `inspect.FrameInfo.__repr__()` but multi-line..
+
+    '''
+    return (
+        'FrameInfo(\n'
+        '  frame={!r},\n'
+        '  filename={!r},\n'
+        '  lineno={!r},\n'
+        '  function={!r},\n'
+        '  code_context={!r},\n'
+        '  index={!r},\n'
+        '  positions={!r})'
+        ).format(
+            fi.frame,
+            fi.filename,
+            fi.lineno,
+            fi.function,
+            fi.code_context,
+            fi.index,
+            fi.positions
+        )
+
+
+def pfmt_callstack(frames: int = 1) -> str:
+    '''
+    Generate a string of nested `inspect.FrameInfo` objects returned
+    from a `inspect.stack()` call such that only the `.frame` field
+    for each  layer is pprinted.
+
+    '''
+    caller_frames: list[FrameInfo] =  stack()[1:1+frames]
+    frames_str: str = ''
+    for i, frame_info in enumerate(caller_frames):
+        frames_str += textwrap.indent(
+            f'{frame_info.frame!r}\n',
+            prefix=' '*i,
+
+        )
+    return frames_str

tractor/ipc/_chan.py

@@ -171,11 +171,23 @@ class Channel:
         )
         assert transport.raddr == addr
         chan = Channel(transport=transport)
-        log.runtime(
+
-            f'Connected channel IPC transport\n'
+        # ?TODO, compact this into adapter level-methods?
-            f'[>\n'
+        # -[ ] would avoid extra repr-calcs if level not active?
-            f' |_{chan}\n'
+        #   |_ how would the `calc_if_level` look though? func?
-        )
+        if log.at_least_level('runtime'):
+            from tractor.devx import (
+                pformat as _pformat,
+            )
+            chan_repr: str = _pformat.nest_from_op(
+                input_op='[>',
+                text=chan.pformat(),
+                nest_indent=1,
+            )
+            log.runtime(
+                f'Connected channel IPC transport\n'
+                f'{chan_repr}'
+            )
         return chan
 
     @cm
@@ -196,9 +208,12 @@ class Channel:
             self._transport.codec = orig
 
     # TODO: do a .src/.dst: str for maddrs?
-    def pformat(self) -> str:
+    def pformat(
+        self,
+        privates: bool = False,
+    ) -> str:
         if not self._transport:
-            return '<Channel with inactive transport?>'
+            return '<Channel( with inactive transport? )>'
 
         tpt: MsgTransport = self._transport
         tpt_name: str = type(tpt).__name__
@@ -206,26 +221,35 @@ class Channel:
             'connected' if self.connected()
             else 'closed'
         )
-        return (
+        repr_str: str = (
             f'<Channel(\n'
             f' |_status: {tpt_status!r}\n'
+        ) + (
             f'   _closed={self._closed}\n'
             f'   _cancel_called={self._cancel_called}\n'
-            f'\n'
+            if privates else ''
-            f' |_peer: {self.aid}\n'
+        ) + (  # peer-actor (processs) section
-            f'\n'
+            f' |_peer: {self.aid.reprol()!r}\n'
+            if self.aid else ' |_peer: <unknown>\n'
+        ) + (
             f' |_msgstream: {tpt_name}\n'
-            f'   proto={tpt.laddr.proto_key!r}\n'
+            f'   maddr: {tpt.maddr!r}\n'
-            f'   layer={tpt.layer_key!r}\n'
+            f'   proto: {tpt.laddr.proto_key!r}\n'
-            f'   laddr={tpt.laddr}\n'
+            f'   layer: {tpt.layer_key!r}\n'
-            f'   raddr={tpt.raddr}\n'
+            f'   codec: {tpt.codec_key!r}\n'
-            f'   codec={tpt.codec_key!r}\n'
+            f'   .laddr={tpt.laddr}\n'
-            f'   stream={tpt.stream}\n'
+            f'   .raddr={tpt.raddr}\n'
-            f'   maddr={tpt.maddr!r}\n'
+        ) + (
-            f'   drained={tpt.drained}\n'
+            f'   ._transport.stream={tpt.stream}\n'
+            f'   ._transport.drained={tpt.drained}\n'
+            if privates else ''
+        ) + (
             f'   _send_lock={tpt._send_lock.statistics()}\n'
-            f')>\n'
+            if privates else ''
+        ) + (
+            ')>\n'
         )
+        return repr_str
 
     # NOTE: making this return a value that can be passed to
     # `eval()` is entirely **optional** FYI!
@@ -247,6 +271,10 @@ class Channel:
     def raddr(self) -> Address|None:
         return self._transport.raddr if self._transport else None
 
+    @property
+    def maddr(self) -> str:
+        return self._transport.maddr if self._transport else '<no-tpt>'
+
     # TODO: something like,
     # `pdbp.hideframe_on(errors=[MsgTypeError])`
     # instead of the `try/except` hack we have rn..
@@ -434,8 +462,8 @@ class Channel:
         await self.send(aid)
         peer_aid: Aid = await self.recv()
         log.runtime(
-            f'Received hanshake with peer actor,\n'
+            f'Received hanshake with peer\n'
-            f'{peer_aid}\n'
+            f'<= {peer_aid.reprol(sin_uuid=False)}\n'
         )
         # NOTE, we always are referencing the remote peer!
         self.aid = peer_aid

tractor/ipc/_server.py

@@ -26,7 +26,7 @@ from contextlib import (
 from functools import partial
 from itertools import chain
 import inspect
-from pprint import pformat
+import textwrap
 from types import (
     ModuleType,
 )
@@ -43,7 +43,10 @@ from trio import (
     SocketListener,
 )
 
-# from ..devx import debug
+from ..devx.pformat import (
+    ppfmt,
+    nest_from_op,
+)
 from .._exceptions import (
     TransportClosed,
 )
@@ -141,9 +144,8 @@ async def maybe_wait_on_canced_subs(
 
     ):
         log.cancel(
-            'Waiting on cancel request to peer..\n'
+            'Waiting on cancel request to peer\n'
-            f'c)=>\n'
+            f'c)=> {chan.aid.reprol()}@[{chan.maddr}]\n'
-            f'  |_{chan.aid}\n'
         )
 
         # XXX: this is a soft wait on the channel (and its
@@ -179,7 +181,7 @@ async def maybe_wait_on_canced_subs(
                 log.warning(
                     'Draining msg from disconnected peer\n'
                     f'{chan_info}'
-                    f'{pformat(msg)}\n'
+                    f'{ppfmt(msg)}\n'
                 )
                 # cid: str|None = msg.get('cid')
                 cid: str|None = msg.cid
@@ -248,7 +250,7 @@ async def maybe_wait_on_canced_subs(
                 if children := local_nursery._children:
                     # indent from above local-nurse repr
                     report += (
-                        f'   |_{pformat(children)}\n'
+                        f'   |_{ppfmt(children)}\n'
                     )
 
                 log.warning(report)
@@ -279,8 +281,9 @@ async def maybe_wait_on_canced_subs(
                     log.runtime(
                         f'Peer IPC broke but subproc is alive?\n\n'
 
-                        f'<=x {chan.aid}@{chan.raddr}\n'
+                        f'<=x {chan.aid.reprol()}@[{chan.maddr}]\n'
-                        f'   |_{proc}\n'
+                        f'\n'
+                        f'{proc}\n'
                     )
 
     return local_nursery
@@ -289,7 +292,7 @@ async def maybe_wait_on_canced_subs(
 #
 # -[x] maybe change to mod-func and rename for implied
 #    multi-transport semantics?
-# -[ ] register each stream/tpt/chan with the owning `IPCEndpoint`
+# -[ ] register each stream/tpt/chan with the owning `Endpoint`
 #     so that we can query per tpt all peer contact infos?
 #  |_[ ] possibly provide a global viewing via a
 #        `collections.ChainMap`?
@@ -309,7 +312,7 @@ async def handle_stream_from_peer(
     any `IPCServer.listen_on()` passed `stream_handler_tn: Nursery`
     such that it is invoked as,
 
-      IPCEndpoint.stream_handler_tn.start_soon(
+      Endpoint.stream_handler_tn.start_soon(
           handle_stream,
           stream,
       )
@@ -324,9 +327,10 @@ async def handle_stream_from_peer(
 
     chan = Channel.from_stream(stream)
     con_status: str = (
-        'New inbound IPC connection <=\n'
+        f'New inbound IPC transport connection\n'
-        f'|_{chan}\n'
+        f'<=( {stream!r}\n'
     )
+    con_status_steps: str = ''
 
     # initial handshake with peer phase
     try:
@@ -372,7 +376,7 @@ async def handle_stream_from_peer(
     if _pre_chan := server._peers.get(uid):
         familiar: str = 'pre-existing-peer'
     uid_short: str = f'{uid[0]}[{uid[1][-6:]}]'
-    con_status += (
+    con_status_steps += (
         f' -> Handshake with {familiar} `{uid_short}` complete\n'
     )
 
@@ -397,7 +401,7 @@ async def handle_stream_from_peer(
         None,
     )
     if event:
-        con_status += (
+        con_status_steps += (
             ' -> Waking subactor spawn waiters: '
             f'{event.statistics().tasks_waiting}\n'
             f' -> Registered IPC chan for child actor {uid}@{chan.raddr}\n'
@@ -408,7 +412,7 @@ async def handle_stream_from_peer(
         event.set()
 
     else:
-        con_status += (
+        con_status_steps += (
             f' -> Registered IPC chan for peer actor {uid}@{chan.raddr}\n'
         )  # type: ignore
 
@@ -422,8 +426,15 @@ async def handle_stream_from_peer(
     # TODO: can we just use list-ref directly?
     chans.append(chan)
 
-    con_status += ' -> Entering RPC msg loop..\n'
+    con_status_steps += ' -> Entering RPC msg loop..\n'
-    log.runtime(con_status)
+    log.runtime(
+        con_status
+        +
+        textwrap.indent(
+            con_status_steps,
+            prefix=' '*3,  # align to first-ln
+        )
+    )
 
     # Begin channel management - respond to remote requests and
     # process received reponses.
@@ -456,41 +467,67 @@ async def handle_stream_from_peer(
             disconnected=disconnected,
         )
 
-        # ``Channel`` teardown and closure sequence
+        # `Channel` teardown and closure sequence
         # drop ref to channel so it can be gc-ed and disconnected
-        con_teardown_status: str = (
+        #
-            f'IPC channel disconnected:\n'
+        # -[x]TODO mk this be like
-            f'<=x uid: {chan.aid}\n'
+        # <=x Channel(
-            f'   |_{pformat(chan)}\n\n'
+        #     |_field: blah
+        # )>
+        op_repr: str = '<=x '
+        chan_repr: str = nest_from_op(
+            input_op=op_repr,
+            op_suffix='',
+            nest_prefix='',
+            text=chan.pformat(),
+            nest_indent=len(op_repr)-1,
+            rm_from_first_ln='<',
         )
+
+        con_teardown_status: str = (
+            f'IPC channel disconnect\n'
+            f'\n'
+            f'{chan_repr}\n'
+            f'\n'
+        )
+
         chans.remove(chan)
 
         # TODO: do we need to be this pedantic?
         if not chans:
             con_teardown_status += (
-                f'-> No more channels with {chan.aid}'
+                f'-> No more channels with {chan.aid.reprol()!r}\n'
             )
             server._peers.pop(uid, None)
 
-        peers_str: str = ''
+        if peers := list(server._peers.values()):
-        for uid, chans in server._peers.items():
+            peer_cnt: int = len(peers)
-            peers_str += (
+            if (
-                f'uid: {uid}\n'
+                (first := peers[0][0]) is not chan
-            )
+                and
-            for i, chan in enumerate(chans):
+                not disconnected
-                peers_str += (
+                and
-                    f' |_[{i}] {pformat(chan)}\n'
+                peer_cnt > 1
+            ):
+                con_teardown_status += (
+                    f'-> Remaining IPC {peer_cnt-1!r} peers:\n'
                 )
-
+                for chans in server._peers.values():
-        con_teardown_status += (
+                    first: Channel = chans[0]
-            f'-> Remaining IPC {len(server._peers)} peers: {peers_str}\n'
+                    if not (
-        )
+                        first is chan
+                        and
+                        disconnected
+                    ):
+                        con_teardown_status += (
+                            f'  |_{first.aid.reprol()!r} -> {len(chans)!r} chans\n'
+                        )
 
         # No more channels to other actors (at all) registered
         # as connected.
         if not server._peers:
             con_teardown_status += (
-                'Signalling no more peer channel connections'
+                '-> Signalling no more peer connections!\n'
             )
             server._no_more_peers.set()
 
@@ -577,12 +614,12 @@ async def handle_stream_from_peer(
     # finally block closure
 
 
-class IPCEndpoint(Struct):
+class Endpoint(Struct):
     '''
-    An instance of an IPC "bound" address where the lifetime of the
+    An instance of an IPC "bound" address where the lifetime of an
-    "ability to accept connections" (from clients) and then handle
+    "ability to accept connections" and handle the subsequent
-    those inbound sessions or sequences-of-packets is determined by
+    sequence-of-packets (maybe oriented as sessions) is determined by
-    a (maybe pair of) nurser(y/ies).
+    the underlying nursery scope(s).
 
     '''
     addr: Address
@@ -600,6 +637,24 @@ class IPCEndpoint(Struct):
         MsgTransport,  # handle to encoded-msg transport stream
     ] = {}
 
+    def pformat(
+        self,
+        indent: int = 0,
+        privates: bool = False,
+    ) -> str:
+        type_repr: str = type(self).__name__
+        fmtstr: str = (
+            # !TODO, always be ns aware!
+            # f'|_netns: {netns}\n'
+            f' |.addr: {self.addr!r}\n'
+            f' |_peers: {len(self.peer_tpts)}\n'
+        )
+        return (
+            f'<{type_repr}(\n'
+            f'{fmtstr}'
+            f')>'
+        )
+
     async def start_listener(self) -> SocketListener:
         tpt_mod: ModuleType = inspect.getmodule(self.addr)
         lstnr: SocketListener = await tpt_mod.start_listener(
@@ -636,35 +691,43 @@ class IPCEndpoint(Struct):
         )
 
 
-class IPCServer(Struct):
+class Server(Struct):
     _parent_tn: Nursery
     _stream_handler_tn: Nursery
+
     # level-triggered sig for whether "no peers are currently
     # connected"; field is **always** set to an instance but
     # initialized with `.is_set() == True`.
     _no_more_peers: trio.Event
 
-    _endpoints: list[IPCEndpoint] = []
+    # active eps as allocated by `.listen_on()`
+    _endpoints: list[Endpoint] = []
 
     # connection tracking & mgmt
     _peers: defaultdict[
         str,  # uaid
         list[Channel],  # IPC conns from peer
     ] = defaultdict(list)
+
+    # events-table with entries registered unset while the local
+    # actor is waiting on a new actor to inbound connect, often
+    # a parent waiting on its child just after spawn.
     _peer_connected: dict[
         tuple[str, str],
         trio.Event,
     ] = {}
 
     # syncs for setup/teardown sequences
+    # - null when not yet booted,
+    # - unset when active,
+    # - set when fully shutdown with 0 eps active.
     _shutdown: trio.Event|None = None
 
-    # TODO, maybe just make `._endpoints: list[IPCEndpoint]` and
+    # TODO, maybe just make `._endpoints: list[Endpoint]` and
     # provide dict-views onto it?
     # @property
-    # def addrs2eps(self) -> dict[Address, IPCEndpoint]:
+    # def addrs2eps(self) -> dict[Address, Endpoint]:
     #     ...
-
     @property
     def proto_keys(self) -> list[str]:
         return [
@@ -690,7 +753,7 @@ class IPCServer(Struct):
             # TODO: obvi a different server type when we eventually
             # support some others XD
             log.runtime(
-                f'Cancelling server(s) for\n'
+                f'Cancelling server(s) for tpt-protos\n'
                 f'{self.proto_keys!r}\n'
             )
             self._parent_tn.cancel_scope.cancel()
@@ -708,7 +771,7 @@ class IPCServer(Struct):
             await self._shutdown.wait()
         else:
             tpt_protos: list[str] = []
-            ep: IPCEndpoint
+            ep: Endpoint
             for ep in self._endpoints:
                 tpt_protos.append(ep.addr.proto_key)
 
@@ -717,6 +780,14 @@ class IPCServer(Struct):
                 f'protos: {tpt_protos!r}\n'
             )
 
+    def len_peers(
+        self,
+    ) -> int:
+        return len([
+            chan.connected()
+            for chan in chain(*self._peers.values())
+        ])
+
     def has_peers(
         self,
         check_chans: bool = False,
@@ -730,13 +801,11 @@ class IPCServer(Struct):
             has_peers
             and
             check_chans
+            and
+            (peer_cnt := self.len_peers())
         ):
             has_peers: bool = (
-                any(chan.connected()
+                peer_cnt > 0
-                    for chan in chain(
-                        *self._peers.values()
-                    )
-                )
                 and
                 has_peers
             )
@@ -790,7 +859,7 @@ class IPCServer(Struct):
 
     def epsdict(self) -> dict[
         Address,
-        IPCEndpoint,
+        Endpoint,
     ]:
         return {
             ep.addr: ep
@@ -803,30 +872,66 @@ class IPCServer(Struct):
 
         return ev.is_set()
 
-    def pformat(self) -> str:
+    @property
-        eps: list[IPCEndpoint] = self._endpoints
+    def repr_state(self) -> str:
+        '''
+        A `str`-status describing the current state of this
+        IPC server in terms of the current operating "phase".
 
-        state_repr: str = (
+        '''
-            f'{len(eps)!r} IPC-endpoints active'
+        status = 'server is active'
-        )
+        if self.has_peers():
+            peer_cnt: int = self.len_peers()
+            status: str = (
+                f'{peer_cnt!r} peer chans'
+            )
+        else:
+            status: str = 'No peer chans'
+
+        if self.is_shutdown():
+            status: str = 'server-shutdown'
+
+        return status
+
+    def pformat(
+        self,
+        privates: bool = False,
+    ) -> str:
+        eps: list[Endpoint] = self._endpoints
+
+        # state_repr: str = (
+        #     f'{len(eps)!r} endpoints active'
+        # )
         fmtstr = (
-            f' |_state: {state_repr}\n'
+            f' |_state: {self.repr_state!r}\n'
-            f'   no_more_peers: {self.has_peers()}\n'
         )
-        if self._shutdown is not None:
+        if privates:
-            shutdown_stats: EventStatistics = self._shutdown.statistics()
+            fmtstr += f'   no_more_peers: {self.has_peers()}\n'
+
+            if self._shutdown is not None:
+                shutdown_stats: EventStatistics = self._shutdown.statistics()
+                fmtstr += (
+                    f'   task_waiting_on_shutdown: {shutdown_stats}\n'
+                )
+
+        if eps := self._endpoints:
+            addrs: list[tuple] = [
+                ep.addr for ep in eps
+            ]
+            repr_eps: str = ppfmt(addrs)
+
             fmtstr += (
-                f'   task_waiting_on_shutdown: {shutdown_stats}\n'
+                f' |_endpoints: {repr_eps}\n'
+                # ^TODO? how to indent closing ']'..
             )
 
-        fmtstr += (
+        if peers := self._peers:
-            # TODO, use the `ppfmt()` helper from `modden`!
+            fmtstr += (
-            f' |_endpoints: {pformat(self._endpoints)}\n'
+                f' |_peers: {len(peers)} connected\n'
-            f' |_peers: {len(self._peers)} connected\n'
+            )
-        )
 
         return (
-            f'<IPCServer(\n'
+            f'<Server(\n'
             f'{fmtstr}'
             f')>\n'
         )
@@ -835,13 +940,13 @@ class IPCServer(Struct):
 
     # TODO? maybe allow shutting down a `.listen_on()`s worth of
     # listeners by cancelling the corresponding
-    # `IPCEndpoint._listen_tn` only ?
+    # `Endpoint._listen_tn` only ?
     # -[ ] in theory you could use this to
     #     "boot-and-wait-for-reconnect" of all current and connecting
     #     peers?
     #  |_ would require that the stream-handler is intercepted so we
     #     can intercept every `MsgTransport` (stream) and track per
-    #     `IPCEndpoint` likely?
+    #     `Endpoint` likely?
     #
     # async def unlisten(
     #     self,
@@ -854,7 +959,7 @@ class IPCServer(Struct):
         *,
         accept_addrs: list[tuple[str, int|str]]|None = None,
         stream_handler_nursery: Nursery|None = None,
-    ) -> list[IPCEndpoint]:
+    ) -> list[Endpoint]:
         '''
         Start `SocketListeners` (i.e. bind and call `socket.listen()`)
         for all IPC-transport-protocol specific `Address`-types
@@ -885,10 +990,10 @@ class IPCServer(Struct):
             )
 
         log.runtime(
-            f'Binding to endpoints for,\n'
+            f'Binding endpoints\n'
-            f'{accept_addrs}\n'
+            f'{ppfmt(accept_addrs)}\n'
         )
-        eps: list[IPCEndpoint] = await self._parent_tn.start(
+        eps: list[Endpoint] = await self._parent_tn.start(
             partial(
                 _serve_ipc_eps,
                 server=self,
@@ -896,15 +1001,21 @@ class IPCServer(Struct):
                 listen_addrs=accept_addrs,
             )
         )
+        self._endpoints.extend(eps)
+
+        serv_repr: str = nest_from_op(
+            input_op='(>',
+            text=self.pformat(),
+            nest_indent=1,
+        )
         log.runtime(
-            f'Started IPC endpoints\n'
+            f'Started IPC server\n'
-            f'{eps}\n'
+            f'{serv_repr}'
         )
 
-        self._endpoints.extend(eps)
+        # XXX, a little sanity on new ep allocations
-        # XXX, just a little bit of sanity
         group_tn: Nursery|None = None
-        ep: IPCEndpoint
+        ep: Endpoint
         for ep in eps:
             if ep.addr not in self.addrs:
                 breakpoint()
@@ -917,6 +1028,10 @@ class IPCServer(Struct):
         return eps
 
 
+# alias until we decide on final naming
+IPCServer = Server
+
+
 async def _serve_ipc_eps(
     *,
     server: IPCServer,
@@ -941,20 +1056,24 @@ async def _serve_ipc_eps(
         listen_tn: Nursery
         async with trio.open_nursery() as listen_tn:
 
-            eps: list[IPCEndpoint] = []
+            eps: list[Endpoint] = []
             # XXX NOTE, required to call `serve_listeners()` below.
             # ?TODO, maybe just pass `list(eps.values()` tho?
             listeners: list[trio.abc.Listener] = []
             for addr in listen_addrs:
-                ep = IPCEndpoint(
+                ep = Endpoint(
                     addr=addr,
                     listen_tn=listen_tn,
                     stream_handler_tn=stream_handler_tn,
                 )
                 try:
+                    ep_sclang: str = nest_from_op(
+                        input_op='>[',
+                        text=f'{ep.pformat()}',
+                    )
                     log.runtime(
                         f'Starting new endpoint listener\n'
-                        f'{ep}\n'
+                        f'{ep_sclang}\n'
                     )
                     listener: trio.abc.Listener = await ep.start_listener()
                     assert listener is ep._listener
@@ -992,17 +1111,6 @@ async def _serve_ipc_eps(
                     handler_nursery=stream_handler_tn
                 )
             )
-            # TODO, wow make this message better! XD
-            log.runtime(
-                'Started server(s)\n'
-                +
-                '\n'.join([f'|_{addr}' for addr in listen_addrs])
-            )
-
-            log.runtime(
-                f'Started IPC endpoints\n'
-                f'{eps}\n'
-            )
             task_status.started(
                 eps,
             )
@@ -1010,7 +1118,7 @@ async def _serve_ipc_eps(
     finally:
         if eps:
             addr: Address
-            ep: IPCEndpoint
+            ep: Endpoint
             for addr, ep in server.epsdict().items():
                 ep.close_listener()
                 server._endpoints.remove(ep)
@@ -1045,8 +1153,7 @@ async def open_ipc_server(
         try:
             yield ipc_server
             log.runtime(
-                f'Waiting on server to shutdown or be cancelled..\n'
+                'Server-tn running until terminated\n'
-                f'{ipc_server}'
             )
             # TODO? when if ever would we want/need this?
             # with trio.CancelScope(shield=True):

tractor/ipc/_tcp.py

@@ -18,6 +18,7 @@ TCP implementation of tractor.ipc._transport.MsgTransport protocol
 
 '''
 from __future__ import annotations
+import ipaddress
 from typing import (
     ClassVar,
 )
@@ -50,13 +51,45 @@ class TCPAddress(
     _host: str
     _port: int
 
+    def __post_init__(self):
+        try:
+            ipaddress.ip_address(self._host)
+        except ValueError as valerr:
+            raise ValueError(
+                'Invalid {type(self).__name__}._host = {self._host!r}\n'
+            ) from valerr
+
     proto_key: ClassVar[str] = 'tcp'
     unwrapped_type: ClassVar[type] = tuple[str, int]
     def_bindspace: ClassVar[str] = '127.0.0.1'
 
+    # ?TODO, actually validate ipv4/6 with stdlib's `ipaddress`
     @property
     def is_valid(self) -> bool:
-        return self._port != 0
+        '''
+        Predicate to ensure a valid socket-address pair.
+
+        '''
+        return (
+            self._port != 0
+            and
+            (ipaddr := ipaddress.ip_address(self._host))
+            and not (
+                ipaddr.is_reserved
+                or
+                ipaddr.is_unspecified
+                or
+                ipaddr.is_link_local
+                or
+                ipaddr.is_link_local
+                or
+                ipaddr.is_multicast
+                or
+                ipaddr.is_global
+            )
+        )
+        # ^XXX^ see various properties of invalid addrs here,
+        # https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address
 
     @property
     def bindspace(self) -> str:
@@ -127,10 +160,9 @@ async def start_listener(
     Start a TCP socket listener on the given `TCPAddress`.
 
     '''
-    log.info(
+    log.runtime(
-        f'Attempting to bind TCP socket\n'
+        f'Trying socket bind\n'
-        f'>[\n'
+        f'>[ {addr}\n'
-        f'|_{addr}\n'
     )
     # ?TODO, maybe we should just change the lower-level call this is
     # using internall per-listener?
@@ -145,11 +177,10 @@ async def start_listener(
     assert len(listeners) == 1
     listener = listeners[0]
     host, port = listener.socket.getsockname()[:2]
-
+    bound_addr: TCPAddress = type(addr).from_addr((host, port))
     log.info(
         f'Listening on TCP socket\n'
-        f'[>\n'
+        f'[> {bound_addr}\n'
-        f' |_{addr}\n'
     )
     return listener
 

tractor/log.py

@@ -81,10 +81,35 @@ BOLD_PALETTE = {
 }
 
 
+def at_least_level(
+    log: Logger|LoggerAdapter,
+    level: int|str,
+) -> bool:
+    '''
+    Predicate to test if a given level is active.
+
+    '''
+    if isinstance(level, str):
+        level: int = CUSTOM_LEVELS[level.upper()]
+
+    if log.getEffectiveLevel() <= level:
+        return True
+    return False
+
+
 # TODO: this isn't showing the correct '{filename}'
 # as it did before..
 class StackLevelAdapter(LoggerAdapter):
 
+    def at_least_level(
+        self,
+        level: str,
+    ) -> bool:
+        return at_least_level(
+            log=self,
+            level=level,
+        )
+
     def transport(
         self,
         msg: str,
@@ -401,19 +426,3 @@ def get_loglevel() -> str:
 
 # global module logger for tractor itself
 log: StackLevelAdapter = get_logger('tractor')
-
-
-def at_least_level(
-    log: Logger|LoggerAdapter,
-    level: int|str,
-) -> bool:
-    '''
-    Predicate to test if a given level is active.
-
-    '''
-    if isinstance(level, str):
-        level: int = CUSTOM_LEVELS[level.upper()]
-
-    if log.getEffectiveLevel() <= level:
-        return True
-    return False

tractor/msg/_ops.py

@@ -210,12 +210,14 @@ class PldRx(Struct):
         match msg:
             case Return()|Error():
                 log.runtime(
-                    f'Rxed final outcome msg\n'
+                    f'Rxed final-outcome msg\n'
+                    f'\n'
                     f'{msg}\n'
                 )
             case Stop():
                 log.runtime(
                     f'Rxed stream stopped msg\n'
+                    f'\n'
                     f'{msg}\n'
                 )
                 if passthrough_non_pld_msgs:
@@ -261,8 +263,9 @@ class PldRx(Struct):
         if (
             type(msg) is Return
         ):
-            log.info(
+            log.runtime(
                 f'Rxed final result msg\n'
+                f'\n'
                 f'{msg}\n'
             )
         return self.decode_pld(
@@ -304,10 +307,13 @@ class PldRx(Struct):
                 try:
                     pld: PayloadT = self._pld_dec.decode(pld)
                     log.runtime(
-                        'Decoded msg payload\n\n'
+                        f'Decoded payload for\n'
+                        # f'\n'
                         f'{msg}\n'
-                        f'where payload decoded as\n'
+                        # ^TODO?, ideally just render with `,
-                        f'|_pld={pld!r}\n'
+                        # pld={decode}` in the `msg.pformat()`??
+                        f'where, '
+                        f'{type(msg).__name__}.pld={pld!r}\n'
                     )
                     return pld
                 except TypeError as typerr:
@@ -494,7 +500,8 @@ def limit_plds(
 
     finally:
         log.runtime(
-            'Reverted to previous payload-decoder\n\n'
+            f'Reverted to previous payload-decoder\n'
+            f'\n'
             f'{orig_pldec}\n'
         )
         # sanity on orig settings
@@ -629,7 +636,8 @@ async def drain_to_final_msg(
                     (local_cs := rent_n.cancel_scope).cancel_called
                 ):
                     log.cancel(
-                        'RPC-ctx cancelled by local-parent scope during drain!\n\n'
+                        f'RPC-ctx cancelled by local-parent scope during drain!\n'
+                        f'\n'
                         f'c}}>\n'
                         f' |_{rent_n}\n'
                         f'   |_.cancel_scope = {local_cs}\n'
@@ -663,7 +671,8 @@ async def drain_to_final_msg(
             # final result arrived!
             case Return():
                 log.runtime(
-                    'Context delivered final draining msg:\n'
+                    f'Context delivered final draining msg\n'
+                    f'\n'
                     f'{pretty_struct.pformat(msg)}'
                 )
                 ctx._result: Any = pld
@@ -697,12 +706,14 @@ async def drain_to_final_msg(
                 ):
                     log.cancel(
                         'Cancelling `MsgStream` drain since '
-                        f'{reason}\n\n'
+                        f'{reason}\n'
+                        f'\n'
                         f'<= {ctx.chan.uid}\n'
-                        f'  |_{ctx._nsf}()\n\n'
+                        f'  |_{ctx._nsf}()\n'
+                        f'\n'
                         f'=> {ctx._task}\n'
-                        f'  |_{ctx._stream}\n\n'
+                        f'  |_{ctx._stream}\n'
-
+                        f'\n'
                         f'{pretty_struct.pformat(msg)}\n'
                     )
                     break
@@ -739,7 +750,8 @@ async def drain_to_final_msg(
             case Stop():
                 pre_result_drained.append(msg)
                 log.runtime(  # normal/expected shutdown transaction
-                    'Remote stream terminated due to "stop" msg:\n\n'
+                    f'Remote stream terminated due to "stop" msg\n'
+                    f'\n'
                     f'{pretty_struct.pformat(msg)}\n'
                 )
                 continue
@@ -814,7 +826,8 @@ async def drain_to_final_msg(
 
     else:
         log.cancel(
-            'Skipping `MsgStream` drain since final outcome is set\n\n'
+            f'Skipping `MsgStream` drain since final outcome is set\n'
+            f'\n'
             f'{ctx.outcome}\n'
         )
 

tractor/msg/pretty_struct.py

@@ -20,6 +20,7 @@ Prettified version of `msgspec.Struct` for easier console grokin.
 '''
 from __future__ import annotations
 from collections import UserList
+import textwrap
 from typing import (
     Any,
     Iterator,
@@ -105,27 +106,11 @@ def iter_fields(struct: Struct) -> Iterator[
         )
 
 
-def pformat(
+def iter_struct_ppfmt_lines(
     struct: Struct,
-    field_indent: int = 2,
+    field_indent: int = 0,
-    indent: int = 0,
+) -> Iterator[tuple[str, str]]:
 
-) -> str:
-    '''
-    Recursion-safe `pprint.pformat()` style formatting of
-    a `msgspec.Struct` for sane reading by a human using a REPL.
-
-    '''
-    # global whitespace indent
-    ws: str = ' '*indent
-
-    # field whitespace indent
-    field_ws: str = ' '*(field_indent + indent)
-
-    # qtn: str = ws + struct.__class__.__qualname__
-    qtn: str = struct.__class__.__qualname__
-
-    obj_str: str = ''  # accumulator
     fi: structs.FieldInfo
     k: str
     v: Any
@@ -135,15 +120,18 @@ def pformat(
         # ..]` over .__name__ == `Literal` but still get only the
         # latter for simple types like `str | int | None` etc..?
         ft: type = fi.type
-        typ_name: str = getattr(ft, '__name__', str(ft))
+        typ_name: str = getattr(
+            ft,
+            '__name__',
+            str(ft)
+        ).replace(' ', '')
 
         # recurse to get sub-struct's `.pformat()` output Bo
         if isinstance(v, Struct):
-            val_str: str =  v.pformat(
+            yield from iter_struct_ppfmt_lines(
-                indent=field_indent + indent,
+                struct=v,
-                field_indent=indent + field_indent,
+                field_indent=field_indent+field_indent,
             )
-
         else:
             val_str: str = repr(v)
 
@@ -161,8 +149,39 @@ def pformat(
                 # raise
                 # return _Struct.__repr__(struct)
 
-        # TODO: LOLOL use `textwrap.indent()` instead dawwwwwg!
+        yield (
-        obj_str += (field_ws + f'{k}: {typ_name} = {val_str},\n')
+            ' '*field_indent,  # indented ws prefix
+            f'{k}: {typ_name} = {val_str},',  # field's repr line content
+        )
+
+
+def pformat(
+    struct: Struct,
+    field_indent: int = 2,
+    indent: int = 0,
+) -> str:
+    '''
+    Recursion-safe `pprint.pformat()` style formatting of
+    a `msgspec.Struct` for sane reading by a human using a REPL.
+
+    '''
+    obj_str: str = ''  # accumulator
+    for prefix, field_repr, in iter_struct_ppfmt_lines(
+        struct,
+        field_indent=field_indent,
+    ):
+        obj_str += f'{prefix}{field_repr}\n'
+
+    # global whitespace indent
+    ws: str = ' '*indent
+    if indent:
+        obj_str: str = textwrap.indent(
+            text=obj_str,
+            prefix=ws,
+        )
+
+    # qtn: str = ws + struct.__class__.__qualname__
+    qtn: str = struct.__class__.__qualname__
 
     return (
         f'{qtn}(\n'

tractor/msg/types.py

@@ -154,6 +154,39 @@ class Aid(
     #     should also include at least `.pid` (equiv to port for tcp)
     #     and/or host-part always?
 
+    @property
+    def uid(self) -> tuple[str, str]:
+        '''
+        Legacy actor "unique-id" pair format.
+
+        '''
+        return (
+            self.name,
+            self.uuid,
+        )
+
+    def reprol(
+        self,
+        sin_uuid: bool = True,
+    ) -> str:
+        if not sin_uuid:
+            return (
+                f'{self.name}[{self.uuid[:6]}]@{self.pid!r}'
+            )
+        return (
+            f'{self.name}@{self.pid!r}'
+        )
+
+    # mk hashable via `.uuid`
+    def __hash__(self) -> int:
+        return hash(self.uuid)
+
+    def __eq__(self, other: Aid) -> bool:
+        return self.uuid == other.uuid
+
+    # use pretty fmt since often repr-ed for console/log
+    __repr__ = pretty_struct.Struct.__repr__
+
 
 class SpawnSpec(
     pretty_struct.Struct,
@@ -170,6 +203,7 @@ class SpawnSpec(
     # a hard `Struct` def for all of these fields!
     _parent_main_data: dict
     _runtime_vars: dict[str, Any]
+    # ^NOTE see `._state._runtime_vars: dict`
 
     # module import capability
     enable_modules: dict[str, str]

tractor/trionics/__init__.py

@@ -31,7 +31,7 @@ from ._broadcast import (
 )
 from ._beg import (
     collapse_eg as collapse_eg,
-    maybe_collapse_eg as maybe_collapse_eg,
+    get_collapsed_eg as get_collapsed_eg,
     is_multi_cancelled as is_multi_cancelled,
 )
 from ._taskc import (

tractor/trionics/_beg.py

@@ -15,8 +15,9 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 '''
-`BaseExceptionGroup` related utils and helpers pertaining to
+`BaseExceptionGroup` utils and helpers pertaining to
-first-class-`trio` from a historical perspective B)
+first-class-`trio` from a "historical" perspective, like "loose
+exception group" task-nurseries.
 
 '''
 from contextlib import (
@@ -24,29 +25,83 @@ from contextlib import (
 )
 from typing import (
     Literal,
+    Type,
 )
 
 import trio
+# from trio._core._concat_tb import (
+#     concat_tb,
+# )
 
 
-def maybe_collapse_eg(
+# XXX NOTE
-    beg: BaseExceptionGroup,
+# taken verbatim from `trio._core._run` except,
+# - remove the NONSTRICT_EXCEPTIONGROUP_NOTE deprecation-note
+#   guard-check; we know we want an explicit collapse.
+# - mask out tb rewriting in collapse case, i don't think it really
+#   matters?
+#
+def collapse_exception_group(
+    excgroup: BaseExceptionGroup[BaseException],
 ) -> BaseException:
+    """Recursively collapse any single-exception groups into that single contained
+    exception.
+
+    """
+    exceptions = list(excgroup.exceptions)
+    modified = False
+    for i, exc in enumerate(exceptions):
+        if isinstance(exc, BaseExceptionGroup):
+            new_exc = collapse_exception_group(exc)
+            if new_exc is not exc:
+                modified = True
+                exceptions[i] = new_exc
+
+    if (
+        len(exceptions) == 1
+        and isinstance(excgroup, BaseExceptionGroup)
+
+        # XXX trio's loose-setting condition..
+        # and NONSTRICT_EXCEPTIONGROUP_NOTE in getattr(excgroup, "__notes__", ())
+    ):
+        # exceptions[0].__traceback__ = concat_tb(
+        #     excgroup.__traceback__,
+        #     exceptions[0].__traceback__,
+        # )
+        return exceptions[0]
+    elif modified:
+        return excgroup.derive(exceptions)
+    else:
+        return excgroup
+
+
+def get_collapsed_eg(
+    beg: BaseExceptionGroup,
+
+) -> BaseException|None:
     '''
-    If the input beg can collapse to a single non-eg sub-exception,
+    If the input beg can collapse to a single sub-exception which is
-    return it instead.
+    itself **not** an eg, return it.
 
     '''
-    if len(excs := beg.exceptions) == 1:
+    maybe_exc = collapse_exception_group(beg)
-        return excs[0]
+    if maybe_exc is beg:
+        return None
 
-    return beg
+    return maybe_exc
 
 
 @acm
 async def collapse_eg(
     hide_tb: bool = True,
-    raise_from_src: bool = False,
+
+    # XXX, for ex. will always show begs containing single taskc
+    ignore: set[Type[BaseException]] = {
+        # trio.Cancelled,
+    },
+    add_notes: bool = True,
+
+    bp: bool = False,
 ):
     '''
     If `BaseExceptionGroup` raised in the body scope is
@@ -58,14 +113,55 @@ async def collapse_eg(
     __tracebackhide__: bool = hide_tb
     try:
         yield
-    except* BaseException as beg:
+    except BaseExceptionGroup as _beg:
-        if (
+        beg = _beg
-            exc := maybe_collapse_eg(beg)
-        ) is not beg:
-            from_exc = beg if raise_from_src else None
-            raise exc from from_exc
 
-        raise beg
+        if (
+            bp
+            and
+            len(beg.exceptions) > 1
+        ):
+            import tractor
+            if tractor.current_actor(
+                err_on_no_runtime=False,
+            ):
+                await tractor.pause(shield=True)
+            else:
+                breakpoint()
+
+        if (
+            (exc := get_collapsed_eg(beg))
+            and
+            type(exc) not in ignore
+        ):
+
+            # TODO? report number of nested groups it was collapsed
+            # *from*?
+            if add_notes:
+                from_group_note: str = (
+                    '( ^^^ this exc was collapsed from a group ^^^ )\n'
+                )
+                if (
+                    from_group_note
+                    not in
+                    getattr(exc, "__notes__", ())
+                ):
+                    exc.add_note(from_group_note)
+
+            # raise exc
+            # ^^ this will leave the orig beg tb above with the
+            # "during the handling of <beg> the following.."
+            # So, instead do..
+            #
+            if cause := exc.__cause__:
+                raise exc from cause
+            else:
+                # suppress "during handling of <the beg>"
+                # output in tb/console.
+                raise exc from None
+
+        # keep original
+        raise # beg
 
 
 def is_multi_cancelled(

tractor/trionics/_mngrs.py

@@ -40,7 +40,7 @@ from typing import (
 import trio
 from tractor._state import current_actor
 from tractor.log import get_logger
-from ._beg import collapse_eg
+# from ._beg import collapse_eg
 
 
 if TYPE_CHECKING:
@@ -72,7 +72,8 @@ async def maybe_open_nursery(
         yield nursery
     else:
         async with lib.open_nursery(**kwargs) as nursery:
-            nursery.cancel_scope.shield = shield
+            if lib == trio:
+                nursery.cancel_scope.shield = shield
             yield nursery
 
 
@@ -151,8 +152,13 @@ async def gather_contexts(
         )
 
     async with (
-        collapse_eg(),
+        # collapse_eg(),
-        trio.open_nursery() as tn,
+        trio.open_nursery(
+            strict_exception_groups=False,
+            # ^XXX^ TODO? soo roll our own then ??
+            # -> since we kinda want the "if only one `.exception` then
+            # just raise that" interface?
+        ) as tn,
     ):
         for mngr in mngrs:
             tn.start_soon(

tractor/trionics/_taskc.py

@@ -60,6 +60,9 @@ def find_masked_excs(
     return None
 
 
+# XXX, relevant discussion @ `trio`-core,
+# https://github.com/python-trio/trio/issues/455
+#
 @acm
 async def maybe_raise_from_masking_exc(
     tn: trio.Nursery|None = None,
@@ -110,7 +113,6 @@ async def maybe_raise_from_masking_exc(
     )
     matching: list[BaseException]|None = None
     maybe_eg: ExceptionGroup|None
-    maybe_eg: ExceptionGroup|None
 
     if tn:
         try:  # handle egs

uv.lock

@@ -417,7 +417,7 @@ dev = [
     { name = "pyperclip", specifier = ">=1.9.0" },
     { name = "pytest", specifier = ">=8.3.5" },
     { name = "stackscope", specifier = ">=0.2.2,<0.3" },
-    { name = "typing-extensions", specifier = ">=4.13.2" },
+    { name = "typing-extensions", specifier = ">=4.14.1" },
     { name = "xonsh", specifier = ">=0.19.2" },
 ]
 
@@ -452,11 +452,11 @@ wheels = [
 
 [[package]]
 name = "typing-extensions"
-version = "4.13.2"
+version = "4.14.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/f6/37/23083fcd6e35492953e8d2aaaa68b860eb422b34627b13f2ce3eb6106061/typing_extensions-4.13.2.tar.gz", hash = "sha256:e6c81219bd689f51865d9e372991c540bda33a0379d5573cddb9a3a23f7caaef", size = 106967, upload-time = "2025-04-10T14:19:05.416Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/98/5a/da40306b885cc8c09109dc2e1abd358d5684b1425678151cdaed4731c822/typing_extensions-4.14.1.tar.gz", hash = "sha256:38b39f4aeeab64884ce9f74c94263ef78f3c22467c8724005483154c26648d36", size = 107673, upload-time = "2025-07-04T13:28:34.16Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/8b/54/b1ae86c0973cc6f0210b53d508ca3641fb6d0c56823f288d108bc7ab3cc8/typing_extensions-4.13.2-py3-none-any.whl", hash = "sha256:a439e7c04b49fec3e5d3e2beaa21755cadbbdc391694e28ccdd36ca4a1408f8c", size = 45806, upload-time = "2025-04-10T14:19:03.967Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/00/d631e67a838026495268c2f6884f3711a15a9a2a96cd244fdaea53b823fb/typing_extensions-4.14.1-py3-none-any.whl", hash = "sha256:d1e1e3b58374dc93031d6eda2420a48ea44a36c2b4766a4fdeb3710755731d76", size = 43906, upload-time = "2025-07-04T13:28:32.743Z" },
 ]
 
 [[package]]