imbue-mngr-codex 0.1.0__tar.gz

imbue_mngr_codex-0.1.0/.gitignore

@@ -0,0 +1,359 @@
+# Byte-compiled / optimized / DLL files
+**/__pycache__/
+**/*.py[codz]
+**/*$py.class
+
+# macOS Finder metadata
+**/.DS_Store
+
+# C extensions
+**/*.so
+
+# Distribution / packaging
+**/.Python
+**/build/
+**/develop-eggs/
+**/dist/
+**/downloads/
+**/eggs/
+**/.eggs/
+**/lib/
+**/lib64/
+**/parts/
+**/sdist/
+**/var/
+**/wheels/
+**/share/python-wheels/
+**/*.egg-info/
+**/.installed.cfg
+**/*.egg
+**/MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+**/*.manifest
+**/*.spec
+
+# Installer logs
+**/pip-log.txt
+**/pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+**/htmlcov/
+**/.tox/
+**/.nox/
+**/.coverage
+**/.coverage.*
+**/.cache
+**/nosetests.xml
+**/coverage.xml
+**/*.cover
+**/*.py.cover
+**/.hypothesis/
+**/.pytest_cache/
+**/cover/
+
+# Translations
+**/*.mo
+**/*.pot
+
+# Django stuff:
+**/*.log
+**/local_settings.py
+**/db.sqlite3
+**/db.sqlite3-journal
+
+# Flask stuff:
+**/instance/
+**/.webassets-cache
+
+# Scrapy stuff:
+**/.scrapy
+
+# Sphinx documentation
+**/docs/_build/
+
+# PyBuilder
+**/.pybuilder/
+**/target/
+
+# Jupyter Notebook
+**/.ipynb_checkpoints
+
+# IPython
+**/profile_default/
+**/ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+**/.pdm-python
+**/.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+**/.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+**/__pypackages__/
+
+# Celery stuff
+**/celerybeat-schedule
+**/celerybeat.pid
+
+# SageMath parsed files
+**/*.sage.py
+
+# Environments
+**/.env
+**/.envrc
+**/.venv
+**/.venv-*
+**/env/
+**/venv/
+**/ENV/
+**/env.bak/
+**/venv.bak/
+
+# Spyder project settings
+**/.spyderproject
+**/.spyproject
+
+# Rope project settings
+**/.ropeproject
+
+# mkdocs documentation
+**/site
+
+# mypy
+**/.mypy_cache/
+**/.dmypy.json
+**/dmypy.json
+
+# Pyre type checker
+**/.pyre/
+
+# pytype static type analyzer
+**/.pytype/
+
+# Cython debug symbols
+**/cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+**/.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+**/.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+**/.ruff_cache/
+
+# PyPI configuration file
+**/.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+**/.cursorignore
+**/.cursorindexingignore
+
+# Marimo
+**/marimo/_static/
+**/marimo/_lsp/
+**/__marimo__/
+
+# task folders for local custom claude workflow (at any depth, incl. the
+# root-level `dev` project's `dev/_tasks/`, which `*/*/_tasks/` missed)
+**/_tasks/
+**/.sesskey
+
+# Node.js
+**/node_modules/
+
+# Frontend build artifacts
+**/frontend-dist/
+
+# Claude Code local settings (session-specific permissions)
+**/.claude/settings.local.json
+
+# Local Claude settings backup files
+**/.claude/*.bak
+
+# Claude worktress
+**/.claude/worktrees
+
+# Agent definitions deployed by mngr_subagent_proxy at session start
+**/.claude/agents/
+
+# Local mngr settings (not committed)
+**/.mngr/settings.local.toml
+
+# Local working / scratch markdown (not committed)
+**/*.local.md
+
+# Local working / scratch shell scripts (not committed)
+# (covers user notification scripts like scripts/notify_user.local.sh, too)
+**/*.local.sh
+
+# Local-only throwaway scripts (e.g. one-off test harnesses).
+**/scripts/*.local.sh
+
+# Test output files (slow tests, coverage summaries)
+**/.test_output/
+
+# TMR output directories (reports + test outputs)
+**/tmr_*/
+**/tmr-report/
+
+# Active session marker file (used to detect interrupted sessions)
+**/.claude/active
+
+# we stick the image build artifacts here
+**/.mngr/dev/build/
+**/.mngr/dev/secrets/
+
+# Offload caches and local files
+**/.offload/**
+**/test-results
+
+# Minds deploy-time build artifacts.
+# Ignore contents so we can un-ignore the committed `template/` subtree: git
+# won't descend into a fully-ignored directory, so negations must live below
+# the contents pattern rather than below the directory pattern.
+**/.minds/*
+# The template directory is committed: it defines the expected keys for each
+# <service>.sh file, with empty values. `scripts/push_modal_secrets.py` uses
+# it to check that per-env .sh files declare every template key.
+!/.minds/template/
+!/.minds/template/**
+# Vault ACL policies for the minds tiers. The HCL is non-sensitive and is
+# the source of truth for the policies pushed to Vault via
+# `vault policy write <name> .minds/policies/<name>.hcl`.
+!/.minds/policies/
+!/.minds/policies/**
+
+# Autofix session artifacts
+**/.autofix/
+**/.reviewer/logs/
+**/.reviewer/outputs/
+**/.reviewer/settings.local.json
+**/.reviewer/.stop_hook_consecutive_blocks
+**/.reviewer/conversation-issues.jsonl
+**/.reviews/
+
+# Stuck agent tracking (stop hook escape valve)
+**/.claude/blocked_stop_commits
+
+# Scheduled tasks lock file
+**/.claude/scheduled_tasks.lock
+
+# Demo recordings (asciinema .cast, .txt, and scripts)
+**/.demos/
+
+# for git worktrees from other repos
+**/.external_worktrees/
+
+# ignore coverage files generated within subprojects
+**/cov.xml
+
+# ignore demos
+**/recordings
+apps/minds_workspace_server/package-lock.json
+**/*.local.md
+
+# Generated by the _generate-dockerignore justfile recipe before each
+# test-offload* run. The recipe strips this self-reference so offload's
+# copy_untracked_files ships the generated file into the build context.
+/.dockerignore
+
+# Transient offload image-cache marker written by test-offload runs; not
+# checked in (unlike the committed .offload-*-cache-key files which pin CI
+# image versions).
+/.offload-image-cache
+
+# Generated by _generate-release-dockerfile from Dockerfile + .release.extras.
+/libs/mngr/imbue/mngr/resources/Dockerfile.release
+**/.reviewer/autofix/issues/
+.reviewer/logs/
+
+# Tailwind Play CDN JS for the minds desktop client. Fetched once via
+# `just minds-tailwind` (plain curl, no build) and shipped with the
+# distributable. Not checked in because it's a ~300KB blob we can always
+# re-fetch.
+/apps/minds/imbue/minds/desktop_client/static/tailwind.js
+
+# macOS Finder metadata
+**/.DS_Store
+**/.env.swp
+# Vim swap files for any file (`.foo.swp`, `.foo.swo`, etc.) -- generated
+# while a file is open in vim. Never checked in.
+**/.*.sw[a-p]
+
+# `minds env deploy` writes a recover-target file at the monorepo root
+# on failed deploys; `minds env recover` deletes it after rolling back.
+# Never checked in. Per-env naming
+# (``.minds-deploy-recover-target-<env-name>.json``) means each in-flight
+# deploy has its own file, so concurrent deploys against different envs
+# don't trip over each other.
+**/.minds-deploy-*.json
+# Per-env deploy lock files (kernel-level ``flock`` targets). Created
+# by ``hold_deploy_lock`` in ``apps/minds/imbue/minds/envs/recover.py``
+# and held for the entire duration of ``minds env deploy`` /
+# ``minds env recover`` so two concurrent invocations against the same
+# env serialize. The file itself is empty and cheap to leave around.
+**/.minds-deploy-lock-*.lock
+**/.antigravitycli/
+
+# Playwright MCP scratch artifacts (mock screenshots, page snapshots)
+**/.playwright-mcp/
+
+# tmr (task-runner) orchestration scratch report
+**/tmr-report/

