@trac3er/oh-my-god 2.0.2 → 2.0.4

package/hooks/setup_wizard.py

@@ -22,16 +22,18 @@ if _PROJECT_ROOT not in sys.path:
 from runtime.cli_provider import get_provider, list_available_providers  # noqa: E402
 from runtime.mcp_config_writers import (  # noqa: E402
     write_claude_mcp_config,
+    write_claude_mcp_stdio_config,
     write_codex_mcp_config,
+    write_codex_mcp_stdio_config,
     write_gemini_mcp_config,
-    write_opencode_mcp_config,
+    write_gemini_mcp_stdio_config,
     write_kimi_mcp_config,
+    write_kimi_mcp_stdio_config,
 )
 
 # Trigger provider auto-registration on import
 import runtime.providers.codex_provider  # noqa: E402, F401
 import runtime.providers.gemini_provider  # noqa: E402, F401
-import runtime.providers.opencode_provider  # noqa: E402, F401
 import runtime.providers.kimi_provider  # noqa: E402, F401
 from runtime.adoption import (  # noqa: E402
     CANONICAL_VERSION,
@@ -43,10 +45,13 @@ from runtime.adoption import (  # noqa: E402
 
 _logger = logging.getLogger(__name__)
 
+OMG_CONTROL_COMMAND = "python3"
+OMG_CONTROL_ARGS = ["-m", "runtime.omg_mcp_server"]
+OMG_CONTROL_SERVER_NAME = "omg-control"
+
 _INSTALL_HINTS: dict[str, str] = {
     "codex": "npm install -g @openai/codex",
     "gemini": "npm install -g @google/gemini-cli",
-    "opencode": "npm install -g opencode-ai  (or: curl -fsSL https://opencode.ai/install | bash)",
     "kimi": "uv tool install --python 3.13 kimi-cli",
 }
 
@@ -112,6 +117,15 @@ MCP_CATALOG: list[dict[str, Any]] = [
         "default": True,
         "category": "memory",
     },
+    {
+        "id": OMG_CONTROL_SERVER_NAME,
+        "name": "OMG Control",
+        "description": "OMG control plane MCP server via stdio",
+        "command": OMG_CONTROL_COMMAND,
+        "args": OMG_CONTROL_ARGS,
+        "default": True,
+        "category": "control",
+    },
     {
         "id": "github",
         "name": "GitHub",
@@ -325,7 +339,7 @@ def get_cli_auth_instructions(provider: str) -> dict[str, str]:
     or store credentials.
 
     Args:
-        provider: CLI provider name (e.g. "codex", "gemini", "kimi", "opencode").
+        provider: CLI provider name (e.g. "codex", "gemini", or "kimi").
 
     Returns:
         Dict with keys: install, auth, verify, subscription.
@@ -350,12 +364,6 @@ def get_cli_auth_instructions(provider: str) -> dict[str, str]:
             "verify": "kimi --version",
             "subscription": "Requires Kimi API key from platform.moonshot.cn",
         },
-        "opencode": {
-            "install": "npm install -g opencode-ai",
-            "auth": "opencode auth login",
-            "verify": "opencode --version",
-            "subscription": "Requires Anthropic API key or Claude subscription",
-        },
     }
 
     return instructions.get(provider, {
@@ -380,8 +388,11 @@ def configure_mcp(
     detected_clis: dict[str, Any],
     server_url: str = "http://127.0.0.1:8765/mcp",
     server_name: str = "omg-memory",
+    control_command: str = OMG_CONTROL_COMMAND,
+    control_args: list[str] | None = None,
+    control_server_name: str = OMG_CONTROL_SERVER_NAME,
 ) -> dict[str, Any]:
-    """Configure MCP memory server for authenticated CLIs.
+    """Configure OMG MCP servers for authenticated CLIs.
 
     For each CLI in detected_clis where detected_clis[cli]["detected"] == True,
     calls the appropriate writer from runtime.mcp_config_writers.
@@ -391,6 +402,9 @@ def configure_mcp(
         detected_clis: Dict of CLI detection results from detect_clis().
         server_url: MCP server URL (default: http://127.0.0.1:8765/mcp).
         server_name: MCP server name (default: omg-memory).
+        control_command: stdio command for the OMG control MCP server.
+        control_args: stdio args for the OMG control MCP server.
+        control_server_name: MCP server name for the OMG control surface.
 
     Returns:
         Dict with keys:
@@ -400,29 +414,40 @@ def configure_mcp(
     """
     configured: list[str] = []
     errors: dict[str, str] = {}
+    resolved_control_args = list(control_args or OMG_CONTROL_ARGS)
 
-    # Always write Claude config
+    # Always write Claude project config for both memory and control surfaces.
     try:
         write_claude_mcp_config(project_dir, server_url, server_name)
+        write_claude_mcp_stdio_config(
+            project_dir,
+            command=control_command,
+            args=resolved_control_args,
+            server_name=control_server_name,
+        )
     except Exception as exc:
         _logger.warning("Failed to write Claude MCP config: %s", exc)
         errors["claude"] = str(exc)
 
-    # Write configs for detected CLIs
+    # Write both memory and control surfaces for detected external CLIs.
     cli_writers = {
-        "codex": write_codex_mcp_config,
-        "gemini": write_gemini_mcp_config,
-        "opencode": write_opencode_mcp_config,
-        "kimi": write_kimi_mcp_config,
+        "codex": (write_codex_mcp_config, write_codex_mcp_stdio_config),
+        "gemini": (write_gemini_mcp_config, write_gemini_mcp_stdio_config),
+        "kimi": (write_kimi_mcp_config, write_kimi_mcp_stdio_config),
     }
 
-    for cli_name, writer_func in cli_writers.items():
+    for cli_name, (http_writer, stdio_writer) in cli_writers.items():
         cli_info = detected_clis.get(cli_name, {})
         if not cli_info.get("detected", False):
             continue
 
         try:
-            writer_func(server_url, server_name)
+            http_writer(server_url, server_name)
+            stdio_writer(
+                command=control_command,
+                args=resolved_control_args,
+                server_name=control_server_name,
+            )
             configured.append(cli_name)
         except Exception as exc:
             _logger.warning("Failed to write %s MCP config: %s", cli_name, exc)
@@ -460,7 +485,6 @@ def set_preferences(project_dir: str, preferences: dict[str, Any]) -> dict[str,
     default_cli_configs: dict[str, Any] = {
         "codex": {"subscription": "free", "max_parallel_agents": 1},
         "gemini": {"subscription": "free", "max_parallel_agents": 1},
-        "opencode": {"subscription": "free", "max_parallel_agents": 1},
         "kimi": {"subscription": "free", "max_parallel_agents": 1},
     }
     preset = resolve_preset(cast(str | None, preferences.get("preset")))

package/hooks/shadow_manager.py

@@ -17,6 +17,7 @@ HOOKS_DIR = os.path.dirname(__file__)
 if HOOKS_DIR not in sys.path:
     sys.path.insert(0, HOOKS_DIR)
 from _common import _resolve_project_dir
+from security_validators import ensure_path_within_dir, validate_opaque_identifier
 
 
 def _project_dir() -> str:
@@ -43,6 +44,10 @@ def _new_run_id() -> str:
     return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
 
 
+def _validated_run_id(run_id: str) -> str:
+    return validate_opaque_identifier(run_id, "run_id")
+
+
 def _hash_file(path: str) -> str:
     h = hashlib.sha256()
     with open(path, "rb") as f:
@@ -61,6 +66,7 @@ def ensure_shadow_dirs(project_dir: str) -> None:
 
 def set_active_run_id(project_dir: str, run_id: str) -> None:
     ensure_shadow_dirs(project_dir)
+    run_id = _validated_run_id(run_id)
     with open(_active_run_path(project_dir), "w", encoding="utf-8") as f:
         f.write(run_id)
 
@@ -81,7 +87,7 @@ def get_active_run_id(project_dir: str) -> str | None:
 
 
 def begin_shadow_run(project_dir: str, metadata: dict[str, Any] | None = None) -> str:
-    run_id = get_active_run_id(project_dir) or _new_run_id()
+    run_id = _validated_run_id(get_active_run_id(project_dir) or _new_run_id())
     run_dir = os.path.join(_shadow_root(project_dir), run_id)
     os.makedirs(run_dir, exist_ok=True)
 
@@ -124,12 +130,14 @@ def _save_manifest(run_dir: str, manifest: dict[str, Any]) -> None:
 
 
 def map_shadow_path(project_dir: str, run_id: str, file_path: str) -> str:
+    run_id = _validated_run_id(run_id)
     rel = os.path.relpath(os.path.abspath(file_path), os.path.abspath(project_dir))
     rel = rel.replace("..", "_up_")
     return os.path.join(_shadow_root(project_dir), run_id, "overlay", rel)
 
 
 def record_shadow_write(project_dir: str, run_id: str, file_path: str, source: str = "tool") -> dict[str, Any]:
+    run_id = _validated_run_id(run_id)
     run_dir = os.path.join(_shadow_root(project_dir), run_id)
     os.makedirs(run_dir, exist_ok=True)
 
@@ -171,8 +179,12 @@ def create_evidence_pack(
     diff_summary: dict[str, Any] | None = None,
     reproducibility: dict[str, Any] | None = None,
     unresolved_risks: list[str] | None = None,
+    provenance: list[dict[str, Any]] | None = None,
+    trust_scores: dict[str, Any] | None = None,
+    api_twin: dict[str, Any] | None = None,
 ) -> str:
     ensure_shadow_dirs(project_dir)
+    run_id = _validated_run_id(run_id)
     evidence = {
         "schema": "EvidencePack",
         "run_id": run_id,
@@ -182,8 +194,14 @@ def create_evidence_pack(
         "diff_summary": diff_summary or {},
         "reproducibility": reproducibility or {},
         "unresolved_risks": unresolved_risks or [],
+        "provenance": provenance or [],
+        "trust_scores": trust_scores or {},
+        "api_twin": api_twin or {},
     }
-    evidence_path = os.path.join(_evidence_root(project_dir), f"{run_id}.json")
+    evidence_path = ensure_path_within_dir(
+        _evidence_root(project_dir),
+        os.path.join(_evidence_root(project_dir), f"{run_id}.json"),
+    )
     with open(evidence_path, "w", encoding="utf-8") as f:
         json.dump(evidence, f, indent=2)
     return evidence_path
@@ -211,6 +229,7 @@ def has_recent_evidence(project_dir: str, hours: int = 24) -> bool:
 
 
 def apply_shadow(project_dir: str, run_id: str) -> dict[str, Any]:
+    run_id = _validated_run_id(run_id)
     run_dir = os.path.join(_shadow_root(project_dir), run_id)
     manifest = _load_manifest(run_dir)
     applied = []
@@ -236,6 +255,7 @@ def apply_shadow(project_dir: str, run_id: str) -> dict[str, Any]:
 
 
 def drop_shadow(project_dir: str, run_id: str) -> dict[str, Any]:
+    run_id = _validated_run_id(run_id)
     run_dir = os.path.join(_shadow_root(project_dir), run_id)
     if os.path.isdir(run_dir):
         print(f"[OMG] Deleting: {run_dir}", file=sys.stderr)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trac3er/oh-my-god",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "OMG (Oh My God) — Multi-agent orchestration, intelligent model routing, and durable session state for Claude Code",
   "main": "OMG-setup.sh",
   "scripts": {

package/plugins/README.md

@@ -17,6 +17,9 @@ OMG exposes a small native front door and keeps the rest of the surface availabl
 | `/OMG:escalate` | Route to Codex, Gemini, or CCG |
 | `/OMG:teams` | Team routing for internal OMG execution |
 | `/OMG:ccg` | Tri-track synthesis |
+| `/OMG:security-check` | Canonical security pipeline |
+| `/OMG:api-twin` | Contract replay and fixture-based API simulation |
+| `/OMG:preflight` | Structured route selection and evidence planning |
 | `/OMG:compat` | Legacy compatibility routing |
 | `/OMG:health-check` | Verify setup and tool integration |
 | `/OMG:mode` | Set cognitive mode for the session |
@@ -28,7 +31,6 @@ OMG exposes a small native front door and keeps the rest of the surface availabl
 | `/OMG:deep-plan` | Planning | Strategic planning with domain awareness |
 | `/OMG:learn` | Knowledge | Convert patterns into OMG-native instincts and skills |
 | `/OMG:code-review` | Quality | Deep review flow |
-| `/OMG:security-review` | Security | Security-focused review |
 | `/OMG:ship` | Delivery | Idea to evidence to release |
 | `/OMG:handoff` | Collaboration | Session transfer and continuity |
 
@@ -50,5 +52,5 @@ Public migration commands are intentionally avoided. OMG uses `/OMG:setup` and `
 
 ## Public Docs
 
-- Install guides live in [docs/install/claude-code.md](../docs/install/claude-code.md), [docs/install/codex.md](../docs/install/codex.md), and [docs/install/opencode.md](../docs/install/opencode.md).
+- Install guides live in [docs/install/claude-code.md](../docs/install/claude-code.md) and [docs/install/codex.md](../docs/install/codex.md).
 - Proof surface lives in [docs/proof.md](../docs/proof.md).

package/plugins/advanced/commands/OMG:deep-plan.md

@@ -87,7 +87,7 @@ Key interfaces: [list the interfaces/types this touches]
 
 ### Phase 3: Integration + Security [N files, ~M lines]
 5. [ ] [specific action]
-6. [ ] Security review: /OMG:security-review [affected files]
+6. [ ] Security review: /OMG:security-check [affected files]
 
 ### Phase 4: Verification
 7. [ ] Tests: [what to test, how]

package/plugins/advanced/commands/OMG:security-review.md

@@ -1,119 +1,16 @@
 ---
-description: Deep security review — scans for vulnerabilities, hardcoded secrets, auth issues, and injection risks. Escalates to Codex for deep line-by-line analysis.
-allowed-tools: Read, Bash(grep:*), Bash(find:*), Bash(cat:*), Bash(git:*), Bash(rg:*), Grep, Glob
-argument-hint: "[file or directory to review, or 'all' for full scan]"
+description: Deprecated alias to OMG's canonical security-check pipeline.
+allowed-tools: Read, Grep, Glob, Bash(python3:*), Bash(rg:*)
+argument-hint: "[path or '.' for the current project]"
 ---
 
-# /OMG:security-review — Vulnerability Scanner + Deep Review
+# /OMG:security-review — Deprecated Alias
 
-## Step 1: Scope Detection
+`/OMG:security-review` remains available only for compatibility.
 
-Determine what to scan:
-- If argument is a file: scan that file deeply
-- If argument is a directory: scan all source files in it
-- If "all" or no argument: scan git-tracked source files
+Use `/OMG:security-check` instead. The canonical pipeline now owns:
 
-Identify security-critical files automatically:
-```bash
-# Auth/session
-find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) | xargs grep -li "auth\|login\|session\|token\|password\|jwt\|oauth" 2>/dev/null
-
-# Payment
-find . -type f -name "*.{ts,js,py,go}" | xargs grep -li "payment\|billing\|stripe\|checkout\|card\|price" 2>/dev/null
-
-# Database
-find . -type f -name "*.{ts,js,py,go}" | xargs grep -li "query\|SELECT\|INSERT\|UPDATE\|DELETE\|migration\|schema" 2>/dev/null
-```
-
-## Step 2: Automated Vulnerability Scan
-
-For each security-critical file, check LINE-BY-LINE:
-
-**2a. Hardcoded Secrets**
-```bash
-grep -rn "AKIA\|sk_live\|sk_test\|ghp_\|github_pat\|xoxb-\|xoxp-\|eyJ.*\.eyJ" [files]
-grep -rn "api[_-]key.*=.*['\"][A-Za-z0-9]" [files]
-grep -rn "password.*=.*['\"]" [files] | grep -v "test\|mock\|example\|placeholder"
-```
-
-**2b. SQL Injection**
-```bash
-grep -rn "f\".*SELECT\|f\".*INSERT\|f\".*UPDATE\|f\".*DELETE" [files]
-grep -rn "\\.format.*SELECT\|%s.*SELECT\|\\+.*SELECT" [files]
-grep -rn "query.*\\$\\{" [files]  # template literal SQL
-```
-
-**2c. XSS / Injection**
-```bash
-grep -rn "innerHTML\|dangerouslySetInnerHTML\|v-html\|\\|safe\b" [files]
-grep -rn "eval(\|exec(\|subprocess.*shell=True" [files]
-grep -rn "document\\.write\|document\\.location" [files]
-```
-
-**2d. Auth/Session Issues**
-```bash
-grep -rn "jwt\\.decode.*verify.*false\|verify.*False" [files]
-grep -rn "cors.*\\*\|origin.*\\*" [files]
-grep -rn "httpOnly.*false\|secure.*false\|sameSite.*none" [files]
-```
-
-**2e. Path Traversal**
-```bash
-grep -rn "req\\.params\|req\\.query\|req\\.body" [files] | grep -i "path\|file\|dir"
-grep -rn "\\.\\./\|\\.\\.\\\\" [files]
-```
-
-**2f. Sensitive Data Exposure**
-```bash
-grep -rn "console\\.log.*password\|console\\.log.*token\|console\\.log.*secret" [files]
-grep -rn "log\\.info.*password\|logger.*token\|print.*secret" [files]
-```
-
-## Step 3: Codex Deep Review (for high-risk files)
-
-For files with auth, payment, or database logic:
-
-```
-/OMG:escalate codex "Security deep review of [file]:
-1. Read every line. Flag any: hardcoded secrets, SQL injection, XSS, CSRF, auth bypass, privilege escalation, insecure deserialization, SSRF.
-2. Check auth flow completeness: does every protected route validate the token? Are permissions checked?
-3. Check payment flow: is card data handled safely? Are amounts validated server-side?
-4. Check database queries: all parameterized? Any raw string concatenation?
-5. Rate this file: SAFE / NEEDS_FIX / CRITICAL with specific line numbers."
-```
-
-## Step 4: Report
-
-```
-Security Review — [scope]
-━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Files scanned: [N]
-Security-critical files: [N]
-
-CRITICAL [N]:
-  [file:line] Hardcoded API key: [type]
-  [file:line] SQL injection: unparameterized query
-
-HIGH [N]:
-  [file:line] Missing auth check on protected route
-  [file:line] CORS wildcard in production config
-
-MEDIUM [N]:
-  [file:line] Sensitive data in console.log
-  [file:line] httpOnly not set on session cookie
-
-LOW [N]:
-  [file:line] Missing rate limiting on login endpoint
-
-Codex Deep Review:
-  [file]: [SAFE|NEEDS_FIX|CRITICAL] — [summary]
-
-Fix priority: [ordered list of what to fix first]
-```
-
-## Anti-patterns
-- Don't just grep and dump raw output — analyze each finding
-- Don't skip test files entirely (they can leak real credentials)
-- Don't claim "looks secure" without running ALL checks above
-- Don't treat this as optional for auth/payment/database changes
+- normalized security findings
+- dependency and AST enrichment
+- evidence-ready provenance and trust scores
+- reuse across CLI, compat routing, control plane, MCP, and ship flows

package/plugins/advanced/commands/OMG:ship.md

@@ -24,7 +24,7 @@ argument-hint: "[goal or optional path to .omg/idea.yml]"
   - `tests[]`, `security_scans[]`, `diff_summary`, `reproducibility`, `unresolved_risks[]`.
 
 ## Step 4: Security and trust checks
-- Run `/OMG:security-review` for auth/payment/database/sensitive changes.
+- Run `/OMG:security-check` for auth/payment/database/sensitive changes.
 - If config/hook/MCP changes are involved, ensure trust manifest is updated at `.omg/trust/manifest.lock.json`.
 
 ## Step 5: PR-ready output

package/plugins/advanced/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "omg-advanced",
   "version": "1.0.5",
-  "description": "Advanced OMG commands - deep planning, learning, code review, security review, and specialized workflows",
+  "description": "Advanced OMG commands - deep planning, learning, code review, and specialized workflows",
   "type": "omg-plugin",
   "commands": {
     "deep-plan": {
@@ -19,11 +19,6 @@
       "description": "Deep code review with line-by-line analysis",
       "category": "quality"
     },
-    "security-review": {
-      "path": "commands/OMG:security-review.md",
-      "description": "Security vulnerability scanning",
-      "category": "security"
-    },
     "ship": {
       "path": "commands/OMG:ship.md",
       "description": "Ship pipeline - idea to PR-ready summary",
@@ -69,10 +64,6 @@
       "description": "Code quality and review",
       "commands": ["code-review"]
     },
-    "security": {
-      "description": "Security analysis and review",
-      "commands": ["security-review"]
-    },
     "knowledge": {
       "description": "Learning and skill creation",
       "commands": ["learn"]

package/plugins/core/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "omg-core",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Core OMG commands - native setup, routing, orchestration, and verification surfaces",
   "type": "omg-plugin",
   "commands": {
@@ -39,6 +39,21 @@
       "description": "Legacy skill compatibility dispatcher",
       "category": "compatibility"
     },
+    "security-check": {
+      "path": "commands/OMG:security-check.md",
+      "description": "Canonical security pipeline with normalized findings and evidence",
+      "category": "security"
+    },
+    "api-twin": {
+      "path": "commands/OMG:api-twin.md",
+      "description": "Contract replay and fixture-based API simulation",
+      "category": "contracts"
+    },
+    "preflight": {
+      "path": "commands/OMG:preflight.md",
+      "description": "Structured routing and evidence planning before execution",
+      "category": "routing"
+    },
     "health-check": {
       "path": "commands/OMG:health-check.md",
       "description": "Verify project setup and tool integration",
@@ -90,7 +105,7 @@
     },
     "routing": {
       "description": "Model routing and escalation",
-      "commands": ["escalate", "teams", "ccg"]
+      "commands": ["escalate", "teams", "ccg", "preflight"]
     },
     "orchestration": {
       "description": "Multi-agent orchestration modes",
@@ -108,6 +123,14 @@
       "description": "Cost tracking and session observability",
       "commands": ["cost", "stats", "deps"]
     },
+    "security": {
+      "description": "Canonical security and trust checks",
+      "commands": ["security-check"]
+    },
+    "contracts": {
+      "description": "Contract replay and API simulation",
+      "commands": ["api-twin"]
+    },
     "visualization": {
       "description": "Codebase visualization and architecture diagrams",
       "commands": ["arch"]

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "oh-my-god"
-version = "2.0.0b1"
+version = "2.0.4"
 description = "OMG (Oh My God) — Multi-agent orchestration, intelligent model routing, and durable session state for Claude Code"
 readme = "README.md"
 requires-python = ">=3.10"

package/runtime/adoption.py

@@ -11,7 +11,7 @@ CANONICAL_REPO_URL = "https://github.com/trac3er00/OMG"
 CANONICAL_PACKAGE_NAME = "@trac3er/oh-my-god"
 CANONICAL_PLUGIN_ID = "omg"
 CANONICAL_MARKETPLACE_ID = "omg"
-CANONICAL_VERSION = "2.0.2"
+CANONICAL_VERSION = "2.0.4"
 
 VALID_ADOPTION_MODES = ("omg-only", "coexist")
 VALID_PRESETS = ("safe", "balanced", "interop", "labs")

package/runtime/api_twin.py

@@ -0,0 +1,130 @@
+"""Fixture-based API twin state and replay helpers."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+STATE_REL_PATH = Path(".omg") / "state" / "api_twin.json"
+
+
+def ingest_contract(project_dir: str, *, name: str, source_path: str) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    contract_path = Path(source_path)
+    contract = {
+        "name": name,
+        "source_path": str(contract_path),
+        "content": contract_path.read_text(encoding="utf-8"),
+        "fidelity": "schema-only",
+    }
+    state.setdefault("contracts", {})[name] = contract
+    _save_state(project_dir, state)
+    return {
+        "schema": "ApiTwinContract",
+        "name": name,
+        "fidelity": "schema-only",
+        "source_path": str(contract_path),
+    }
+
+
+def record_fixture(
+    project_dir: str,
+    *,
+    name: str,
+    request: dict[str, Any],
+    response: dict[str, Any],
+    validated: bool,
+) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    fixture = {
+        "name": name,
+        "request": request,
+        "response": response,
+        "fidelity": "recorded-validated" if validated else "recorded",
+        "validated": validated,
+    }
+    state.setdefault("fixtures", {})[name] = fixture
+    _save_state(project_dir, state)
+    return {
+        "schema": "ApiTwinFixture",
+        "name": name,
+        "fidelity": fixture["fidelity"],
+    }
+
+
+def serve_fixture(
+    project_dir: str,
+    *,
+    name: str,
+    latency_ms: int = 0,
+    failure_mode: str = "",
+    schema_drift: bool = False,
+) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    fixture = _fixture(state, name)
+    response = dict(fixture.get("response", {}))
+    fidelity = str(fixture.get("fidelity", "recorded"))
+    if schema_drift:
+        response["__schema_drift__"] = True
+        fidelity = "stale"
+    if failure_mode:
+        response = {"error": failure_mode}
+        fidelity = "stale"
+    return {
+        "schema": "ApiTwinServeResult",
+        "name": name,
+        "latency_ms": latency_ms,
+        "failure_mode": failure_mode,
+        "fidelity": fidelity,
+        "response": response,
+    }
+
+
+def verify_fixture(project_dir: str, *, name: str, live_response: dict[str, Any]) -> dict[str, Any]:
+    state = _load_state(project_dir)
+    fixture = _fixture(state, name)
+    matches_live = fixture.get("response", {}) == live_response
+    fidelity = "recorded-validated" if matches_live else "stale"
+    fixture["fidelity"] = fidelity
+    fixture["validated"] = matches_live
+    state.setdefault("fixtures", {})[name] = fixture
+    _save_state(project_dir, state)
+    return {
+        "schema": "ApiTwinVerifyResult",
+        "name": name,
+        "fidelity": fidelity,
+        "matches_live": matches_live,
+        "live_verification_required": True,
+    }
+
+
+def _state_path(project_dir: str) -> Path:
+    return Path(project_dir) / STATE_REL_PATH
+
+
+def _load_state(project_dir: str) -> dict[str, Any]:
+    path = _state_path(project_dir)
+    if not path.exists():
+        return {"contracts": {}, "fixtures": {}}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"contracts": {}, "fixtures": {}}
+    return payload if isinstance(payload, dict) else {"contracts": {}, "fixtures": {}}
+
+
+def _save_state(project_dir: str, payload: dict[str, Any]) -> None:
+    path = _state_path(project_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=True) + "\n", encoding="utf-8")
+
+
+def _fixture(state: dict[str, Any], name: str) -> dict[str, Any]:
+    fixtures = state.get("fixtures", {})
+    if not isinstance(fixtures, dict) or name not in fixtures:
+        raise ValueError(f"Unknown API twin fixture: {name}")
+    fixture = fixtures[name]
+    if not isinstance(fixture, dict):
+        raise ValueError(f"Invalid API twin fixture: {name}")
+    return fixture