@pharaoh-so/mcp 0.3.21 → 0.3.23

package/dist/auth.d.ts

@@ -12,6 +12,15 @@ export interface TokenResponse {
     access_token: string;
     token_type: string;
     expires_in: number;
+    /**
+     * Refresh token for silent access-token renewal. Present on all new sessions
+     * (server at src/web/routes/agent-auth.ts). Optional at the type level only
+     * for backward compat with hypothetical older servers — if missing, the proxy
+     * falls through to the full re-auth path on expiry.
+     */
+    refresh_token?: string;
+    /** Refresh token TTL in seconds. */
+    refresh_token_expires_in?: number;
     sse_url: string;
     github_login?: string;
     tenant_name?: string;
@@ -19,17 +28,65 @@ export interface TokenResponse {
     provisional?: boolean;
     install_url?: string;
 }
+/**
+ * Result of a single poll against /device/token.
+ *
+ * This type is the contract between the state-machine gateway (gateway.ts),
+ * the blocking interactive poller (pollForToken), and the test harness. It
+ * collapses HTTP details into the four lifecycle outcomes callers actually
+ * need to branch on, plus a network_error bucket so callers can distinguish
+ * "server said no" from "couldn't reach server."
+ */
+export type PollResult = {
+    status: "pending";
+    slowDown?: boolean;
+} | {
+    status: "authorized";
+    token: TokenResponse;
+} | {
+    status: "expired";
+} | {
+    status: "denied";
+    error: string;
+} | {
+    status: "network_error";
+    error: string;
+};
 /**
  * Request a device code from the Pharaoh server (RFC 8628 §3.1).
  * Returns the device code, user code, and verification URIs.
  */
 export declare function requestDeviceCode(baseUrl: string): Promise<DeviceCodeResponse>;
+/**
+ * Perform one POST to /device/token. No loop, no sleep — maps HTTP responses
+ * into a PollResult discriminated union.
+ *
+ * Called in two shapes:
+ * - pollForToken() (TTY path): loops with interval+jitter until terminal state.
+ * - gateway.handleToolCall() (proxy path): called once per tool call, gated
+ *   by a last_poll_at check against the server's interval.
+ *
+ * Note: slow_down is mapped to "pending" — the caller's pacing logic is what
+ * responds to it. pollForToken bumps its local interval; gateway relies on the
+ * server-specified interval it already tracks. This keeps pollOnce stateless.
+ */
+export declare function pollOnce(baseUrl: string, deviceCode: string): Promise<PollResult>;
 /**
  * Poll for device authorization completion (RFC 8628 §3.5).
  * Blocks until the user authorizes, the code expires, or an error occurs.
  * Adds 1s jitter to the server-specified interval to avoid thundering herd.
  */
 export declare function pollForToken(baseUrl: string, deviceCode: string, interval: number): Promise<TokenResponse>;
+/**
+ * Open a URL in the user's default browser.
+ * Uses platform-specific commands; fails silently if unavailable.
+ *
+ * Exported for gateway.ts — the state machine fires this once per device code
+ * to pre-fill the activation URL in the user's browser. Silent-on-failure is
+ * critical for headless environments: a missing `open`/`xdg-open` binary must
+ * not crash the proxy.
+ */
+export declare function openBrowser(url: string): void;
 /**
  * Print the device activation prompt to stderr.
  * Shows the user code and verification URI in a visible box,

package/dist/auth.js

@@ -19,48 +19,94 @@ export async function requestDeviceCode(baseUrl) {
     }
     return (await res.json());
 }
+/**
+ * Perform one POST to /device/token. No loop, no sleep — maps HTTP responses
+ * into a PollResult discriminated union.
+ *
+ * Called in two shapes:
+ * - pollForToken() (TTY path): loops with interval+jitter until terminal state.
+ * - gateway.handleToolCall() (proxy path): called once per tool call, gated
+ *   by a last_poll_at check against the server's interval.
+ *
+ * Note: slow_down is mapped to "pending" — the caller's pacing logic is what
+ * responds to it. pollForToken bumps its local interval; gateway relies on the
+ * server-specified interval it already tracks. This keeps pollOnce stateless.
+ */
+export async function pollOnce(baseUrl, deviceCode) {
+    const grantType = "urn:ietf:params:oauth:grant-type:device_code";
+    let res;
+    try {
+        res = await fetch(`${baseUrl}/device/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ device_code: deviceCode, grant_type: grantType }),
+        });
+    }
+    catch (err) {
+        return {
+            status: "network_error",
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    if (res.ok) {
+        const token = (await res.json());
+        return { status: "authorized", token };
+    }
+    const body = (await res.json().catch(() => ({ error: "unknown" })));
+    if (body.error === "authorization_pending") {
+        return { status: "pending" };
+    }
+    if (body.error === "slow_down") {
+        return { status: "pending", slowDown: true };
+    }
+    if (body.error === "expired_token") {
+        return { status: "expired" };
+    }
+    if (body.error === "access_denied") {
+        return { status: "denied", error: "Authorization was denied." };
+    }
+    return {
+        status: "denied",
+        error: `Device token error: ${body.error} — ${body.error_description ?? ""}`,
+    };
+}
 /**
  * Poll for device authorization completion (RFC 8628 §3.5).
  * Blocks until the user authorizes, the code expires, or an error occurs.
  * Adds 1s jitter to the server-specified interval to avoid thundering herd.
  */
 export async function pollForToken(baseUrl, deviceCode, interval) {
-    const grantType = "urn:ietf:params:oauth:grant-type:device_code";
+    let currentInterval = interval;
     while (true) {
         // Wait interval + 0–1s jitter before each poll
         const jitterMs = Math.random() * 1000;
-        await sleep(interval * 1000 + jitterMs);
-        const res = await fetch(`${baseUrl}/device/token`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ device_code: deviceCode, grant_type: grantType }),
-        });
-        if (res.ok) {
-            return (await res.json());
-        }
-        const body = (await res.json().catch(() => ({ error: "unknown" })));
-        if (body.error === "authorization_pending") {
-            continue;
-        }
-        if (body.error === "slow_down") {
-            // RFC 8628 §3.5: increase interval by 5 seconds
-            interval += 5;
-            continue;
-        }
-        if (body.error === "expired_token") {
+        await sleep(currentInterval * 1000 + jitterMs);
+        const result = await pollOnce(baseUrl, deviceCode);
+        if (result.status === "authorized")
+            return result.token;
+        if (result.status === "expired") {
             throw new Error("Device code expired. Please try again.");
         }
-        if (body.error === "access_denied") {
-            throw new Error("Authorization was denied.");
-        }
-        throw new Error(`Device token error: ${body.error} — ${body.error_description ?? ""}`);
+        if (result.status === "denied")
+            throw new Error(result.error);
+        if (result.status === "network_error")
+            throw new Error(result.error);
+        // result.status === "pending". RFC 8628 §3.5: only bump interval on
+        // slow_down (authorization_pending is the normal polling response).
+        if (result.slowDown)
+            currentInterval += 5;
     }
 }
 /**
  * Open a URL in the user's default browser.
  * Uses platform-specific commands; fails silently if unavailable.
+ *
+ * Exported for gateway.ts — the state machine fires this once per device code
+ * to pre-fill the activation URL in the user's browser. Silent-on-failure is
+ * critical for headless environments: a missing `open`/`xdg-open` binary must
+ * not crash the proxy.
  */
-function openBrowser(url) {
+export function openBrowser(url) {
     if (process.platform === "darwin") {
         execFile("open", [url], () => { });
     }

package/dist/backend.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Backend interface — the abstraction the ProxyServer delegates tool calls to.
+ *
+ * Two concrete implementations:
+ *
+ * 1. AuthRequiredBackend — advertises a single tool (`get_codebase_map`) that
+ *    turns every invocation into a device-flow state step. Used while the
+ *    proxy is waiting for the user to authorize.
+ *
+ * 2. SseProxyBackend (returned by createSseBackend) — wraps an MCP Client
+ *    connected to the remote Pharaoh SSE server. Forwards list/call requests
+ *    verbatim and preserves the ghost-session reconnect fix from proxy.ts.
+ *
+ * ProxyServer swaps between the two by reassigning a reference. The SDK
+ * resolves each tool call's handler at request-arrival time, so in-flight
+ * calls complete against whichever backend started them.
+ */
+import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { DeviceFlowGateway } from "./gateway.js";
+/** The contract ProxyServer uses to delegate tool handling. */
+export interface Backend {
+    readonly name: "auth-required" | "sse";
+    listTools(): Promise<Tool[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    /** Optional one-time startup (e.g. connect SSE). Idempotent. */
+    start?(): Promise<void>;
+    /** Optional teardown (e.g. close SSE). Idempotent. */
+    stop?(): Promise<void>;
+}
+/**
+ * Minimal pre-auth catalog. Single tool — matches Pharaoh's "call this first"
+ * protocol (CLAUDE.md, skills), so the pre-auth surface mirrors the first
+ * tool most agents try. Keeping this at 1 means the swap to the real catalog
+ * fires a clean visible sendToolListChanged delta.
+ *
+ * If you add tools here, sync with src/mcp/tool-registry.ts in the main
+ * package — descriptions should match so agents get consistent behavior
+ * across the pre-auth / authorized transition.
+ */
+export declare const AUTH_REQUIRED_TOOLS: Tool[];
+/**
+ * Pre-auth backend. Every tool call triggers a device-flow state step via the
+ * gateway; returns a structured auth-required response. Once the gateway
+ * reports the user has authorized (handleToolCall returns null), the caller
+ * (ProxyServer) swaps to SseProxyBackend — this backend does NOT swap itself.
+ */
+export declare class AuthRequiredBackend implements Backend {
+    private readonly gateway;
+    readonly name: "auth-required";
+    constructor(gateway: DeviceFlowGateway);
+    listTools(): Promise<Tool[]>;
+    callTool(_name: string, _args: Record<string, unknown>): Promise<CallToolResult>;
+}
+/**
+ * Real SSE-backed backend. Owns an MCP Client + SSEClientTransport and a
+ * reconnect loop. Forwards listTools/callTool to the remote server.
+ *
+ * Reconnect semantics (preserved verbatim from the old startProxy):
+ *   EventSource's built-in auto-reconnect creates ghost sessions on the
+ *   server (new auth, new session ID per 3s reconnect). On any non-fatal
+ *   error we explicitly close() the transport to kill EventSource, then
+ *   let this loop create a fresh transport for the next attempt. 5 retries
+ *   (2s, 4s, 8s, 16s, 32s) before giving up.
+ */
+declare class SseProxyBackend implements Backend {
+    private readonly sseUrl;
+    private readonly token;
+    readonly name: "sse";
+    private client;
+    private transport;
+    private stopped;
+    private reconnectPromise;
+    constructor(sseUrl: string, token: string);
+    start(): Promise<void>;
+    /**
+     * Expose the long-running reconnect loop so a supervisor can await it.
+     * Session C uses this to bubble TokenExpiredError / TenantSuspendedError
+     * up to the same handler that used to wrap `startProxy`.
+     */
+    waitForExit(): Promise<void>;
+    private connectOnce;
+    /** Wait for the current transport to close, then decide what to do. */
+    private waitForClose;
+    private reconnectAfter;
+    private runReconnectLoop;
+    listTools(): Promise<Tool[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    stop(): Promise<void>;
+}
+/**
+ * Public factory — ProxyServer / Session C build SSE backends via this.
+ * Keeps the SseProxyBackend class private so callers can't accidentally
+ * depend on its internal reconnect state.
+ */
+export declare function createSseBackend(sseUrl: string, token: string): SseProxyBackend;
+export {};

package/dist/backend.js

@@ -0,0 +1,250 @@
+/**
+ * Backend interface — the abstraction the ProxyServer delegates tool calls to.
+ *
+ * Two concrete implementations:
+ *
+ * 1. AuthRequiredBackend — advertises a single tool (`get_codebase_map`) that
+ *    turns every invocation into a device-flow state step. Used while the
+ *    proxy is waiting for the user to authorize.
+ *
+ * 2. SseProxyBackend (returned by createSseBackend) — wraps an MCP Client
+ *    connected to the remote Pharaoh SSE server. Forwards list/call requests
+ *    verbatim and preserves the ghost-session reconnect fix from proxy.ts.
+ *
+ * ProxyServer swaps between the two by reassigning a reference. The SDK
+ * resolves each tool call's handler at request-arrival time, so in-flight
+ * calls complete against whichever backend started them.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { classifySSEError, TenantSuspendedError, TokenExpiredError } from "./proxy.js";
+import { getPackageVersion } from "./version.js";
+/**
+ * Minimal pre-auth catalog. Single tool — matches Pharaoh's "call this first"
+ * protocol (CLAUDE.md, skills), so the pre-auth surface mirrors the first
+ * tool most agents try. Keeping this at 1 means the swap to the real catalog
+ * fires a clean visible sendToolListChanged delta.
+ *
+ * If you add tools here, sync with src/mcp/tool-registry.ts in the main
+ * package — descriptions should match so agents get consistent behavior
+ * across the pre-auth / authorized transition.
+ */
+export const AUTH_REQUIRED_TOOLS = [
+    {
+        name: "get_codebase_map",
+        description: "Pharaoh — call this FIRST to understand the codebase structure. " +
+            "Requires authentication; calling this tool will surface the auth URL.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: {
+                    type: "string",
+                    description: "Optional repo slug (owner/name) to map.",
+                },
+            },
+        },
+    },
+];
+/**
+ * Pre-auth backend. Every tool call triggers a device-flow state step via the
+ * gateway; returns a structured auth-required response. Once the gateway
+ * reports the user has authorized (handleToolCall returns null), the caller
+ * (ProxyServer) swaps to SseProxyBackend — this backend does NOT swap itself.
+ */
+export class AuthRequiredBackend {
+    gateway;
+    name = "auth-required";
+    constructor(gateway) {
+        this.gateway = gateway;
+    }
+    async listTools() {
+        return AUTH_REQUIRED_TOOLS;
+    }
+    async callTool(_name, _args) {
+        const response = await this.gateway.handleToolCall();
+        if (response === null) {
+            // Credentials just became valid. Return a success result so the
+            // agent's current tool call doesn't error out. ProxyServer checks
+            // gateway.hasValidCredentials() after each call and swaps backends.
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Pharaoh: authenticated. Call this tool again to get the codebase map.",
+                    },
+                ],
+                isError: false,
+            };
+        }
+        // The gateway response shape is CallToolResult-compatible (content,
+        // isError, _meta) — the MCP SDK accepts it verbatim.
+        return response;
+    }
+}
+/** Backoff schedule for reconnect attempts (milliseconds). */
+const BACKOFF_MS = [2000, 4000, 8000, 16000, 32000];
+/**
+ * Build the SSEClientTransport with Bearer token auth. Injects the
+ * Authorization header into both the SSE connection (via custom fetch) and
+ * POST requests (via requestInit).
+ */
+function createSSETransport(sseUrl, token) {
+    const authHeader = `Bearer ${token}`;
+    return new SSEClientTransport(new URL(sseUrl), {
+        eventSourceInit: {
+            fetch: (url, init) => {
+                const h = new Headers(init.headers);
+                h.set("Authorization", authHeader);
+                return fetch(url, { ...init, headers: h });
+            },
+        },
+        requestInit: {
+            headers: { Authorization: authHeader },
+        },
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Real SSE-backed backend. Owns an MCP Client + SSEClientTransport and a
+ * reconnect loop. Forwards listTools/callTool to the remote server.
+ *
+ * Reconnect semantics (preserved verbatim from the old startProxy):
+ *   EventSource's built-in auto-reconnect creates ghost sessions on the
+ *   server (new auth, new session ID per 3s reconnect). On any non-fatal
+ *   error we explicitly close() the transport to kill EventSource, then
+ *   let this loop create a fresh transport for the next attempt. 5 retries
+ *   (2s, 4s, 8s, 16s, 32s) before giving up.
+ */
+class SseProxyBackend {
+    sseUrl;
+    token;
+    name = "sse";
+    client = null;
+    transport = null;
+    stopped = false;
+    reconnectPromise = null;
+    constructor(sseUrl, token) {
+        this.sseUrl = sseUrl;
+        this.token = token;
+    }
+    async start() {
+        if (this.client)
+            return; // idempotent
+        await this.connectOnce();
+        // Keep the reconnect loop alive in the background. It resolves when
+        // the SSE stream closes cleanly; on typed errors (401/403) it throws.
+        this.reconnectPromise = this.runReconnectLoop();
+        // Surface typed errors at the top level so the CLI (or future
+        // supervisor) can act on them.
+        this.reconnectPromise.catch(() => {
+            /* error is retrieved via waitForExit() when needed */
+        });
+    }
+    /**
+     * Expose the long-running reconnect loop so a supervisor can await it.
+     * Session C uses this to bubble TokenExpiredError / TenantSuspendedError
+     * up to the same handler that used to wrap `startProxy`.
+     */
+    waitForExit() {
+        return this.reconnectPromise ?? Promise.resolve();
+    }
+    async connectOnce() {
+        this.transport = createSSETransport(this.sseUrl, this.token);
+        this.client = new Client({ name: "pharaoh-proxy", version: getPackageVersion() }, { capabilities: {} });
+        await this.client.connect(this.transport);
+    }
+    /** Wait for the current transport to close, then decide what to do. */
+    waitForClose() {
+        return new Promise((resolve, reject) => {
+            if (!this.transport) {
+                resolve();
+                return;
+            }
+            const sse = this.transport;
+            sse.onclose = () => resolve();
+            sse.onerror = (err) => {
+                try {
+                    classifySSEError(err);
+                }
+                catch (typed) {
+                    reject(typed);
+                    return;
+                }
+                // Non-fatal — explicitly close the transport to kill
+                // EventSource's built-in auto-reconnect. Without this,
+                // EventSource reconnects every ~3s, creating ghost sessions
+                // on the server (100+ auth successes, zero tool calls
+                // completing). close() fires onclose which resolves this
+                // promise, handing control back to the backoff loop.
+                sse.close().catch(() => { });
+            };
+        });
+    }
+    async reconnectAfter(attempt) {
+        const delay = BACKOFF_MS[attempt - 1];
+        process.stderr.write(`Pharaoh: reconnecting in ${delay / 1000}s (attempt ${attempt}/${BACKOFF_MS.length})...\n`);
+        await sleep(delay);
+        await this.connectOnce();
+        process.stderr.write("Pharaoh: reconnected\n");
+    }
+    async runReconnectLoop() {
+        process.stderr.write("Pharaoh: connected\n");
+        let attempt = 0;
+        while (!this.stopped) {
+            try {
+                await this.waitForClose();
+                attempt++;
+                if (attempt > BACKOFF_MS.length) {
+                    process.stderr.write("Pharaoh: max reconnect attempts reached — exiting\n");
+                    throw new Error("SSE connection failed after maximum retries");
+                }
+                await this.reconnectAfter(attempt);
+                attempt = 0;
+            }
+            catch (err) {
+                if (err instanceof TokenExpiredError || err instanceof TenantSuspendedError) {
+                    throw err;
+                }
+                attempt++;
+                if (attempt > BACKOFF_MS.length) {
+                    throw err instanceof Error
+                        ? err
+                        : new Error("SSE connection failed after maximum retries");
+                }
+            }
+        }
+    }
+    async listTools() {
+        if (!this.client)
+            throw new Error("SseProxyBackend.listTools() before start()");
+        const res = await this.client.listTools();
+        return res.tools;
+    }
+    async callTool(name, args) {
+        if (!this.client)
+            throw new Error("SseProxyBackend.callTool() before start()");
+        const res = await this.client.callTool({ name, arguments: args });
+        return res;
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.transport) {
+            await this.transport.close().catch(() => { });
+            this.transport = null;
+        }
+        if (this.client) {
+            await this.client.close().catch(() => { });
+            this.client = null;
+        }
+    }
+}
+/**
+ * Public factory — ProxyServer / Session C build SSE backends via this.
+ * Keeps the SseProxyBackend class private so callers can't accidentally
+ * depend on its internal reconnect state.
+ */
+export function createSseBackend(sseUrl, token) {
+    return new SseProxyBackend(sseUrl, token);
+}

package/dist/credentials.d.ts

@@ -1,12 +1,21 @@
-/** Current credential schema version — bump when the format changes. */
-declare const SCHEMA_VERSION = 1;
+/**
+ * Current credential schema version. v2 adds refresh_token + refresh_expires_at
+ * so the proxy can silently renew access tokens. v1 files parse as null, which
+ * forces one re-auth on upgrade — unavoidable because v1 never had a refresh
+ * token to upgrade from.
+ */
+declare const SCHEMA_VERSION = 2;
 /** Stored credential shape. */
 export interface Credentials {
     version: typeof SCHEMA_VERSION;
     access_token: string;
-    /** ISO 8601 timestamp when the token expires. */
+    /** Refresh token used by refreshIfNeeded() to renew the access token. */
+    refresh_token: string;
+    /** ISO 8601 timestamp when the access token expires. */
     expires_at: string;
-    /** Original TTL in seconds (from the token response). */
+    /** ISO 8601 timestamp when the refresh token itself expires. */
+    refresh_expires_at: string;
+    /** Original access token TTL in seconds (from the token response). */
     expires_in: number;
     sse_url: string;
     github_login: string | null;
@@ -15,7 +24,8 @@ export interface Credentials {
 }
 /**
  * Read and parse stored credentials. Returns null if missing, unreadable,
- * malformed, or wrong schema version.
+ * malformed, or wrong schema version (v1 credentials will return null here,
+ * forcing one last re-auth on upgrade to v2).
  */
 export declare function readCredentials(path?: string): Credentials | null;
 /**
@@ -26,8 +36,13 @@ export declare function writeCredentials(creds: Credentials, path?: string): voi
 /** Delete the credential file. No-op if it doesn't exist. */
 export declare function deleteCredentials(path?: string): void;
 /**
- * Check if credentials are expired or within 10% of expiry.
+ * Check if the access token is expired or within 10% of expiry.
  * The 10% buffer prevents connecting with a token that will expire mid-session.
  */
 export declare function isExpired(creds: Credentials): boolean;
+/**
+ * Check if the refresh token itself has expired. When this returns true, even
+ * refresh cannot rescue the session — the user must re-authenticate.
+ */
+export declare function isRefreshExpired(creds: Credentials): boolean;
 export {};

package/dist/credentials.js

@@ -5,13 +5,19 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-/** Current credential schema version — bump when the format changes. */
-const SCHEMA_VERSION = 1;
+/**
+ * Current credential schema version. v2 adds refresh_token + refresh_expires_at
+ * so the proxy can silently renew access tokens. v1 files parse as null, which
+ * forces one re-auth on upgrade — unavoidable because v1 never had a refresh
+ * token to upgrade from.
+ */
+const SCHEMA_VERSION = 2;
 /** Default credential file path. */
 const CREDENTIALS_PATH = join(homedir(), ".pharaoh", "credentials.json");
 /**
  * Read and parse stored credentials. Returns null if missing, unreadable,
- * malformed, or wrong schema version.
+ * malformed, or wrong schema version (v1 credentials will return null here,
+ * forcing one last re-auth on upgrade to v2).
  */
 export function readCredentials(path = CREDENTIALS_PATH) {
     try {
@@ -46,7 +52,7 @@ export function deleteCredentials(path = CREDENTIALS_PATH) {
     }
 }
 /**
- * Check if credentials are expired or within 10% of expiry.
+ * Check if the access token is expired or within 10% of expiry.
  * The 10% buffer prevents connecting with a token that will expire mid-session.
  */
 export function isExpired(creds) {
@@ -58,6 +64,16 @@ export function isExpired(creds) {
     const bufferMs = totalTtlMs * 0.1;
     return now >= expiresAt - bufferMs;
 }
+/**
+ * Check if the refresh token itself has expired. When this returns true, even
+ * refresh cannot rescue the session — the user must re-authenticate.
+ */
+export function isRefreshExpired(creds) {
+    const refreshExpiresAt = new Date(creds.refresh_expires_at).getTime();
+    if (Number.isNaN(refreshExpiresAt))
+        return true;
+    return Date.now() >= refreshExpiresAt;
+}
 /** Type guard for valid credential objects. */
 function isValidCredentials(value) {
     if (typeof value !== "object" || value === null)
@@ -65,7 +81,9 @@ function isValidCredentials(value) {
     const obj = value;
     return (obj.version === SCHEMA_VERSION &&
         typeof obj.access_token === "string" &&
+        typeof obj.refresh_token === "string" &&
         typeof obj.expires_at === "string" &&
+        typeof obj.refresh_expires_at === "string" &&
         typeof obj.expires_in === "number" &&
         typeof obj.sse_url === "string" &&
         Array.isArray(obj.repos));