ouroboros-ai 0.31.2.dev11__tar.gz → 0.31.2.dev13__tar.gz

{ouroboros_ai-0.31.2.dev11 → ouroboros_ai-0.31.2.dev13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.31.2.dev11
+Version: 0.31.2.dev13
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.31.2.dev11 → ouroboros_ai-0.31.2.dev13}/docs/README.md

@@ -48,6 +48,7 @@ replayable execution contract on your choice of runtime backend.
 
 - [Contributing Guide](../CONTRIBUTING.md) - How to set up, code, test, and submit PRs
 - [Architecture for Contributors](./contributing/architecture-overview.md) - How modules connect
+- [Agent OS Kernel Terminology](./contributing/agent-os-kernel-terminology.md) - Locked vocabulary for `AgentRuntimeContext`, `ControlPlane`, `ControlContract`, `Directive`, `ControlBus`, and `IOJournal`
 - [Testing Guide](./contributing/testing-guide.md) - Writing and running tests
 - [Key Patterns](./contributing/key-patterns.md) - Result type, immutability, event sourcing, protocols
 - [Findings Registry](./contributing/findings-registry.md) - Documentation audit findings registry

{ouroboros_ai-0.31.2.dev11 → ouroboros_ai-0.31.2.dev13}/docs/architecture.md

@@ -4,6 +4,12 @@
 
 Ouroboros is a **specification-first AI workflow engine** that transforms vague ideas into validated specifications before execution. Built on event sourcing with a rich TUI interface, it provides complete lifecycle management from requirements to evaluation.
 
