fix: address review feedback on runtime detection and codex version pin

- Replace non-ASCII em dashes with ASCII "--" per repo encoding rules
- Fix false-positive runtime detection: use word-boundary regex instead
  of substring checks in _detect_runtime(), is_runtime_cmd, and
  _transform_runtime_command(); also handle .exe/.cmd extensions
- Route _transform_runtime_command via _detect_runtime() to prevent
  model names like "gpt-5.3-codex" from triggering the codex branch
- Add .cmd/.bat candidates to Windows executable resolution in
  _execute_runtime_command, matching how setup-llm.ps1 installs wrappers
- Include llm in APM runtimes dir detection (setup-llm installs
  llm/llm.cmd to ~/.apm/runtimes/)
- Correct codex version pin: wire_api="chat" was removed in v0.95.0,
  not v0.116/v0.118; pin to rust-v0.94.0 (last compatible release)
- Add ensure_path_within() containment checks in _resolve_prompt_file
  and _discover_prompt_file to prevent symlinks escaping project or
  apm_modules boundaries
- Update docs (runtime-compatibility, agent-workflows, cli-commands) to
  reflect codex version pinning and updated runtime preference order
- Update tests: mock Path.exists in Windows resolution tests; adjust
  symlink containment test to expect PathTraversalError

Author: edenfunf

docs/src/content/docs/guides/agent-workflows.md

@@ -41,7 +41,7 @@ apm runtime list
 | Runtime | Requirements | Notes |
 |---------|-------------|-------|
 | Copilot CLI | Node.js v22+, npm v10+ | Recommended. MCP config at `~/.copilot/` |
-| Codex | Node.js | Set `GITHUB_TOKEN` for GitHub Models support |
+| Codex | Node.js | Pinned to v0.94.0 for GitHub Models compatibility. Set `GITHUB_TOKEN` |
 | LLM | Python 3.10+ | Supports multiple model providers |
 
 **Copilot CLI** is the recommended runtime — it requires no API keys for installation and integrates with GitHub Copilot directly.

docs/src/content/docs/integrations/runtime-compatibility.md

