Agents panel reports SIGN-IN EXPIRED when only the 8-hour access token lapsed

[echelonzero]

System details

Intel i7-1185G7 / Iris Xe, Omarchy 4.0.3-1, Claude Code 2.1.265. bin/omarchy-agent-usage-claude on this machine is byte-identical to quattro HEAD, so the line numbers below are current.

What's wrong?

Leave the machine alone for ~8 hours and the agents panel reports SIGN-IN EXPIRED over stale limits. The sign-in has not expired. Launching claude clears it immediately.

Repro

1. Sign in to Claude Code, open the agents panel, confirm the limits are live.
2. Don't run claude for 8+ hours (overnight is enough).
3. Open the panel: SIGN-IN EXPIRED, "showing the last known limits", bars frozen where they last read.
4. Run claude in a terminal, then reopen the panel — green again.

Why

collect_limits branches on one field, bin/omarchy-agent-usage-claude:813:

if expires_at_ms > 0 and expires_at_ms <= time.time() * 1000:
    result["limits"] = fallback
    result["usageStatusText"] = "Sign-in expired"

expires_at_ms comes from claudeAiOauth.expiresAt in ~/.claude/.credentials.json (oauth_login, line 584). That is the access token, and it lives about 8 hours. The same file carries claudeAiOauth.refreshTokenExpiresAt — the actual sign-in — which is good for about 30 days. On this machine the access token lapses ~8h after the last claude run while the refresh token still has three weeks on it, and the panel calls that an expired sign-in.

The comment above the branch shows the 8-hour lapse is known and the message is deliberate. The lapse isn't the complaint; the wording is. SIGN-IN EXPIRED in the panel header, plus "Start Claude Code, or run claude auth login, to refresh it", tells a user their session died and invites a re-auth that isn't needed — for a cache that expired on schedule. Users will re-login, which is a browser round trip to fix nothing.

Two ways out, either is fine

1. Refresh instead of reporting. The refresh token is right there in the file. A collector that mints its own access token keeps the panel live without the CLI, and the "lapsed token" state stops existing.
2. Say what was measured. Keep the passive behaviour, but distinguish the two. Check refreshTokenExpiresAt first: if that has passed, Sign-in expired is the truth and claude auth login is the fix. If it hasn't, the state is a stale access token — something like Limits paused — run claude to refresh — and the help text should not mention re-authenticating.

Option 2 is the smaller change and removes the misleading half. Worth noting that option 1 has a sharp edge: a rejected refresh makes the CLI drop the stored tokens, so a collector doing its own refresh needs to handle rotation and write-back carefully, and races with a running CLI over the same file.

Which commands actually refresh — measured against a throwaway CLAUDE_CONFIG_DIR copy, so the real credential file was never touched. Useful if anyone documents a workaround:

• claude auth status does not refresh. Handed an expired token it reports loggedIn:true and leaves the file byte-identical.
• claude doctor does. Handed an expired token and a deliberately bogus refresh token, it came back with the stored tokens cleared — the server rejected the refresh — while the same run with the network blackholed (HTTPS_PROXY at a dead port) left the file untouched. Only a real round trip to the token endpoint explains the difference.

Locally I've worked around it with a user timer running claude doctor every 6 hours, which keeps the access token inside its window and the panel green. That's a patch on my side, not a fix — the panel is still reporting the wrong thing when it fires late.

[Plutarch01]

⚠ Outcome 2026-09-24 — read before deploying the loop below. Its first live window ran today: the gate fired 15:10 CEST with the token inside its final 15 minutes, doctor camped ~9 min printing healthy output each minute, then the ~15:17 refresh was rejected server-side and the CLI silently wiped both tokens (expiresAt 0, file 519→291 bytes, exit 0, no error text). Cause undetermined — our loop was the only process writing in the window, but a competing refresher sharing this login could not be fully excluded either. Do not deploy the loop below until the root cause is found; the timer here is disabled.

---

Update: this is the final shape of the workaround (rewriting my earlier comment, which went through hourly → 75-min-gate iterations that each had a hole). That window has now run — see the outcome at the top: it ended in the wipe, so the loop below is not recommended. The steady-state paths (gate skips, verify, tray update) remain proven live. Correction first, then the units.

Correction: a throwaway CLAUDE_CONFIG_DIR copy does not leave the real credential file untouched. I ran doctor against a copy holding my live refreshToken (expired expiresAt planted). It minted a new expiresAt in /tmp, and the next doctor against the real ~/.claude was rejected and cleared both tokens (expiresAt 0, file 519→291 bytes), forcing a browser claude auth login. That is direct evidence for the "sharp edge" on option 1 — a copy shares the refresh secret, and rotation burns the original. Verify refresh behavior against the real file (diff expiresAt/mtime before/after), never a copy carrying a live refresh token.

Verified here (Omarchy, Claude 2.1.278 via mise):

• auth status → exit 0, loggedIn:true, credential file byte-identical. Does not refresh.
• doctor → exit 0, rewrote expiresAt to a fresh +8h window on a naturally expired token. Free diagnostic (~0.6 s, no inference). This is the refresh to automate — not claude -p, which bills quota every fire.
• Two doctor failure modes found the hard way: it exits 0 without touching the file when the network isn't up (timer fired on overnight resume), and it is only proven to mint near/after expiry — a still-valid token it leaves alone. Both are handled below.