+Agent OS terminology is intentionally locked so kernel-level PRs do not blur
+runtime context, control contracts, transport, and observability. See
+[Agent OS Kernel Terminology](./contributing/agent-os-kernel-terminology.md)
+for the canonical meanings of `AgentRuntimeContext`, `ControlPlane`,
+`ControlContract`, `Directive`, `ControlBus`, and `IOJournal`.
+
 ```
 ┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                                 OUROBOROS ARCHITECTURE                                               │

ouroboros_ai-0.31.2.dev13/docs/contributing/agent-os-kernel-terminology.md

@@ -0,0 +1,73 @@
+# Agent OS Kernel Terminology
+
+This document locks the kernel-level vocabulary for the Agent OS workstream.
+It exists so review comments and stacked PRs use the same words for runtime
+context, control decisions, transport, and journaled observability.
+
+## Locked Terms
+
+| Term | Layer | Definition | Naming Rule |
+|------|-------|------------|-------------|
+| `AgentRuntimeContext` | Runtime context | The per-agent execution envelope. It carries stable runtime dependencies and capabilities such as event storage, runtime backend identity, LLM backend identity, MCP bridge access, and control surfaces. | Use when describing what an agent process is allowed to see or use during a run. |
+| `ControlPlane` | Kernel control layer | The top-level conceptual layer for workflow control. It owns the vocabulary, contracts, routing rules, and transport surfaces that tell a runtime what should happen next. | Use for the architecture layer. Do not use `ControlBus` as the top-level concept. |
+| `ControlContract` | Control invariant layer | The stable schema and behavioral contract for control messages: allowed directives, terminal semantics, retry budgets, timeout behavior, resume invariants, and required journaling. | Use when a PR defines or changes an invariant that consumers must obey. |
+| `Directive` | Control vocabulary | The small, stable action alphabet emitted by decision sites, for example `CONTINUE`, `RETRY`, `WAIT`, `CANCEL`, and `CONVERGE`. | Use for the actual command value. Do not introduce local synonyms when an existing directive carries the meaning. |
+| `ControlBus` | Control transport | The in-process publish/subscribe implementation that delivers control events or directives to subscribers. It is a transport inside the `ControlPlane`, not the plane itself. | Use only for the implementation that dispatches messages. |
+| `IOJournal` | Observability journal | The durable record of external I/O, including paired LLM and tool call events. It explains what the runtime asked, what came back, and whether a call failed. | Use for the event-backed I/O log. Avoid treating ad hoc logs or stdout as the journal. |
+
+## Layering
+
+The intended relationship is:
+
+```text
+AgentRuntimeContext
+  -> exposes ControlPlane and runtime capabilities to a running agent
+
+ControlPlane
+  -> governed by ControlContract
+  -> emits Directive values
+  -> may use ControlBus as an in-process transport
+  -> persists durable decisions through control.* events
+
+IOJournal
+  -> records external LLM/tool I/O alongside control decisions
+```
+
+In OS terms, `AgentRuntimeContext` is the process execution envelope,
+`ControlPlane` is the kernel control layer, `ControlContract` is the syscall
+contract, `Directive` is the command vocabulary, `ControlBus` is one local
+delivery mechanism, and `IOJournal` is the replayable black box.
+
+## Control Contract Invariants
+
+The following invariants should guide Agent OS PR review:
+
+- Terminal directives are terminal. After `CANCEL` or `CONVERGE`, a runtime
+  must not start new work for the same execution unless a new contract ID or
+  explicit rerun is allocated.
+- Retry behavior belongs to the control contract. `RETRY` must respect the
+  owning retry budget and must be journaled with enough context to explain why
+  the retry happened.
+- `WAIT` means no forward progress until the awaited input, timeout, or queued
+  event arrives.
+- Resume must preserve the original execution envelope: runtime backend, LLM
+  backend, working directory, MCP bridge capability, and user-selected safety
+  options must not silently change.
+- Every durable control decision must be reconstructable from the event store.
+  Reactive delivery through `ControlBus` is not a substitute for persistence.
+- External I/O that influences a decision must be reconstructable from the
+  `IOJournal`, using paired request/return events when possible.
+
+## Review Guidance
+
+When reviewing Agent OS PRs:
+
+- Ask whether the change belongs to context, contract, vocabulary, transport,
+  or journal.
+- Prefer `ControlPlane` for architecture discussions and `ControlBus` only for
+  the in-process pub/sub implementation.
+- Treat `ControlContract` changes as compatibility-sensitive, even when the
+  code diff is small.
+- Treat `IOJournal` gaps as observability bugs when they prevent replaying why
+  a control decision happened.
+- Treat resume drift as a control-contract bug, not a CLI polish issue.

{ouroboros_ai-0.31.2.dev11 → ouroboros_ai-0.31.2.dev13}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.31.2.dev11'
-__version_tuple__ = version_tuple = (0, 31, 2, 'dev11')
+__version__ = version = '0.31.2.dev13'
+__version_tuple__ = version_tuple = (0, 31, 2, 'dev13')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.31.2.dev11 → ouroboros_ai-0.31.2.dev13}/src/ouroboros/cli/commands/setup.py

@@ -12,7 +12,9 @@ Also provides brownfield repository management subcommands:
 from __future__ import annotations
 
 import asyncio
+from contextlib import contextmanager
 import json
+import os
 from pathlib import Path
 import shutil
 from typing import Annotated
@@ -718,6 +720,21 @@ def _detect_opencode_mcp_command() -> dict[str, list[str]] | None:
 # this file keeps its historic `_BRIDGE_PLUGIN_*` naming.
 
 
+@contextmanager
+def _temporary_opencode_cli_path(opencode_path: str):
+    """Expose the setup-selected OpenCode CLI path to config-dir discovery."""
+    key = "OUROBOROS_OPENCODE_CLI_PATH"
+    previous = os.environ.get(key)
+    os.environ[key] = opencode_path
+    try:
+        yield
+    finally:
+        if previous is None:
+            os.environ.pop(key, None)
+        else:
+            os.environ[key] = previous
+
+
 def _bridge_plugin_source_text() -> str | None:
     """Return the bridge plugin TypeScript source, or ``None`` when missing.
 
@@ -778,7 +795,7 @@ def _install_opencode_bridge_plugin() -> bool:
     Writes to the platform-appropriate OpenCode plugins directory:
 
     * Linux:   ``~/.config/opencode/plugins/ouroboros-bridge/``
-    * macOS:   ``~/Library/Application Support/OpenCode/plugins/ouroboros-bridge/``
+    * macOS:   ``~/.config/opencode/plugins/ouroboros-bridge/`` (or the directory reported by ``opencode debug paths``)
     * Windows: ``%APPDATA%\\OpenCode\\plugins\\ouroboros-bridge\\``
 
     Robustness:
@@ -1003,7 +1020,8 @@ def _setup_opencode(opencode_path: str, mode: str = "plugin") -> bool:
 
         # Mutual-exclusion cleanup: remove plugin-mode artifacts so both
         # paths are not active simultaneously (duplicate dispatch).
-        _cleanup_plugin_artifacts()
+        with _temporary_opencode_cli_path(opencode_path):
+            _cleanup_plugin_artifacts()
 
         print_success(f"Configured OpenCode subprocess runtime (CLI: {opencode_path})")
         print_info(f"Config saved to: {config_path}")
@@ -1013,9 +1031,10 @@ def _setup_opencode(opencode_path: str, mode: str = "plugin") -> bool:
     # if ALL steps succeed (fail-closed).  Without this, a failed bridge install
     # leaves the user in plugin mode without a working bridge — subsequent runs
     # take the plugin dispatch path and silently break.
-    _install_ok = _install_opencode_bridge_plugin()
-    _mcp_ok = _ensure_opencode_mcp_entry()
-    _plugin_ok = _ensure_opencode_plugin_entry()
+    with _temporary_opencode_cli_path(opencode_path):
+        _install_ok = _install_opencode_bridge_plugin()
+        _mcp_ok = _ensure_opencode_mcp_entry()
+        _plugin_ok = _ensure_opencode_plugin_entry()
 
     if not (_install_ok and _mcp_ok and _plugin_ok):
         failed = []

ouroboros_ai-0.31.2.dev13/src/ouroboros/cli/opencode_config.py

@@ -0,0 +1,179 @@
+"""Shared helpers for locating the OpenCode configuration file.
+
+Both :mod:`~ouroboros.cli.commands.setup` and
+:mod:`~ouroboros.cli.commands.uninstall` need to find the same config file;
+centralising the logic here avoids duplication and keeps the ``PermissionError``
+/ ``OSError`` guard in one place.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+import yaml
+
+
+def _expand_config_dir(raw: str) -> Path:
+    """Expand an OpenCode config directory string into a :class:`Path`."""
+    return Path(raw).expanduser()
+
+
+def _configured_opencode_cli_path() -> Path | None:
+    """Return the setup-selected OpenCode CLI path when one is persisted.
+
+    Path discovery must be stable across setup, cleanup, and uninstall.  Do not
+    fall back to whichever ``opencode`` happens to be on ``PATH`` here: machines
+    can have several OpenCode installs, and uninstall should target the same
+    install tree that setup recorded.
+    """
+    for key in ("OUROBOROS_OPENCODE_CLI_PATH", "OPENCODE_CLI_PATH"):
+        raw = os.environ.get(key, "").strip()
+        if raw:
+            return Path(raw).expanduser()
+
+    config_path = Path.home() / ".ouroboros" / "config.yaml"
+    try:
+        config = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(config, dict):
+        return None
+    orchestrator = config.get("orchestrator")
+    if not isinstance(orchestrator, dict):
+        return None
+    raw = orchestrator.get("opencode_cli_path")
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    return Path(raw.strip()).expanduser()
+
+
+def _debug_paths_config_dir() -> Path | None:
+    """Return ``opencode debug paths`` config dir when the CLI reports one.
+
+    Current OpenCode releases expose the authoritative runtime directories via
+    ``opencode debug paths``. Querying it first avoids baking version-specific
+    platform assumptions into Ouroboros. Any failure falls back to deterministic
+    local resolution so setup still works on machines without OpenCode on PATH.
+    """
+    opencode = _configured_opencode_cli_path()
+    if not opencode:
+        return None
+    try:
+        result = subprocess.run(
+            [str(opencode), "debug", "paths"],
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=5,
+        )
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    for line in result.stdout.splitlines():
+        parts = line.split(None, 1)
+        if len(parts) == 2 and parts[0] == "config":
+            return _expand_config_dir(parts[1])
+    return None
+
+
+def opencode_config_dir() -> Path:
+    """Return the active OpenCode global config directory.
+
+    Resolution order:
+
+    1. ``OPENCODE_CONFIG_DIR`` when explicitly set.
+    2. ``opencode debug paths`` ``config`` value when the CLI is available.
+    3. XDG-style default (``$XDG_CONFIG_HOME/opencode`` or
+       ``~/.config/opencode``) on macOS/Linux/other Unix platforms.
+    4. Windows roaming config directory for Windows.
+
+    Older Ouroboros releases wrote macOS config under
+    ``~/Library/Application Support/OpenCode``. Current OpenCode releases use
+    XDG config paths on macOS too, so that legacy directory is intentionally not
+    the default unless OpenCode itself reports it through ``debug paths``.
+    """
+    explicit = os.environ.get("OPENCODE_CONFIG_DIR")
+    if explicit:
+        return _expand_config_dir(explicit)
+
+    reported = _debug_paths_config_dir()
+    if reported is not None:
+        return reported
+
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+        return Path(appdata) / "OpenCode"
+
+    xdg = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(xdg) / "opencode"
+
+
+def find_opencode_config(*, allow_default: bool = True) -> Path | None:
+    """Locate the existing OpenCode config file.
+
+    OpenCode checks (in order): ``opencode.jsonc``, ``opencode.json`` —
+    both inside :func:`opencode_config_dir`.
+
+    Args:
+        allow_default: When ``True`` (setup path), return
+            ``<config_dir>/opencode.json`` as a default for new
+            installations if neither file exists.  When ``False``
+            (uninstall path), return ``None`` so the caller can skip
+            cleanly when no config is present.
+
+    Returns:
+        The first existing config path, the default path (when
+        *allow_default* is ``True``), or ``None``.
+    """
+    explicit_config = os.environ.get("OPENCODE_CONFIG")
+    if explicit_config:
+        config_path = Path(explicit_config).expanduser()
+        if allow_default or config_path.exists():
+            return config_path
+        return None
+
+    config_dir = opencode_config_dir()
+    for name in ("opencode.jsonc", "opencode.json"):
+        candidate = config_dir / name
+        try:
+            if candidate.exists():
+                return candidate
+        except OSError:
+            continue
+    return (config_dir / "opencode.json") if allow_default else None
+
+
+# ── Bridge-plugin identity ───────────────────────────────────────
+# Canonical subdirectory + filename of the OpenCode bridge plugin.
+# Shared by setup (install + dedupe) and uninstall (tail-match removal)
+# so both paths agree on what counts as "a bridge-plugin entry".
+BRIDGE_PLUGIN_SUBDIR: tuple[str, str] = ("plugins", "ouroboros-bridge")
+BRIDGE_PLUGIN_FILENAME: str = "ouroboros-bridge.ts"
+
+
+def is_bridge_plugin_entry(entry: object) -> bool:
+    """Return ``True`` when *entry* refers to any bridge-plugin install.
+
+    Matches by directory-tail (``plugins/ouroboros-bridge``) + basename
+    (``ouroboros-bridge.ts``) rather than exact string equality — catches
+    stale entries from XDG reshuffles, Windows mixed separators, legacy
+    install paths, and sudo/root migrations. Setup uses this for dedupe;
+    uninstall uses it to remove stale entries, not just the exact
+    canonical path for this machine's current config layout.
+    """
+    if not isinstance(entry, str) or not entry:
+        return False
+    # Normalise path separators so Windows entries (``\``) compare equal.
+    normalised = entry.replace("\\", "/")
+    parts = [p for p in normalised.split("/") if p]
+    if len(parts) < 3:
+        return False
+    return (
+        parts[-1] == BRIDGE_PLUGIN_FILENAME
+        and parts[-2] == BRIDGE_PLUGIN_SUBDIR[1]
+        and parts[-3] == BRIDGE_PLUGIN_SUBDIR[0]
+    )

