feat: add copilot token health alerting

Author: jcaose

logbook.md

@@ -209,6 +209,18 @@ Working tree progress:
 - Updated the dashboard top badges to show `Active Backend` separately from `Scope`, and adjusted related status/log copy to use `scope` wording where the dashboard is describing filtered history rather than the process runtime backend.
 - Added coverage that the overview API preserves the active backend even when the dashboard is filtered to a different backend scope.
 
+## 2026-03-21
+
+### Copilot token health alerting
+
+Working tree progress:
+
+- Added Copilot token expiry tracking and refresh-failure state in `src/lib/state.ts` and `src/lib/token.ts`.
+- Switched Copilot token refresh to record failures without crashing the process, so the existing token can stay in use until the next successful refresh.
+- Added a dashboard token-health endpoint and a persistent top banner that appears when the Copilot token has expired and refresh has failed.
+- Added coverage for token-health reporting, the refresh failure path, and the dashboard shell for the banner.
+- Updated the Responses SSE route test fixture so the mocked module still provides the route-level normalization export.
+
 ## Commit Trail
 
 - `42214b8` 2026-03-08 `feat: port PR #205 — Responses API support and model-level routing`

src/lib/copilot-token-health.ts

@@ -0,0 +1,46 @@
+import { type CopilotTokenRefreshError, state } from "./state"
+
+export interface CopilotTokenHealthResponse {
+  alert: boolean
+  backend: typeof state.backend
+  expired: boolean
+  expiresAt?: number
+  refreshError?: CopilotTokenRefreshError
+}
+
+export interface CopilotTokenResponse {
+  expires_at: number
+  refresh_in: number
+  token: string
+}
+
+export function recordCopilotTokenSuccess(
+  response: CopilotTokenResponse,
+): void {
+  state.copilotToken = response.token
+  state.copilotTokenExpiresAt = response.expires_at
+  state.copilotTokenRefreshError = undefined
+}
+
+export function recordCopilotTokenRefreshFailure(error: unknown): void {
+  state.copilotTokenRefreshError = {
+    at: Date.now(),
+    message: error instanceof Error ? error.message : String(error),
+  }
+}
+
+export function getCopilotTokenHealth(
+  now: number = Date.now(),
+): CopilotTokenHealthResponse {
+  const expiresAt = state.copilotTokenExpiresAt
+  const expired = typeof expiresAt === "number" && now >= expiresAt
+  const refreshError = state.copilotTokenRefreshError
+
+  return {
+    alert: state.backend === "copilot" && expired && Boolean(refreshError),
+    backend: state.backend,
+    expired,
+    expiresAt,
+    ...(refreshError ? { refreshError } : {}),
+  }
+}

src/lib/state.ts

@@ -15,10 +15,17 @@ export interface OpenAIOAuthState {
   accountId: string
 }
 
