Campaign: support isolated Codex authentication on headless Linux

[jeffhuber]

Part of roadmap #900. Follow-up from the owner-supplied v1.4.0 hosted Ubuntu adoption report; planned after v1.4.1 stabilization/Graphify and before final v1.5.0 qualification. This does not add a dependency to stabilization epic #979 or delay #915.

Problem and verified scope

The released isolated Codex campaign home uses keyring-only credentials. A headless host can have working ordinary Codex/Claude authentication while the isolated Codex release-campaign lane remains unavailable. Merged #953/#966 fixes unrelated campaign-auth owner actions when no campaign is intended; it does not implement non-keyring campaign authentication. Preserve that distinction and the existing credential-isolation contract.

Outcome / PR mapping

One bounded OSS PR provides an explicitly selected, supported isolated authentication path for Codex campaigns on headless Linux, with the same readiness rule used by the adapter and doctor. Planned Code Mower Codex builder and independent eligible Code Mower Claude review. Coordinate campaign authentication sources with #976 release reporting; this is separate from #962 runner/Git handoff capability and from hosted Devin role qualification.

Acceptance criteria

• Verify the supported Codex CLI credential mechanisms against the maintained CLI/official contract before choosing an implementation; do not assume file or environment inheritance is safe or supported.
• Explicit opt-in bootstrap uses a protected credential boundary scoped to the campaign adapter. Preserve restricted provider configuration, workspace containment, and existing keyring mode; no silent ambient-home/token fallback, credential copies into the model-readable workspace, or broad credential inheritance.
• Adapter execution and doctor probe use the same selected isolated authentication source. Ordinary adoption with no campaign intent remains free of campaign-auth owner actions.
• Headless cold-start, authenticated, logged-out, missing/unavailable credential source, restart, and revoked-auth cases produce bounded actionable diagnostics. An unsupported mode never becomes a readiness pass.
• Tests prove secrets do not enter argv, prompts, transcripts, reports, public JSON, generated setup, or model-readable artifacts; review isolation/permission behavior and backwards compatibility.
• Document the supported headless setup and its remaining operator actions. Normal CLI login, transport installation, and campaign readiness remain separate.
• Obtain an independent exact-head Code Mower audit, resolve P0/P1/P2, and pass focused/relevant checks, normal CI and authoritative gate before merge. Bind inclusion to the published package before marking shipped.

If no supported mechanism meets the isolation boundary, record the evidence and propose an explicit scope revision before calling this item complete. Do not weaken isolation to satisfy the adoption report. No new paid canary, hosted-Devin create, recovery allowance, credential purchase, or owner token provisioning is authorized by this issue.

[jeffhuber]

Work Order: implement supported isolated Codex authentication for headless campaigns

Build #983 from current main at 5272bfe33d5d5fc583ab672352ee86f880ec5701 with one Code Mower Claude writer and one focused PR. The prior Codex assignment was a scheduling proposal; Claude owns this unit now so #983 can proceed in parallel with Codex-owned #977.

First verify the maintained Codex CLI credential contract from installed/official surfaces. Implement only an explicitly selected isolated authentication source that preserves the campaign boundary: no silent ambient-home or token fallback, no secret in argv/prompts/transcripts/reports/public JSON/generated setup/model-readable artifacts, and no weakening of keyring mode. Adapter execution and doctor must apply the same readiness rule. Ordinary adoption without campaign intent must remain free of campaign-auth owner actions.

Cover headless cold start, authenticated, logged-out, missing/unavailable source, restart and revoked-auth cases. Avoid #977 supervisor adapter ownership and avoid paid/hosted sessions or credential provisioning. Run focused and relevant tests, privacy/package checks, commit and push a single claude/ branch, open a draft PR closing #983, add builder:claude and request needs-codex-audit. If the supported CLI exposes no mechanism meeting the isolation boundary, record the evidence and stop for scope revision instead of weakening isolation.

[jeffhuber]

Claude lane - Dispatch for claude: implement issue #983 ("Campaign: support isolated Codex authentication on headless Linux") following docs/lanes/claude.md and docs/build-loop.md. Open exactly one PR, add builder:claude and audit labels: needs-codex-audit. Comment here with the PR link and head SHA when it is ready.

