Deprecate opencode_env and pi_env in favour of harbor_env (removal in 0.8.0)

[sergiopaniego]

Summary

OpenCode and Pi are validated Harbor harnesses (harness="opencode", harness="pi"), with the same token-level capture for training (both are stable with optimizer_pass in the Harbor provider qualification table), so opencode_env and pi_env are now a second path to the same agents. This deprecates both, with removal in OpenEnv 0.8.0, and points users to harbor_env. Nothing is removed yet.

This is the first time an environment is deprecated in OpenEnv, and there was no written convention (the only precedent is the openenv_core import shim). So the approach follows how TRL does it, which it has applied since well before its 1.0: the warning names the removal version and a concrete replacement, it is a FutureWarning so users actually see it, the docs say the same, and the removal lands in the announced release. That convention is now written down in .claude/docs/INVARIANTS.md (#1277), and this PR follows it. For the two-minor-release runway, this should land before the 0.6.1 cut so the warning ships in 0.6.1; if it lands later, the removal version moves to 0.9.0.

What changes

• Importing opencode_env or pi_env emits a FutureWarning:

  opencode_env is deprecated and will be removed in OpenEnv 0.8.0. Run opencode through harbor_env instead: HarborSessionFactory(server_url, harness='opencode') against openenv harbor serve. See https://huggingface.co/docs/openenv/environments/harbor

• The env READMEs (and their generated doc pages via sync_env_docs.py) open with the same notice and a migration snippet (openenv harbor serve + HarborSessionFactory(..., harness=...)). Tasks become Harbor task directories instead of OpenCodeTask / PiTask.
• Both tutorials open with the notice, and the sidebar, the environments catalog and the tutorials index mark them "(deprecated)".
• The OpenCode tutorial's TRL links are pinned to v1.14.1, the last release with that recipe, since TRL drops the example in Train harnesses through Harbor: drop the standalone opencode example trl#7457.
• The Pi tutorial linked examples/scripts/openenv/pi.py in TRL, which was never merged (Add Pi coding-agent loop-owning GRPO examples trl#6600 was closed) and 404s. It now says so and points to Harbor.

Notes

• pi_env imports opencode_env's sandbox layer, so importing pi_env shows both warnings. Both envs go away together, so I kept it simple rather than filtering one.
• The openenv_core shim predates this and uses DeprecationWarning with no removal version; it can be aligned separately.
• Removal in 0.8.0 (a follow-up PR): the two envs, their tests, the four images in docker-build.yml, their docs and tutorials, examples/opencode_env_simple.py and examples/pi_env_simple.py.

cc @jayzuccarelli, since you have a few opencode_env fixes open (#1262, #1263, #1264, #1074): heads up that the env is on its way out, and the same agent through Harbor is where fixes would land from now on.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• New environment
• Refactoring

Alignment Checklist

Before submitting, verify:

• I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
• I have checked .claude/docs/INVARIANTS.md and no invariants are violated
• I have run /pre-submit-pr (or bash .claude/hooks/lint.sh and tests) and addressed all issues

RFC Status

• Not required (bug fix, docs, minor refactoring)
• RFC exists: #___
• RFC needed (will create before merge)

Test Plan

• PYTHONPATH=src:envs pytest tests/envs/test_opencode_env.py tests/envs/test_opencode_factory_lifecycle.py tests/envs/test_opencode_hf_sandbox.py tests/envs/test_opencode_sandbox_home.py tests/envs/test_pi_factory_lifecycle.py tests/envs/test_pi_runtime.py: 60 passed, 1 skipped, and the FutureWarning is reported at the importing line.
• python -c "import pi_env" prints the warnings with default filters (no -W needed).
• ruff check / ruff format --check clean on the changed files. bash .claude/hooks/lint.sh reports the same 56 pre-existing format diffs on main with the local ruff (0.16.9), none in files touched here.
• python scripts/sync_env_docs.py --check passes.

Claude Code Review

N/A

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation and import-time warnings only; no runtime behavior change beyond visible deprecation notices for existing opencode_env/pi_env users.

Overview
Deprecates opencode_env and pi_env in favor of harbor_env (planned removal in OpenEnv 0.8.0). Packages still work; imports now emit FutureWarning with Harbor migration instructions (openenv harbor serve + HarborSessionFactory(..., harness="opencode"|"pi")).

Docs and navigation label OpenCode/Pi environments and GRPO tutorials as (deprecated) and add top-of-page warnings with the same Harbor path. The OpenCode tutorial’s TRL links are pinned to v1.14.1; the Pi tutorial drops a broken TRL script link and directs readers to Harbor instead.

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

[bot-ci-comment]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[cursor]

Alignment Review Report

Automated Checks

• Lint: PASS — uv run usort check, ruff format --check, and ruff check are all clean for the two touched Python files (envs/opencode_env/__init__.py, envs/pi_env/__init__.py). The repo-wide usort check still flags tests/envs/test_grid_world.py and tests/envs/test_julia_env.py, but those are pre-existing and untouched by this PR (per AGENTS.md).
• Debug code: CLEAN — check-debug.sh's repo-wide print/TODO hits are all pre-existing and outside the files this PR touches; nothing new was introduced.
• Docs sync: PASS — python scripts/sync_env_docs.py --check reports the generated docs/source/environments/{opencode,pi}.md stubs are in sync with the updated READMEs.
• Tests: tests/envs/test_opencode_env.py and tests/envs/test_pi_runtime.py (26 passed, 1 skipped) still pass; they now surface the new FutureWarnings but nothing turns warnings into errors in this repo's pytest config, so no breakage.

Open RFCs Context

• RFC 005 (Agentic Harness Integration, In Review) — defines the harness-wrapping pattern (HarborSessionFactory(harness=...)) that this PR's deprecation notices point users toward. Directly relevant, and this change is consistent with it.
• RFC 012 (Harbor capture purpose/provider fidelity, In Review) — documents run_rollout(..., harness="opencode", ...) as an existing, validated capture path, confirming harness="opencode"/"pi" are real, supported seams and not just examples.
• No other Draft/In Review RFCs (008, 010, 011) touch coding-harness environments or deprecation policy.

Tier 1: Fixes Required

None identified.

Tier 2: Alignment Discussion

Principle Conflicts

None identified. The deprecation is purely additive (a FutureWarning on import plus doc notices); it doesn't change any Gym-like API signatures, doesn't touch client/server boundaries, and doesn't move reward logic. The two-minor-version runway (current 0.6.1.dev0 → removal in 0.8.0) is more conservative than the "pre-1.0 breaking changes acceptable" policy in PRINCIPLES.md requires.

RFC Conflicts

None identified. The change directly implements the migration path RFC 005 and RFC 012 already describe (per-harness envs → harbor_env with harness="opencode"/"pi"), rather than conflicting with either.

Minor Observations (non-blocking)

• pi_env/__init__.py imports from opencode_env.sandbox import ..., so importing pi_env now also triggers opencode_env's FutureWarning as a side effect (confirmed in the test run above). Since both packages are being removed together in 0.8.0, this is harmless and arguably informative, but callers who only ever touch pi_env will see a warning mentioning an unrelated package name — worth a one-line note in the warning message if it's ever revisited, but not worth blocking on.

Summary

• 0 mechanical issues to fix
• 0 alignment points for human review
• 0 RFC conflicts to discuss

  

_{Sent by Cursor Automation: Pre-review}