PR #74493: fix(cli): identity-only auth-epoch hashing for token credentials (#74312)

• Repository: openclaw/openclaw
• Author: stainlu
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/74493

Description (problem / solution / changelog)

Summary

• Problem: Claude CLI sessions are hard-reset every few minutes during active conversations on macOS. Logs show cli session reset: provider=claude-cli reason=auth-epoch clusters that correlate with claude-cli's OAuth token rotation. Reporter (#74312) observed ~16 resets in 24h on one host, accelerating to 2 resets in 3 minutes near token expiry. The user's live conversation context is dropped on every rotation.
• Why it matters: macOS Claude keychain rewrites are non-atomic. A read during rotation can briefly see accessToken without refreshToken, causing parseClaudeCliOauthCredential to return type: "token" instead of type: "oauth". The previous encodeClaudeCredential token branch hashed credential.token directly, so that transient race flipped the auth-epoch and reset every reusable claude-cli session. On macOS keychain-only setups (no ~/.claude/.credentials.json fallback), getLocalCliCredentialFingerprint returns undefined and the auth-profile branch is the dominant trigger; encodeAuthProfileCredential token case had the same hash-rotates-with-token defect.
• What changed: Extends the identity-only hashing pattern Ayaan started in 1ff461fe7b (fix(cli): stabilize oauth session auth epochs) and 3eb6edc67c (fix(cli): key oauth session epochs on identity), and which Chunyue extended to Gemini in #71076, to the static-token credential branch. encodeClaudeCredential routes both OAuth and token claude-cli credentials through encodeOAuthIdentity, collapsing partial keychain reads onto the same provider-keyed identity hash. encodeAuthProfileCredential token case drops credential.token from the hash; identity fields (provider, tokenRef, email, displayName) are the discriminator. CLI_AUTH_EPOCH_VERSION bumped 4 → 5.
• What did NOT change: parseClaudeCliOauthCredential (the parser, not hardened here per scope discipline; identity-only hashing makes the partial-read race harmless without parser changes), the OAuth branches (already identity-only since 3eb6edc67c), Gemini and Codex encoders (already identity-only), resolveCliAuthEpoch orchestration, or any consumer code (prepareExecution reads the same string).

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #74312
• Related: 1ff461fe7b, 3eb6edc67c, #71076 (the OAuth + Gemini precedent)
• This PR fixes a bug or regression

Root Cause

• Root cause: encodeClaudeCredential and encodeAuthProfileCredential retained credential.token in the auth-epoch hash for the static-token branch, even though Ayaan's recent commits had moved OAuth credentials and Chunyue's #71076 had moved Gemini OAuth onto identity-only hashing. The remaining token branches hashed rotating material, so any transient type: "token" parse (which the macOS keychain rewrite race triggers reliably) flipped the epoch.
• Missing detection / guardrail: The existing test asserted token rotation expect(second).not.toBe(first) — i.e., locked in the buggy behavior. There was no regression case proving OAuth and token claude-cli epochs match (which the partial-read race requires).
• Contributing context: parseClaudeCliOauthCredential falls through to type: "token" when refreshToken is empty/missing. This is correct for credentials that were never OAuth, but produces false type: "token" parses during keychain rotation. The hash semantics needed to be stable across that fallthrough.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/cli-auth-epoch.test.ts
• Scenarios the tests lock in:
  • keeps claude cli token epochs stable across token rotation (replaces the previous changes ... when the static token changes assertion)
  • matches claude cli token and oauth epochs so partial keychain reads do not flip (new regression case for the partial-read race)
  • keeps token auth-profile epochs stable across credential.token rotation (auth-profile branch — the dominant trigger on keychain-only macOS setups)
  • changes token auth-profile epochs when the email identity changes (preserves real account-switch invalidation)

User-visible / Behavior Changes

• Active claude-cli conversations no longer drop context every few minutes during token rotation.
• cli session reset: reason=auth-epoch log lines no longer correlate with token rotation; they now only fire on real identity changes (provider, email, tokenRef, displayName).
• CLI_AUTH_EPOCH_VERSION bumped 4 → 5; existing stored auth-epochs invalidate once on first read after upgrade (one expected reset per host on the upgrade boundary).
• No config changes, no new directives.

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No (the hash is over identity fields; tokens are still read and used for auth requests, just no longer included in the epoch fingerprint)
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS (reporter on Ubuntu Kylin 20.04 — keychain race is macOS-specific but auth-profile branch hits other platforms via auth-profile sync)
• Backend: claude-cli with OAuth credentials in macOS keychain

