Python 3.10 is documented as supported, but every documented way to supply the interpreter fails; only an undocumented one works

[genforAI]

Summary

README.md documents Python 3.10 as supported, and the CLI's own error message tells you to use pythonPath, --python, or PYTHON. On Python 3.10 all of those fail. The only way to get a working 3.10 interpreter accepted is to put a virtualenv on PATH and let bare-python3 discovery find it, which is documented nowhere.

This also breaks the repository's own test suite: on a Python 3.10 host, bun test fails 29 tests, all of them for this reason.

Environment

• @openai/codex-security 0.1.5 (commit 5625adc159bbbfb4bd85557d83e2805d27379230)
• Ubuntu 22.04, Python 3.10.12, Node.js v22.23.1

What happens

Three ways to supply a Python 3.10 interpreter, run against the same machine:

# A) Documented: explicit interpreter path (PYTHON / --python / pythonPath)
$ PYTHON=/home/me/tomlienv/bin/python codex-security scans
codex-security: The PYTHON interpreter is unavailable or unusable:
/home/me/tomlienv/bin/python. The bundled Codex Security plugin requires
Python 3.10 or later for scan execution; Python 3.10 also requires tomli.

# B) Undocumented: same venv, discovered from PATH
$ PATH=/home/me/tomlienv/bin:$PATH codex-security scans
scans: []                                    # works

# C) System python3 with `pip install tomli` (installs to user site)
$ codex-security scans
codex-security: The bundled Codex Security plugin requires Python 3.10 or later
(Python 3.10 also requires tomli), but no usable interpreter was found.
Set pythonPath, --python, or PYTHON, install the Codex managed runtime, or add
python3/python to PATH.

Note that the error in (C) recommends exactly the mechanism that fails in (A).

The venv in (A) and (B) is byte-for-byte the same venv:

$ /home/me/tomlienv/bin/python -c "import tomli; print('ok')"
ok

Root cause

Two independent behaviours combine:

1. -I excludes user site-packages. The interpreter probe runs in isolated mode (runtime.ts L2198-L2212):

const { stdout } = await execFile(
  command.executable,
  [
    "-I",
    "-c",
    "import importlib.util,sys\nif sys.version_info < (3, 10): raise SystemExit(1)\nif sys.version_info < (3, 11) and importlib.util.find_spec('tomli') is None: raise SystemExit(1)\nprint('codex-security-python-ok')",
  ],
  ...

-I implies -s, so pip install tomli (which defaults to ~/.local for a non-root user) is invisible:

$ python3 -c "import tomli; print(tomli.__file__)"
/home/me/.local/lib/python3.10/site-packages/tomli/__init__.py
$ python3 -I -c "import importlib.util; print(importlib.util.find_spec('tomli'))"
None

2. Explicit paths are canonicalised out of their venv. In trusted-executable.ts L68:

executable ??= pathLike ? canonical : current.path;

A candidate containing a separator is path-like, so the realpath is used. /home/me/tomlienv/bin/python resolves to /usr/bin/python3.10, which leaves the venv behind, so the venv's site-packages (and its tomli) disappear. A candidate discovered from PATH keeps current.path, which is why (B) works and (A) does not — the two branches disagree, and the working one is the undocumented one.

Impact

• On the minimum documented Python version, the two remedies a user will reach for first — pip install tomli and a virtualenv passed with --python — both fail, and the error text points at the failing one.
• The project's own tests do not pass on a Python 3.10 host with an explicit interpreter configured:

$ bun test
682 pass, 4 skip, 29 fail

# same tree, with a working venv on PATH:
$ PATH=/home/me/tomlienv/bin:$PATH bun test ./tests-ts/scan-recovery.test.ts \
    ./tests-ts/workbench-canonical-paths.test.ts ./tests-ts/runtime.test.ts ./tests-ts/api.test.ts
163 pass, 2 skip, 1 fail

The one remaining failure is this same bug, because the test configures an explicit path:

$ bun test -t "does not load repository-controlled Python startup code" ./tests-ts/runtime.test.ts
PluginPythonUnavailableError: The configured plugin Python interpreter is unavailable
or unusable: /home/me/tomlienv/bin/python3.

Suggested fixes (any one resolves it)

1. Preserve explicit interpreter paths. Keep current.path for path-like candidates too, or canonicalise only for the trust check while executing the path the user gave. Realpath'ing a venv launcher is what breaks venvs, and venvs are the normal way to satisfy the tomli requirement.
2. Vendor tomli (or use a -I-safe fallback such as prepending the interpreter's own site-packages) so the 3.10 dependency does not need user-managed installation at all.
3. Raise the documented minimum to Python 3.11, where tomllib is in the stdlib and none of this applies.

At minimum, the error message should stop recommending --python/PYTHON on 3.10 and should mention that a venv must be on PATH.