---
model: claude-opus-4-7[1m]
service: claude
session: subints-spawner-design-kickoff
timestamp: 2026-04-17T03:49:18Z
git_ref: 9703210
scope: docs
substantive: true
raw_file: 20260417T034918Z_9703210_prompt_io.raw.md
---

## Prompt

Drive the "first big boi, from GH issue" task seeded by
`ai/prompt-io/prompts/subints_spawner.md`: design, plan
and implement sub-interpreter (subint) spawn-backend
support per issue #379, including (1) modularizing
`tractor.spawn._spawn` into per-backend submods, (2) a new
`._subint` backend, and (3) harness parametrization via the
existing `--spawn-backend` / `start_method` pytest fixture
in `tractor._testing.pytest`.

Follow-up clarifications from the user (this turn):
1. Pin `<3.15` on this dev branch and feature-gate subint
   tests — chose option (a).
2. Split Phase A (modularization) into its own PR first.
3. Defer the `fork()`-via-subint hack to a follow-up.
4. Harness flag is `pytest --spawn-backend <key>` CLI →
   `start_method` fixture (prompt file updated to match).

## Response summary

Produced a three-phase plan and a concrete Phase A (pure
modularization) file-split plan for user review; no code
written yet — the green-light to start Phase A was given
in this same turn conditional on logging this prompt-io
entry first.

Phases:
- **A — modularize** `tractor/spawn/_spawn.py` (847 LOC):
  keep generic machinery in `_spawn.py`, extract
  `trio_proc` → `spawn/_trio.py`, `mp_proc` →
  `spawn/_mp.py`. No pin bump.
- **B — `_subint` backend**: bump `pyproject.toml`
  `requires-python` upper to `<3.15`; add `'subint'` to
  `SpawnMethodKey`; reuse existing UDS transport; shm
  escape-hatch deferred.
- **C — harness**: drive the valid-backend tuple in
  `tractor/_testing/pytest.py:345-349` from
  `typing.get_args(SpawnMethodKey)`; skip subint tests on
  Python < 3.14.

Key findings surfaced to the user:
- `pyproject.toml:12` currently pins `<3.14`; PEP 734
  `concurrent.interpreters` only ships in 3.14 — the
  load-bearing constraint.
- `_testing/pytest.py:345-349` hardcodes valid backends
  as a string tuple (`'mp_spawn'`, `'mp_forkserver'`,
  `'trio'`) — should be `get_args(SpawnMethodKey)`.
- `_testing/pytest.py:228` already imports
  `try_set_start_method` from `tractor.spawn._spawn` —
  keeping the `_spawn.py` path as the "core" module
  avoids breaking external refs during Phase A.

Phase A commit breakdown (each green via `/run-tests`):
1. Drive `_testing/pytest.py` backend-tuple from
   `get_args(SpawnMethodKey)` — prep.
2. Extract `trio_proc` → `spawn/_trio.py`; `_methods`
   registry imports it.
3. Extract `mp_proc` → `spawn/_mp.py`; `_methods` imports
   it.
4. Tidy `spawn/__init__.py` docstring for the new layout.

Workflow: Phase A runs in a new worktree via `/open-wkt
spawn_modularize` (branch `wkt/spawn_modularize`) and
lands as its own PR before Phase B/C returns to the
current `claude_bun_opus4.7_subint_spawner_backend`
branch.

## Files changed

None this turn — design/planning only. The user updated
`ai/prompt-io/prompts/subints_spawner.md` themselves to
complete the truncated sentence on line 32 (harness-flag
reference).

Upcoming (Phase A, next turn):
- `tractor/spawn/_spawn.py` — trimmed to "core"
- `tractor/spawn/_trio.py` — new; holds `trio_proc()`
- `tractor/spawn/_mp.py` — new; holds `mp_proc()`
- `tractor/spawn/__init__.py` — docstring refresh
- `tractor/_testing/pytest.py` — backend tuple from
  `get_args(SpawnMethodKey)`

## Human edits

None — committed as generated. User completed the
truncated sentence on line 32 of
`ai/prompt-io/prompts/subints_spawner.md` themselves
*before* this prompt-io log was written; that edit was
the user's authoring, not an edit to AI output.