[jason-murray]

Closes #26.

Problem

OpenCode 2.1 (2.1.0 released 2026-10-20; 2.1.4 current) is refused for native import (unsupported OpenCode CLI version: 2.1.4). Any compacted 2.1 export fails to read with OpenCode v2 compaction has invalid summary, because 2.1 no longer writes recent. Uncompacted exports read, but report 2.1's native field as an unknown content field. Details and OpenCode source references are in #26.

Change

• Version gate: _VERSION accepts 2.0.x and 2.1.x; 2.1.4 joins VALIDATED_VERSIONS. Other 2.1 releases get the existing unvalidated_target_version warning, and 2.2/3.x still fail closed.
• Reader: a new _from_2_1() projects a 2.1 transfer onto the 2.0 schema before _validate_native, applied in to_legacy and loss_events. It's the inverse of OpenCode's own SessionLegacy upgrade:
  • native → state on text/reasoning, and → providerState on tools, assistant steps and compactions, so omission codes are the same for 2.0 and 2.1 sources. If both names are present, the 2.0 name wins.
  • A missing recent on a running/completed compaction is rebuilt from the messages between metadata.keepID and the compaction with _recent_text, a port of OpenCode's SessionRecentText.messageToText, so the kept tail still appears as "Recent context" in conversions. It comes from metadata.recent instead when OpenCode upgraded the compaction from 2.0 storage, and is "" otherwise. A present non-string recent still fails closed.
  • A provider compaction's native.messages window is counted as private state and doesn't retire readable history, same as 2.0's providerContext.
  • idle.error is an accepted field (already validated and counted as opencode_v2_error).
• Writer: unchanged. 2.1 targets still get the 2.0 schema, which stock 2.1 upgrades on import.
• CI: a new opencode-v2.1 matrix job installs @opencode/cli@2.1.4 and runs the same assigned v2 native tests. The native tests now accept opencode_v2.VALIDATED_VERSIONS instead of a hard-coded 2.0 set. The installer records 2.1.4 before 2.0.23, so all keeps 2.0.23 as the default.
• Docs/changelog: an "OpenCode 2.1" section in docs/opencode-v2.md, plus version-family wording in the CLI reference, troubleshooting, compatibility, native-testing and development docs.

Two existing expectations change on purpose: test_version_schema_gate (2.1.0 is now accepted; 2.2.0 and 2.10.0 added as rejected), and the running-compaction row in test_opencode_v2_review.py, where recent is no longer required. A present None/[]/non-string recent is still rejected, covered by a new test.

Testing

• New tests/test_opencode_v2_1.py (11 tests): native renames and their omission codes, keepID tail reconstruction, fallbacks (no metadata, unresolved keepID, upgraded metadata.recent), provider window privacy, idle.error, malformed recent, and _recent_text against OpenCode's rendering (skills, attachments, truncation at 1,250 code points, tool error/streaming, background shell). 8 of the 11 fail on main, with compaction has invalid summary and the missing helper; the other 3 are fail-closed checks that pass on both.
• ruff check ., ruff format --check …, git diff --check and python -m unittest discover .github/tests pass.
• Full pytest was run on Windows only (no Linux machine available). Failing test IDs are identical between main and this branch (1181 each, all pre-existing Windows-environment failures), so there are no new failures. I'm relying on CI for the Linux suite and the new opencode-v2.1 native job.
• Manual native round trip with stock 2.1.4 on Windows (isolated HOME/USERPROFILE/APPDATA/XDG; directory fsync stubbed because of the Windows bug noted in Support OpenCode 2.1.x: compacted 2.1 exports fail and native import is version-gated #26): the Codex fixture with a completed compaction converted with target_cli_version="2.1.4", with no warnings. It imported through install_opencode_artifact, the cold session export --standalone returned a 2.1-shaped compaction (no recent), and this branch re-parsed it with content and compaction intact. 0.12.0 fails on that same export. The repo's own native tests can't start OpenCode's standalone server on Windows because their stripped environment (PATH=/usr/bin:/bin) lacks SYSTEMROOT/APPDATA, so they need the Linux CI job.
• Real 2.1.4 exports (7 sessions) parse with the expected omission codes and no unknown-field counts.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WW649bqoSmoitkj96NB5WB

[github-actions]

🔴 Contributor eligibility requirements not met for @jason-murray.

• 🟢 Account created: 2014-10-27; age: 4381 days (required: at least six calendar months).
• 🔴 Contributions dated on or before 2026-09-25: 0 (required: at least 100).

Pull request authors must have a GitHub account at least six calendar months old and at least 100 GitHub contributions dated on or before the date one calendar month before the check.

See the contributor eligibility policy.

Closing this PR because these requirements were not met. This policy is intended to reduce spam from AI agents; it is not an assessment of the quality of your change.