@@ -15,7 +15,7 @@ APM acts as a runtime package manager, downloading and configuring LLM runtimes
 | Runtime | Description | Best For | Configuration |
 |---------|-------------|----------|---------------|
 | [**GitHub Copilot CLI**](https://github.com/github/copilot-cli) | GitHub's Copilot CLI (Recommended) | Advanced AI coding, native MCP support | Auto-configured, no auth needed |
-| [**OpenAI Codex**](https://github.com/openai/codex) | OpenAI's Codex CLI | Code tasks, GitHub Models API | Auto-configured with GitHub Models |
+| [**OpenAI Codex**](https://github.com/openai/codex) | OpenAI's Codex CLI (pinned to v0.94.0) | Code tasks, GitHub Models API | Auto-configured with GitHub Models |
 | [**LLM Library**](https://llm.datasette.io/en/stable/index.html) | Simon Willison's `llm` CLI | General use, many providers | Manual API key setup |
 
 ## Quick Setup
@@ -75,6 +75,8 @@ scripts:
 
 APM automatically downloads, installs, and configures the Codex CLI with GitHub Models for free usage.
 
+> **Note:** Codex v0.95.0+ dropped Chat Completions API support (`wire_api="chat"`) in favor of the Responses API, which GitHub Models does not support. APM pins the default Codex version to `rust-v0.94.0` (the last compatible release). If you need a newer Codex version, pass `--version` explicitly and configure a compatible API provider.
+
 ### Setup
 
 #### 1. Install via APM
@@ -83,7 +85,7 @@ apm runtime setup codex
 ```
 
 This automatically:
-- Downloads the latest Codex binary for your platform
+- Downloads Codex binary (v0.94.0) for your platform
 - Installs to `~/.apm/runtimes/codex`
 - Creates configuration for GitHub Models (`github/gpt-4o`)
 - Updates your PATH

docs/src/content/docs/reference/cli-commands.md

@@ -1416,7 +1416,7 @@ apm runtime COMMAND [OPTIONS]
 
 **Supported Runtimes:**
 - **`copilot`** - GitHub Copilot coding agent
-- **`codex`** - OpenAI Codex CLI with GitHub Models support
+- **`codex`** - OpenAI Codex CLI with GitHub Models support (pinned to v0.94.0 for compatibility)
 - **`llm`** - Simon Willison's LLM library with multiple providers
 
 #### `apm runtime setup` - Install AI runtime
@@ -1497,6 +1497,6 @@ apm runtime status
 ```
 
 **Output includes:**
-- Runtime preference order (copilot → codex → llm)
+- Runtime preference order (APM runtimes: copilot, llm; then PATH: llm > copilot > codex)
 - Currently active runtime
 - Next steps if no runtime is available

scripts/runtime/setup-codex.ps1

@@ -4,8 +4,8 @@
 param(
     [switch]$Vanilla,
     # Pinned to last version compatible with GitHub Models (wire_api="chat").
-    # rust-v0.118.0+ requires wire_api="responses" which GitHub Models does not support.
-    [string]$Version = "rust-v0.117.0"
+    # rust-v0.95.0+ requires wire_api="responses" which GitHub Models does not support.
+    [string]$Version = "rust-v0.94.0"
 )
 
 $ErrorActionPreference = "Stop"

scripts/runtime/setup-codex.sh

@@ -24,8 +24,8 @@ source "$SCRIPT_DIR/setup-common.sh"
 # Configuration
 CODEX_REPO="openai/codex"
 # Pinned to last version compatible with GitHub Models (wire_api="chat").
-# rust-v0.118.0+ requires wire_api="responses" which GitHub Models does not support.
-CODEX_VERSION="rust-v0.117.0"  # Default version
+# rust-v0.95.0+ requires wire_api="responses" which GitHub Models does not support.
+CODEX_VERSION="rust-v0.94.0"  # Default version
 VANILLA_MODE=false
 
 # Parse command line arguments

src/apm_cli/core/script_runner.py

@@ -12,6 +12,7 @@
 
 from .token_manager import setup_runtime_environment
 from ..output.script_formatters import ScriptExecutionFormatter
+from ..utils.path_security import ensure_path_within
 
 
 class ScriptRunner:
@@ -110,7 +111,7 @@ def run_script(self, script_name: str, params: Dict[str, str]) -> bool:
         error_msg += f"Available scripts in apm.yml: {available}\n"
         error_msg += f"\nTo get started, create a prompt file first:\n"
         error_msg += f"  echo '# My agent prompt' > {script_name}.prompt.md\n"
-        error_msg += f"\nThen run again — APM will auto-discover it.\n"
+        error_msg += f"\nThen run again -- APM will auto-discover it.\n"
         error_msg += f"\nOr define a script explicitly in apm.yml:\n"
         error_msg += f"  scripts:\n"
         error_msg += f"    {script_name}: copilot {script_name}.prompt.md\n"
@@ -264,7 +265,8 @@ def _auto_compile_prompts(
 
             # Check if this is a runtime command (copilot, codex, llm) before transformation
             is_runtime_cmd = any(
-                runtime in command for runtime in ["copilot", "codex", "llm"]
+                re.search(r"(?:^|[\s/\\])" + runtime + r"(?:\.exe|\.cmd)?(?:\s|$)", command)
+                for runtime in ["copilot", "codex", "llm"]
             ) and re.search(re.escape(prompt_file), command)
 
             # Transform command based on runtime pattern
@@ -343,12 +345,17 @@ def _transform_runtime_command(
                             result += f" {args_after_file}"
                         return result
 
-        # Handle individual runtime patterns without environment variables
+        # Handle individual runtime patterns without environment variables.
+        # Detect the runtime from the executable (first token) to avoid
+        # false positives when a runtime name appears in flags or model names.
+        detected = self._detect_runtime(command)
+        _ext = r"(?:\.exe|\.cmd)?"
+        _pf = re.escape(prompt_file)
 
         # Handle "codex [args] file.prompt.md [more_args]" -> "codex exec [args] [more_args]"
-        if re.search(r"codex\s+.*" + re.escape(prompt_file), command):
+        if detected == "codex" and re.search(r"codex" + _ext + r"\s+.*" + _pf, command):
             match = re.search(
-                r"codex\s+(.*?)(" + re.escape(prompt_file) + r")(.*?)$", command
+                r"codex" + _ext + r"\s+(.*?)(" + _pf + r")(.*?)$", command
             )
             if match:
                 args_before_file = match.group(1).strip()
@@ -362,9 +369,9 @@ def _transform_runtime_command(
                 return result
 
         # Handle "copilot [args] file.prompt.md [more_args]" -> "copilot [args] [more_args]"
-        elif re.search(r"copilot\s+.*" + re.escape(prompt_file), command):
+        elif detected == "copilot" and re.search(r"copilot" + _ext + r"\s+.*" + _pf, command):
             match = re.search(
-                r"copilot\s+(.*?)(" + re.escape(prompt_file) + r")(.*?)$", command
+                r"copilot" + _ext + r"\s+(.*?)(" + _pf + r")(.*?)$", command
             )
             if match:
                 args_before_file = match.group(1).strip()
@@ -381,9 +388,9 @@ def _transform_runtime_command(
                 return result
 
         # Handle "llm [args] file.prompt.md [more_args]" -> "llm [args] [more_args]"
-        elif re.search(r"llm\s+.*" + re.escape(prompt_file), command):
+        elif detected == "llm" and re.search(r"llm" + _ext + r"\s+.*" + _pf, command):
             match = re.search(
-                r"llm\s+(.*?)(" + re.escape(prompt_file) + r")(.*?)$", command
+                r"llm" + _ext + r"\s+(.*?)(" + _pf + r")(.*?)$", command
             )
             if match:
                 args_before_file = match.group(1).strip()
@@ -413,15 +420,15 @@ def _detect_runtime(self, command: str) -> str:
             Name of the detected runtime (copilot, codex, llm, or unknown)
         """
         command_lower = command.lower().strip()
-        # Check for runtime keywords anywhere in the command, not just at the start
-        if "copilot" in command_lower:
-            return "copilot"
-        elif "codex" in command_lower:
-            return "codex"
-        elif "llm" in command_lower:
-            return "llm"
-        else:
-            return "unknown"
+        # Check for runtime keywords as standalone tokens or at end of a path
+        # (e.g. /path/to/copilot, copilot.exe, copilot.cmd)
+        for runtime in ["copilot", "codex", "llm"]:
+            if re.search(
+                r"(?:^|[\s/\\])" + runtime + r"(?:\.exe|\.cmd)?(?:\s|$)",
+                command_lower,
+            ):
+                return runtime
+        return "unknown"
 
     def _execute_runtime_command(
         self, command: str, content: str, env: dict
@@ -505,8 +512,13 @@ def _execute_runtime_command(
         if sys.platform == "win32" and actual_command_args:
             exe_name = actual_command_args[0]
             apm_runtimes = Path.home() / ".apm" / "runtimes"
-            # Check APM runtimes directory first
-            apm_candidates = [apm_runtimes / exe_name, apm_runtimes / f"{exe_name}.exe"]
+            # Check APM runtimes directory first (include .exe, .cmd, .bat wrappers)
+            apm_candidates = [
+                apm_runtimes / exe_name,
+                apm_runtimes / f"{exe_name}.exe",
+                apm_runtimes / f"{exe_name}.cmd",
+                apm_runtimes / f"{exe_name}.bat",
+            ]
             apm_resolved = next((str(c) for c in apm_candidates if c.exists()), None)
             if apm_resolved:
                 actual_command_args[0] = apm_resolved
@@ -574,6 +586,17 @@ def _discover_prompt_file(self, name: str) -> Optional[Path]:
                     if skill_file.exists():
                         matches.append(skill_file)
 
+            # Filter out matches that escape the apm_modules directory
+            # (e.g. symlinks pointing outside the project)
+            safe_matches = []
+            for m in matches:
+                try:
+                    ensure_path_within(m, apm_modules)
+                    safe_matches.append(m)
+                except ValueError:
+                    pass
+            matches = safe_matches
+
             if len(matches) == 0:
                 return None
             elif len(matches) == 1:
@@ -861,10 +884,10 @@ def _detect_installed_runtime(self) -> str:
         system-level stubs (e.g. GitHub CLI copilot extensions).
 
         Priority:
-          1. APM runtimes dir: copilot  (codex excluded — v0.116+ is
+          1. APM runtimes dir: copilot, llm  (codex excluded -- v0.95.0+ is
              incompatible with GitHub Models' Chat Completions API)
-          2. PATH: llm > copilot > codex  (llm uses Chat Completions, works
-             with GitHub Models even when codex dropped that API)
+          2. PATH: llm > copilot > codex  (codex v0.95.0+ dropped Chat
+             Completions, so PATH codex is last resort for older binaries)
 
         Returns:
             Name of detected runtime
@@ -877,11 +900,10 @@ def _detect_installed_runtime(self) -> str:
         apm_runtimes = Path.home() / ".apm" / "runtimes"
 
         # 1. Check APM-managed runtimes directory first (highest priority).
-        #    Only copilot is checked here — codex installed via APM runtimes
-        #    will be v0.116+ which dropped Chat Completions support and is
-        #    incompatible with GitHub Models.
-        #    llm is checked via PATH only (installed as a Python package).
-        for name in ("copilot",):
+        #    copilot and llm are checked here -- codex installed via APM
+        #    runtimes will be v0.95.0+ which dropped Chat Completions support
+        #    and is incompatible with GitHub Models.
+        for name in ("copilot", "llm"):
             candidates = [
                 apm_runtimes / name,
                 apm_runtimes / f"{name}.exe",
@@ -893,7 +915,7 @@ def _detect_installed_runtime(self) -> str:
                 if exe.stat().st_size > 0:
                     return name
 
-        # 2. Fall back to PATH — prefer llm (uses Chat Completions, works with
+        # 2. Fall back to PATH -- prefer llm (uses Chat Completions, works with
         #    GitHub Models even when codex has dropped that API format)
         if shutil.which("llm"):
             return "llm"
@@ -927,7 +949,7 @@ def _generate_runtime_command(self, runtime: str, prompt_file: Path) -> str:
             # Codex CLI with default sandbox and git repo check skip
             return f"codex -s workspace-write --skip-git-repo-check {prompt_file}"
         elif runtime == "llm":
-            # llm CLI — uses Chat Completions, compatible with GitHub Models
+            # llm CLI -- uses Chat Completions, compatible with GitHub Models
             return f"llm -m github/gpt-4o {prompt_file}"
         else:
             raise ValueError(f"Unsupported runtime: {runtime}")
@@ -999,16 +1021,19 @@ def _resolve_prompt_file(self, prompt_file: str) -> Path:
             FileNotFoundError: If prompt file is not found in local or dependency modules
         """
         prompt_path = Path(prompt_file)
+        project_root = Path.cwd()
 
         # First check if it exists in current directory (local)
         if prompt_path.exists():
+            ensure_path_within(prompt_path, project_root)
             return prompt_path
 
         # Check in common project directories
         common_dirs = [".github/prompts", ".apm/prompts"]
         for common_dir in common_dirs:
             common_path = Path(common_dir) / prompt_file
             if common_path.exists():
+                ensure_path_within(common_path, project_root)
                 return common_path
 
         # If not found locally, search in dependency modules
@@ -1024,12 +1049,14 @@ def _resolve_prompt_file(self, prompt_file: str) -> Path:
                             # Check in the root of the repository
                             dep_prompt_path = repo_dir / prompt_file
                             if dep_prompt_path.exists():
+                                ensure_path_within(dep_prompt_path, apm_modules_dir)
                                 return dep_prompt_path
 
                             # Also check in common subdirectories
                             for subdir in ["prompts", ".", "workflows"]:
                                 sub_prompt_path = repo_dir / subdir / prompt_file
                                 if sub_prompt_path.exists():
+                                    ensure_path_within(sub_prompt_path, apm_modules_dir)
                                     return sub_prompt_path
 
         # If still not found, raise an error with helpful message

tests/unit/test_runtime_windows.py

@@ -193,6 +193,7 @@ def test_execute_runtime_command_uses_shlex_on_windows(self):
         env = {"PATH": "/usr/bin"}
 
         with patch("sys.platform", "win32"), \
+             patch("pathlib.Path.exists", return_value=False), \
              patch("apm_cli.core.script_runner.shutil.which", return_value=None), \
              patch("subprocess.run", return_value=MagicMock(returncode=0)) as mock_run:
             runner._execute_runtime_command("codex --quiet", "prompt content", env)
@@ -206,6 +207,7 @@ def test_execute_runtime_command_preserves_quotes_on_windows(self):
         env = {"PATH": "/usr/bin"}
 
         with patch("sys.platform", "win32"), \
+             patch("pathlib.Path.exists", return_value=False), \
              patch("apm_cli.core.script_runner.shutil.which", return_value=None), \
              patch("subprocess.run", return_value=MagicMock(returncode=0)) as mock_run:
             runner._execute_runtime_command(

tests/unit/test_symlink_containment.py

@@ -41,8 +41,9 @@ def tearDown(self):
         shutil.rmtree(self.tmpdir, ignore_errors=True)
 
     def test_symlinked_prompt_outside_project_rejected(self):
-        """Symlinked .prompt.md is rejected with clear error message."""
+        """Symlinked .prompt.md pointing outside project is rejected."""
         from apm_cli.core.script_runner import PromptCompiler
+        from apm_cli.utils.path_security import PathTraversalError
 
         prompts_dir = self.project / ".apm" / "prompts"
         prompts_dir.mkdir(parents=True)
@@ -53,9 +54,8 @@ def test_symlinked_prompt_outside_project_rejected(self):
         old_cwd = os.getcwd()
         try:
             os.chdir(self.project)
-            with self.assertRaises(FileNotFoundError) as ctx:
+            with self.assertRaises(PathTraversalError):
                 compiler._resolve_prompt_file(".apm/prompts/evil.prompt.md")
-            self.assertIn("symlink", str(ctx.exception).lower())
         finally:
             os.chdir(old_cwd)