v3.20.1 — 2026-06-13
TUI-mode auth hardening: fixes the recurring Please run /login · API Error: 401 (the PI231 incident) and reaps leaked defunct claude sessions. (#141)
Fixed
- TUI 401 / credential corruption (#141) — interactive
claudeprefers~/.claude/.credentials.jsonover theCLAUDE_CODE_OAUTH_TOKENenv var (unlike-pmode, where the env token wins). OCP TUI's per-request spawn +kill-sessioncycle raced claude's single-use refresh-token rotation, corrupting the refresh token to an empty string → permanent 401 thatclaude /logincouldn't fix (each new spawn re-corrupted it). This bit Linux/file-based hosts specifically (macOS reads credentials from the Keychain, so Mac mini was immune). Fix: whenCLAUDE_CODE_OAUTH_TOKENis set, the TUI claude now runs in a credential-free scratch HOME (<HOME>/.ocp-tui/home, overridable byOCP_TUI_HOME) seeded with onboarding + cwd-trust but no.credentials.json, so the env token is the only credential and claude never runs the refresh path. Recurrence-proof — a laterclaude logincan no longer break TUI. Also:buildTuiCmdpassesCLAUDE_CODE_OAUTH_TOKENto the spawn, andreapStaleTuiSessionsreaps defunctclaudesessions (tmux-server-owned zombies) viakill-serverwhen no foreign session remains, plus a 15-min idle-gated periodic reap. When the env token is unset, behaviour is byte-for-byte unchanged (real-home + credentials.json). Two independent fresh-context reviewers (Iron Rule 10) + a live PI231 portability test (works with a corrupt credentials.json present). Authorized by the ADR 0007 PR-D amendment (Class B).
Environment variables
CLAUDE_CODE_OAUTH_TOKEN— when set on a TUI host, TUI authenticates via this long-lived token in a credential-isolated home (recommended; immune to credentials.json corruption).OCP_TUI_HOME— overrides the TUI scratch home; if you previously pointed it at your real home, unset it to get the credential-isolated default.