FE-1470: Split the Python bindings' transport from the session facade

[kube]

🌟 What is the purpose of this PR?

Review on #9228 asked when to use session.py and when to use optimization.py, and the honest answer was hard to see in the code: session.py mixed ~300 lines of process machinery with the 50-line model-protocol facade a consumer actually reads, and the two session classes constructed differently. This PR separates the machinery from the vocabulary and makes the two classes construct the same way.

Part of stack #9280: sits on FE-1412 (#9229), with the arch-docs PRs above.

🔗 Related links

• FE-1470 (internal): this PR
• FE-1270: Extract Python bindings for the Petrinaut CLI into @local/petrinaut-python #9228 review thread that prompted it

🔍 What does this change?

New private module _transport.py. CliTransport owns everything about how the child process is driven: spawn with a scrubbed environment, the bootstrap line and readiness wait, size- and time-bounded reads, the JSON-lines exchange with checked ids, and process-group shutdown. The line-cap constants, encode_bootstrap_line, and the child environment move with it. Nothing in the module knows what any protocol method means.

session.py is now the part a consumer reads. PetrinautSession keeps the factories, healthz/metadata/run/request, and delegates start/close to the transport it owns. The file drops from ~470 lines to ~160, all of them protocol surface.

OptimizationSession constructs like its base class. New from_manifest(manifest) and from_manifest_file(path) mirror from_model/from_model_file; the positional constructor stays. Choosing a class is now the same gesture in both cases: name what the process serves.

The superset rule is stated where readers look. Both class docstrings now say it: a manifest embeds a model and the CLI serves both from one process, so every PetrinautSession method works on an OptimizationSession, and only the latter answers optimization.*.

No public API changes: every exported name, signature, and exception is as before.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a workspace but not a publishable library. @local/petrinaut-python is private to the monorepo.

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR: the bindings README shows the mirrored factory. The usage manual gains the symmetric construction table in FE-1456 (FE-1456: Add a usage manual for the Python bindings #9266), where it lives.

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph.

🛡 What tests cover this?

The existing 31 bindings tests and 75 petrinaut-opt tests run unchanged, apart from three assertions that reached into _request_timeout_seconds and two module-level monkeypatches, which follow the constants to _transport. One new test pins that the manifest factories spawn the same CLI invocations as the constructor forms.

❓ How to test this?

1. turbo run test:unit lint:ruff lint:types --filter @local/petrinaut-python --filter @apps/petrinaut-opt

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 22, 2026 3:02am
petrinaut	Ready	Preview	Aug 22, 2026 3:02am
petrinaut-docs	Ready	Preview	Aug 22, 2026 3:02am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 22, 2026 3:02am

[cursor]

PR Summary

Low Risk
Internal refactor of a private Python package with additive factories and no protocol or spawn-behavior changes. Process isolation and timeouts move as-is into _transport.

Overview
Splits process/stdio machinery out of PetrinautSession into a private CliTransport so session modules only expose protocol methods.

session.py now owns a transport and delegates spawn, JSON-lines exchange, timeouts, and shutdown. OptimizationSession adds from_manifest / from_manifest_file to match the model factories; existing constructors stay. Docstrings and the README state that a manifest session is a superset of the model protocol.

No change to exported names, signatures, or exception behavior. Tests follow the moved constants and assert the new factories spawn the same CLI invocations.

^{Reviewed by Cursor Bugbot for commit b2ba703. Bugbot is set up for automated code reviews on this repo. Configure here.}