feat(adapters): add Codex engine adapter with app-server JSON-RPC protocol (#412)

## Summary
- CodexAdapter implementing AgentAdapter protocol with bidirectional JSON-RPC over stdio
- Full 4-step handshake, turn streaming with event routing, auto-approval (configurable)
- Timeout enforcement via selectors (turn, read, stall — no blocking readline deadlocks)
- Token usage tracking, sandbox_mode forwarding, git-based modified file detection
- Registered in engine_registry, CLI help text updated, OPENAI_API_KEY validator added
- Shared git_utils.detect_modified_files() extracted from duplicated code

## Validation
- Review feedback: All addressed (3 rounds — code reviewer, CodeRabbit, claude-review)
- Demo: All 8 acceptance criteria verified
- Tests: 24 unit tests, 1681 total core tests passing
- CI: All checks green (Backend Tests, Lint, GitGuardian, claude-review, CodeRabbit)
- Linting: Clean

Closes #412

Author: frankbria

codeframe/cli/app.py

@@ -1998,7 +1998,7 @@ def work_start(
     engine: Optional[str] = typer.Option(
         None,
         "--engine",
-        help="Agent engine: react (default), plan (legacy), claude-code, opencode, or built-in",
+        help="Agent engine: react (default), plan (legacy), claude-code, codex, opencode, or built-in",
     ),
     stall_timeout: int = typer.Option(
         300,
@@ -2059,10 +2059,12 @@ def work_start(
         task = matching[0]
 
         # Validate API key before creating run record (avoids dangling IN_PROGRESS state)
-        # External engines (claude-code, opencode) manage their own authentication
         if execute:
             from codeframe.core.engine_registry import is_external_engine
-            if not is_external_engine(engine):
+            if engine == "codex":
+                from codeframe.cli.validators import require_openai_api_key
+                require_openai_api_key()
+            elif not is_external_engine(engine):
                 from codeframe.cli.validators import require_anthropic_api_key
                 require_anthropic_api_key()
 
@@ -2888,7 +2890,7 @@ def batch_run(
     engine: Optional[str] = typer.Option(
         None,
         "--engine",
-        help="Agent engine: react (default), plan (legacy), claude-code, opencode, or built-in",
+        help="Agent engine: react (default), plan (legacy), claude-code, codex, opencode, or built-in",
     ),
     stall_timeout: int = typer.Option(
         300,
@@ -2989,9 +2991,11 @@ def batch_run(
             return
 
         # Validate API key before batch execution
-        # External engines (claude-code, opencode) manage their own authentication
         from codeframe.core.engine_registry import is_external_engine
-        if not is_external_engine(engine):
+        if engine == "codex":
+            from codeframe.cli.validators import require_openai_api_key
+            require_openai_api_key()
+        elif not is_external_engine(engine):
             from codeframe.cli.validators import require_anthropic_api_key
             require_anthropic_api_key()
 

codeframe/cli/validators.py

@@ -46,3 +46,40 @@ def require_anthropic_api_key() -> str:
         "Set it in your environment or add it to a .env file."
     )
     raise typer.Exit(1)
+
+
+def require_openai_api_key() -> str:
+    """Ensure OPENAI_API_KEY is available, loading from .env if needed.
+
+    Checks os.environ first. If not found, attempts to load from .env files
+    (~/.env as base, then cwd/.env with override). If found after loading,
+    sets in os.environ so subprocesses inherit it.
+
+    Returns:
+        The API key string.
+
+    Raises:
+        typer.Exit: If the key cannot be found anywhere.
+    """
+    key = os.getenv("OPENAI_API_KEY")
+    if key:
+        return key
+
+    cwd_env = Path.cwd() / ".env"
+    home_env = Path.home() / ".env"
+
+    if home_env.exists():
+        load_dotenv(home_env)
+    if cwd_env.exists():
+        load_dotenv(cwd_env, override=True)
+
+    key = os.getenv("OPENAI_API_KEY")
+    if key:
+        os.environ["OPENAI_API_KEY"] = key
+        return key
+
+    console.print(
+        "[red]Error:[/red] OPENAI_API_KEY is not set. "
+        "Set it in your environment or add it to a .env file."
+    )
+    raise typer.Exit(1)

codeframe/core/adapters/__init__.py

@@ -11,6 +11,7 @@
     BuiltinReactAdapter,
 )
 from codeframe.core.adapters.claude_code import ClaudeCodeAdapter
+from codeframe.core.adapters.codex import CodexAdapter
 from codeframe.core.adapters.opencode import OpenCodeAdapter
 from codeframe.core.adapters.subprocess_adapter import SubprocessAdapter
 from codeframe.core.adapters.verification_wrapper import VerificationWrapper
@@ -25,6 +26,7 @@
     "BuiltinPlanAdapter",
     "BuiltinReactAdapter",
     "ClaudeCodeAdapter",
+    "CodexAdapter",
     "OpenCodeAdapter",
     "SubprocessAdapter",
     "VerificationWrapper",