imbue_mngr_codex-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog - mngr_codex
+
+A concise, human-friendly summary of changes for the `mngr_codex` library. Entries are categorized using the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) categories: Added, Changed, Deprecated, Removed, Fixed, Security.
+
+For the full, unedited changelog entries, see [UNABRIDGED_CHANGELOG.md](UNABRIDGED_CHANGELOG.md).
+
+## [Unreleased]
+
+## [v0.1.0] - 2026-06-13
+
+### Added
+
+- Added: real `codex` agent-type support as its own plugin (`imbue-mngr-codex`), wiring OpenAI's Codex CLI into mngr and replacing the previous in-core `BaseAgent` stub. Each agent runs under its own per-agent `CODEX_HOME` for isolated config, sessions, and transcripts, while sharing authentication through a write-through `auth.json` symlink so logging in once authenticates every agent. Codex agents report RUNNING while working and WAITING when idle via four hooks (`UserPromptSubmit`/`Stop`/`SubagentStart`/`SubagentStop`); because codex subagents run asynchronously, the `active` marker is recomputed under a lock from a root-turn flag plus one file per in-flight subagent so it stays RUNNING until the root turn AND every subagent are done. Includes conversation resume across stop/start (root `session_id` captured to a tracking file; `mngr start` shell-evaluates `codex resume <id>`), common transcripts readable by `mngr transcript`, and seeded trust/onboarding for a silent first launch.
+- Added: `send_message` blocks until submission registers — the `UserPromptSubmit` hook signals a `mngr-submit-<session>` tmux wait-for channel after it sets the active marker, so `mngr message` returns only once the agent reads RUNNING (closes a race where a follow-up lifecycle check could see the pre-turn idle state).
+- Added: Update handling — codex's blocking startup "Update available!" prompt is disabled, and mngr surfaces updates itself at provision by comparing `codex --version` to `~/.codex/version.json`. A single `update_policy` setting governs action (default `ASK`): `AUTO` runs `codex update` silently, `ASK` prompts on an attended local run (interactive tty + local host) and otherwise logs a non-blocking notice, and `NEVER` only logs the notice.
+- Added: Conformance test asserting codex's emitted common-transcript records validate against the canonical envelope schema (`imbue.mngr.agents.common_transcript_records`); release test now runs on the shared agent release-lifecycle harness (`imbue.mngr.agents.agent_release_testing`) against the real codex binary, including stop/start resume.

