fix(auth): improved refresh token logic & token handling (#1066)

## Problem

The PostHog MCP server disconnects after some time and can't recover. Apparently, the problem was a combination of factors:
- Refreshing of OAuth tokens was happening in the background even if we had active agent sessions. Since the OAuth token is deleted from the database when it is refreshed, it exposes two bugs:
  - The MCP server couldn't find the old token while the session was still in progress, so it would throw 401.
  - The Claude Code adapter was opening a second ghost session by retrieving tools using the MCP SDK, so Claude Code was actually using two connections (it explained why I saw both regular tools and mcp-cli commands in some screenshots). The ghost session was never cleaned up, so when Claude Code received the updated MCP credentials, it preferred to use an open session with a stale token (it's most likely a bug in CC).
- `mcp-cli` was too experimental and didn't handle reconnections. I'm not sure here 100% because I think it might have handled reconnections, but tools were injected into the context by the ghost session, so the agent was obviously preferring contextual. However, it was removed from the new version of CC☹️ 
- The OAuth token update was too close to expiration (5m). As it appears, it was not enough for most internal usage sessions, since we've received a few reports of broken connections to the MCP.
- Related PR PostHog/posthog#49269 to update caching TTL of tokens, as the broken OAuth refresh was partially masked by the increased TTL of refreshed tokens.

## Changes

- Bumped token refresh from 5 minutes before expiration to 30 minutes. This gives enough time to find a window between active sessions and to propagate changes. 20 minutes might be fine, but sessions have become longer nowadays.
- Implemented smarter OAuth token refresh: If there are no active sessions, update. If there are active sessions, look for a window when they will all become inactive. Otherwise, update if we're very close to token expiration.
- Replaced the experimental MCP CLI with tool offloading. I'll additionally work on the MCP to increase the probability of tool discovery.
- Bumped CC to the new version, which required adding Sonnet 4.6: PostHog/posthog#49310.
- Fixed the ghost MCP session (next PR in the stack).

## Tests

Feels like this requires an e2e test?

Author: skoob13

apps/twig/src/main/services/agent/schemas.ts

@@ -187,6 +187,7 @@ export const subscribeSessionInput = z.object({
 export const AgentServiceEvent = {
   SessionEvent: "session-event",
   PermissionRequest: "permission-request",
+  SessionsIdle: "sessions-idle",
 } as const;
 
 export interface AgentSessionEventPayload {
@@ -205,6 +206,7 @@ export type PermissionRequestPayload = Omit<
 export interface AgentServiceEvents {
   [AgentServiceEvent.SessionEvent]: AgentSessionEventPayload;
   [AgentServiceEvent.PermissionRequest]: PermissionRequestPayload;
+  [AgentServiceEvent.SessionsIdle]: undefined;
 }
 
 // Permission response input for tRPC

apps/twig/src/main/services/agent/service.ts

@@ -368,6 +368,18 @@ export class AgentService extends TypedEventEmitter<AgentServiceEvents> {
     this.pendingPermissions.delete(key);
   }
 
+  /**
+   * Check if any sessions are currently active (i.e. have a prompt pending).
+   */
+  public hasActiveSessions(): boolean {
+    for (const session of this.sessions.values()) {
+      if (session.promptPending) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   private getToken(fallback: string): string {
     return this.currentToken || fallback;
   }
@@ -778,6 +790,10 @@ export class AgentService extends TypedEventEmitter<AgentServiceEvents> {
     } finally {
       session.promptPending = false;
       this.sleepService.release(sessionId);
+
+      if (!this.hasActiveSessions()) {
+        this.emit(AgentServiceEvent.SessionsIdle, undefined);
+      }
     }
   }
 

apps/twig/src/main/trpc/routers/agent.ts

@@ -142,6 +142,19 @@ export const agentRouter = router({
       getService().notifySessionContext(input.sessionId, input.context),
     ),
 
+  hasActiveSessions: publicProcedure.query(() =>
+    getService().hasActiveSessions(),
+  ),
+
+  onSessionsIdle: publicProcedure.subscription(async function* (opts) {
+    const service = getService();
+    for await (const _ of service.toIterable(AgentServiceEvent.SessionsIdle, {
+      signal: opts.signal,
+    })) {
+      yield true;
+    }
+  }),
+
   markAllForRecreation: publicProcedure.mutation(() =>
     getService().markAllSessionsForRecreation(),
   ),

apps/twig/src/renderer/features/auth/stores/authStore.ts

@@ -9,6 +9,7 @@ import {
   OAUTH_SCOPE_VERSION,
   OAUTH_SCOPES,
   TOKEN_REFRESH_BUFFER_MS,
+  TOKEN_REFRESH_FORCE_MS,
 } from "@shared/constants/oauth";
 import { ANALYTICS_EVENTS } from "@shared/types/analytics";
 import type { CloudRegion } from "@shared/types/oauth";
@@ -98,6 +99,75 @@ interface AuthState {
 
 let refreshTimeoutId: number | null = null;
 
+function isTokenExpiringSoon(tokenExpiry: number | null): boolean {
+  return (
+    tokenExpiry != null && tokenExpiry - Date.now() <= TOKEN_REFRESH_FORCE_MS
+  );
+}
+
+async function attemptRefreshWithActivityCheck(
+  getState: () => AuthState,
+): Promise<void> {
+  try {
+    // If the token is about to expire, skip the activity check and refresh immediately
+    if (isTokenExpiringSoon(getState().tokenExpiry)) {
+      log.warn(
+        "Token expiring imminently, forcing refresh despite active sessions",
+      );
+      await getState().refreshAccessToken();
+      return;
+    }
+
+    // Refresh if there are no active sessions
+    const hasActive = await trpcVanilla.agent.hasActiveSessions.query();
+    if (!hasActive) {
+      await getState().refreshAccessToken();
+      return;
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      let settled = false;
+      const settle = (reason: string, fn: () => Promise<void>) => {
+        if (settled) return;
+        settled = true;
+        subscription.unsubscribe();
+        window.clearInterval(expiryCheckId);
+        log.info(`Settling activity wait: ${reason}`);
+        fn().then(resolve).catch(reject);
+      };
+
+      // Subscribe to the idle event
+      const subscription = trpcVanilla.agent.onSessionsIdle.subscribe(
+        undefined,
+        {
+          onData: () =>
+            settle("sessions idle", () => getState().refreshAccessToken()),
+          onError: (error) => {
+            log.warn(
+              "Sessions idle subscription failed, refreshing anyway",
+              error,
+            );
+            settle("subscription error", () => getState().refreshAccessToken());
+          },
+        },
+      );
+
+      // Safety net: if the token is about to expire while we wait, force refresh
+      const expiryCheckId = window.setInterval(() => {
+        if (isTokenExpiringSoon(getState().tokenExpiry)) {
+          settle("token expiring imminently", () =>
+            getState().refreshAccessToken(),
+          );
+        }
+      }, TOKEN_REFRESH_FORCE_MS / 2);
+    });
+  } catch (error) {
+    // IPC call failed — refresh anyway (better than letting the token expire)
+    log.warn("Activity check failed, refreshing token anyway", error);
+    await getState().refreshAccessToken();
+  }
+}
+
 export const useAuthStore = create<AuthState>()(
   subscribeWithSelector(
     persist(
@@ -399,18 +469,14 @@ export const useAuthStore = create<AuthState>()(
 
           if (timeUntilRefresh > 0) {
             refreshTimeoutId = window.setTimeout(() => {
-              get()
-                .refreshAccessToken()
-                .catch((error) => {
-                  log.error("Proactive token refresh failed:", error);
-                });
+              attemptRefreshWithActivityCheck(get).catch((error) => {
+                log.error("Proactive token refresh failed:", error);
+              });
             }, timeUntilRefresh);
           } else {
-            get()
-              .refreshAccessToken()
-              .catch((error) => {
-                log.error("Immediate token refresh failed:", error);
-              });
+            attemptRefreshWithActivityCheck(get).catch((error) => {
+              log.error("Immediate token refresh failed:", error);
+            });
           }
         },
 

apps/twig/src/shared/constants/oauth.ts

@@ -47,7 +47,8 @@ export const REGION_LABELS: Record<CloudRegion, string> = {
 };
 
 // Token refresh settings
-export const TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1000; // 5 minutes before expiry
+export const TOKEN_REFRESH_BUFFER_MS = 30 * 60 * 1000; // 30 minutes before expiry
+export const TOKEN_REFRESH_FORCE_MS = 60 * 1000; // Force refresh when <1 min to expiry, even with active sessions
 
 export function getCloudUrlFromRegion(region: CloudRegion): string {
   switch (region) {

packages/agent/package.json

@@ -85,7 +85,7 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.14.0",
-    "@anthropic-ai/claude-agent-sdk": "0.2.58",
+    "@anthropic-ai/claude-agent-sdk": "0.2.59",
     "@anthropic-ai/sdk": "^0.71.0",
     "@hono/node-server": "^1.19.9",
     "@modelcontextprotocol/sdk": "^1.25.3",

packages/agent/src/adapters/claude/claude-agent.ts

@@ -33,7 +33,7 @@ import { v7 as uuidv7 } from "uuid";
 import packageJson from "../../../package.json" with { type: "json" };
 import type { SessionContext } from "../../otel-log-writer.js";
 import type { SessionLogWriter } from "../../session-log-writer.js";
-import { withTimeout } from "../../utils/common.js";
+import { unreachable, withTimeout } from "../../utils/common.js";
 import { Logger } from "../../utils/logger.js";
 import { Pushable } from "../../utils/streams.js";
 import { BaseAcpAgent } from "../base-acp-agent.js";
@@ -646,9 +646,9 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
         return null;
 
       default:
-        this.logger.warn("Unhandled message type", {
-          type: (message as { type: string }).type,
-        });
+        // SDKMessage union includes undefined types (SDKRateLimitEvent, SDKPromptSuggestionMessage)
+        // that resolve to `any`, preventing exhaustive narrowing
+        unreachable(message as never, this.logger);
         return null;
     }
   }

packages/agent/src/adapters/claude/session/options.ts

@@ -88,7 +88,8 @@ function buildEnvironment(): Record<string, string> {
     ...process.env,
     ELECTRON_RUN_AS_NODE: "1",
     CLAUDE_CODE_ENABLE_ASK_USER_QUESTION_TOOL: "true",
-    ENABLE_EXPERIMENTAL_MCP_CLI: "true",
+    // Offload all MCP tools by default
+    ENABLE_TOOL_SEARCH: "auto:0",
   };
 }
 

packages/agent/src/agent.ts

@@ -69,7 +69,7 @@ export class Agent {
     options: TaskExecutionOptions = {},
   ): Promise<InProcessAcpConnection> {
     const gatewayConfig = this._configureLlmGateway(options.adapter);
-
+    this.logger.info("Configured LLM gateway", options);
     this.taskRunId = taskRunId;
 
     let allowedModelIds: Set<string> | undefined;