+export interface CopilotTokenRefreshError {
+  at: number
+  message: string
+}
+
 export interface State {
   backend: BackendId
   githubToken?: string
   copilotToken?: string
+  copilotTokenExpiresAt?: number
+  copilotTokenRefreshError?: CopilotTokenRefreshError
   openaiOAuth?: OpenAIOAuthState
 
   accountType: string

src/lib/token.ts

@@ -7,6 +7,10 @@ import { getDeviceCode } from "~/services/github/get-device-code"
 import { getGitHubUser } from "~/services/github/get-user"
 import { pollAccessToken } from "~/services/github/poll-access-token"
 
+import {
+  recordCopilotTokenRefreshFailure,
+  recordCopilotTokenSuccess,
+} from "./copilot-token-health"
 import { HTTPError } from "./error"
 import { state } from "./state"
 
@@ -15,30 +19,34 @@ const readGithubToken = () => fs.readFile(PATHS.GITHUB_TOKEN_PATH, "utf8")
 const writeGithubToken = (token: string) =>
   fs.writeFile(PATHS.GITHUB_TOKEN_PATH, token)
 
+export async function refreshCopilotToken(): Promise<void> {
+  consola.debug("Refreshing Copilot token")
+  try {
+    const response = await getCopilotToken()
+    recordCopilotTokenSuccess(response)
+    consola.debug("Copilot token refreshed")
+    if (state.showToken) {
+      consola.info("Refreshed Copilot token:", response.token)
+    }
+  } catch (error) {
+    recordCopilotTokenRefreshFailure(error)
+    consola.error("Failed to refresh Copilot token:", error)
+  }
+}
+
 export const setupCopilotToken = async () => {
-  const { token, refresh_in } = await getCopilotToken()
-  state.copilotToken = token
+  const response = await getCopilotToken()
+  recordCopilotTokenSuccess(response)
 
   // Display the Copilot token to the screen
   consola.debug("GitHub Copilot Token fetched successfully!")
   if (state.showToken) {
-    consola.info("Copilot token:", token)
+    consola.info("Copilot token:", response.token)
   }
 
-  const refreshInterval = (refresh_in - 60) * 1000
-  setInterval(async () => {
-    consola.debug("Refreshing Copilot token")
-    try {
-      const { token } = await getCopilotToken()
-      state.copilotToken = token
-      consola.debug("Copilot token refreshed")
-      if (state.showToken) {
-        consola.info("Refreshed Copilot token:", token)
-      }
-    } catch (error) {
-      consola.error("Failed to refresh Copilot token:", error)
-      throw error
-    }
+  const refreshInterval = (response.refresh_in - 60) * 1000
+  setInterval(() => {
+    void refreshCopilotToken()
   }, refreshInterval)
 }
 

src/routes/dashboard/page-body.ts

@@ -7,6 +7,17 @@ export const dashboardBody = String.raw`
         </div>
       </section>
 
+      <section
+        class="panel panel-pad auth-banner"
+        id="auth-banner"
+        hidden
+        role="alert"
+        aria-live="polite"
+      >
+        <div class="auth-banner-title" id="auth-banner-title"></div>
+        <div class="auth-banner-copy" id="auth-banner-copy"></div>
+      </section>
+
       <section class="summary-grid" id="summary-grid"></section>
 
       <section class="upper-grid">

src/routes/dashboard/page-script.ts

@@ -35,6 +35,7 @@ export const dashboardScript = String.raw`
             borderColor: "#ff9f5a",
           },
         ];
+        var TOKEN_HEALTH_REFRESH_MS = 30_000;
         var state = {
           backend: "all",
           bucket: "day",
@@ -47,6 +48,8 @@ export const dashboardScript = String.raw`
           overview: null,
           range: "total",
           refreshTimer: null,
+          tokenHealth: null,
+          tokenHealthTimer: null,
           series: [],
           timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC",
           usage: null,
@@ -110,6 +113,18 @@ export const dashboardScript = String.raw`
           }
         }
 
+        function formatHealthTime(value) {
+          if (!value) {
+            return "unknown time";
+          }
+
+          try {
+            return new Date(value).toLocaleTimeString();
+          } catch {
+            return String(value);
+          }
+        }
+
         function backendLabel(value) {
           switch (value) {
             case "copilot": {
@@ -1180,12 +1195,49 @@ export const dashboardScript = String.raw`
             : "Waiting for first refresh";
         }
 
+        function renderTokenHealthBanner() {
+          var banner = q("auth-banner");
+          var title = q("auth-banner-title");
+          var copy = q("auth-banner-copy");
+          var health = state.tokenHealth;
+
+          if (!banner || !title || !copy) {
+            return;
+          }
+
+          if (!health || health.backend !== "copilot" || !health.alert) {
+            banner.hidden = true;
+            title.textContent = "";
+            copy.textContent = "";
+            return;
+          }
+
+          var parts = [];
+          if (health.expiresAt) {
+            parts.push("Expired at " + formatHealthTime(health.expiresAt));
+          }
+
+          if (health.refreshError) {
+            parts.push(
+              "Refresh failed at " +
+                formatHealthTime(health.refreshError.at) +
+                ": " +
+                health.refreshError.message,
+            );
+          }
+
+          banner.hidden = false;
+          title.textContent = "Copilot token expired";
+          copy.textContent = parts.join(" · ");
+        }
+
         function render() {
           renderControls();
           renderSummary();
           renderChart();
           renderQuotaRegion();
           renderLog();
+          renderTokenHealthBanner();
           renderStatus();
         }
 
@@ -1274,6 +1326,29 @@ export const dashboardScript = String.raw`
             });
         }
 
