fix(mcp/opencode): don't clobber an unparseable opencode.json on register

[abhay-codes07]

Description

OpencodeRegistrar._write_entry does a full-file read-modify-write of
opencode.json:

data = _read_json(self._config_path)     # returns {} on JSONDecodeError
mcp = data.setdefault("mcp", {})
mcp[spec.name] = _spec_to_entry(spec)
_write_json(self._config_path, data)     # overwrites the ENTIRE file

_read_json returns {} for a file that exists but doesn't parse. OpenCode
configs are commonly hand-edited and JSONC-ish (comments, trailing commas), so a
file that doesn't strictly parse gets silently rewritten as just
{"mcp": {"headroom": {...}}} — destroying the user's theme, model,
provider, and any other MCP servers. No backup.

This is the same class of data-loss bug as the Claude registrar (separate PR);
this one is headroom/mcp_registry/opencode.py.

Closes: no issue filed — found while auditing the MCP registry config-write paths.

Fix

Keep _read_json (returning {}) for read-only callers. Add
_read_json_for_write for the rewrite path: it returns {} only when the file
is absent or empty, and raises _MalformedConfigError when the file is
present but not a JSON object. _write_entry catches it and returns FAILED
with an actionable message instead of overwriting.

Absent/empty → registers fresh (unchanged); valid → merges, all keys preserved
(unchanged); present-but-invalid → left untouched.

Type of Change

• Bug fix (non-breaking change that fixes an issue)

Changes Made

• headroom/mcp_registry/opencode.py: add _read_json_for_write + _MalformedConfigError; _write_entry uses it and returns FAILED (without writing) when opencode.json is present-but-unparseable. _read_json unchanged for read-only callers.
• tests/test_mcp_registry_opencode.py: regression tests — register against malformed configs leaves the bytes untouched and returns FAILED; register against a valid config still merges and preserves theme/model plus a pre-existing MCP server.
• CHANGELOG.md: Bug Fixes entry under Unreleased.

Testing

• New tests added for the fixed behavior
• Linting passes (ruff check) and formatting is clean (ruff format --check)
• Full pytest deferred to CI (local-OOM reason below).

$ uv run ruff check headroom/mcp_registry/opencode.py tests/test_mcp_registry_opencode.py
All checks passed!

Real Behavior Proof

• Environment: Windows 11, Python 3.12.11, headroom built from this branch. Importing headroom loads the torch/transformers stack; a full pytest gets OOM-killed on this box, so I verified the write-path logic with a dependency-free script and left the full pytest to CI.
• Exact command / steps: the write-path logic here is identical to the Claude registrar fix, so I verified it with the same standalone script — replicated _read_json_for_write + the read-modify-write flow (only stdlib, no headroom import) against real temp files, exercising absent, empty, four malformed variants, and a valid config carrying unrelated keys.
• Observed result: absent/empty register fresh; every malformed variant returns FAILED and the on-disk bytes are unchanged (no clobber); a valid config merges the new server while unrelated keys survive:

OK: absent -> fresh register
OK: empty -> fresh register
OK: malformed -> FAILED, original bytes preserved (no clobber)
OK: valid config -> merged, unrelated keys preserved
MCP CONFIG-WRITE LOGIC VERIFIED

• Not tested: driving a real opencode install end-to-end (didn't want to touch a real config); the file-write path is exercised directly by the regression tests. Full local pytest deferred to CI (OOM, per above).

Review Readiness

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

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes — ran lint + a standalone logic check; full pytest deferred to CI (local OOM, disclosed above)
• I have updated the CHANGELOG.md if applicable

Additional Notes

• Companion to the Claude-registrar fix (same root cause, different file). No new dependencies. This does not touch OpenCode's opencode.jsonc file-selection (handled elsewhere) — it only hardens the existing opencode.json write against clobbering.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

PR governance

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

[JerrettDavis]

Reviewed the OpenCode registrar write-path guard and tests. The change keeps read-only tolerance for malformed JSON while making full-file rewrites refuse an existing unparseable config, which addresses the data-loss risk without broadening behavior elsewhere. The valid-config merge test also covers preserving unrelated keys and existing MCP servers.

I updated the branch from main; CI/governance is rerunning on that merge commit.

[JerrettDavis]

Still looks good. I re-reviewed the write path after the latest update: read-only callers retain tolerant parsing, while the full-file rewrite path now refuses a present-but-unparseable opencode.json so user config is not clobbered.

I pushed a test-only fix for the remaining stale expectation that still asserted the old destructive behavior. Local focused verification passed: python -m pytest tests/test_mcp_registry_opencode.py -q. The commit was made with --no-verify so no local commit hooks were executed. CI has re-queued after the push.

[JerrettDavis]

The latest head is red in CI, so I am moving this back to changes requested.

Current failing check: test (2) on run 29115340570.

Failure:

• tests/test_mcp_registry_opencode.py::test_register_server_on_malformed_config_file
• Expected RegisterStatus.REGISTERED, got RegisterStatus.FAILED.

This is directly in the malformed OpenCode config path this PR changes, so please update the implementation or the regression test expectation and rerun the shard.

[abhay-codes07]

Fixed and rebased on latest main. The failing test (2) was the pre-existing test_register_server_on_malformed_config_file, which still asserted the old behavior ("overwrites a malformed config file, preserving nothing" → REGISTERED). That's exactly the behavior this PR changes: a present-but-unparseable opencode.json now refuses the write (FAILED) and is left untouched, so the user's theme/model/other MCP servers aren't wiped.

I'd updated that test in the original PR, but a rebase conflict resolution reverted it to the upstream version. I've re-applied the update - it now asserts FAILED and that the malformed file is preserved byte-for-byte, matching the guard (and my test_register_server_preserves_malformed_config). Green now.

[JerrettDavis]

Looks good now. The stale malformed-config expectation is corrected, CI is green, and the focused OpenCode registrar suite passes locally:

uv run pytest tests/test_mcp_registry_opencode.py -q -> 36 passed.

The write path now refuses to overwrite a present-but-unparseable opencode.json, while read-only callers remain tolerant and valid configs still merge without dropping unrelated keys.