feat(opencode): HEADROOM_OPENCODE_BIN for forks + config/rtk fixes

[lennney]

Description

Allow HEADROOM_OPENCODE_BIN env var to support OpenCode forks with custom binary names (e.g. Rolandcode). Also fixes 10+ long-standing and newly-discovered bugs in the OpenCode integration discovered through adversarial testing: config file preference, backup naming, duplicate rtk injection, MCP block stripping, lock file permissions, Windows fcntl compatibility, JSONC parsing edge cases, and more.

Closes #1927, closes #1588, closes #1980

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Documentation (docs update)

Changes Made

Feature

• Add HEADROOM_OPENCODE_BIN env var to customise binary name resolution
• Deduplicate _opencode_home_dir() logic spread across 4 files into single _shared.py
• Make MCP registrar config writes atomic (temp-file + rename, guarded by fcntl.flock)
• Add _locked_config() context manager with advisory locking to prevent concurrent write corruption

Bug fixes (design review)

• Prefer opencode.jsonc over opencode.json when both exist ([BUG] wrap opencode writes to opencode.json even if opencode.jsonc exists #1588)
• Fix backup naming: use .with_name() instead of .with_suffix() so .jsonc backup is .jsonc.headroom-backup
• Stop injecting rtk into project AGENTS.md — only global ~/.config/opencode/AGENTS.md ([FEATURE] Option to opt out of rtk instruction injection into repo-level AGENTS.md when running headroom wrap #1980)
• Strip prior Headroom-managed blocks before re-injecting in apply_provider_scope(), mirroring inject_opencode_provider_config() — and preserve MCP blocks during reapply (only strip provider scope)
• Fix lock file permissions: 0o644 → 0o600 (CodeQL)
• Remove stale HEADROOM_OPENCODE_BIN basename reference from opencode_config_path() docstring

Bug fixes (adversarial testing — 8 workers × concurrent stress + malicious inputs + crash recovery)

• MCP block stripped on reinstall: apply_provider_scope called strip_opencode_headroom_blocks with default remove_mcp=True, nuking MCP entries during install→wrap→reinstall cycle
• Windows import fcntl crashes: Module-level import fcntl caused ModuleNotFoundError on Windows (docstring claimed no-op but code didn't protect it). Now guarded with try/except.
• _locked_config mypy 1.20.2 type error: CI uses mypy 1.x which requires explicit -> Generator[None, None, None] on @contextmanager functions (mypy 2.x relaxed this)
• JSONC config destroyed by registrar: _read_json used strict json.load which fails on // comments, returning {} and causing _write_json to overwrite entire config (model, provider, user data all lost). Now strips comments as fallback.
• Trailing JSONC comments without \n not stripped: Regex ^\s*//[^\n]*\n missed EOF-terminating comments. Fixed to handle EOF boundary.
• Empty command: [] causes IndexError: _entry_to_spec indexing command_value[0] without emptiness guard. Now falls through to safe branch.

Test updates

• Added test_opencode_config_paths_prefers_jsonc
• Added 42 tests across E2E (30) and concurrency (11) suites
• Updated E2E wrap test to no longer assert project AGENTS.md creation
• Adversarial testing: 8-thread concurrent hammer (160 ops, 0 errors), 8-thread mixed register/unregister/force (160 ops, 0 leaks), 15 malicious input variants, crash recovery (kill-9 mid-write), 200 register/unregister cycles, 10-thread force overwrite race, 6 JSONC comment variants, injection attacks, 100-entry × 10-args scale test, real headroom wrap E2E with custom binary

Testing

• Unit tests (pytest)
• Adversarial testing (concurrent stress + malicious inputs + crash recovery)
• E2E tests (real fork+exec of headroom wrap)
• Concurrency safety tests (lock file prevents corruption)
• CI lint pre-check (ruff check + ruff format --check + mypy)

$ uv run pytest tests/test_providers_opencode_config.py tests/test_cli/test_wrap_opencode.py tests/test_mcp_registry_opencode.py tests/test_install/ tests/test_providers_opencode_install.py -q
209 passed, 1 skipped in 13.15s

# Adversarial: 8 workers × 20 concurrent registrations
=== CONCURRENT HAMMER: 8 workers × 20 ops = 160 total ===
Results: 160 | Errors: 0
Config entries: 160 | Missing: 0 | Extra: 0
get_server failures: 0/160

# Adversarial: 8 workers mixed reg/unreg/force
=== CONCURRENT MIXED: 8 workers, 10 reg + 5 unreg + 5 force each ===
Total ops: 160 | Errors: 0
Config entries: 40 (expected ~40)
Unregistered entries still present: 0

# Adversarial: 15 malicious inputs
empty file ✅ | whitespace ✅ | no mcp key ✅ | mcp is string ✅ | mcp is list ✅
long server name ✅ | empty name ✅ | big env dict ✅ | nul in name ✅
shell metacharacters ✅ | unicode ✅ | json injection ✅ | empty mcp cleanup ✅

# Adversarial: crash recovery
Config exists after crash: True | Original data intact: ✅
Stale temp files: harmlessly present | Operations unblocked: ✅

# E2E: real headroom wrap with custom binary
Custom binary detected ✅ | config.json created ✅ | backup created ✅
lock file permissions 600 ✅ | unwrap removes provider ✅

Real Behavior Proof

• Environment: Python 3.12, headroom dev install (uv sync), Ubuntu 24.04
• Exact command / steps: (1) HEADROOM_OPENCODE_BIN=my-opencode headroom wrap opencode --port 9999 -- --help → custom binary invoked; (2) headroom wrap opencode --port 9999 -- --help → default opencode binary; (3) headroom unwrap opencode --port 9999 → provider removed, config restored; (4) uv run pytest ... → 209 passed; (5) adversarial tests above → 0 errors across all categories; (6) uv run ruff check . && uv run ruff format --check . && uv run mypy headroom --ignore-missing-imports → 0 errors
• Observed result: Custom binary resolution via HEADROOM_OPENCODE_BIN works. Config writes are atomic (crash-kill mid-write leaves original intact). Lock file 0o600. Backup naming correct for .jsonc (.jsonc.headroom-backup). Concurrent 8-thread registration/unregistration produces 0 errors, 0 leaks, 0 missing entries. JSONC files with comments are NOT destroyed by the registrar (non-MCP data preserved). MCP blocks survive install→wrap→reinstall cycle. Windows import fcntl guarded by try/except. All lint/format/mypy clean.
• Not tested: OpenCode fork with entirely different config path structure; Windows CI runner (fcntl guard is code-level, tested on Linux only); macOS CI runner (rust-based OpenCode)

Review Readiness

• I have performed a self-review
• This PR is ready for human review

[github-actions]

PR governance

This PR follows the template and is marked ready for human review.

[JerrettDavis]

The implementation is close, and CI is green on the hosted matrix, but I hit a Windows portability failure in the focused OpenCode test suite:

uv run pytest tests/test_providers_opencode_config.py -q
FAILED tests/test_providers_opencode_config.py::test_build_launch_env_with_project
assert 'C:\\...\\entry.opencode.js' in '{"plugin":["C:\\\\...\\\\entry.opencode.js"]}'

The actual launch env is JSON-encoding the Windows path, so backslashes are escaped in OPENCODE_CONFIG_CONTENT. The assertion should parse the JSON and compare config["plugin"] (or compare against json.dumps(str(plugin))), rather than searching for the raw platform path inside the serialized JSON string.

This is small, but worth fixing before merge because this PR is explicitly touching OpenCode config/wrap behavior and the repository supports Windows workflows. The MCP registry tests passed locally (31 passed), and CI is otherwise green.

[lennney]

Rebased on upstream/main. Changes:

• Resolved merge conflict with fix(mcp/opencode): don't clobber an unparseable opencode.json on register #1661 (upstream refactored opencode.py)
• Kept upstream's _read_json_for_write + _MalformedConfigError
• Kept our atomic writes + advisory locking + JSONC comment handling
• Windows assertion fix (parse JSON instead of raw string check) is included
• 76 opencode tests pass locally

[JerrettDavis]

Thanks for the rebase and follow-up. The Windows-specific blocker from my last review is fixed: test_build_launch_env_with_project now parses OPENCODE_CONFIG_CONTENT as JSON and compares the plugin array instead of searching for the raw platform path.

Verified locally on Windows:

python -m pytest tests/test_providers_opencode_config.py -q
40 passed

I also rechecked the PR state: current head bab4f1ca is clean with no failed or pending GitHub checks. The broader tests/test_cli/test_wrap_opencode.py file stalled in my freshly cleaned local worktree before pytest emitted the session header, so I am not treating that as a PR failure; the hosted checks are green and the previous concrete blocker is resolved.