# Codex runs on a ChatGPT plan login (ES-F120–F129)

The `codex` engine authenticates from `OPENAI_API_KEY` in the environment
the worker inherits. Someone with only a ChatGPT plan has no key, and the
sandbox masks the Codex CLI's own login file (`~/.codex/auth.json`, W33).
This note records how a codex run may use the plan login instead, and why
it is built the way it is.

Invariants touched: **I5** (no new permission system: the opt-in is a
project-policy key resolved like every other), **I8** (the card, the run
record and `skep doctor` say which login a run used, never a value),
**I9** (every refusal names the way forward), **I12** (the network pin
gains exactly the host this mode needs). I1–I4 are untouched: the engine
stays forced into the sandbox, still needs a pinned `verify_command`, and
the patch still lands only through a human approval.

## How the Codex CLI uses and refreshes `auth.json`

Read from the Codex CLI source at tag `rust-v0.167.2` (the version
installed when this was built), `codex-rs/login/src/`:

- `auth/storage.rs` (`AuthDotJson`): the file holds `auth_mode`,
  `OPENAI_API_KEY`, `tokens` (`id_token`, `access_token`,
  `refresh_token`, `account_id`, ...) and `last_refresh`.
- `auth/manager.rs:3528` (`proactive_refresh_reason`): a ChatGPT login
  (`auth_mode: "chatgpt"`) is refreshed when the access token expires
  within 5 minutes (`:222`), or when `last_refresh` is older than 8 days
  (`:221`). A 401 also triggers a refresh (`UnauthorizedRecovery`).
- `auth/manager.rs:3612` (`refresh_and_persist_chatgpt_token`): the
  refresh **calls the token endpoint first** (`:3630`) and only then
  writes the new tokens back to `auth.json` (`persist_tokens`, `:1726`).
- `auth/storage.rs:281` + `auth/storage_file.rs:34`: a read-only
  `auth.json` makes the *write* fail ("credential file is read-only"),
  but by then the refresh token has already been spent at the server.
- `auth/manager.rs:225`: refresh tokens are single-use. A reused one
  fails with "your refresh token was already used. Please log out and
  sign in again."
- `auth/manager.rs:469`, `:1933`, `:3446`: a file whose `auth_mode` is
  `chatgptAuthTokens` (tokens supplied by an external host) loads as
  `CodexAuth::ChatgptAuthTokens`, uses in-memory storage (it is never
  written back), and its refresh is a no-op: Codex never contacts the
  token endpoint for it. `from_external_chatgpt_tokens` (`:899`) is
  Codex's own constructor for this mode: access token plus account id,
  empty refresh token.
- `model-provider-info/src/lib.rs:86`: ChatGPT-mode requests go to
  `chatgpt.com` (`/backend-api/codex`), not `api.openai.com`.

The access token in a fresh login lives about ten days.

## The danger

Handing a run a copy of the whole file means the run holds the
operator's refresh token. If Codex refreshes inside the sandbox, the
server rotates the token: the run's copy gets the new one, the
operator's own file keeps the spent one, and the operator's next Codex
refresh fails with "already used". The operator is logged out. Making
the copy read-only does not help, because the token is spent before the
write is attempted. Copying a refreshed file back at the end of the run
(the first sketch of W37) narrows the window but still breaks on a
crash, a kill or two runs at once.

## The design

The refresh token never leaves the host.

1. The supervisor reads the operator's `$CODEX_HOME/auth.json` (default
   `~/.codex`). It never writes it.
2. For a codex run that opted in and has no `OPENAI_API_KEY`, it writes
   a **new** file in Codex's `chatgptAuthTokens` mode: the access token,
   the account id, an empty refresh token, mode 0400. Codex never
   refreshes this mode, so nothing a run does can rotate or revoke the
   operator's login. The file lives in the run's audit dir
   (`<home>/supervisor/audit/<task>/codex-login.json`), which every
   worker's sandbox masks; the run's redirected `CODEX_HOME`
   (`<workspace>/.toolchain/codex`, 0700, v106-F1) holds only an
   `auth.json` link to it, and that one run's sandbox binds the file back
   read-only after the masks. A copy inside the worktree would be
   readable by every other sandboxed run on the machine, whatever its
   engine or project: worktrees are not masked.
3. The access token must outlive the run's wall-clock budget plus 5
   minutes, or the dispatch refuses before any run record exists and
   says how to refresh on the host (use `codex` once, or `codex login`;
   the Codex CLI refreshes its own file, under its own rules).
4. The run's network pin gets `chatgpt.com:443` instead of
   `api.openai.com:443`: the one host this mode talks to.
5. The file is deleted when the run ends (the `finally` of
   `run_task`), including runs whose worktree is kept for a retry.
   `.toolchain/` (and so the link) is excluded from every patch.
