fix(learn): detect the active OpenCode database (#2587)

## Description

`headroom learn --agent opencode` can silently mine a frozen
conversation corpus. `OpenCodePlugin` hardcodes
`~/.local/share/opencode/opencode.db`, but source-built OpenCode writes
`opencode-local.db` in the same directory. When both files exist, learn
still succeeds against the stale packaged DB and ignores the live
source-built corpus.

This follows the report in
https://github.com/headroomlabs-ai/headroom/issues/2581 and builds on
the existing OpenCode learn path introduced in
https://github.com/headroomlabs-ai/headroom/pull/559.

This change keeps explicit constructor paths authoritative, honors
`HEADROOM_OPENCODE_DB` when it is set, and otherwise selects the newest
existing database between `opencode.db` and `opencode-local.db`,
preferring canonical `opencode.db` on exact ties. It also updates the
OpenCode learn docs line so the documented behavior matches the landed
resolver. Closes #2581.

The branch also carries one narrow CI repair requested during review:
`headroom/cli/wrap.py` now binds the `unwrap claude` Click command back
to `unwrap_claude` instead of the leak-warning helper, which restores
the existing unwrap test surface and leaves the helper as an internal
warning function.

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- add a private OpenCode DB resolver in
`headroom/learn/plugins/opencode.py` with precedence `db_path` then
`HEADROOM_OPENCODE_DB` then newest existing default filename then
canonical fallback
- preserve canonical `opencode.db` for exact mtime ties and for
canonical-only installs
- add focused regression coverage for newer-local, explicit-path,
canonical-only, equal-tie, missing-override, and end-to-end scanning
cases
- sync the OpenCode learn docs paragraph so it no longer claims
`opencode.db` is the only supported default path
- restore the `unwrap claude` Click command binding in
`headroom/cli/wrap.py` and apply the repo formatter so the branch passes
the existing unwrap test and lint gates

## Testing

- [x] Unit tests pass (`uv run pytest
tests/test_learn/test_opencode_scanner.py -q`)
- [x] Linting passes (`uv run ruff check
headroom/learn/plugins/opencode.py
tests/test_learn/test_opencode_scanner.py`)
- [x] Type checking passes (`uv run mypy
headroom/learn/plugins/opencode.py`)
- [x] New tests added for new functionality when applicable
- [x] Manual testing performed

### Test Output

```text
uv run pytest tests/test_learn/test_opencode_scanner.py -q -k "newer_local_database"
1 passed, 9 deselected in 0.26s

uv run pytest tests/test_learn/test_opencode_scanner.py -q
10 passed in 0.50s

uv run ruff check headroom/learn/plugins/opencode.py tests/test_learn/test_opencode_scanner.py
All checks passed!

uv run ruff format headroom/learn/plugins/opencode.py tests/test_learn/test_opencode_scanner.py --check
2 files already formatted

uv run mypy headroom/learn/plugins/opencode.py
Success: no issues found in 1 source file

rg -n "opencode-local\.db|HEADROOM_OPENCODE_DB|opencode\.db" docs/content/docs/opencode.mdx
78:`headroom learn` supports OpenCode as a scan target. It reads past sessions from the newer of `~/.local/share/opencode/opencode-local.db` and `~/.local/share/opencode/opencode.db`, or from `HEADROOM_OPENCODE_DB` when you set an explicit override, and writes corrections to your project's `AGENTS.md`.

uv run pytest tests/test_cli/test_unwrap_claude.py -q -k "removes_mcp_rtk_and_stops_proxy or preserves_user_managed_serena or removes_headroom_installed_serena or keep_flags_skip_cleanup or restores_all_base_url_modes or stops_claude_owned_persistent_deployment or reports_ambiguous_same_port_persistent_deployment or warns_about_same_port_inherited_env or ignores_malformed_inherited_env_port"
9 passed, 5 deselected in 0.40s

uv run ruff check .
All checks passed!

uv run ruff format --check .
1340 files already formatted
```

## Real Behavior Proof

- Environment: temporary SQLite databases exercised through the
production `OpenCodePlugin()` constructor
- Exact command / steps: run `uv run pytest
tests/test_learn/test_opencode_scanner.py -q -k "newer_local_database"`
against `origin/main` with the new regression test overlaid, then run
the same command and the full `uv run pytest
tests/test_learn/test_opencode_scanner.py -q` suite on the branch head
- Observed result: the base reproduction fails with `AssertionError:
assert 'Canonical' == 'Local'`, proving current main still selects the
stale canonical DB; the branch head passes the reproduction row and the
full 10-test scanner suite
- Not tested: live user OpenCode corpus

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable

## Additional Notes

- `CHANGELOG.md` stays untouched because Headroom generates release
notes from conventional commits.
- The automatic chooser is intentionally limited to the two known
default filenames, `opencode.db` and `opencode-local.db`. Other layouts
can use `HEADROOM_OPENCODE_DB`.
- The fix stays inside `headroom/learn/plugins/opencode.py`; no
provider-neutral learn or pipeline code changes are planned.
This commit is contained in:
Rod Boev 2026-07-26 22:50:59 -04:00 committed by GitHub
parent 904bc675b3
commit f74d874777
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 268 additions and 22 deletions

View file

@ -75,7 +75,7 @@ The default model is `headroom/claude-sonnet-4-6`. Change it in `opencode.json`
## Failure Learning
`headroom learn` supports OpenCode as a scan target. It reads past sessions from `~/.local/share/opencode/opencode.db` and writes corrections to your project's `AGENTS.md`.
`headroom learn` supports OpenCode as a scan target. It reads past sessions from the newer of `~/.local/share/opencode/opencode-local.db` and `~/.local/share/opencode/opencode.db`, or from `HEADROOM_OPENCODE_DB` when you set an explicit override, and writes corrections to your project's `AGENTS.md`.
```bash
headroom learn --agent opencode --apply

View file

@ -5262,13 +5262,6 @@ def claude(
# =============================================================================
@unwrap.command("claude")
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@click.option("--no-stop-proxy", is_flag=True, help="Do not stop the local Headroom proxy")
@click.option("--keep-mcp", is_flag=True, help="Keep Headroom MCP registrations")
@click.option("--keep-rtk", is_flag=True, help="Keep rtk Claude hooks")
def _warn_if_proxy_env_leaked(port: int) -> None:
"""Issue #2238: surface a proxy URL that survived unwrap in the live shell.
@ -5286,9 +5279,7 @@ def _warn_if_proxy_env_leaked(port: int) -> None:
leaked.append((name, value))
if not leaked:
return
click.echo(
" ⚠ Headroom's proxy URL is still exported in this shell's environment:"
)
click.echo(" ⚠ Headroom's proxy URL is still exported in this shell's environment:")
for name, value in leaked:
click.echo(f" {name}={value}")
click.echo(
@ -5303,6 +5294,13 @@ def _warn_if_proxy_env_leaked(port: int) -> None:
)
@unwrap.command("claude")
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@click.option("--no-stop-proxy", is_flag=True, help="Do not stop the local Headroom proxy")
@click.option("--keep-mcp", is_flag=True, help="Keep Headroom MCP registrations")
@click.option("--keep-rtk", is_flag=True, help="Keep rtk Claude hooks")
def unwrap_claude(
port: int,
no_stop_proxy: bool,

View file

@ -1,7 +1,9 @@
"""OpenCode plugin for headroom learn.
Reads conversation data from the OpenCode SQLite database at
``~/.local/share/opencode/opencode.db``.
``~/.local/share/opencode/opencode.db`` or
``~/.local/share/opencode/opencode-local.db``. Set
``HEADROOM_OPENCODE_DB`` to force a specific database path.
OpenCode stores messages and tool parts in two tables:
- ``message``: one row per turn (user/assistant), with JSON ``data``
@ -28,6 +30,7 @@ from __future__ import annotations
import json
import logging
import os
import sqlite3
from datetime import datetime, timezone
from pathlib import Path
@ -45,7 +48,10 @@ from ..writer import CodexWriter, ContextWriter
logger = logging.getLogger(__name__)
_OPENCODE_DB = Path.home() / ".local" / "share" / "opencode" / "opencode.db"
_OPENCODE_DIR = Path.home() / ".local" / "share" / "opencode"
_OPENCODE_DB = _OPENCODE_DIR / "opencode.db"
_OPENCODE_DB_ENV = "HEADROOM_OPENCODE_DB"
_OPENCODE_DB_CANDIDATES = ("opencode-local.db", "opencode.db")
# Tool part status values that indicate failure.
_ERROR_STATUSES = {"error", "failed", "aborted"}
@ -59,7 +65,7 @@ class OpenCodePlugin(LearnPlugin, ConversationScanner):
"""
def __init__(self, db_path: Path | None = None) -> None:
self._db_path = db_path or _OPENCODE_DB
self._db_path = self._resolve_db_path(db_path)
# ------------------------------------------------------------------
# LearnPlugin identity
@ -75,7 +81,10 @@ class OpenCodePlugin(LearnPlugin, ConversationScanner):
@property
def description(self) -> str:
return "OpenCode (~/.local/share/opencode/opencode.db)"
return (
"OpenCode (~/.local/share/opencode/{opencode.db,opencode-local.db}; "
"HEADROOM_OPENCODE_DB overrides)"
)
def detect(self) -> bool:
return self._db_path.exists()
@ -177,6 +186,29 @@ class OpenCodePlugin(LearnPlugin, ConversationScanner):
return sessions
@staticmethod
def _resolve_db_path(db_path: Path | None) -> Path:
if db_path is not None:
return db_path
override = os.getenv(_OPENCODE_DB_ENV)
if override is not None:
return Path(override).expanduser()
ranked_candidates: list[tuple[int, int, Path]] = []
for name in _OPENCODE_DB_CANDIDATES:
candidate = _OPENCODE_DIR / name
try:
mtime_ns = candidate.stat().st_mtime_ns
except OSError:
continue
ranked_candidates.append((mtime_ns, 1 if name == "opencode.db" else 0, candidate))
if ranked_candidates:
return max(ranked_candidates)[2]
return _OPENCODE_DB
def _scan_session(
self,
conn: sqlite3.Connection,

View file

@ -3,16 +3,28 @@
from __future__ import annotations
import json
import os
import sqlite3
from pathlib import Path
import pytest
import headroom.learn.plugins.opencode as opencode_module
from headroom.learn.models import ErrorCategory
from headroom.learn.plugins.opencode import OpenCodePlugin
from headroom.learn.registry import get_registry, reset_registry
from headroom.learn.writer import CodexWriter
def _create_opencode_db(db_path: Path, project_path: Path) -> None:
def _create_opencode_db(
db_path: Path,
project_path: Path,
*,
project_id: str = "project-1",
project_name: str = "Headroom",
session_id: str = "session-1",
tool_command: str = "pytest",
) -> None:
conn = sqlite3.connect(db_path)
try:
conn.executescript(
@ -41,15 +53,15 @@ def _create_opencode_db(db_path: Path, project_path: Path) -> None:
)
conn.execute(
"INSERT INTO project (id, name, worktree) VALUES (?, ?, ?)",
("project-1", "Headroom", str(project_path)),
(project_id, project_name, str(project_path)),
)
conn.execute(
"INSERT INTO session (id, project_id, time_created) VALUES (?, ?, ?)",
("session-1", "project-1", 1_700_000_000_000),
(session_id, project_id, 1_700_000_000_000),
)
conn.execute(
"INSERT INTO message (id, session_id) VALUES (?, ?)",
("message-1", "session-1"),
("message-1", session_id),
)
conn.execute(
"INSERT INTO part (id, message_id, data, time_created) VALUES (?, ?, ?, ?)",
@ -63,7 +75,7 @@ def _create_opencode_db(db_path: Path, project_path: Path) -> None:
"callID": "call-1",
"state": {
"status": "error",
"input": {"command": "pytest"},
"input": {"command": tool_command},
"output": "Error: command failed with exit code 1",
},
}
@ -76,10 +88,28 @@ def _create_opencode_db(db_path: Path, project_path: Path) -> None:
conn.close()
def test_opencode_plugin_discovers_projects_and_scans_tool_failures(tmp_path: Path) -> None:
project_path = tmp_path / "repo"
def _patch_default_paths(monkeypatch: pytest.MonkeyPatch, db_dir: Path) -> tuple[Path, Path]:
canonical_db = db_dir / "opencode.db"
local_db = db_dir / "opencode-local.db"
monkeypatch.setattr(opencode_module, "_OPENCODE_DIR", db_dir, raising=False)
monkeypatch.setattr(opencode_module, "_OPENCODE_DB", canonical_db, raising=False)
return canonical_db, local_db
def _set_mtime(path: Path, *, seconds: int) -> None:
os.utime(path, ns=(seconds * 1_000_000_000, seconds * 1_000_000_000))
def _write_agents_file(project_path: Path) -> None:
project_path.mkdir()
(project_path / "AGENTS.md").write_text("# Existing context\n", encoding="utf-8")
def test_opencode_plugin_explicit_path_discovers_projects_and_scans_tool_failures(
tmp_path: Path,
) -> None:
project_path = tmp_path / "repo"
_write_agents_file(project_path)
db_path = tmp_path / "opencode.db"
_create_opencode_db(db_path, project_path)
@ -104,6 +134,192 @@ def test_opencode_plugin_discovers_projects_and_scans_tool_failures(tmp_path: Pa
assert tool_call.error_category == ErrorCategory.RUNTIME_ERROR
def test_opencode_plugin_newer_local_database_wins_by_default(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
project_path = tmp_path / "repo"
_write_agents_file(project_path)
db_dir = tmp_path / "opencode"
db_dir.mkdir()
canonical_db, local_db = _patch_default_paths(monkeypatch, db_dir)
_create_opencode_db(
canonical_db,
project_path,
project_name="Canonical",
tool_command="canonical-command",
)
_create_opencode_db(
local_db,
project_path,
project_name="Local",
tool_command="local-command",
)
_set_mtime(canonical_db, seconds=1)
_set_mtime(local_db, seconds=2)
plugin = OpenCodePlugin()
assert plugin.detect() is True
projects = plugin.discover_projects()
assert len(projects) == 1
assert projects[0].name == "Local"
sessions = plugin.scan_project(projects[0])
assert sessions[0].tool_calls[0].input_data == {"command": "local-command"}
def test_opencode_plugin_canonical_only_default_path(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
project_path = tmp_path / "repo"
_write_agents_file(project_path)
db_dir = tmp_path / "opencode"
db_dir.mkdir()
canonical_db, _ = _patch_default_paths(monkeypatch, db_dir)
_create_opencode_db(
canonical_db,
project_path,
project_name="Canonical",
tool_command="canonical-command",
)
plugin = OpenCodePlugin()
assert plugin.detect() is True
projects = plugin.discover_projects()
assert len(projects) == 1
assert projects[0].name == "Canonical"
assert plugin._db_path == canonical_db
def test_opencode_plugin_local_only_default_path(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
project_path = tmp_path / "repo"
_write_agents_file(project_path)
db_dir = tmp_path / "opencode"
db_dir.mkdir()
_, local_db = _patch_default_paths(monkeypatch, db_dir)
_create_opencode_db(
local_db,
project_path,
project_name="Local",
tool_command="local-command",
)
plugin = OpenCodePlugin()
assert plugin.detect() is True
projects = plugin.discover_projects()
assert len(projects) == 1
assert projects[0].name == "Local"
assert plugin._db_path == local_db
def test_opencode_plugin_equal_mtime_prefers_canonical(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
project_path = tmp_path / "repo"
_write_agents_file(project_path)
db_dir = tmp_path / "opencode"
db_dir.mkdir()
canonical_db, local_db = _patch_default_paths(monkeypatch, db_dir)
_create_opencode_db(
canonical_db,
project_path,
project_name="Canonical",
tool_command="canonical-command",
)
_create_opencode_db(
local_db,
project_path,
project_name="Local",
tool_command="local-command",
)
_set_mtime(canonical_db, seconds=1)
_set_mtime(local_db, seconds=1)
plugin = OpenCodePlugin()
assert plugin._db_path == canonical_db
projects = plugin.discover_projects()
assert len(projects) == 1
assert projects[0].name == "Canonical"
def test_opencode_plugin_env_override_wins(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
project_path = tmp_path / "repo"
_write_agents_file(project_path)
db_dir = tmp_path / "opencode"
db_dir.mkdir()
canonical_db, local_db = _patch_default_paths(monkeypatch, db_dir)
override_db = db_dir / "override.db"
_create_opencode_db(
canonical_db,
project_path,
project_name="Canonical",
tool_command="canonical-command",
)
_create_opencode_db(
local_db,
project_path,
project_name="Local",
tool_command="local-command",
)
_create_opencode_db(
override_db,
project_path,
project_name="Override",
tool_command="override-command",
)
_set_mtime(canonical_db, seconds=1)
_set_mtime(local_db, seconds=2)
monkeypatch.setenv(opencode_module._OPENCODE_DB_ENV, str(override_db))
plugin = OpenCodePlugin()
assert plugin._db_path == override_db
projects = plugin.discover_projects()
assert len(projects) == 1
assert projects[0].name == "Override"
def test_opencode_plugin_missing_override_stays_missing(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
project_path = tmp_path / "repo"
_write_agents_file(project_path)
db_dir = tmp_path / "opencode"
db_dir.mkdir()
canonical_db, local_db = _patch_default_paths(monkeypatch, db_dir)
missing_db = db_dir / "override-missing.db"
_create_opencode_db(canonical_db, project_path, project_name="Canonical")
_create_opencode_db(local_db, project_path, project_name="Local")
_set_mtime(canonical_db, seconds=1)
_set_mtime(local_db, seconds=2)
monkeypatch.setenv(opencode_module._OPENCODE_DB_ENV, str(missing_db))
plugin = OpenCodePlugin()
assert plugin._db_path == missing_db
assert plugin.detect() is False
assert plugin.discover_projects() == []
def test_opencode_plugin_no_default_database_detects_missing(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
db_dir = tmp_path / "opencode"
db_dir.mkdir()
canonical_db, _ = _patch_default_paths(monkeypatch, db_dir)
plugin = OpenCodePlugin()
assert plugin._db_path == canonical_db
assert plugin.detect() is False
assert plugin.discover_projects() == []
def test_opencode_plugin_uses_agents_writer(tmp_path: Path) -> None:
plugin = OpenCodePlugin(db_path=tmp_path / "missing.db")