---
type: auth-credentials
coverage: 5
source: COMPLAINT_REGISTRY.jsonl via taxonomy.json _meta (2026-08-08)
absorbs: [credential-session-loss]
---

# KB — auth-credentials

audience: AI coding agents first. Type-level patterns; per-incident entries land separately.

## Coverage

5 records (`credential-session-loss`). Three independent planes — mixing them is top failure mode.

## Recurring failure patterns

1. **Wrong plane diagnosed** — account routing vs seat credential vs workstation root conflated.
2. **Hand-seeded token** — `scp` auth.json to buildbox instead of `seat-creds.mjs` convergence.
3. **Dangling symlink** — `~/.codex/auth.json` points to inactive account; agent assumes logged out.
4. **Exit 97 misread as auth** — local-dispatch-guard, not credential; fix is routing not login.
5. **`--account`/`--profile` misuse** — pins wrong account; `seat-run.sh` exit 3.

## Fix vectors that worked

- `cdx route` / `cdx --status` before any auth edit.
- Digest compare local vs remote credential paths; let convergence run on dispatch.
- `od-auth` skill — automate probes first; owner last resort.

## Related skill

`od-auth` (existing — not part of phase-2 new skill set)