+        function refreshTokenHealth() {
+          return requestJson("/dashboard/api/token-health")
+            .then(function (result) {
+              state.tokenHealth = result;
+              renderTokenHealthBanner();
+            })
+            .catch(function () {
+              // Keep the last known token health if the dashboard status
+              // endpoint is temporarily unavailable.
+            });
+        }
+
+        function startTokenHealthRefresh() {
+          if (state.tokenHealthTimer) {
+            clearInterval(state.tokenHealthTimer);
+          }
+
+          void refreshTokenHealth();
+          state.tokenHealthTimer = setInterval(function () {
+            void refreshTokenHealth();
+          }, TOKEN_HEALTH_REFRESH_MS);
+        }
+
         function scheduleRefresh() {
           if (state.refreshTimer) {
             clearTimeout(state.refreshTimer);
@@ -1381,10 +1456,14 @@ export const dashboardScript = String.raw`
           if (state.eventSource) {
             state.eventSource.close();
           }
+          if (state.tokenHealthTimer) {
+            clearInterval(state.tokenHealthTimer);
+          }
         });
 
         render();
         connectLive();
+        startTokenHealthRefresh();
         void refreshAll();
       })();
 `

src/routes/dashboard/page-styles.ts

@@ -62,6 +62,33 @@ export const dashboardStyles = String.raw`
         margin-bottom: 20px;
       }
 
+      .auth-banner {
+        display: grid;
+        gap: 8px;
+        margin-bottom: 20px;
+        border-color: rgba(245, 111, 111, 0.42);
+        background:
+          linear-gradient(
+            180deg,
+            rgba(245, 111, 111, 0.18),
+            rgba(255, 255, 255, 0.03)
+          );
+      }
+
+      .auth-banner-title {
+        color: var(--red);
+        font-size: 0.92rem;
+        font-weight: 700;
+        letter-spacing: 0.04em;
+        text-transform: uppercase;
+      }
+
+      .auth-banner-copy {
+        color: var(--text);
+        font-size: 0.95rem;
+        line-height: 1.5;
+      }
+
       .topbar-row {
         display: flex;
         justify-content: space-between;

src/routes/dashboard/route.ts

@@ -2,6 +2,7 @@ import { Hono } from "hono"
 import { createRequire } from "node:module"
 import path from "node:path"
 
+import { getCopilotTokenHealth } from "~/lib/copilot-token-health"
 import {
   getTelemetryModelBreakdown,
   getTelemetryOverview,
@@ -80,4 +81,8 @@ dashboardRoutes.get("/api/events", async (c) => {
   return c.json(await listTelemetryEvents({ backend, limit, model, outcome }))
 })
 
+dashboardRoutes.get("/api/token-health", (c) => {
+  return c.json(getCopilotTokenHealth())
+})
+
 dashboardRoutes.get("/api/events/stream", streamDashboardEvents)

tests/copilot-token-health.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, expect, mock, test } from "bun:test"
+
+import { recordCopilotTokenSuccess } from "../src/lib/copilot-token-health"
+import { state } from "../src/lib/state"
+
+const getCopilotTokenMock = mock()
+
+void mock.module("~/services/github/get-copilot-token", () => ({
+  getCopilotToken: getCopilotTokenMock,
+}))
+
+const { refreshCopilotToken } = await import("../src/lib/token")
+
+afterEach(() => {
+  getCopilotTokenMock.mockReset()
+  state.backend = "copilot"
+  state.copilotToken = undefined
+  state.copilotTokenExpiresAt = undefined
+  state.copilotTokenRefreshError = undefined
+})
+
+test("recordCopilotTokenSuccess stores expiry and clears refresh errors", () => {
+  const expiresAt = Date.now() + 120_000
+  state.copilotTokenRefreshError = {
+    at: Date.now(),
+    message: "old error",
+  }
+
+  recordCopilotTokenSuccess({
+    token: "initial-token",
+    expires_at: expiresAt,
+    refresh_in: 120,
+  })
+
+  expect(state.copilotToken).toBe("initial-token")
+  expect(state.copilotTokenExpiresAt).toBe(expiresAt)
+  expect(state.copilotTokenRefreshError).toBeUndefined()
+})
+
+test("refreshCopilotToken records refresh failures without throwing", async () => {
+  state.copilotToken = "initial-token"
+  state.copilotTokenExpiresAt = Date.now() + 120_000
+  getCopilotTokenMock.mockRejectedValueOnce(new Error("ConnectionRefused"))
+
+  await refreshCopilotToken()
+
+  expect(state.copilotToken).toBe("initial-token")
+  expect(state.copilotTokenRefreshError?.message).toBe("ConnectionRefused")
+  expect(typeof state.copilotTokenRefreshError?.at).toBe("number")
+})