{ouroboros_ai-0.31.2.dev11 → ouroboros_ai-0.31.2.dev13}/src/ouroboros/opencode/plugin/ouroboros-bridge.test.ts

@@ -64,10 +64,18 @@ describe("cfg — platform config dir", () => {
     expect(cfg()).toBe("/home/u/.config/opencode")
   })
 
-  test("darwin uses Library/Application Support", () => {
+  test("darwin uses XDG-style config path", () => {
     process.env.HOME = "/Users/u"
+    delete process.env.XDG_CONFIG_HOME
+    Object.defineProperty(process, "platform", { value: "darwin" })
+    expect(cfg()).toBe("/Users/u/.config/opencode")
+  })
+
+  test("OPENCODE_CONFIG_DIR overrides platform defaults", () => {
+    process.env.HOME = "/Users/u"
+    process.env.OPENCODE_CONFIG_DIR = "/custom/opencode"
     Object.defineProperty(process, "platform", { value: "darwin" })
-    expect(cfg()).toBe("/Users/u/Library/Application Support/OpenCode")
+    expect(cfg()).toBe("/custom/opencode")
   })
 
   test("win32 uses APPDATA when present", () => {

{ouroboros_ai-0.31.2.dev11 → ouroboros_ai-0.31.2.dev13}/src/ouroboros/opencode/plugin/ouroboros-bridge.ts

@@ -6,10 +6,10 @@ import { randomBytes } from "crypto"
 // Platform-aware opencode config dir
 export function cfg(): string {
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp"
+  if (process.env.OPENCODE_CONFIG_DIR)
+    return process.env.OPENCODE_CONFIG_DIR
   if (process.platform === "win32")
     return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "OpenCode")
-  if (process.platform === "darwin")
-    return join(home, "Library", "Application Support", "OpenCode")
   return join(process.env.XDG_CONFIG_HOME ?? join(home, ".config"), "opencode")
 }
 
@@ -557,4 +557,3 @@ export default {
 
 // Test-only exports for mocked-client coverage.
 export { resolveMid as _resolveMid, dispatch as _dispatch, patch as _patch, sleep as _sleep, PATCH_RETRIES as _PATCH_RETRIES, RESOLVE_RETRIES as _RESOLVE_RETRIES }
-

ouroboros_ai-0.31.2.dev13/tests/unit/cli/test_opencode_config.py

@@ -0,0 +1,244 @@
+"""Unit tests for the shared opencode_config helper.
+
+All tests patch ``opencode_config_dir`` directly so they are
+platform-agnostic — no reliance on Linux-specific XDG paths.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from ouroboros.cli.opencode_config import find_opencode_config, opencode_config_dir
+
+_OCD = "ouroboros.cli.opencode_config.opencode_config_dir"
+
+
+class TestFindOpencodeConfig:
+    """Tests for find_opencode_config()."""
+
+    def test_prefers_jsonc_over_json(self, tmp_path: Path) -> None:
+        """opencode.jsonc takes priority over opencode.json when both exist."""
+        config_dir = tmp_path / "opencode"
+        config_dir.mkdir()
+        jsonc = config_dir / "opencode.jsonc"
+        json_ = config_dir / "opencode.json"
+        jsonc.write_text("{}")
+        json_.write_text("{}")
+
+        with patch(_OCD, return_value=config_dir):
+            result = find_opencode_config(allow_default=True)
+
+        assert result == jsonc
+
+    def test_falls_back_to_json_when_no_jsonc(self, tmp_path: Path) -> None:
+        """Returns opencode.json when only that file exists."""
+        config_dir = tmp_path / "opencode"
+        config_dir.mkdir()
+        json_ = config_dir / "opencode.json"
+        json_.write_text("{}")
+
+        with patch(_OCD, return_value=config_dir):
+            result = find_opencode_config(allow_default=True)
+
+        assert result == json_
+
+    def test_allow_default_true_returns_default_when_missing(self, tmp_path: Path) -> None:
+        """Returns default opencode.json path when no config exists and allow_default=True."""
+        config_dir = tmp_path / "opencode"
+        config_dir.mkdir()
+
+        with patch(_OCD, return_value=config_dir):
+            result = find_opencode_config(allow_default=True)
+
+        assert result == config_dir / "opencode.json"
+        assert result is not None
+
+    def test_allow_default_false_returns_none_when_missing(self, tmp_path: Path) -> None:
+        """Returns None when no config exists and allow_default=False."""
+        config_dir = tmp_path / "opencode"
+        config_dir.mkdir()
+
+        with patch(_OCD, return_value=config_dir):
+            result = find_opencode_config(allow_default=False)
+
+        assert result is None
+
+    def test_allow_default_false_returns_existing_file(self, tmp_path: Path) -> None:
+        """Returns existing file even when allow_default=False."""
+        config_dir = tmp_path / "opencode"
+        config_dir.mkdir()
+        jsonc = config_dir / "opencode.jsonc"
+        jsonc.write_text("{}")
+
+        with patch(_OCD, return_value=config_dir):
+            result = find_opencode_config(allow_default=False)
+
+        assert result == jsonc
+
+    def test_oserror_on_candidate_is_skipped(self, tmp_path: Path) -> None:
+        """OSError on exists() check is silently skipped — fallback continues."""
+        config_dir = tmp_path / "opencode"
+        config_dir.mkdir()
+        json_ = config_dir / "opencode.json"
+        json_.write_text("{}")
+
+        original_exists = Path.exists
+
+        def patched_exists(self: Path) -> bool:
+            if self.name == "opencode.jsonc":
+                raise OSError("permission denied")
+            return original_exists(self)
+
+        with (
+            patch(_OCD, return_value=config_dir),
+            patch.object(Path, "exists", patched_exists),
+        ):
+            result = find_opencode_config(allow_default=True)
+
+        # jsonc errored, falls through to json which exists
+        assert result == json_
+
+    def test_returns_jsonc_path_type(self, tmp_path: Path) -> None:
+        """Return value is always a Path instance (not str)."""
+        config_dir = tmp_path / "opencode"
+        config_dir.mkdir()
+        (config_dir / "opencode.jsonc").write_text("{}")
+
+        with patch(_OCD, return_value=config_dir):
+            result = find_opencode_config(allow_default=True)
+
+        assert isinstance(result, Path)
+
+    def test_honors_opencode_config_file_env(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """OPENCODE_CONFIG points setup at an explicit config file."""
+        explicit = tmp_path / "custom" / "opencode.json"
+        monkeypatch.setenv("OPENCODE_CONFIG", str(explicit))
+
+        result = find_opencode_config(allow_default=True)
+
+        assert result == explicit
+
+    def test_opencode_config_file_env_requires_existing_when_no_default(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Uninstall-style lookup ignores a missing OPENCODE_CONFIG file."""
+        explicit = tmp_path / "missing.json"
+        monkeypatch.setenv("OPENCODE_CONFIG", str(explicit))
+
+        result = find_opencode_config(allow_default=False)
+
+        assert result is None
+
+
+class TestOpencodeConfigDir:
+    """Tests for active OpenCode config-directory resolution."""
+
+    def test_honors_opencode_config_dir_env(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """OPENCODE_CONFIG_DIR is the strongest explicit directory override."""
+        custom = tmp_path / "custom-opencode"
+        monkeypatch.setenv("OPENCODE_CONFIG_DIR", str(custom))
+
+        result = opencode_config_dir()
+
+        assert result == custom
+
+    def test_uses_debug_paths_config_when_available(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """The OpenCode CLI-reported config dir is authoritative."""
+        reported = tmp_path / ".config" / "opencode"
+        monkeypatch.delenv("OPENCODE_CONFIG_DIR", raising=False)
+        monkeypatch.setenv("OUROBOROS_OPENCODE_CLI_PATH", "/bin/opencode")
+        monkeypatch.delenv("OPENCODE_CLI_PATH", raising=False)
+
+        completed = SimpleNamespace(
+            returncode=0,
+            stdout=f"home       {tmp_path}\nconfig     {reported}\nstate      {tmp_path / '.state'}\n",
+        )
+        with patch("ouroboros.cli.opencode_config.subprocess.run", return_value=completed) as run:
+            result = opencode_config_dir()
+
+        assert result == reported
+        run.assert_called_once()
+        assert run.call_args.args[0][:3] == ["/bin/opencode", "debug", "paths"]
+
+    def test_uses_persisted_opencode_cli_path_for_debug_paths(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Post-setup cleanup/uninstall use the configured OpenCode binary."""
+        reported = tmp_path / "active" / "opencode"
+        config_dir = tmp_path / ".ouroboros"
+        config_dir.mkdir()
+        (config_dir / "config.yaml").write_text(
+            "orchestrator:\n  opencode_cli_path: /configured/bin/opencode\n",
+            encoding="utf-8",
+        )
+        monkeypatch.delenv("OPENCODE_CONFIG_DIR", raising=False)
+        monkeypatch.delenv("OUROBOROS_OPENCODE_CLI_PATH", raising=False)
+        monkeypatch.delenv("OPENCODE_CLI_PATH", raising=False)
+
+        completed = SimpleNamespace(returncode=0, stdout=f"config     {reported}\n")
+        with (
+            patch("pathlib.Path.home", return_value=tmp_path),
+            patch("ouroboros.cli.opencode_config.subprocess.run", return_value=completed) as run,
+        ):
+            result = opencode_config_dir()
+
+        assert result == reported
+        assert run.call_args.args[0][:3] == ["/configured/bin/opencode", "debug", "paths"]
+
+    def test_does_not_query_path_opencode_without_configured_cli(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Avoid targeting a different OpenCode install from PATH after setup."""
+        monkeypatch.delenv("OPENCODE_CONFIG_DIR", raising=False)
+        monkeypatch.delenv("OUROBOROS_OPENCODE_CLI_PATH", raising=False)
+        monkeypatch.delenv("OPENCODE_CLI_PATH", raising=False)
+        monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+
+        with (
+            patch("pathlib.Path.home", return_value=tmp_path),
+            patch("ouroboros.cli.opencode_config.subprocess.run") as run,
+        ):
+            result = opencode_config_dir()
+
+        assert result == tmp_path / ".config" / "opencode"
+        run.assert_not_called()
+
+    def test_darwin_defaults_to_xdg_config_path(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Modern OpenCode uses XDG config on macOS, not Application Support."""
+        monkeypatch.delenv("OPENCODE_CONFIG_DIR", raising=False)
+        monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+
+        with (
+            patch("ouroboros.cli.opencode_config.sys.platform", "darwin"),
+            patch("pathlib.Path.home", return_value=tmp_path),
+        ):
+            result = opencode_config_dir()
+
+        assert result == tmp_path / ".config" / "opencode"
+
+    def test_darwin_honors_xdg_config_home(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """XDG_CONFIG_HOME applies on macOS as it does on Linux."""
+        xdg = tmp_path / "xdg"
+        monkeypatch.delenv("OPENCODE_CONFIG_DIR", raising=False)
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(xdg))
+
+        with (
+            patch("ouroboros.cli.opencode_config.sys.platform", "darwin"),
+        ):
+            result = opencode_config_dir()
+
+        assert result == xdg / "opencode"