[RFC 005] 3/4: HarnessEnvironment, subprocess helper, and MCP tool bridge

[splusq]

Stack for RFC 005 — 3 of 4. Depends on #1098.

Targets main because cross-fork PRs cannot chain bases, so the diff includes #1097 and #1098. Review the top commit only: f3d90c2.

1. 1/4 — package split ([RFC 005] 1/4: split openenv.core.harness into a package #1097)
2. 2/4 — foundation types ([RFC 005] 2/4: foundation types for agentic harnesses #1098)
3. 3/4 — this PR: the environment runtime
4. 4/4 — production /harness route + mode wiring

---

What

Makes the types from #1098 runnable: an environment that owns a harness subprocess, hands it the environment's MCP tools, and turns each step() into one conversational turn.

• environment.py — HarnessAction + HarnessEnvironment(MCPEnvironment). reset() stops any live harness, enumerates and conflict-resolves env tools, starts the bridge, injects, then starts the harness (injection strictly before start, per the RFC). step() runs one turn; MCP actions keep their normal routing. Rubrics run after the turn, outside the harness's control loop — RFC 004's reward boundary.
• process.py — HarnessProcess: readiness-gated start, stderr-tail diagnostics, idempotent stop with SIGTERM → SIGKILL escalation over the process group.
• bridge.py — HarnessMCPBridge: serves the env's FastMCP tool surface over loopback HTTP for the harness to consume.

Three decisions I would like challenged

1. HarnessEnvironment subclasses MCPEnvironment, substituting an empty internal FastMCP when mcp=None.
The RFC writes mcp: Optional[FastMCP] = None with a conditional super().__init__(mcp), which cannot work: mcp_server is a required positional, and skipping super().__init__ would skip Environment.__init__ entirely (no rubric, no transform). Substituting an empty server keeps reserved-name validation, _async_handle_list_tools() for injection, and mcp_session() integration for free. Alternative considered: subclass Environment directly and hold a FastMCP — rejected, it means reimplementing all of the above.

2. subprocess.Popen + reader threads, not asyncio.create_subprocess_exec.
Asyncio subprocess transports are bound to their creating loop. This object has to survive three regimes: the server's long-lived loop, the sync facade (run_async_safely spins a fresh loop per call, so a subprocess created in reset()'s loop would be unusable in step()'s), and close() from an executor thread. Popen plus asyncio.to_thread is loop-agnostic. Precedent: envs/julia_env/server/julia_process_pool.py.

3. The bridge is a separate loopback server, not a reuse of the env server's /mcp endpoint.
Reusing /mcp fails on two counts: it lives on the same app as /reset, /step, /state, so pointing the harness at that origin hands the agent the orchestration API — a direct violation of the RFC's security boundary and RFC 001's agents cannot reset; and WS /mcp calls _create_session(), so the harness would talk to a different env instance than the one wrapping it. A separate tool-only server on 127.0.0.1 makes the boundary structural rather than filter-based.

Failure handling

Turn timeouts and harness crashes become terminal observations (done=True, metadata.error_type of turn_timeout / harness_crashed) rather than exceptions, so a training loop scores the episode and moves on instead of unwinding. Deliberate; happy to change if reviewers prefer raising.

Known limitation

HTTP POST /reset and /step create a fresh env per request and close it, which would mean a harness subprocess per HTTP call. Harness envs must be driven over the WebSocket session path. Documented in the class docstring; a route-level guard is a candidate follow-up.

Verification

76 passed

Real subprocesses (no mocks) for the lifecycle edge cases: startup timeout, immediate exit reporting code + stderr tail, crash mid-session, double-stop idempotency, and a child that ignores SIGTERM to prove kill escalation lands within the grace window. Real loopback HTTP for the bridge, connecting an actual fastmcp.Client to list and call a tool. Environment tests cover reset ordering, conflict resolution, rubric ordering, crash/timeout paths, sync-facade parity, and that overrides_method sees the async overrides (which is what makes the server pick the async path). Lint clean.

Subprocess behaviors live in tests/core/scripted_harness.py — a real, lintable module spawned by mode (echo, slow-start, exit-now, crash-after-echo, ignore-sigterm), rather than code embedded in string literals.

---

Note

Medium Risk
Introduces subprocess lifecycle, loopback MCP serving, and new environment reset/step semantics that training loops depend on; failures are softened to terminal observations rather than exceptions.

Overview
Adds the RFC 005 turn-based runtime on top of the harness package split: external agentic harnesses run as long-lived subprocesses, with each HarnessAction step() treated as one conversational turn.

HarnessEnvironment (MCPEnvironment) owns episode lifecycle: reset() always stops prior state, conflict-resolves env MCP tools (resolve_tool_conflicts), starts a loopback-only HarnessMCPBridge when tools exist (with build_bridge_server so injected renames like env_read_file actually resolve), then inject_tools before start. Turns stream events into observation metadata; rubrics run after the harness finishes the turn. Crashes and turn timeouts return terminal observations (done=True, error_type) instead of raising, so training can score and continue.

HarnessProcess provides loop-agnostic stdio subprocess management (Popen + reader threads, UTF-8, SIGTERM→SIGKILL on the process group). collect.py now imports rollout types from harness.rollout; the package root still re-exports the trainer rollout API and _resolve_env_reward for back-compat.

Broad test coverage adds real subprocess and loopback HTTP integration via scripted_harness.py.

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 4 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 025191d. Configure here.}