diff --git a/devlog/_plan/260902_nonbug_adoption_backlog/070_wp7_shim_free_token.md b/devlog/_plan/260902_nonbug_adoption_backlog/070_wp7_shim_free_token.md new file mode 100644 index 00000000000..8a1209706b9 --- /dev/null +++ b/devlog/_plan/260902_nonbug_adoption_backlog/070_wp7_shim_free_token.md @@ -0,0 +1,35 @@ +# wp7 — #2713 shim-free Codex token injection + +State at entry: the narrow `ocx doctor` diagnostic requested by the issue ("env_key set + variable +absent + shim missing → actionable repair line") landed on `dev` in PR #2844 (`5734a1caf`, +`collectCodexEnvKeyReadiness` in `src/cli/doctor.ts`, tests in +`tests/doctor-codex-envkey-readiness.test.ts`). The maintainer review (score 58) and the reviewer +follow-up (2026-08-29) both settled the remaining design questions: + +- A `systemd --user` drop-in is rejected as the default: it does not fit a root-owned server and + only reaches services launched by the user manager, not interactive shells, cron, or Desktop. +- `EnvironmentFile=` on `opencodex-proxy.service` lands only in the proxy process; it cannot + inject `OPENCODEX_API_AUTH_TOKEN` into an independently launched `codex exec`. Validated by the + reporter on a root VPS. +- Codex has no credential-file directive for `env_key`; the value must exist in the Codex process + environment. Do not invent one. +- No new token file; the existing `service-api-token` is the source. Do not add another launcher + interception at the Codex binary path (that is the hole the issue reports). +- Verdict: no `ocx codex-env` command yet; a narrow documentation update is what remains. + +## Scope (docs only) + +`docs-site/src/content/docs/reference/cli/lifecycle.md`, in the `ocx codex-shim` section: a +subsection "Token injection without the shim" that states the process boundary, lists what does and +does not carry `OPENCODEX_API_AUTH_TOKEN` to Codex (shim; exporting the variable in the launching +process — shell profile, cron line, service unit that launches Codex itself; `EnvironmentFile=` on +the proxy unit does not), points to `ocx doctor`'s "Codex env_key launch readiness" line, and +reminds that the token value is never printed and must not be copied into `config.toml`. + +## Acceptance + +- Section present; no new commands or config keys claimed (`skill:surface:check` unaffected). +- `bun run privacy:scan` clean. +- PR to dev; close #2713 with English rationale: doctor slice landed (#2844), documentation landed, + first-class `ocx codex-env` declined for now with the reasons above; reopen path stated. + diff --git a/devlog/_plan/260902_nonbug_adoption_backlog/071_wp7_audit_r1_synthesis.md b/devlog/_plan/260902_nonbug_adoption_backlog/071_wp7_audit_r1_synthesis.md new file mode 100644 index 00000000000..fe4e8432e7e --- /dev/null +++ b/devlog/_plan/260902_nonbug_adoption_backlog/071_wp7_audit_r1_synthesis.md @@ -0,0 +1,9 @@ +# wp7 audit r1 — synthesis + +Audit input is the issue's own review chain: maintainer review (grok-bot, score 58) and the reviewer +follow-up confirming both referenced landings on `dev` (`5734a1ca` doctor, `bb3321ca` framing) and +the process-boundary conclusion. Verified in this tree: `collectCodexEnvKeyReadiness` +(`src/cli/doctor.ts:473`) and its action line; `src/codex/shim.ts:726` is the only reader that +exports the token into a Codex process; `src/cli/index.ts:241` exports it for `ocx` itself. +Verdict: pass for a docs-only closure; nothing in the plan changes runtime behavior. + diff --git a/docs-site/src/content/docs/reference/cli/lifecycle.md b/docs-site/src/content/docs/reference/cli/lifecycle.md index 75ca9da788a..46d34a84e5e 100644 --- a/docs-site/src/content/docs/reference/cli/lifecycle.md +++ b/docs-site/src/content/docs/reference/cli/lifecycle.md @@ -418,6 +418,32 @@ Use `ocx service` for an always-on background proxy (recommended). Use `ocx code lightweight, on-demand startup without a daemon — the proxy starts only when `codex` is launched. ::: +#### Token injection without the shim + +On a non-loopback bind the injected provider carries `env_key = "OPENCODEX_API_AUTH_TOKEN"`. That +line tells Codex which variable to read; it does not create it. Codex refuses to start a request +when the variable is missing (`Missing environment variable: OPENCODEX_API_AUTH_TOKEN`), and the +proxy is never reached. The value lives in `$OPENCODEX_HOME/service-api-token`; only a process that +exports it into Codex's environment closes the gap. + +What does carry the token into a Codex process: + +- the shim installed by `ocx codex-shim install` (reads the token file at launch; the supported path + for Codex started from shells, Desktop, cron, or another service); +- exporting `OPENCODEX_API_AUTH_TOKEN` yourself in the process that starts Codex — a shell profile, + the cron line, or an `Environment=`/`EnvironmentFile=` on the systemd unit that launches + **Codex** (not the proxy). Point it at the existing token file; do not copy the value into + `config.toml`. + +What does not: an `EnvironmentFile=` or `OCX_API_TOKEN_FILE` on `opencodex-proxy.service`. Those +configure the proxy process only and never flow into an independently launched `codex exec`. + +A Codex upgrade that replaces the launcher removes the shim; the next ordinary `ocx` command restores +it (see above), but a `codex exec` that runs before that fails. `ocx doctor` reports this exact +state under "Codex env_key launch readiness" (env_key configured, variable unset, shim missing or +unhealthy, token file present) with the repair command, and never prints the token. Reading the token +file directly from Codex is not something Codex supports, so there is no OpenCodex directive for it. + ### `ocx tray [--json] [--no-start]` Install and control the Windows status tray icon. It starts at Windows login and provides one-click