A subinterpreter-in-thread spawning backend

[goodboy]

Add subint (in-thread sub-interpreter) spawn backend

Motivation

This PR is Phase B.2 of the multi-backend spawn rework tracked
under #379: it lands the first member of the subint family — a
single-process spawn backend that runs each sub-actor inside a
CPython PEP 734 sub-interpreter driven by a dedicated OS thread,
while reusing tractor's existing IPC handshake (UDS/TCP) for the
parent↔child channel. The result is multiple Actors in one OS
process with state isolation and faster startup than
mp_spawn/mp_forkserver, but without the per-interp-GIL
parallelism that's still gated upstream on msgspec PEP 684 support
(jcrist/msgspec#563 and more specifically jcrist/msgspec#1026).

Why the dedicated-thread machinery? PEP 734's public
concurrent.interpreters only exposes 'isolated' config, which
refuses to import any C extension missing the
Py_mod_multiple_interpreters slot — and that's currently msgspec,
which tractor uses pervasively in the IPC layer. So we drop to the
private _interpreters C module in 'legacy' config: shared
main GIL, but the sys.modules/__main__/globals isolation we
actually want for the actor model. We also feature-gate to 3.14+
via the public-module presence check: the private API exists on 3.13,
but tractor's multi-trio-task usage of _interpreters.exec() wedges
silently there and only works cleanly on 3.14.

This PR also documents two known hang classes specific to in-thread
subints (a class-A SIGINT-starvation hang and an orphaned-channel
park) and ships the skipon_spawn_backend() pytest marker +
tractor.devx._debug_hangs module that fell out of triaging them. It
serves as the foundation for the stacked subint-family PRs (#447
forkserver, future fork variants).

---

Src of research

• PEP 734 — concurrent.interpreters public API
  • https://peps.python.org/pep-0734/
• PEP 684 — per-interpreter GIL / Py_mod_multiple_interpreters
  • https://peps.python.org/pep-0684/
• CPython public wrapper (Lib/concurrent/interpreters/) *
  https://github.com/python/cpython/tree/main/Lib/concurrent/interpreters
• CPython private C ext (Modules/_interpretersmodule.c) *
  https://github.com/python/cpython/blob/main/Modules/_interpretersmodule.c
• msgspec PEP 684 upstream tracker — Use multi-phase init for c-extension initialization jcrist/msgspec#563
• anyio's to_interpreter._Worker for a set___main___attrs()
  reference impl *
  https://github.com/agronholm/anyio/blob/master/src/anyio/to_interpreter.py

---

Summary of changes

By chronological commit (all hashes from
main..subint_spawner_backend),

• (d318f1f8) Add the 'subint' spawn-method scaffold to
  tractor.spawn._spawn: register the key in SpawnMethodKey, gate
  try_set_start_method('subint') on the public
  concurrent.interpreters module, and wire the dispatch table.
• (b8f243e9) Implement min-viable subint_proc() in
  tractor.spawn._subint: _interpreters.create('legacy') →
  bootstrap-string driven _interpreters.exec() on a daemon
  threading.Thread → reuse ipc_server.wait_for_peer() for the
  existing UDS/TCP handshake → graceful Portal.cancel_actor()
  teardown → _interpreters.destroy().
• (8a8d01e0) Doc the _interpreters private-API choice
  in the _subint module docstring (PEP 734 isolated mode +
  msgspec PEP 684 incompat → forced legacy mode + 3.14 floor).
• (03bf2b93) Avoid skipping the tractor.ipc._ringbuf
  import path when cffi is missing (now an optional eventfd dep).
• (d2ea8aa2) Handle py3.14+ stdlib incompats as test
  skips so the suite can boot under the new floor.
• (31cbd11a) Fix the subint destroy-race: route
  _interpreters.exec() to a dedicated threading.Thread rather
  than trio.to_thread.run_sync(), since trio's thread cache
  recycles workers and leaves the subint tstate attached — blocking
  _interpreters.destroy() in teardown.
• (99541fee) Bound the teardown shields with
  _HARD_KILL_TIMEOUT=3.0s + daemon=True driver thread +
  move_on_after() shielded scopes; abandon-and-log if the subint
  can't be cleanly destroyed (vs. wedging the parent forever).
• (09466a1e) Add tractor.devx._debug_hangs exposing
  dump_on_hang() (file-target
  faulthandler.dump_traceback_later()) and
  track_resource_deltas() (thread + subint counts) — the
  actually-useful triage primitives that fell out of subint bringup.
• (34d9d482) Raise the subint-floor to py3.14 in
  pyproject.toml and split deps into per-feature groups (subints,
  eventfd, sync_pause) so 3.14-only deps don't bleed into the
  3.13 install path.
• (2ed5e6a6) Add tests/test_subint_cancellation.py —
  focused cancel + hard-kill audit covering the corner cases the
  hard-kill paths are meant to cover.
• (4a325458) Doc the two subint hang classes
  (subint_sigint_starvation_issue.md,
  subint_cancel_delivery_hang_issue.md) and arm dump_on_hang() in
  the test conftests.
• (189f4e3f) Wall-cap subint audit tests via
  @pytest.mark.timeout(method='thread') so a regressing hang fails
  fast instead of stalling CI.
• (a6cbac95) Bump uv.lock for pytest-timeout +
  py3.13-gated wheel deps.
• (59987745) Add a global 200s pytest-timeout ceiling
  in pyproject.toml.
• (985ea76d) Skip test_stale_entry_is_deleted under
  --spawn-backend=subint (class-A SIGINT-starvation reproducer;
  tracked in subint_sigint_starvation_issue.md).
• (f3cea714) Expand the subint SIGINT-starvation hang
  catalog with additional reproducers / strace evidence.
• (3b26b59d) Add the
  @pytest.mark.skipon_spawn_backend('<backend>', reason='...')
  marker (registered in tractor._testing.pytest, expanded in
  pytest_collection_modifyitems) so backend-borked tests can be
  cleanly gated.
• (4b2a0886) Apply skipon_spawn_backend('subint', ...)
  (with hang-doc tracker refs as reason=) to the affected test
  modules.
• (c041518b) (a65fded4) Prompt-IO logs for
  the destroy-race fix and hang-class docs (NLNet generative-AI
  provenance).
• (9cf3d588) (d3d6f646) Reorganize
  .gitignore by skill/purpose; ignore notes & snippets subdirs.
• (ba86d482) (b1a0753a) /run-tests skill
  polish: lastfailed-cache inspection + venv pre-flight expansion.
• (b524ee46) (64ddc42a) Bump xonsh to
  0.22.8-pre and pin to GH main editable as a workaround for an
  upstream packaging gap on 3.14.

---

Scopes changed

• tractor.spawn._subint (new, ~433 LoC)

  • subint_proc() — full subint actor lifecycle (create /
    driver-thread / handshake / cancel / destroy)
  • _HARD_KILL_TIMEOUT + bounded move_on_after() shields at every
    teardown blocking-point
  • extensive module docstring covering the PEP 734 / 684 / msgspec
    triangle + 3.14 gate rationale

• tractor.spawn._spawn

  • register 'subint' in SpawnMethodKey + _methods dispatch
  • runtime gate try_set_start_method('subint') on the public
    concurrent.interpreters module presence

• tractor._child

  • factor _actor_child_main() shared entry shape used by both the
    CLI (trio/mp subproc backends) and the subint bootstrap string

• tractor._testing.pytest

  • skipon_spawn_backend(*backends, reason=None) marker +
    pytest_collection_modifyitems() expansion
  • convert try_set_start_method RuntimeError into a clean
    pytest.UsageError

• tractor.devx._debug_hangs (new)

  • dump_on_hang() — file-target
    faulthandler.dump_traceback_later() (avoids pytest's stderr
    capture)
  • track_resource_deltas() — log thread + subint counts across a
    block

• pyproject.toml + uv.lock

  • raise requires-python floor to >=3.13, <3.15
  • split optional-deps into subints (msgspec≥0.21), eventfd
    (cffi), sync_pause (greenback) groups
  • [tool.uv.dependency-groups] → subints = {requires-python = ">=3.14"}
  • add global pytest-timeout=200s ceiling

• ai/conc-anal/ (new)

  • subint_sigint_starvation_issue.md — class-A GIL-contention
    SIGINT-never-delivered hang
  • subint_cancel_delivery_hang_issue.md — orphaned-channel park
    after subint teardown

• tests/test_subint_cancellation.py (new)

  • focused subint cancel + hard-kill test audit

• tests.discovery.test_registrar, tests.test_cancellation,
  tests.test_inter_peer_cancellation, tests.test_pubsub,
  tests.test_ringbuf, tests.test_shm

  • pytestmark = pytest.mark.skipon_spawn_backend('subint', reason='...') with hang-doc tracker refs

• .claude/skills/run-tests/SKILL.md

  • lastfailed-cache inspection + venv pre-flight coverage
    (incidental)

---

Future follow up

• Drop the dedicated-thread machinery once msgspec PEP 684 +
  isolated mode lands Once Use multi-phase init for c-extension initialization jcrist/msgspec#563 ships and our
  remaining C-ext deps grow Py_mod_multiple_interpreters, switch
  from the private _interpreters legacy-mode driver to public
  concurrent.interpreters.create() (isolated) +
  trio.to_thread.run_sync(Interpreter.exec, ...). Tracked in Audit subint_forkserver thread constraints once msgspec PEP 684 lands #450.

• Surface subint-bootstrap exceptions to the parent task via a
  nonlocal err slot tractor.spawn._subint:_subint_target()
  currently only log.exception()s a hard bootstrap failure (e.g.
  ImportError of the actor module inside the subint, or syntax
  error in the bootstrap string). Adopt anyio's (retval, is_exception) tuple pattern (and the equivalent already used in
  the _subint_forkserver.py:480-494 block on the stacked PR Working toward a "subinterpreter-forkserver" spawning backend #447)
  to re-raise into the parent — needs to coordinate with the existing
  trio.Cancelled paths around subint_exited.wait(). (?TODO in
  _subint.py.)

• Switch bootstrap arg-passing to
  _interpreters.set___main___attrs() The current
  repr()-into-bootstrap-string approach only roundtrips literals.
  For a pre-built SpawnSpec struct, credentials, or callables we'd
  want anyio's set___main___attrs(interp_id, {...}) pattern.
  Tracked in Trying out sub-interpreters (subints), maybe fork() can be hacked now?' #379. (?TODO in _subint.py.)

• Resolve the class-A SIGINT-starvation hang catalog
  ai/conc-anal/subint_sigint_starvation_issue.md documents
  reproducers where an abandoned-subint thread starves the parent's
  trio loop hard enough that SIGINT is dropped at the
  kernel↔Python boundary. Currently mitigated via
  skipon_spawn_backend('subint') on affected tests + the
  _HARD_KILL_TIMEOUT shields. Real fix is upstream-CPython-shaped
  (per-interp GIL / true subint cancellation primitive).

• Fix the orphaned-channel park after subint teardown
  ai/conc-anal/subint_cancel_delivery_hang_issue.md — Ctrl-C-able
  (so not the GIL-hostage class) but the parent-side
  process_messages loop parks on a now-dead subint's IPC channel
  without ever seeing a clean EOF/BrokenResourceError.
  Tractor-shaped fix; needs an explicit channel-tear from the subint
  side as part of the soft-kill sequence.

• Cross-link the cancel-cascade hang from PR Working toward a "subinterpreter-forkserver" spawning backend #447
  test_nested_multierrors cancel-cascade hang gated by pytest
  --capture=fd is mostly a subint_forkserver symptom (subint_forkserver: test_nested_multierrors cancel-cascade hang gated by pytest --capture=fd #449) but
  the underlying mechanism may also affect single-process subints
  under specific schedules — worth re-running the audit once Working toward a "subinterpreter-forkserver" spawning backend #447
  lands.

---

---

(this pr content was generated in some part by claude-code)

[goodboy]

we're missing a link to the older pep-554 here?

[goodboy]

Reason for pinning to the legacy API..

[goodboy]

The full reason we need a GIL per subint..