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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.31.2.dev13
+Version: 0.31.2.dev14
 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.dev13 → ouroboros_ai-0.31.2.dev14}/docs/cli-reference.md

@@ -71,6 +71,7 @@ ouroboros setup [OPTIONS]
 | `-r, --runtime TEXT` | Runtime backend to configure. Shipped values: `claude`, `codex`, `opencode`. Auto-detected if omitted |
 | `--opencode-mode TEXT` | OpenCode integration mode: `plugin` (default, recommended — bridge plugin for interactive sessions) or `subprocess` (headless/CI). Mutually exclusive — see [OpenCode runtime guide](runtime-guides/opencode.md#configuration) |
 | `--non-interactive` | Skip interactive prompts (for scripted installs) |
+| `--mcp-mode TEXT` | Codex MCP config mode: `auto` (default), `preserve`, or `stdio` |
 
 **Examples:**
 
@@ -97,11 +98,11 @@ ouroboros setup --non-interactive
 - For Codex CLI: sets `orchestrator.codex_cli_path` and `llm.backend: codex` in `~/.ouroboros/config.yaml`
 - For Codex CLI: installs managed Ouroboros rules into `~/.codex/rules/`
 - For Codex CLI: installs managed Ouroboros skills into `~/.codex/skills/`
-- For Codex CLI: registers the Ouroboros MCP/env block in `~/.codex/config.toml`
+- For Codex CLI: registers the Ouroboros MCP/env block in `~/.codex/config.toml` when absent, refreshes setup-managed stdio blocks, and preserves user-managed URL/custom blocks by default
 - For OpenCode: registers the Ouroboros MCP server in OpenCode's configuration
 - For OpenCode (plugin mode): installs the bridge plugin into `<opencode_config_dir>/plugins/ouroboros-bridge/`
 
-> **Codex config split:** put persistent Ouroboros per-role model overrides in `~/.ouroboros/config.yaml` (`clarification.default_model`, `llm.qa_model`, `evaluation.semantic_model`, `consensus.models`, `consensus.advocate_model`, `consensus.devil_model`, `consensus.judge_model`). `~/.codex/config.toml` is only the Codex MCP/env hookup file used by setup.
+> **Codex config split:** put persistent Ouroboros per-role model overrides in `~/.ouroboros/config.yaml` (`clarification.default_model`, `llm.qa_model`, `evaluation.semantic_model`, `consensus.models`, `consensus.advocate_model`, `consensus.devil_model`, `consensus.judge_model`). `~/.codex/config.toml` is only the Codex MCP/env hookup file used by setup. If you run a long-lived URL-based Ouroboros MCP server, setup preserves that user-managed entry in the default `--mcp-mode auto`; use `--mcp-mode stdio` only when you intentionally want setup to replace it.
 
 ### Brownfield Subcommands
 
@@ -423,6 +424,21 @@ ouroboros config validate
 
 ---
 
+
+## `ouroboros codex`
+
+Manage Codex-specific Ouroboros integration artifacts.
+
+### `codex refresh`
+
+Refresh the packaged Codex-side Ouroboros rules and skills without changing MCP or Ouroboros config files.
+
+```bash
+ouroboros codex refresh
+```
+
+This command updates packaged `~/.codex/rules/ouroboros*.md` and `~/.codex/skills/ouroboros-*` artifacts. It does not modify `~/.codex/config.toml` or `~/.ouroboros/config.yaml`. It intentionally does not prune extra `ouroboros-*` files because prefix ownership can include user-managed artifacts.
+
 ## `ouroboros uninstall`
 
 Cleanly remove all Ouroboros configuration from your system. Reverses everything `ouroboros setup` did.
@@ -459,7 +475,7 @@ ouroboros uninstall --keep-data
 
 - `ouroboros` entry from `~/.claude/mcp.json`
 - `[mcp_servers.ouroboros]` section from `~/.codex/config.toml`
-- `~/.codex/rules/ouroboros.md` and `~/.codex/skills/ouroboros/`
+- `~/.codex/rules/ouroboros*.md` and `~/.codex/skills/ouroboros-*`
 - `<!-- ooo:START -->` … `<!-- ooo:END -->` block from `CLAUDE.md`
 - OpenCode bridge plugin (`<opencode_config_dir>/plugins/ouroboros-bridge/`) and its entry in `opencode.jsonc`
 - `.ouroboros/` directory in the current project

{ouroboros_ai-0.31.2.dev13 → ouroboros_ai-0.31.2.dev14}/docs/getting-started.md

@@ -172,7 +172,7 @@ consensus:
   judge_model: gpt-5.4
 ```
 
-`ouroboros setup --runtime codex` uses `~/.codex/config.toml` only for the Codex MCP/env hookup and installs managed Ouroboros rules/skills into `~/.codex/`.
+`ouroboros setup --runtime codex` uses `~/.codex/config.toml` only for the Codex MCP/env hookup and installs managed Ouroboros rules/skills into `~/.codex/`. Existing URL/custom Ouroboros MCP entries are preserved by default; run `ouroboros codex refresh` when you only need to refresh `~/.codex/rules/ouroboros*.md` and `~/.codex/skills/ouroboros-*`.
 
 ### Environment Variables
 

{ouroboros_ai-0.31.2.dev13 → ouroboros_ai-0.31.2.dev14}/docs/runtime-guides/codex.md

@@ -112,13 +112,13 @@ Under the hood, `CodexCliRuntime` still talks to the local `codex` executable, b
 - Records `orchestrator.codex_cli_path` when available
 - Installs managed Ouroboros rules into `~/.codex/rules/`
 - Installs managed Ouroboros skills into `~/.codex/skills/`
-- Registers the Ouroboros MCP/env hookup in `~/.codex/config.toml`
+- Registers the Ouroboros MCP/env hookup in `~/.codex/config.toml` when absent, refreshes setup-managed stdio blocks, and preserves user-managed URL/custom entries by default
 
-`~/.codex/config.toml` is not where Ouroboros per-role model overrides belong. Keep `clarification`, `qa`, `semantic`, and `consensus` model settings in `~/.ouroboros/config.yaml`.
+`~/.codex/config.toml` is not where Ouroboros per-role model overrides belong. Keep `clarification`, `qa`, `semantic`, and `consensus` model settings in `~/.ouroboros/config.yaml`. If you manage a long-running URL-based Ouroboros MCP server, keep that URL entry in `~/.codex/config.toml`; `ouroboros setup --runtime codex` preserves it by default. Use `--mcp-mode stdio` only when you intentionally want setup to replace the entry with the managed command-spawned server.
 
 ### `ooo` Skill Availability on Codex
 
-After running `ouroboros setup --runtime codex`, the bundled `ooo` skills are installed into `~/.codex/skills/` and the routing rules into `~/.codex/rules/`. The table below shows each skill and its CLI equivalent for terminal-only workflows.
+After running `ouroboros setup --runtime codex`, the bundled `ooo` skills are installed into `~/.codex/skills/ouroboros-*` and the routing rules into `~/.codex/rules/`. To refresh only those artifacts after upgrading Ouroboros, run `ouroboros codex refresh`; it does not modify `~/.codex/config.toml` or `~/.ouroboros/config.yaml`. The table below shows each skill and its CLI equivalent for terminal-only workflows.
 
 | `ooo` Skill | Codex session | CLI equivalent (Terminal) |
 |-------------|---------------|--------------------------|

{ouroboros_ai-0.31.2.dev13 → ouroboros_ai-0.31.2.dev14}/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.dev13'
-__version_tuple__ = version_tuple = (0, 31, 2, 'dev13')
+__version__ = version = '0.31.2.dev14'
+__version_tuple__ = version_tuple = (0, 31, 2, 'dev14')
 
 __commit_id__ = commit_id = None

ouroboros_ai-0.31.2.dev14/src/ouroboros/cli/commands/codex.py

@@ -0,0 +1,35 @@
+"""Codex CLI integration helper commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from ouroboros.cli.formatters.panels import print_error, print_success
+from ouroboros.codex import install_codex_artifacts
+
+app = typer.Typer(
+    name="codex",
+    help="Manage Ouroboros Codex CLI integration artifacts.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def codex() -> None:
+    """Manage Ouroboros Codex CLI integration artifacts."""
+
+
+@app.command("refresh")
+def refresh() -> None:
+    """Refresh Codex rules and skills without changing MCP or Ouroboros config."""
+    codex_dir = Path.home() / ".codex"
+    try:
+        result = install_codex_artifacts(codex_dir=codex_dir, prune=False)
+    except FileNotFoundError as exc:
+        print_error(str(exc))
+        raise typer.Exit(1) from exc
+
+    print_success(f"Installed Codex rules → {result.rules_path}")
+    print_success(f"Installed {len(result.skill_paths)} Codex skills → {codex_dir / 'skills'}")

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

@@ -17,7 +17,7 @@ import json
 import os
 from pathlib import Path
 import shutil
-from typing import Annotated
+from typing import Annotated, Literal
 
 from rich.prompt import Prompt
 from rich.table import Table
@@ -206,6 +206,43 @@ _CODEX_MCP_COMMENT_LINES = (
     "# This file is only for the Codex MCP/env registration block.",
 )
 
+CodexMcpMode = Literal["auto", "preserve", "stdio"]
+_CODEX_MCP_ARGS = ["--from", "ouroboros-ai[mcp]", "ouroboros", "mcp", "serve"]
+
+
+def _normalize_codex_mcp_mode(value: str) -> CodexMcpMode:
+    """Validate and normalize the Codex MCP setup mode."""
+    normalized = value.lower()
+    if normalized not in {"auto", "preserve", "stdio"}:
+        print_error("Unsupported Codex MCP mode. Use one of: auto, preserve, stdio.")
+        raise typer.Exit(1)
+    return normalized  # type: ignore[return-value]
+
+
+def _codex_mcp_entry_from_toml(data: dict[str, object]) -> dict[str, object] | None:
+    """Return the parsed Ouroboros Codex MCP entry, if present."""
+    mcp_servers = data.get("mcp_servers")
+    if not isinstance(mcp_servers, dict):
+        return None
+    entry = mcp_servers.get("ouroboros")
+    return entry if isinstance(entry, dict) else None
+
+
+def _is_setup_managed_codex_mcp_entry(entry: dict[str, object]) -> bool:
+    """Return whether setup may safely replace this Codex MCP entry."""
+    if "url" in entry:
+        return False
+
+    command = entry.get("command")
+    args = entry.get("args")
+    if command != "uvx" or not isinstance(args, list):
+        return False
+
+    # Current setup-managed config and older setup-managed uvx configs both
+    # end by launching `ouroboros mcp serve`. Editable/worktree configs often
+    # use a direct command path and are intentionally treated as user-managed.
+    return len(args) >= 3 and args[-3:] == ["ouroboros", "mcp", "serve"]
+
 
 def _is_codex_ouroboros_table_header(line: str) -> bool:
     """Return True when the line starts the managed Codex MCP table."""
@@ -270,21 +307,33 @@ def _upsert_codex_mcp_section(raw: str) -> tuple[str, bool]:
     return "\n".join(output_lines).rstrip() + "\n", existed_before
 
 
-def _register_codex_mcp_server() -> None:
+def _register_codex_mcp_server(*, mode: CodexMcpMode = "auto") -> None:
     """Register the Ouroboros MCP/env hookup in ~/.codex/config.toml."""
     import tomllib
 
+    if mode == "preserve":
+        print_info("Preserved Codex MCP config.")
+        return
+
     codex_config = Path.home() / ".codex" / "config.toml"
     codex_config.parent.mkdir(parents=True, exist_ok=True)
 
     if codex_config.exists():
         raw = codex_config.read_text(encoding="utf-8")
         try:
-            tomllib.loads(raw)
+            parsed = tomllib.loads(raw)
         except tomllib.TOMLDecodeError:
             print_error(f"Could not parse {codex_config} — skipping MCP registration.")
             return
 
+        entry = _codex_mcp_entry_from_toml(parsed)
+        if mode == "auto" and entry is not None and not _is_setup_managed_codex_mcp_entry(entry):
+            print_info(
+                "Preserved existing user-managed Ouroboros MCP config in "
+                f"{codex_config}. Use --mcp-mode stdio to replace it."
+            )
+            return
+
         updated_raw, existed_before = _upsert_codex_mcp_section(raw)
         if updated_raw == raw:
             print_info("Codex MCP server already up to date.")
@@ -308,24 +357,19 @@ def _print_codex_config_guidance(config_path: Path) -> None:
 
 def _install_codex_artifacts() -> None:
     """Install packaged Ouroboros rules and skills into ~/.codex/."""
-    from ouroboros.codex import install_codex_rules, install_codex_skills
+    from ouroboros.codex import install_codex_artifacts
 
     codex_dir = Path.home() / ".codex"
 
     try:
-        rules_path = install_codex_rules(codex_dir=codex_dir, prune=True)
-        print_success(f"Installed Codex rules → {rules_path}")
+        result = install_codex_artifacts(codex_dir=codex_dir, prune=True)
+        print_success(f"Installed Codex rules → {result.rules_path}")
+        print_success(f"Installed {len(result.skill_paths)} Codex skills → {codex_dir / 'skills'}")
     except FileNotFoundError:
-        print_error("Could not locate packaged Codex rules.")
-
-    try:
-        skill_paths = install_codex_skills(codex_dir=codex_dir, prune=True)
-        print_success(f"Installed {len(skill_paths)} Codex skills → {codex_dir / 'skills'}")
-    except FileNotFoundError:
-        print_error("Could not locate packaged Codex skills.")
+        print_error("Could not locate packaged Codex rules or skills.")
 
 
-def _setup_codex(codex_path: str) -> None:
+def _setup_codex(codex_path: str, *, mcp_mode: CodexMcpMode = "auto") -> None:
     """Configure Ouroboros for the Codex runtime."""
     from ouroboros.config.loader import create_default_config, ensure_config_dir
 
@@ -356,7 +400,7 @@ def _setup_codex(codex_path: str) -> None:
     _install_codex_artifacts()
 
     # Register MCP server in Codex config (~/.codex/config.toml)
-    _register_codex_mcp_server()
+    _register_codex_mcp_server(mode=mcp_mode)
     _print_codex_config_guidance(config_path)
 
 
@@ -1264,6 +1308,13 @@ def setup(
             help="OpenCode integration mode (mutually exclusive): plugin (default) or subprocess.",
         ),
     ] = "plugin",
+    mcp_mode: Annotated[
+        str,
+        typer.Option(
+            "--mcp-mode",
+            help="Codex MCP config mode: auto preserves user-managed entries, preserve skips MCP changes, stdio replaces with the managed stdio entry.",
+        ),
+    ] = "auto",
 ) -> None:
     """Set up Ouroboros for your environment.
 
@@ -1357,7 +1408,7 @@ def setup(
         if not codex_path:
             print_error("Codex CLI not found in PATH.")
             raise typer.Exit(1)
-        _setup_codex(codex_path)
+        _setup_codex(codex_path, mcp_mode=_normalize_codex_mcp_mode(mcp_mode))
     elif selected in ("opencode", "opencode_cli"):
         opencode_path = available.get("opencode")
         if not opencode_path:

{ouroboros_ai-0.31.2.dev13 → ouroboros_ai-0.31.2.dev14}/src/ouroboros/cli/commands/uninstall.py

@@ -3,7 +3,7 @@
 Cleanly reverses everything `ouroboros setup` did:
   1. MCP server registration  (~/.claude/mcp.json, ~/.codex/config.toml)
   2. CLAUDE.md integration block (<!-- ooo:START --> … <!-- ooo:END -->)
-  3. Codex artifacts          (~/.codex/rules/ouroboros.md, ~/.codex/skills/ouroboros/)
+  3. Codex artifacts          (current packaged rules/skills plus legacy ~/.codex/skills/ouroboros/)
   4. Data directory           (~/.ouroboros/)
 
 Does NOT remove:
@@ -33,6 +33,7 @@ from ouroboros.cli.opencode_config import (
     is_bridge_plugin_entry,
     opencode_config_dir,
 )
+from ouroboros.codex import CODEX_RULE_FILENAME, resolve_packaged_codex_assets
 
 app = typer.Typer(
     name="uninstall",
@@ -140,12 +141,28 @@ def _remove_codex_artifacts(dry_run: bool) -> bool:
     Returns True only if ALL existing artifacts were removed successfully.
     Returns False if any artifact could not be removed.
     """
-    rules_path = Path.home() / ".codex" / "rules" / "ouroboros.md"
-    skills_path = Path.home() / ".codex" / "skills" / "ouroboros"
+    codex_dir = Path.home() / ".codex"
+    try:
+        with resolve_packaged_codex_assets() as assets:
+            managed_relative_paths = set(assets.managed_relative_install_paths)
+    except FileNotFoundError:
+        managed_relative_paths = {Path("rules") / CODEX_RULE_FILENAME}
+    managed_relative_paths.add(Path("skills") / "ouroboros")  # legacy setup path
+
+    rule_paths = [
+        codex_dir / relative_path
+        for relative_path in managed_relative_paths
+        if relative_path.parts[:1] == ("rules",) and (codex_dir / relative_path).exists()
+    ]
+    skill_paths = [
+        codex_dir / relative_path
+        for relative_path in managed_relative_paths
+        if relative_path.parts[:1] == ("skills",) and (codex_dir / relative_path).exists()
+    ]
     had_work = False
     all_ok = True
 
-    if rules_path.exists():
+    for rules_path in rule_paths:
         had_work = True
         if dry_run:
             print_info(f"[dry-run] Would remove {rules_path}")
@@ -157,7 +174,7 @@ def _remove_codex_artifacts(dry_run: bool) -> bool:
                 print_warning(f"Could not remove {rules_path} — skipping.")
                 all_ok = False
 
-    if skills_path.exists():
+    for skills_path in skill_paths:
         had_work = True
         if dry_run:
             print_info(f"[dry-run] Would remove {skills_path}/")
@@ -430,9 +447,14 @@ def uninstall(
     except (json.JSONDecodeError, OSError):
         targets.append(f"OpenCode MCP config ({opencode_config} — may be malformed)")
 
-    codex_rules = Path.home() / ".codex" / "rules" / "ouroboros.md"
-    codex_skills = Path.home() / ".codex" / "skills" / "ouroboros"
-    if codex_rules.exists() or codex_skills.exists():
+    codex_dir = Path.home() / ".codex"
+    try:
+        with resolve_packaged_codex_assets() as assets:
+            managed_relative_paths = set(assets.managed_relative_install_paths)
+    except FileNotFoundError:
+        managed_relative_paths = {Path("rules") / CODEX_RULE_FILENAME}
+    managed_relative_paths.add(Path("skills") / "ouroboros")
+    if any((codex_dir / relative_path).exists() for relative_path in managed_relative_paths):
         targets.append("Codex rules and skills (~/.codex/)")
 
     cwd = Path.cwd()

{ouroboros_ai-0.31.2.dev13 → ouroboros_ai-0.31.2.dev14}/src/ouroboros/cli/main.py

@@ -16,6 +16,7 @@ import typer
 from ouroboros import __version__
 from ouroboros.cli.commands import (
     cancel,
+    codex,
     config,
     detect,
     init,
@@ -44,6 +45,7 @@ app.add_typer(run.app, name="run")
 app.add_typer(config.app, name="config")
 app.add_typer(status.app, name="status")
 app.add_typer(cancel.app, name="cancel")
+app.add_typer(codex.app, name="codex")
 app.add_typer(mcp.app, name="mcp")
 app.add_typer(setup.app, name="setup")
 app.add_typer(detect.app, name="detect")

{ouroboros_ai-0.31.2.dev13 → ouroboros_ai-0.31.2.dev14}/src/ouroboros/codex/__init__.py

@@ -3,9 +3,11 @@
 from ouroboros.codex.artifacts import (
     CODEX_RULE_FILENAME,
     CODEX_SKILL_NAMESPACE,
+    CodexArtifactInstallResult,
     CodexManagedArtifact,
     CodexPackagedAssets,
     CodexPackagedSkill,
+    install_codex_artifacts,
     install_codex_rules,
     install_codex_skills,
     load_packaged_codex_rules,
@@ -16,10 +18,12 @@ from ouroboros.codex.artifacts import (
 
 __all__ = [
     "CodexManagedArtifact",
+    "CodexArtifactInstallResult",
     "CodexPackagedAssets",
     "CodexPackagedSkill",
     "CODEX_RULE_FILENAME",
     "CODEX_SKILL_NAMESPACE",
+    "install_codex_artifacts",
     "install_codex_rules",
     "install_codex_skills",
     "load_packaged_codex_skill",

{ouroboros_ai-0.31.2.dev13 → ouroboros_ai-0.31.2.dev14}/src/ouroboros/codex/artifacts.py

@@ -45,6 +45,14 @@ class CodexManagedArtifact:
     relative_install_path: Path
 
 
+@dataclass(frozen=True, slots=True)
+class CodexArtifactInstallResult:
+    """Installed Codex artifact paths produced by an artifact refresh."""
+
+    rules_path: Path
+    skill_paths: tuple[Path, ...]
+
+
 @dataclass(frozen=True, slots=True)
 class CodexPackagedAssets:
     """Resolved packaged skills and the matching Codex rule assets."""
@@ -374,12 +382,29 @@ def install_codex_skills(
     return tuple(installed_paths)
 
 
+def install_codex_artifacts(
+    *,
+    codex_dir: str | Path | None = None,
+    prune: bool = True,
+) -> CodexArtifactInstallResult:
+    """Install or refresh all packaged Ouroboros Codex artifacts.
+
+    This intentionally only touches managed Codex rules and skills. It does
+    not read or write ``~/.codex/config.toml`` or ``~/.ouroboros/config.yaml``.
+    """
+    rules_path = install_codex_rules(codex_dir=codex_dir, prune=prune)
+    skill_paths = install_codex_skills(codex_dir=codex_dir, prune=prune)
+    return CodexArtifactInstallResult(rules_path=rules_path, skill_paths=skill_paths)
+
+
 __all__ = [
+    "CodexArtifactInstallResult",
     "CodexManagedArtifact",
     "CodexPackagedAssets",
     "CodexPackagedSkill",
     "CODEX_RULE_FILENAME",
     "CODEX_SKILL_NAMESPACE",
+    "install_codex_artifacts",
     "install_codex_rules",
     "install_codex_skills",
     "load_packaged_codex_skill",

ouroboros_ai-0.31.2.dev14/tests/unit/cli/test_codex_command.py

@@ -0,0 +1,40 @@
+"""Unit tests for Codex integration helper commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+from typer.testing import CliRunner
+
+from ouroboros.cli.commands.codex import app
+from ouroboros.codex import CodexArtifactInstallResult
+
+runner = CliRunner()
+
+
+class TestCodexRefresh:
+    """Tests for `ouroboros codex refresh`."""
+
+    def test_refresh_installs_rules_and_skills_without_config_files(self, tmp_path: Path) -> None:
+        rules_path = tmp_path / ".codex" / "rules" / "ouroboros.md"
+        skill_paths = (
+            tmp_path / ".codex" / "skills" / "ouroboros-interview",
+            tmp_path / ".codex" / "skills" / "ouroboros-run",
+        )
+        result = CodexArtifactInstallResult(rules_path=rules_path, skill_paths=skill_paths)
+
+        with (
+            patch("pathlib.Path.home", return_value=tmp_path),
+            patch(
+                "ouroboros.cli.commands.codex.install_codex_artifacts", return_value=result
+            ) as mock_install,
+        ):
+            cli_result = runner.invoke(app, ["refresh"])
+
+        assert cli_result.exit_code == 0
+        mock_install.assert_called_once_with(codex_dir=tmp_path / ".codex", prune=False)
+        assert "Installed Codex rules" in cli_result.output
+        assert "Installed 2 Codex skills" in cli_result.output
+        assert not (tmp_path / ".codex" / "config.toml").exists()
+        assert not (tmp_path / ".ouroboros" / "config.yaml").exists()

{ouroboros_ai-0.31.2.dev13 → ouroboros_ai-0.31.2.dev14}/tests/unit/cli/test_setup.py

@@ -21,6 +21,7 @@ from ouroboros.cli.commands.setup import (
     _scan_and_register_repos,
     _set_default_repo,
 )
+from ouroboros.codex import CodexArtifactInstallResult
 
 # ── Codex setup tests ────────────────────────────────────────────
 
@@ -84,21 +85,91 @@ class TestCodexSetup:
         assert 'OUROBOROS_LLM_BACKEND = "codex"' in contents
         assert "tool_timeout_sec" not in contents
 
+    def test_register_codex_mcp_server_preserves_url_config_by_default(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        """URL-based Codex MCP configs are user-managed and preserved in auto mode."""
+        codex_config = tmp_path / ".codex" / "config.toml"
+        codex_config.parent.mkdir(parents=True)
+        codex_config.write_text(
+            '[mcp_servers.ouroboros]\nurl = "http://127.0.0.1:12000/mcp"\n',
+            encoding="utf-8",
+        )
+
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            setup_cmd._register_codex_mcp_server()
+
+        contents = codex_config.read_text(encoding="utf-8")
+        assert 'url = "http://127.0.0.1:12000/mcp"' in contents
+        assert 'command = "uvx"' not in contents
+        assert "[mcp_servers.ouroboros.env]" not in contents
+
+    def test_register_codex_mcp_server_preserves_custom_command_by_default(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        """Custom command-based Codex MCP configs are preserved in auto mode."""
+        codex_config = tmp_path / ".codex" / "config.toml"
+        codex_config.parent.mkdir(parents=True)
+        codex_config.write_text(
+            "[mcp_servers.ouroboros]\n"
+            'command = "/tmp/ouroboros/.venv/bin/ouroboros"\n'
+            'args = ["mcp", "serve"]\n',
+            encoding="utf-8",
+        )
+
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            setup_cmd._register_codex_mcp_server()
+
+        contents = codex_config.read_text(encoding="utf-8")
+        assert 'command = "/tmp/ouroboros/.venv/bin/ouroboros"' in contents
+        assert 'command = "uvx"' not in contents
+
+    def test_register_codex_mcp_server_stdio_mode_replaces_url_config(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        """Explicit stdio mode replaces a user-managed URL config."""
+        codex_config = tmp_path / ".codex" / "config.toml"
+        codex_config.parent.mkdir(parents=True)
+        codex_config.write_text(
+            '[mcp_servers.ouroboros]\nurl = "http://127.0.0.1:12000/mcp"\n',
+            encoding="utf-8",
+        )
+
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            setup_cmd._register_codex_mcp_server(mode="stdio")
+
+        contents = codex_config.read_text(encoding="utf-8")
+        assert 'url = "http://127.0.0.1:12000/mcp"' not in contents
+        assert 'command = "uvx"' in contents
+        assert "[mcp_servers.ouroboros.env]" in contents
+
+    def test_register_codex_mcp_server_preserve_mode_does_not_create_config(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        """Preserve mode skips MCP config changes entirely."""
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            setup_cmd._register_codex_mcp_server(mode="preserve")
+
+        assert not (tmp_path / ".codex" / "config.toml").exists()
+
     def test_install_codex_artifacts_installs_rules_and_skills(self, tmp_path: Path) -> None:
         """Codex setup should install both managed rules and managed skills."""
         rules_path = tmp_path / ".codex" / "rules"
         skill_paths = [tmp_path / ".codex" / "skills" / "evaluate"]
+        result = CodexArtifactInstallResult(rules_path, tuple(skill_paths))
 
         with (
             patch("pathlib.Path.home", return_value=tmp_path),
-            patch("ouroboros.codex.install_codex_rules", return_value=rules_path) as mock_rules,
-            patch("ouroboros.codex.install_codex_skills", return_value=skill_paths) as mock_skills,
+            patch("ouroboros.codex.install_codex_artifacts", return_value=result) as mock_install,
             patch("ouroboros.cli.commands.setup.print_success") as mock_success,
         ):
             setup_cmd._install_codex_artifacts()
 
-        mock_rules.assert_called_once()
-        mock_skills.assert_called_once()
+        mock_install.assert_called_once()
         success_messages = [call.args[0] for call in mock_success.call_args_list]
         assert any("Installed Codex rules" in message for message in success_messages)
         assert any("Installed 1 Codex skills" in message for message in success_messages)
@@ -128,7 +199,7 @@ class TestCodexSetup:
         assert config_dict["orchestrator"]["codex_cli_path"] == "/usr/local/bin/codex"
         assert config_dict["llm"]["backend"] == "codex"
         mock_install.assert_called_once_with()
-        mock_register.assert_called_once_with()
+        mock_register.assert_called_once_with(mode="auto")
 
         info_messages = [call.args[0] for call in mock_info.call_args_list]
         assert any("Config saved to" in message for message in info_messages)

{ouroboros_ai-0.31.2.dev13 → ouroboros_ai-0.31.2.dev14}/tests/unit/cli/test_uninstall.py

@@ -11,6 +11,7 @@ from typer.testing import CliRunner
 from ouroboros.cli.commands.uninstall import (
     _remove_claude_mcp,
     _remove_claude_md_block,
+    _remove_codex_artifacts,
     _remove_codex_mcp,
     _remove_data_dir,
     _remove_opencode_bridge_plugin,
@@ -192,6 +193,36 @@ class TestRemoveCodexMcp:
         assert result is False
 
 
+# ── _remove_codex_artifacts ──────────────────────────────────────
+
+
+class TestRemoveCodexArtifacts:
+    """Tests for _remove_codex_artifacts helper."""
+
+    def test_removes_namespaced_codex_artifacts(self, tmp_path: Path) -> None:
+        rules_dir = tmp_path / ".codex" / "rules"
+        skills_dir = tmp_path / ".codex" / "skills"
+        rules_dir.mkdir(parents=True)
+        skills_dir.mkdir(parents=True)
+        (rules_dir / "ouroboros.md").write_text("rules", encoding="utf-8")
+        (rules_dir / "ouroboros-extra.md").write_text("extra", encoding="utf-8")
+        (rules_dir / "other.md").write_text("other", encoding="utf-8")
+        (skills_dir / "ouroboros-interview").mkdir()
+        (skills_dir / "ouroboros-run").mkdir()
+        (skills_dir / "other").mkdir()
+
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            result = _remove_codex_artifacts(dry_run=False)
+
+        assert result is True
+        assert not (rules_dir / "ouroboros.md").exists()
+        assert (rules_dir / "ouroboros-extra.md").exists()
+        assert (rules_dir / "other.md").exists()
+        assert not (skills_dir / "ouroboros-interview").exists()
+        assert not (skills_dir / "ouroboros-run").exists()
+        assert (skills_dir / "other").exists()
+
+
 # ── _remove_claude_md_block ──────────────────────────────────────