Steps (per reporter)

1. Run a long-lived claude-cli agent on Telegram or another active channel.
2. Monitor gateway.out for cli session reset: provider=claude-cli reason=auth-epoch lines.
3. Observe that resets correlate with claude-cli OAuth token rotation activity (~every 30-60 minutes, accelerating near token expiry).

Expected (after this PR)

No auth-epoch resets during normal token rotation. Conversation context preserved across rotations.

Actual (before this PR)

Resets on every rotation. Each reset drops mid-conversation context. Reporter measured ~16 resets/24h, peaking at 2 resets in 3 minutes near token expiry.

Actual (after this PR)

Local test verification: pnpm test src/agents/cli-auth-epoch.test.ts → 12 passed (9 prior + 3 new). The 3 new cases prove (a) token rotation no longer flips, (b) OAuth and token epochs match, (c) auth-profile token rotation no longer flips. A real email identity change still flips the epoch (regression guard).

Evidence

RUN  v4.1.5
Test Files  1 passed (1)
     Tests  12 passed (12)

pnpm test src/agents/cli-auth-epoch.test.ts → 12 passed. pnpm test src/agents/cli-credentials.test.ts → 16 passed (no regressions). pnpm test src/agents/cli-session.test.ts → 12 passed (auth-epoch consumer). pnpm tsgo:core and pnpm tsgo:core:test clean. oxlint 0 warnings, 0 errors. Format check clean.

Followed clawsweeper acceptance criteria from the issue:

• pnpm test src/agents/cli-auth-epoch.test.ts src/agents/cli-credentials.test.ts ✓
• pnpm exec oxfmt --check --threads=1 src/agents/cli-auth-epoch.ts src/agents/cli-auth-epoch.test.ts ✓

Human Verification

• Verified the new regression cases catch the bug: temporarily reverting either guard makes the relevant new test fail with the exact expect(second).toBe(first) mismatch.
• Verified that real account changes still invalidate: the new "changes token auth-profile epochs when the email identity changes" test asserts the inverse and passes.
• Verified that the OAuth side is unaffected: the existing OAuth tests (keeps identity-less claude cli oauth epochs stable across token changes, keeps oauth auth-profile epochs stable across token refreshes, changes oauth auth-profile epochs when the account identity changes) all still pass with their original assertions.
• Confirmed no other consumers depend on the old token-flipping behavior — cli-session.test.ts (12 tests) and cli-credentials.test.ts (16 tests) both pass unchanged. prepareExecution at src/agents/cli-runner/prepare.ts:216 only reads the resolved string, not the encoding internals.
• What I did not verify: live macOS keychain race reproduction. The fix is at the encoding layer, upstream of any keychain or parser behavior; with the encoding stable, the parser's fallthrough is harmless.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes for runtime behavior. The CLI_AUTH_EPOCH_VERSION bump (4 → 5) means cached epochs from prior versions invalidate once on first read; users see one expected auth-epoch reset on the upgrade boundary, then stable epochs afterward.
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: A user actually using a static type: "token" credential (e.g. PAT) and switching to a different token for the SAME identity will no longer get a session reset on the swap. Mitigation: This is the intended behavior per Ayaan's OAuth pattern — token replacement is an authorized refresh, not an identity change. Real identity changes (different email/provider/tokenRef) still invalidate.
• Risk: The parseClaudeCliOauthCredential partial-read fallthrough still produces a "token" credential type that gets persisted to auth-profile, even though the hash is now stable. The semantic is misleading (claude-cli OAuth users may see a "token" auth-profile entry). Mitigation: Out of scope for this PR per the reporter's preferred fix shape ("identity-only hash for both types"). If parser hardening is desired as defense-in-depth, that's a clean follow-up — the current fix is sufficient for the reported symptom.
• Risk: CLI_AUTH_EPOCH_VERSION bump invalidates cached epochs once. Mitigation: Documented behavior; one-time upgrade-boundary reset is acceptable cost vs ongoing rotation-induced resets.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/cli-auth-epoch.test.ts (modified, +127/-3)
• src/agents/cli-auth-epoch.ts (modified, +19/-6)