6. The real login file stays masked from every worker (W33), wherever it
   is: `~/.codex/auth.json`, or `$CODEX_HOME/auth.json` when the operator
   set `CODEX_HOME` (the file skep reads is the file it masks). The builtin worker, `claude_code`, `aider`, `pi` and every
   other codex run never get the run file: it is written only for an
   opted-in `codex` run and only that run's sandbox can read it. The
   copy is on the secret floor too (`codex-login.json`, and the link to
   it by its realpath): the Queen's `read_file`, `search_files` and host
   shell refuse it, and no card lifts that.

## Codex's own sandbox is off

skep runs `codex exec --sandbox danger-full-access` (ES-F220). Codex's
default, read-only, refuses every edit (ES-F128), and any Codex sandbox
starts its own bubblewrap for each shell call, which the kernel refuses
inside skep's Landlock domain: the first live run's shell calls all failed
with `bwrap: Failed to make / slave: Operation not permitted` and it made
no patch. On macOS, Codex's Seatbelt could not nest inside skep's either.
skep's sandbox (bubblewrap with the Landlock step on Linux, Seatbelt on
macOS) is the wall: a codex run is always dispatched in sandbox mode
(v94-F4), and the codex worker refuses to start when the spawner did not
mark its launch as sandboxed. See `sandboxing.md`, Landlock.

## Opting in

Off by default. A project-policy key, `codex_chatgpt_login` (bool):

- CLI: `skep project setup <repo> --strategy <strategy> --phase <phase>
  --codex-chatgpt-login` (`--no-codex-chatgpt-login` turns it off again).
  A repeated setup keeps every stored key but needs the strategy again, and
  `--phase` defaults to `build`, so name an existing project's own strategy
  and phase (`skep project show <id>`); the NO AUTH ENV refusal prints the
  exact line for the repo it refused.
- chat: `setup_project ... codex_chatgpt_login=true` (a HIGH confirmation
  card: it holds once and is never confirmable from a messenger channel);
  `codex_chatgpt_login=false` turns it off
- `copy_project_policy` never copies it: each project opts in with its own
  HIGH card.

`OPENAI_API_KEY`, when set, still wins: the plan login is used only when
no key is present.

## What says so

- The dispatch card and manifest: "uses your ChatGPT plan login (Codex)".
- The run record (the `dispatched` transition) and the run's
  `worker.log`: `codex_auth=chatgpt_login`. Never a value. Not the policy
  decision log (`<audit>/policy/decisions.jsonl`): that is the ledger of
  `decide()` verdicts, its replay counts every row as one, and a login
  choice is not a policy verdict.
- `skep doctor`: whether a ChatGPT login is saved, its plan and expiry
  when the token names them, which projects opted in, and what a codex
  run would use.
- The NO AUTH ENV refusal names the option when a ChatGPT login exists.

## Failure modes

- **The token expires or is revoked mid-run** (signed out elsewhere,
  password change): Codex gets a 401, cannot refresh, and the run fails.
  The operator's login is unaffected beyond whatever revoked it.
- **The token is too close to expiry at dispatch**: refused up front,
  with the refresh hint.
- **The supervisor dies mid-run**: the `finally` does not run and the
  0400 file stays in the run's audit dir, which no worker can read,
  until the operator removes it. It holds an access token only (at most
  ~10 days of life), never the refresh token.
- **The run reads its own token**: the codex process and the commands it
  runs can read the file, exactly as they can read `OPENAI_API_KEY` in
  the key mode. The network pin limits where it can be sent to
  `chatgpt.com`.
- **Codex changes the format**: `chatgptAuthTokens` is a documented mode
  of Codex's app-server protocol. If a later Codex stops loading it from
  disk, the run fails with Codex's own "not logged in" error, the
  operator's login is untouched, and the API-key mode still works.

## The Queen on the same login (v118, ADR 0063)

The Queen can run on the plan too, through the provider registry: `skep
provider add openai-codex --preset openai-codex --activate` (or the chat
`add_provider` card, a HIGH card). It talks the Responses protocol to
`https://chatgpt.com/backend-api/codex` with the access token from the same
`auth.json`, read in place and never refreshed or written: nothing here
changes the rules above.

- The key for any profile on `chatgpt.com` is this login or nothing — never
  the profile's key file, `llm-secret` or an env var. `skep provider
  set-key` and `provider login` refuse such a profile.
- It is the Queen's alone. Activating it leaves `profile.json` (the
  workers' provider) as it was, so builtin workers and the key relay keep
  their own provider; with none configured they refuse and say how to set
  one. No run is routed to it, pinned to its host or unmasked a key for it.
- A missing login, an API-key login, a token within 5 minutes of expiry,
  or a 401 from chatgpt.com ends the Queen's turn with the reason and the
  fix: use `codex` once on this machine, or `codex login`.
- The provider list, `/api/llm/config`, Settings and `skep doctor` report
  the login's presence, plan and expiry, never a value.