Design (correct regardless of doctor's exact refresh threshold):

• Absolute mise binary, not ~/.local/bin/claude — that wrapper runs mise use -g plus an unattended pull of newest claude on every fire.
• OnCalendar=*:0/10 + Persistent=true + OnBootSec=2min. Monotonic OnUnitActiveSec runs off CLOCK_MONOTONIC (pauses across suspend) and Persistent is silently ignored without OnCalendar (man systemd.timer). The 10-minute tick plus the camping loop bounds the worst tray gap to ~60 s past doctor's own refresh threshold, whatever it is; the gate below costs ~25 ms per tick and doctor itself runs only inside the window.
• 15-minute fail-open gate: skip only when the token is clearly valid; any read failure logs and runs, so a dead credential surfaces instead of skipping silently.
• Camping wrapper: when the gate fires, rerun doctor every 60s (up to 10 tries) until expiresAt moves forward. Pass on refresh or a token still valid beyond the window; fail the unit only when expired or about to lapse. A missing refreshToken fails immediately with a "needs interactive login" message. No Wants/After network-online.target — those order against nothing in a user unit; the retries own offline-at-fire instead.

~/.config/systemd/user/claude-token-refresh.service:

[Unit]
Description=Refresh Claude Code OAuth token (free doctor check)

[Service]
Type=oneshot
WorkingDirectory=%h
ExecCondition=%h/.local/bin/claude-token-check
ExecStart=%h/.local/bin/claude-token-refresh
TimeoutStartSec=17min
ExecStartPost=/usr/bin/omarchy-agent-usage-update claude

~/.config/systemd/user/claude-token-refresh.timer:

[Unit]
Description=Refresh Claude Code token every 10 minutes (catch up on resume)

[Timer]
OnBootSec=2min
OnCalendar=*:0/10
Persistent=true

[Install]
WantedBy=timers.target

~/.local/bin/claude-token-check (executable):

#!/usr/bin/python3
"""Gate: run doctor only when the token needs it; fail open with a log."""
import json
import sys
import time
import pathlib

try:
    data = json.loads((pathlib.Path.home() / ".claude" / ".credentials.json").read_text())
    login = data.get("claudeAiOauth") or {}
    exp = int(login.get("expiresAt") or 0)
    raise SystemExit(0 if exp <= (time.time() + 900) * 1000 else 1)
except SystemExit:
    raise
except Exception as exc:
    print(f"claude-token-check: credential read failed ({exc}), running refresh to surface failure",
          file=sys.stderr)
    raise SystemExit(0)

~/.local/bin/claude-token-refresh (executable):

#!/bin/sh
set -u
CLAUDE_BIN="$HOME/.local/share/mise/installs/claude/latest/claude"
BEFORE_EXPR='import json,pathlib; d=json.loads((pathlib.Path.home()/".claude/.credentials.json").read_text()).get("claudeAiOauth") or {}; print(int(d.get("expiresAt") or 0))'
HAS_EXPR='import json,pathlib,sys; d=json.loads((pathlib.Path.home()/".claude/.credentials.json").read_text()).get("claudeAiOauth") or {}; sys.exit(0 if d.get("refreshToken") else 3)'
CHECK_EXPR='import json,sys,time,pathlib; d=json.loads((pathlib.Path.home()/".claude/.credentials.json").read_text()).get("claudeAiOauth") or {}; after=int(d.get("expiresAt") or 0); sys.exit(0 if after > int(sys.argv[1]) or after > (time.time()+900)*1000 else 1)'
if python3 -c "$HAS_EXPR" 2>/dev/null; then
  :
elif [ "$?" -eq 3 ]; then
  echo "claude-token-refresh: no refresh token stored; needs interactive 'claude auth login'" >&2
  exit 1
fi
tries=10
while [ "$tries" -gt 0 ]; do
  BEFORE=$(python3 -c "$BEFORE_EXPR" 2>/dev/null || echo 0)
  "$CLAUDE_BIN" doctor
  if python3 -c "$CHECK_EXPR" "$BEFORE" 2>/dev/null; then
    exit 0
  fi
  tries=$((tries - 1))
  [ "$tries" -gt 0 ] && sleep 60
done
echo "claude-token-refresh: token not refreshed and near expiry" >&2
exit 1

Proven live: verify clean on both units, gate skips while fresh, doctor refreshes an expired token to a fresh +8h window, tray usageStatusText='' with both windows live. Superseded: the first live camping run happened on 2026-09-24 — see the outcome at the top. The retry path is therefore not awaiting validation; it is disqualified pending root cause. Still a workaround, not a fix — #8092's Limits paused vs Sign-in expired distinction remains the right upstream change.

[manuaudio]

Fixed on quattro by #14049, which carried #8093: when only the ~8-hour access token has lapsed, the Claude collector now reports "Limits paused" ("Claude Code's access token has lapsed"), and "Sign-in expired" is kept for a lapsed refresh token. I think this can be closed.