imbue_mngr_codex-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: imbue-mngr-codex
+Version: 0.1.0
+Summary: Codex agent type plugin for mngr
+Requires-Python: >=3.12
+Requires-Dist: imbue-mngr==0.2.13
+Description-Content-Type: text/markdown
+
+# imbue-mngr-codex
+
+The `codex` agent-type plugin for [`mngr`](https://pypi.org/project/imbue-mngr/): real
+support for the OpenAI Codex CLI (the Rust `codex` binary) as a first-class mngr agent,
+on par with the `claude` and `antigravity` agent types.
+
+`mngr create my-task codex` launches an interactive Codex TUI agent that mngr can monitor
+(RUNNING/WAITING), message, transcript, stop, resume, and isolate per agent.
+
+## How it works
+
+See `specs/agent-plugin-parity/codex-investigation.md` in the monorepo for the full,
+source-verified investigation behind each decision.
+
+- **Per-agent isolation via `CODEX_HOME`.** Codex resolves its whole
+  config/auth/session/hook tree from `CODEX_HOME` (default `~/.codex`). Each agent gets its
+  own `CODEX_HOME` under the agent state dir, injected only on the codex process
+  (`env CODEX_HOME=...`), leaving the user's real `$HOME` untouched. codex accepts the
+  dotted `~/.mngr/...` cwd, so there is no workspace symlink either.
+- **Shared auth.** The per-agent `auth.json` is a symlink to the user's shared
+  `~/.codex/auth.json`. Codex writes that file in place and reloads-before-refreshing, so
+  one login authenticates every agent and token refreshes propagate. `config.toml` pins
+  `cli_auth_credentials_store = "file"` so codex never falls back to a keyring entry keyed
+  by the per-agent `CODEX_HOME` path (which would defeat sharing).
+- **Lifecycle marker (RUNNING/WAITING), subagent-aware.** Codex subagents (the multi-agent
+  `spawn_agent` feature) run *asynchronously* -- the root agent's `Stop` hook fires while
+  subagents are still running, with no `fullyIdle` signal. So mngr does not just clear the
+  marker on `Stop`; it recomputes an `active` marker that is present while either the root
+  turn is running (`codex_root_active`, set on `UserPromptSubmit`, cleared on the root
+  `Stop`) or any subagent is in flight (one file per `agent_id` under `codex_subagents/`,
+  maintained by the `SubagentStart`/`SubagentStop` hooks). The recompute runs under a portable
+  `mkdir` lock so a concurrent root `Stop` and final `SubagentStop` can't strand it. A
+  recorded root `session_id` guards against a nested `codex` process sharing the same
+  `CODEX_HOME`. (Backgrounded OS processes the agent launches are not tracked -- codex emits
+  no hook for them.)
+- **Conversation resume.** `mngr stop` then `mngr start` resumes the prior conversation: the
+  hook records the root `session_id`, and the launch command shell-evaluates
+  `codex resume <id>` (codex's session JSONL survives the hard kill `mngr stop` performs).
+- **Transcripts.** The native rollout JSONL is streamed verbatim to the raw transcript and
+  converted into mngr's agent-agnostic common transcript that `mngr transcript` reads.
+- **Trust & hook bypass (consent-gated).** mngr seeds the work dir as a trusted project to
+  skip codex's folder-trust dialog, and passes `--dangerously-bypass-hook-trust` so its own
+  lifecycle hooks run. Because trusting the workspace also lets codex load repo-local
+  `.codex/hooks.json`, that bypass is consent-gated together with workspace trust: mngr
+  prompts before trusting (or use `mngr create --yes` / `auto_dismiss_dialogs = true`).
+
+## Configuration
+
+Set fields under an `[agent_types.codex]` table in your mngr config, or pass overrides.
+
+- `model` — model slug to pin (e.g. `"gpt-5.5"`). Default: unset (codex's own default).
+- `model_reasoning_effort` — `none|minimal|low|medium|high|xhigh`. Default: unset.
+- `sandbox_mode` — `read-only|workspace-write|danger-full-access`. Default: `workspace-write`.
+- `auto_allow_permissions` — when `true`, sets `approval_policy = "never"` so codex never
+  prompts for tool approval (the sandbox still applies). Default: `false`.
+- `config_overrides` — free-form key/values merged last into the per-agent `config.toml`.
+- `auto_dismiss_dialogs` — when `true`, trust the repo and allow the hook bypass without
+  prompting. Default: `false`.
+- `update_policy` — how mngr handles an outdated codex CLI at provision (see "Updates" below):
+  `AUTO` (run `codex update`, no prompt), `ASK` (prompt on an attended local run, else just
+  notify), or `NEVER` (only notify). Default: `ASK`.
+- `emit_common_transcript` — emit the common-schema transcript. Default: `true`.
+
+### Updates
+
+mngr pins `check_for_update_on_startup = false` in the per-agent `config.toml`, because codex's
+own "Update available!" prompt is **blocking** and would intercept the first message mngr sends
+(an Enter could even select "Update now"). mngr surfaces updates itself instead: at provision it
+compares `codex --version` against the `latest_version` codex last recorded in its own
+`~/.codex/version.json` (no network call — codex refreshes that file on its own throttled
+schedule during your normal codex use). The check always runs and is best-effort: any probe or
+parse failure is swallowed (debug-logged) and never blocks agent creation. When codex is outdated,
+the action is governed by `update_policy`: `AUTO` runs `codex update`; `ASK` (the default) prompts
+to update now only on an *attended* run — a local host driven from an interactive terminal, and
+not `--yes` — otherwise it logs a non-blocking notice (so an unattended remote/deploy agent
+defaults to neither prompting nor upgrading the remote's global install); `NEVER` only logs the
+notice. `codex update` self-detects the install method (it runs `brew upgrade --cask codex` for a
+brew install, `npm i -g` for npm, the curl installer for standalone), so mngr needs no per-method
+logic. Updating is optional — an outdated codex still runs — so a declined prompt, a `NEVER`
+policy, or a non-interactive run never blocks agent creation, and `--yes` does **not** trigger a
+global upgrade (only the explicit `AUTO` policy does).
+
+### Model note
+
+Codex picks the account's default model, and a **ChatGPT-account login rejects some
+`*-codex` model slugs** (e.g. `gpt-5.2-codex`) with a 400 "model is not supported when using
+Codex with a ChatGPT account". Two distinct things cause this:
+
+- **Deprecation:** `gpt-5.2` / `gpt-5.2-codex` / `gpt-5.3-codex` have been sunset for ChatGPT
+  subscriptions (OpenAI's announcement points those users to the API). These fail on a ChatGPT
+  plan in *every* mode, including the TUI.
+- **Run-mode entitlement:** the backend gates some `*-codex` models by the `originator` HTTP
+  header (i.e. the client identity). The interactive TUI presents as `codex-tui` and is
+  allowed; `codex exec` presents as `codex_exec` and is denied. (See the app-server note below
+  for why this matters and why we do *not* spoof the TUI identity.)
+
+If your agent errors on the first message with the "not supported" 400, set `model` to a model
+your account supports (e.g. `"gpt-5.5"`), or authenticate with an API key (which carries the
+full model entitlement).
+
+## Not yet implemented
+
+Relative to `mngr_claude`, these are not yet ported (tracked for follow-up): session
+preservation on destroy, deploy/scheduling contributions, field generators (`waiting_reason`),
+the streaming snapshot, and installation/version management.
+
+## Future direction: an app-server-backed agent variant
+
+This agent drives the codex **TUI** by `tmux send-keys` (paste + Enter), with banner-poll
+readiness. That works, but it's fragile (screen-scraping) and codex's `SessionStart` fires
+lazily, so there's no clean pre-input readiness signal. Codex offers a much cleaner surface to
+drive programmatically -- the **app-server** -- and a second agent type built on it is a planned
+follow-up (mirroring `mngr_claude`'s `claude` + `headless_claude` split).
+
+We built the TUI agent **first**, though, for a concrete reason: like `claude -p`, the app-server
+does not have full feature parity with the interactive TUI on a ChatGPT-subscription login. The
+backend gates some `*-codex` models on the **client identity** (the `originator`, derived from the
+app-server's `initialize` `clientInfo.name`) -- the first-party TUI presents as `codex-tui` and is
+entitled to them; a programmatic app-server client identifying honestly as mngr is not. The only
+way to close that gap is to spoof the TUI identity, which OpenAI's terms disallow (see "client
+identity" below). So the TUI agent is how you get full `*-codex` model access on a ChatGPT login
+today, and the app-server variant is a *complement* for the cases where the identity gap is
+acceptable (API-key auth, which carries the full entitlement; or only models the honest identity
+already gets) -- not a replacement.
+
+### What it would give us
+- **Programmatic messaging instead of tmux paste.** `codex app-server` speaks a JSON-RPC
+  protocol over a socket; you send a turn with `initialize` -> `thread/start` -> `turn/start`.
+  No `send-keys`, no paste-visibility polling.
+- **You can still view it in the TUI.** Launch the TUI as a *viewer* with
+  `codex --remote unix://<sock>` (accepts `ws://`, `wss://`, `unix://` too) connected to the
+  app-server -- so it runs in tmux and you watch it live, but mngr drives it over the socket.
+- **Clean synchronous readiness.** The `initialize` response / `thread.started` event is an
+  unambiguous "ready for input" signal -- it eliminates the lazy-`SessionStart` banner-poll
+  workaround entirely.
+- **Cleaner lifecycle/transcript.** `turn.started` / `turn.completed` / `item.*` events could
+  drive the RUNNING/WAITING marker and the transcript directly, instead of (or alongside) the
+  hook scripts. The hooks, subagents, sandbox, and approval policy are all **engine-level**
+  (`codex-core`), so they fire identically whether codex is driven via the TUI or the
+  app-server -- the existing marker hooks would keep working.
+
+### How (verified against codex 0.138.0)
+- `codex app-server --listen unix://<sock>` runs the server and **works with the brew/npm
+  install**. (The convenience wrapper `codex remote-control start` / `codex app-server daemon`
+  requires codex's *standalone* installer at a fixed path -- avoid it; use raw `app-server
+  --listen`.) `codex app-server proxy --sock <sock>` proxies stdio to a running server's
+  control socket.
+- mngr would override `send_message` to speak JSON-RPC to the socket, and `assemble_command`
+  would launch `app-server` + a `--remote` TUI viewer instead of the bare TUI.
+
+### Important: client identity and OpenAI's ToS (do NOT spoof the TUI)
+The app-server sets its `originator` from the `initialize` request's `clientInfo.name`. It is
+**tempting but against the spirit (and likely the letter) of OpenAI's terms** to set
+`clientInfo.name = "codex-tui"` so the backend grants the `*-codex` model entitlement it
+otherwise denies non-TUI clients. That presents a programmatic client as the first-party TUI
+specifically to bypass an *intentional* server-side model gate -- which falls under OpenAI's
+"circumvent any restrictions / bypass any protective measures" clause (codex's own code treats
+these names as a trust boundary; the override env var is literally `CODEX_INTERNAL_ORIGINATOR_OVERRIDE`).
+
+So the app-server variant must **identify honestly** (mngr's own client name) and use whatever
+models that identity is legitimately entitled to. For the gated `*-codex` models in app-server
+mode, authenticate with an **API key** (OpenAI's documented path for programmatic workflows) --
+do not spoof the TUI. The genuine `codex` TUI agent in this plugin remains the legitimate way
+to use `*-codex` models on a ChatGPT-subscription login (it really *is* the TUI).
+
+(Driving codex programmatically via the app-server on a single user's own ChatGPT login is
+itself fine -- it's a first-party feature and OpenAI staff have called such use "permissive";
+the line we don't cross is identity-spoofing to defeat the model gate, plus the usual no
+credential-sharing / no multi-tenant-proxying / no rate-limit-bypass.)