claude-code-session-manager 0.112.0 → 0.114.0

package/src/main/config.cjs

@@ -392,8 +392,21 @@ function watchKeyOf(key, depth) {
  */
 function watch(paths, senderId, opts) {
   const depth = opts?.depth;
+  const watched = [];
+  const rejected = [];
   for (const rawPath of paths) {
-    validatePath(expandHome(rawPath)); // security check — throws if out of bounds
+    try {
+      validatePath(expandHome(rawPath)); // security check — throws if out of bounds
+    } catch (err) {
+      // Per-path: one bad path must not abort the rest of the batch.
+      rejected.push(rawPath);
+      if (!warnedRejectedPaths.has(rawPath)) {
+        warnedRejectedPaths.add(rawPath);
+        logs.writeLine({ level: 'warn', scope: 'config', message: 'config:watch path reject', meta: { path: rawPath, error: err?.message } });
+      }
+      continue;
+    }
+    watched.push(rawPath);
     const key = normalizePathKey(rawPath);
     const mapKey = watchKeyOf(key, depth);
     if (senderId != null) {
@@ -430,8 +443,12 @@ function watch(paths, senderId, opts) {
     });
     watchers.set(mapKey, { watcher: w, refCount: 1 });
   }
+  return { watched, rejected };
 }
 
+// Distinct rejected watch paths already warned about (once per process).
+const warnedRejectedPaths = new Set();
+
 function unwatch(paths, senderId, opts) {
   for (const rawPath of paths) {
     const key = watchKeyOf(normalizePathKey(rawPath), opts?.depth);

package/src/main/index.cjs

@@ -115,7 +115,6 @@ const { registerProjectBriefIpc } = require('./projectBrief.cjs');
 const { registerProjectPagesIpc, attachWindow: attachProjectPagesWindow, closeAllOutputWatchers: closeAllProjectPagesWatchers } = require('./projectPages.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const { computeEpicDelegationStats } = require('./lib/epic/epicDelegationStats.cjs');
-const agentMemory = require('./agentMemory.cjs');
 const git = require('./git.cjs');
 const heapSnapshot = require('./heapSnapshot.cjs');
 const filesIpc = require('./files.cjs');
@@ -1034,7 +1033,6 @@ ipcMain.handle('auditLog:append', validated(schemas.auditLogAppend, async ({ kin
   appendAuditEvent(kind, { cwd, epicId, source });
   return { ok: true };
 }));
-agentMemory.registerAgentMemoryHandlers();
 git.register(ipcMain);
 filesIpc.registerFilesHandlers();
 registerDocEditHandlers();
@@ -1402,6 +1400,12 @@ app.whenReady().then(async () => {
     console.log(`[main] scheduler ownership held by pid ${ownership.holderPid} — running scheduler-passive (no reconciliation, no admin server)`);
     logs.writeLine({ scope: 'scheduler', level: 'info', message: 'scheduler-passive: ownership held by another instance', meta: { holderPid: ownership.holderPid } });
   }
+  // Sweep orphaned `<file>.tmp-<pid>-…` files from crashed atomic writers in the
+  // machine-global state dir (per-project dirs belong to reconcile).
+  try {
+    const { removed } = require('./lib/util/atomicFs.cjs').sweepStaleTmpFiles(path.join(os.homedir(), '.claude', 'session-manager'));
+    logs.writeLine({ scope: 'main', level: 'info', message: 'stale tmp sweep', meta: { removed: removed.length } });
+  } catch { /* sweep is best-effort */ }
   // First-boot default: install the bundled session-manager-dev plugin (its 3
   // dev skills) from the app's own marketplace. One-shot + idempotent; never
   // throws. SM_SEED_DEV_PLUGIN_DISABLE=1 to opt out.

package/src/main/ipcSchemas.cjs

@@ -634,30 +634,48 @@ const { MEMORY_SLUG_RE } = require('./lib/memorySlug.cjs');
 // 1 MiB hard cap — matches MAX_FILE_BYTES in memoryTool.cjs.
 const MEMORY_MAX_BYTES = 1024 * 1024;
 
+// Optional native-dir addressing: `cwd` selects Claude Code's own workspace dir
+// (git root + autoMemoryDirectory); `agent` selects native subagent memory.
+const MEMORY_CWD = z.string().max(4096).optional();
+const MEMORY_AGENT = z.object({
+  name: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/),
+  scope: z.enum(['user', 'project', 'local']),
+}).strict().optional();
+
 const memoryList = z.object({
   workspace: z.string().regex(MEMORY_WORKSPACE_RE).optional(),
+  cwd: MEMORY_CWD,
+  agent: MEMORY_AGENT,
 }).strict();
 
 const memoryRead = z.object({
   workspace: z.string().regex(MEMORY_WORKSPACE_RE).optional(),
   name: z.string().regex(MEMORY_SLUG_RE),
+  cwd: MEMORY_CWD,
+  agent: MEMORY_AGENT,
 }).strict();
 
 const memoryWrite = z.object({
   workspace: z.string().regex(MEMORY_WORKSPACE_RE).optional(),
   name: z.string().regex(MEMORY_SLUG_RE),
   content: z.string().max(MEMORY_MAX_BYTES),
+  cwd: MEMORY_CWD,
+  agent: MEMORY_AGENT,
 }).strict();
 
 const memoryDelete = z.object({
   workspace: z.string().regex(MEMORY_WORKSPACE_RE).optional(),
   name: z.string().regex(MEMORY_SLUG_RE),
+  cwd: MEMORY_CWD,
+  agent: MEMORY_AGENT,
 }).strict();
 
 const memoryCreate = z.object({
   workspace: z.string().regex(MEMORY_WORKSPACE_RE).optional(),
   name: z.string().regex(MEMORY_SLUG_RE),
   description: z.string().max(2048).optional(),
+  cwd: MEMORY_CWD,
+  agent: MEMORY_AGENT,
 }).strict();
 
 // memory:stale — deterministic staleness scorer (PRD 601). `cwd`, when given,
@@ -666,6 +684,11 @@ const memoryCreate = z.object({
 const memoryStale = z.object({
   workspace: z.string().regex(MEMORY_WORKSPACE_RE).optional(),
   cwd: z.string().max(4096).optional(),
+  agent: MEMORY_AGENT,
+}).strict();
+
+const memoryAgents = z.object({
+  cwd: MEMORY_CWD,
 }).strict();
 
 // memory:aggregate — Memory Clusters (PRD 356). `workspace` here is already
@@ -826,36 +849,6 @@ const auditLogAppend = z.object({
   source: z.string().min(1).max(256),
 }).strict();
 
-// ──────────────────────────────────────────── Per-subagent memory
-// Distinct from the workspace-scoped Memory tool: agentMemory is keyed by
-// subagent name (the .md filename in ~/.claude/agents/, e.g. "code-reviewer"),
-// not by cwd. Storage lives at ~/.claude/session-manager/agent-memory/<agentId>.json.
-// Regex caps must stay in lockstep with agentMemory.cjs AGENT_ID_RE / ENTRY_ID_RE.
-const AGENT_MEMORY_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
-const AGENT_MEMORY_CATEGORY = z.enum(['command', 'preference', 'pattern', 'failure', 'workflow']);
-const AGENT_MEMORY_MAX_BODY = 1024 * 1024; // 1 MiB — must match MAX_BODY_BYTES in agentMemory.cjs
-
-const agentMemoryList = z.object({
-  agentId: z.string().regex(AGENT_MEMORY_ID_RE),
-}).strict();
-
-const agentMemoryGet = z.object({
-  agentId: z.string().regex(AGENT_MEMORY_ID_RE),
-  entryId: z.string().regex(AGENT_MEMORY_ID_RE),
-}).strict();
-
-const agentMemorySet = z.object({
-  agentId: z.string().regex(AGENT_MEMORY_ID_RE),
-  entryId: z.string().regex(AGENT_MEMORY_ID_RE),
-  body: z.string().max(AGENT_MEMORY_MAX_BODY),
-  category: AGENT_MEMORY_CATEGORY.optional(),
-}).strict();
-
-const agentMemoryDelete = z.object({
-  agentId: z.string().regex(AGENT_MEMORY_ID_RE),
-  entryId: z.string().regex(AGENT_MEMORY_ID_RE),
-}).strict();
-
 // ──────────────────────────────────────────── Exchanges (PRD 324 read path)
 const SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
 
@@ -919,6 +912,9 @@ const chatRun = z.object({
   // Originating PromptTicket.id (PRD 748) when this run was dequeued from a
   // tab's prompt queue — absent for a fresh manual send with no ticket.
   promptId: z.string().min(1).max(128).optional(),
+  // Who authored this send. Only 'human' is auto-approve evidence for
+  // crossProjectFeedback; absent or any other value is treated as not-human.
+  origin: z.enum(['human', 'external', 'inbound-proposal']).optional(),
 });
 
 const chatCancel = z.object({
@@ -1279,6 +1275,7 @@ module.exports = {
     memoryCreate,
     memoryAggregate,
     memoryStale,
+    memoryAgents,
     projectBriefCwd,
     projectPagesCwd,
     projectHomeAdminWriteBody,
@@ -1295,10 +1292,6 @@ module.exports = {
     promptSessionsGetWorktreeDisabled,
     promptSessionsSetWorktreeDisabled,
     auditLogAppend,
-    agentMemoryList,
-    agentMemoryGet,
-    agentMemorySet,
-    agentMemoryDelete,
     watchersAdd,
     watchersList,
     watchersRemove,

package/src/main/lib/activeSessions.cjs

@@ -37,6 +37,17 @@ const TMP_DROP_ROOTS = {
   get prefixDropRoots() { return [WORKTREE_KIND_CONFIG.job.root, WORKTREE_KIND_CONFIG.epic.root]; },
 };
 
+// Test-harness project cwds live at <tmpdir>/sst-*/…. They are never real
+// projects, and leaking them into the active list made the renderer's batched
+// config:watch hit 618 "Path outside allowed boundaries" rejects. Only the
+// `sst-` first segment is matched, so test-stubbed HOMEs that are not sst-*
+// dirs (see the exactDropCwds note above) are still kept.
+function isSstHarnessCwd(cwd) {
+  const rel = path.relative(TMPDIR, cwd);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return false;
+  return rel.split(path.sep)[0].startsWith('sst-');
+}
+
 // Transcript reads only need the last line with a `cwd` field — a few dozen
 // lines is always enough. 64 KB keeps peak RSS proportionate.
 const TAIL_BYTES = 64 * 1024;
@@ -389,6 +400,7 @@ function deriveCwds(records, maxAgeMin, maxCwds, tmpDropRoots) {
       return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
     });
     if (isUnderPrefixDropRoot) return;
+    if (isSstHarnessCwd(cwd)) return;
     if (seen.has(cwd) || result.length >= maxCwds) return;
     // Must exist AND be a directory — a transcript naming a since-deleted
     // path, or a file, is not a project.
@@ -456,6 +468,7 @@ module.exports = {
   allProjectCwds,
   projectRootOf,
   worktreeMainRootOf,
+  isSstHarnessCwd,
   bustProjectCwdCache,
   __waitForPendingRefresh,
 };

package/src/main/lib/claude/rateLimitDetect.cjs

@@ -13,20 +13,39 @@
 
 const { readTail } = require('../util/fileTail.cjs');
 
-/** Scan the tail of a job's log for the canonical rate-limit signal. We look
- *  at the last 16 KB — final result event always lands at the end. Covers
- *  both unified-window rate-limit types (five_hour, seven_day), the raw
- *  429 status, and the two human-readable limit-message phrasings the CLI
- *  emits ("You've hit your limit" / "You've reached your <model> limit"). */
+/** Scan the tail of a job's log for a GENUINE rate-limit rejection. Parses the
+ *  last 16 KB line by line as JSON (non-JSON / partial lines are skipped) and
+ *  returns true only for: (a) a rate_limit_event whose rate_limit_info.status
+ *  is 'rejected'; (b) a result event with api_error_status 429; (c) an
+ *  is_error result event whose `result` text is the CLI's limit message
+ *  ("You've hit your ... limit" / "You've reached your ... limit").
+ *
+ *  Never substring-match the raw text: informational rate_limit_event lines
+ *  (status 'allowed' / 'allowed_warning') carry rateLimitType on every run, so
+ *  the old substring match turned any non-zero exit (e.g. a watchdog SIGTERM,
+ *  exit 143) into a machine-wide rate_limit pause (2026-10-11 incident: 4-day
+ *  pause at 58% weekly). Tool output may also mention 429 or "rate limit". */
 function detectRateLimitInLog(logPath) {
   try {
     const text = readTail(logPath, 16384);
     if (!text) return false;
-    return /"rateLimitType":"five_hour"/.test(text)
-      || /"rateLimitType":"seven_day"/.test(text)
-      || /"api_error_status":429/.test(text)
-      || /You'?ve hit your limit/.test(text)
-      || /You'?ve reached your .* limit/.test(text);
+    for (const line of text.split('\n')) {
+      const t = line.trim();
+      if (!t || t[0] !== '{') continue;
+      let ev;
+      try { ev = JSON.parse(t); } catch { continue; }
+      if (!ev || typeof ev !== 'object') continue;
+      if (ev.type === 'rate_limit_event') {
+        if (ev.rate_limit_info && ev.rate_limit_info.status === 'rejected') return true;
+      } else if (ev.type === 'result') {
+        if (ev.api_error_status === 429) return true;
+        if (ev.is_error === true && typeof ev.result === 'string'
+          && (/You'?ve hit your .*limit/.test(ev.result) || /You'?ve reached your .* limit/.test(ev.result))) {
+          return true;
+        }
+      }
+    }
+    return false;
   } catch {
     return false;
   }

package/src/main/lib/claude/rateLimitWindow.cjs

@@ -21,17 +21,21 @@ const { readTail } = require('../util/fileTail.cjs');
 const TAIL_BYTES = 64 * 1024;
 
 /**
- * Scans a run log's tail for rate_limit_event entries and returns the
- * UNIX-seconds resetsAt of the window that actually bound (utilization >= 1.0)
- * in the LAST such event. When multiple windows bind in that event, the
- * latest resetsAt wins. Returns null when no rate_limit_event is found, or
- * none of its windows are at/above 1.0 utilization.
+ * Scans a run log's tail for rate_limit_event entries. The REJECTED event is
+ * authoritative (2026-10-11 incident: an allowed-only log with a seven_day
+ * window pause landed on the seven_day reset 4 days out): if any event has
+ * status 'rejected', the LAST one's reset wins — rate_limit_info.resetsAt, else
+ * unifiedWindows[rateLimitType].resetsAt. Otherwise, a last event carrying a
+ * status (allowed / allowed_warning) yields null, even if a window shows
+ * utilization >= 1.0 (overage is not a rejection). Legacy: a last event with
+ * no status falls back to the latest resetsAt among windows at utilization >= 1.0.
  */
 function resolveBindingRateLimitReset(logPath) {
   const text = readTail(logPath, TAIL_BYTES);
   if (!text) return null;
 
-  let lastWindows = null;
+  let lastRejected = null;
+  let lastEvent = null;
   for (const line of text.split('\n')) {
     const trimmed = line.trim();
     if (!trimmed || trimmed[0] !== '{') continue;
@@ -41,12 +45,20 @@ function resolveBindingRateLimitReset(logPath) {
     } catch {
       continue;
     }
-    const windows = event?.rate_limit_info?.unifiedWindows;
-    if (event?.type === 'rate_limit_event' && windows && typeof windows === 'object') {
-      lastWindows = windows;
-    }
+    if (event?.type !== 'rate_limit_event' || !event.rate_limit_info) continue;
+    lastEvent = event.rate_limit_info;
+    if (lastEvent.status === 'rejected') lastRejected = lastEvent;
+  }
+
+  if (lastRejected) {
+    if (typeof lastRejected.resetsAt === 'number') return lastRejected.resetsAt;
+    const typed = lastRejected.unifiedWindows?.[lastRejected.rateLimitType]?.resetsAt;
+    return typeof typed === 'number' ? typed : null;
   }
-  if (!lastWindows) return null;
+  if (!lastEvent || lastEvent.status !== undefined) return null;
+
+  const lastWindows = lastEvent.unifiedWindows;
+  if (!lastWindows || typeof lastWindows !== 'object') return null;
 
   let latestBoundReset = null;
   for (const window of Object.values(lastWindows)) {

package/src/main/lib/credentials.cjs

@@ -6,7 +6,6 @@ const path = require('node:path');
 const os = require('node:os');
 const { spawn, execFileSync } = require('node:child_process');
 const { cleanChildEnv, pathWithUserBins } = require('./process/cleanEnv.cjs');
-const atomicFs = require('./util/atomicFs.cjs');
 const { resolveClaudeBin, claudeSpawnTarget } = require('./claude/claudeBin.cjs');
 
 const CREDS_PATH = path.join(os.homedir(), '.claude', '.credentials.json');
@@ -47,22 +46,9 @@ function keychainAccount() {
   return os.userInfo().username;
 }
 
-/** Write the credential JSON back into the Keychain (-U upserts in place). */
-function writeKeychainRaw(value) {
-  execFileSync(
-    'security',
-    ['add-generic-password', '-U', '-s', KEYCHAIN_SERVICE, '-a', keychainAccount(), '-w', value],
-    { timeout: 10_000, stdio: 'ignore' },
-  );
-}
 const REFRESH_LOG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'credential-refresh.log');
 const REFRESH_LOG_MAX_BYTES = 100 * 1024;
 
-// Standard OAuth 2.0 refresh grant — endpoint discovered from Claude Code CLI behavior.
-// Returns { kind: 'unsupported' } if the endpoint returns 404 or cannot be reached,
-// allowing the caller to fall back gracefully.
-const OAUTH_TOKEN_URL = 'https://claude.ai/api/auth/oauth/token';
-
 /** Parse a raw credential JSON blob (from file or Keychain) into a result. */
 function parseCredsRaw(raw, source) {
   let data;
@@ -125,14 +111,13 @@ function isExpiringSoon(creds, withinMs = 5 * 60_000) {
  * isRefreshFutile(creds) → boolean
  *
  * True when the token is already expired AND there is no refresh token to
- * present. In that state every refresh avenue is a dead end: tryOAuthRefresh
- * short-circuits to 'unsupported' (it needs `creds.refreshToken`), and the
+ * present. In that state the refresh avenue is a dead end: the
  * `claude --version` CLI fallback performs its own silent OAuth refresh from
  * that SAME missing refresh token, so it cannot help either. The only recovery
  * is an out-of-band `claude login` — which refreshIfNeeded picks up on its very
  * next call via the isExpiringSoon early-return, since fresh creds never reach
  * this path. Left ungated, this state made pollLoop spawn a `claude --version`
- * process and write the oauth_refresh_unsupported → cli_fallback_ok →
+ * process and write the cli_fallback_ok →
  * auth_failed_expired triple on EVERY 15 s poll, forever (observed 2026-09-23:
  * expiredAtMs 1775277875159, identical triple every ~15 min across the log).
  */
@@ -153,17 +138,6 @@ function __resetFutileRefreshThrottle() {
   lastFutileRefreshLoggedAt = null;
 }
 
-async function writeCredentials(rawData, freshOauth, source = 'file') {
-  const next = { ...rawData, claudeAiOauth: { ...rawData.claudeAiOauth, ...freshOauth } };
-  if (source === 'keychain') {
-    // macOS: upsert back into the Keychain. Sync + may throw — caller catches
-    // and falls back to the `claude --version` CLI refresh path.
-    writeKeychainRaw(JSON.stringify(next));
-    return;
-  }
-  await atomicFs.writeJsonAtomic(CREDS_PATH, next, { mode: 0o600, newline: false });
-}
-
 function appendRefreshLog(entry) {
   try {
     const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + '\n';
@@ -179,36 +153,7 @@ function appendRefreshLog(entry) {
   } catch { /* non-fatal; telemetry must not break the main flow */ }
 }
 
-// Stretch: attempt standard OAuth 2.0 refresh token grant.
-async function tryOAuthRefresh(creds) {
-  if (!creds.refreshToken) return { kind: 'unsupported', message: 'no refresh token in credentials' };
-  try {
-    const r = await fetch(OAUTH_TOKEN_URL, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ grant_type: 'refresh_token', refresh_token: creds.refreshToken }),
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (r.status === 404) return { kind: 'unsupported', message: 'refresh endpoint not found (HTTP 404)' };
-    if (r.status === 401 || r.status === 403) return { kind: 'auth', message: `refresh rejected: HTTP ${r.status}` };
-    if (!r.ok) return { kind: 'transient', message: `HTTP ${r.status}` };
-    const j = await r.json();
-    if (!j.access_token) return { kind: 'auth', message: 'no access_token in refresh response' };
-    return {
-      kind: 'ok',
-      fresh: {
-        accessToken: j.access_token,
-        refreshToken: j.refresh_token ?? creds.refreshToken,
-        expiresAt: j.expires_at ?? (Date.now() + (j.expires_in ?? 3600) * 1000),
-      },
-    };
-  } catch (e) {
-    if (e?.name === 'TimeoutError') return { kind: 'transient', message: 'refresh request timed out' };
-    return { kind: 'unsupported', message: `refresh error: ${e?.message}` };
-  }
-}
-
-// Stretch fallback: spawning `claude --version` triggers silent token refresh in the CLI binary.
+// Sole refresh avenue: spawning `claude --version` triggers silent token refresh in the CLI binary.
 function tryCliFallback() {
   return new Promise((resolve) => {
     let settled = false;
@@ -244,7 +189,7 @@ function tryCliFallback() {
 async function refreshIfNeeded(forceRefresh = false) {
   const cr = await readCredentials();
   if (cr.kind !== 'ok') return cr;
-  const { creds, raw, source } = cr;
+  const { creds } = cr;
 
   if (!forceRefresh && !isExpiringSoon(creds)) {
     return { kind: 'ok', creds };
@@ -253,12 +198,12 @@ async function refreshIfNeeded(forceRefresh = false) {
   const alreadyExpired = isExpired(creds);
 
   // Futile-refresh short-circuit: token already expired AND no refresh token
-  // to present. Every downstream avenue (OAuth grant, `claude --version` CLI
-  // fallback) is a guaranteed dead end from the same missing token, so running
-  // them on every 15 s poll only spawns a doomed child process and re-logs the
+  // to present. The `claude --version` CLI fallback is a guaranteed dead end
+  // from the same missing token, so running it on every 15 s poll only spawns
+  // a doomed child process and re-logs the
   // same triple forever (2026-09-23 storm). Re-read once — cheap, and the ONE
   // real recovery (`claude login`) lands here — then, if still futile, return
-  // the auth verdict WITHOUT the OAuth call or the CLI-fallback spawn, logging
+  // the auth verdict WITHOUT the CLI-fallback spawn, logging
   // at most once per FUTILE_REFRESH_COOLDOWN_MS instead of every poll.
   if (isRefreshFutile(creds)) {
     const recheckCr = await readCredentials();
@@ -279,38 +224,19 @@ async function refreshIfNeeded(forceRefresh = false) {
     };
   }
 
-  // Stretch: try OAuth refresh endpoint first.
-  const oauthResult = await tryOAuthRefresh(creds);
-  appendRefreshLog({ event: `oauth_refresh_${oauthResult.kind}`, message: oauthResult.message ?? null });
-
-  if (oauthResult.kind === 'ok') {
-    try {
-      await writeCredentials(raw, oauthResult.fresh, source);
-      const freshCr = await readCredentials();
-      if (freshCr.kind === 'ok') {
-        appendRefreshLog({ event: 'oauth_refresh_written_ok' });
-        return { kind: 'ok', creds: freshCr.creds };
-      }
-    } catch (e) {
-      appendRefreshLog({ event: 'oauth_refresh_write_failed', error: e?.message });
-    }
-  }
-
-  // Stretch: if OAuth didn't explicitly reject the token, try `claude --version` fallback.
-  if (oauthResult.kind !== 'auth') {
-    const cliResult = await tryCliFallback();
-    appendRefreshLog({ event: cliResult.ok ? 'cli_fallback_ok' : 'cli_fallback_failed', reason: cliResult.reason ?? null });
-    if (cliResult.ok) {
-      const freshCr = await readCredentials();
-      if (freshCr.kind === 'ok' && !isExpired(freshCr.creds)) {
-        return { kind: 'ok', creds: freshCr.creds };
-      }
+  // The CLI owns the real refresh contract: `claude --version` refreshes silently.
+  const cliResult = await tryCliFallback();
+  appendRefreshLog({ event: cliResult.ok ? 'cli_fallback_ok' : 'cli_fallback_failed', reason: cliResult.reason ?? null });
+  if (cliResult.ok) {
+    const freshCr = await readCredentials();
+    if (freshCr.kind === 'ok' && !isExpired(freshCr.creds)) {
+      return { kind: 'ok', creds: freshCr.creds };
     }
   }
 
   if (alreadyExpired) {
     // Re-read from disk in case credentials were externally refreshed (e.g. via
-    // `claude login`) between our initial read and the failed OAuth attempt.
+    // `claude login`) between our initial read and the failed CLI fallback.
     const recheckCr = await readCredentials();
     if (recheckCr.kind === 'ok' && !isExpired(recheckCr.creds)) {
       appendRefreshLog({ event: 'externally_refreshed_ok', recheckExpiresAt: recheckCr.creds.expiresAt ?? null });