[jeffhuber]

Claude lane — #983 delivered as a draft PR.

PR: #1010 (closes #983)
Branch: claude/983-isolated-codex-auth-headless
Head SHA: 2c2dbf13e4cfacdadcb18f4e21239f61b0123cfc
Labels: builder:claude, needs-codex-audit

Contract verified before implementing

The installed codex binary could not be executed in this lane's sandbox (codex --version and codex login --help were both denied; WebFetch was denied too). The maintained contract was therefore read from upstream source via the GitHub API rather than assumed:

• codex-rs/core/config.schema.json, AuthCredentialsStoreMode — cli_auth_credentials_store accepts exactly file ("Persist credentials in CODEX_HOME/auth.json"), keyring ("Persist credentials in the keyring. Fail if unavailable"), auto, ephemeral.
• codex-rs/config/defaults.toml — cli_auth_credentials_store = "file" is the packaged default, so file mode is a maintained default store, not a side path.
• codex-rs/cli/src/login.rs — --with-api-key takes the key on stdin; --device-auth is the documented headless flow; run_login_status calls load_auth(/*enable_codex_api_key_env*/ false), so login status ignores the ambient API-key environment and reports the isolated home's own stored credential.
• codex-rs/core/src/config/auth_keyring.rs — secret_auth_storage selects only the keyring backend kind, so it is meaningless for a file-backed home.

What shipped

CODE_MOWER_CODEX_CAMPAIGN_AUTH_MODE explicitly selects the isolated source: unset/keyring is the released behaviour unchanged, file is the opt-in headless path. auto and ephemeral are refused (neither names one explicit durable source), and any unrecognized value fails closed in the adapter and becomes an actionable doctor warning — never a skip, because a skip would leave the provider in ready_providers.

File mode keeps the same restricted provider configuration, workspace containment, 0700/0600 credential permissions, and refusal of symlinks or non-regular credential files. No ambient-home or ambient-token fallback, no credential copy into the model-readable workspace, no weakening of keyring mode. Doctor and the adapter resolve the source through one shared helper. Only the bounded words keyring/file and present/missing/unusable reach doctor JSON. Ordinary adoption with no campaign intent still asks the owner for nothing (#953/#966 boundary preserved).

Docs: docs/release-qualification.md → "Headless Linux campaign authentication" (mode table, setup steps, what changes and what does not, remaining operator actions). CHANGELOG.md Unreleased/Added.

Tests run

Command	Result
scripts/dev-python -m pytest tests/test_codex_campaign_auth_modes.py -q	30 passed, 14 subtests
scripts/dev-python -m pytest tests/test_doctor_campaign_auth.py -q	passed
scripts/dev-python -m pytest tests/test_campaign_adapters.py tests/test_release_hygiene.py -q	457 passed, 959 subtests
scripts/dev-python scripts/privacy_scan.py	privacy scan passed
scripts/dev-python -m pytest tests -q (full suite)	running at hand-off

One existing assertion in tests/test_doctor_campaign_auth.py was narrowed rather than deleted: it forbade the substring keyring anywhere in rendered doctor output, which now legitimately contains the bounded campaign_auth_mode word. It now asserts the probe's own text (failed to read keyring entry, user@example.com) is absent and that the mode word is the fixed constant, so the privacy guarantee it protected is intact and stated more precisely.

What remains

1. Independent exact-head Codex audit at 2c2dbf1 (needs-codex-audit requested); resolve any P0/P1/P2.
2. Normal CI and the authoritative gate must pass — running at hand-off.
3. Mark the PR ready for review and merge.
4. Bind inclusion to the published package before marking Campaign: support isolated Codex authentication on headless Linux #983 shipped.

Owner note: the file-mode path was exercised only through tests and the verified upstream contract. A one-time real headless-Linux run of the documented codex login --with-api-key / --device-auth setup against the isolated home is the remaining end-to-end confirmation; it needs a credential, so this lane did not attempt it.