feat(copilot): migrate to new Copilot usage metrics reports API

src/actions/copilot-data.ts

@@ -34,6 +34,50 @@ async function getActiveConnection() {
   });
 }
 
+/**
+ * Days behind today (UTC) before metrics are considered stale.
+ *
+ * GitHub finalizes Copilot usage data within ~3 days; we add a 3-day buffer to
+ * stay quiet during normal latency, surfacing only persistent freshness issues.
+ */
+const FRESHNESS_STALENESS_THRESHOLD_DAYS = 6;
+
+export interface CopilotFreshness {
+  /** Latest metric date in `copilot_usage_metrics`, or null if no rows. */
+  latestDate: string | null;
+  /** Whole UTC days between today and `latestDate`. Null when latestDate null. */
+  daysBehind: number | null;
+  /** True when `daysBehind` exceeds the staleness threshold. */
+  stale: boolean;
+}
+
+export async function getCopilotMetricsFreshness(): Promise<CopilotFreshness> {
+  const connection = await getActiveConnection();
+  if (!connection) {
+    return { latestDate: null, daysBehind: null, stale: false };
+  }
+
+  const [row] = await db
+    .select({ latest: sql<string>`MAX(${copilotUsageMetrics.date})` })
+    .from(copilotUsageMetrics)
+    .where(eq(copilotUsageMetrics.connectionId, connection.id));
+
+  if (!row?.latest) {
+    return { latestDate: null, daysBehind: null, stale: false };
+  }
+
+  const today = new Date();
+  const latest = new Date(row.latest);
+  const msPerDay = 24 * 60 * 60 * 1000;
+  const daysBehind = Math.floor((today.getTime() - latest.getTime()) / msPerDay);
+
+  return {
+    latestDate: row.latest,
+    daysBehind,
+    stale: daysBehind > FRESHNESS_STALENESS_THRESHOLD_DAYS,
+  };
+}
+
 function derivePlanType(tierName: string | null): "business" | "enterprise" {
   return (tierName ?? "").toLowerCase().includes("enterprise")
     ? "enterprise"

src/app/copilot/analytics/page.tsx

@@ -1,13 +1,20 @@
-import { getCopilotAnalytics } from "@/actions/copilot-data";
+import {
+  getCopilotAnalytics,
+  getCopilotMetricsFreshness,
+} from "@/actions/copilot-data";
 import { LanguageChart } from "@/components/copilot/language-chart";
 import { EditorChart } from "@/components/copilot/editor-chart";
 import { ActivityDistribution } from "@/components/copilot/activity-distribution";
+import { MetricsFreshnessCard } from "@/components/copilot/metrics-freshness-card";
 import { Card, CardContent } from "@/components/ui/card";
 import { BarChart3 } from "lucide-react";
 import Link from "next/link";
 
 export default async function CopilotAnalyticsPage() {
-  const result = await getCopilotAnalytics();
+  const [result, freshness] = await Promise.all([
+    getCopilotAnalytics(),
+    getCopilotMetricsFreshness(),
+  ]);
 
   if (!result.success) {
     return (
@@ -20,18 +27,22 @@ export default async function CopilotAnalyticsPage() {
 
   if (!hasData) {
     return (
-      <Card>
-        <CardContent className="py-12 text-center space-y-3">
-          <BarChart3 className="size-12 mx-auto text-muted-foreground" />
-          <h3 className="text-lg font-medium">No analytics data yet</h3>
-          <p className="text-sm text-muted-foreground">Enable Copilot sync in <Link href="/settings/integrations" className="underline text-primary">Settings</Link> to start collecting usage analytics.</p>
-        </CardContent>
-      </Card>
+      <div className="space-y-6">
+        <MetricsFreshnessCard freshness={freshness} />
+        <Card>
+          <CardContent className="py-12 text-center space-y-3">
+            <BarChart3 className="size-12 mx-auto text-muted-foreground" />
+            <h3 className="text-lg font-medium">No analytics data yet</h3>
+            <p className="text-sm text-muted-foreground">Enable Copilot sync in <Link href="/settings/integrations" className="underline text-primary">Settings</Link> to start collecting usage analytics.</p>
+          </CardContent>
+        </Card>
+      </div>
     );
   }
 
   return (
     <div className="space-y-6">
+      <MetricsFreshnessCard freshness={freshness} />
       <div className="grid gap-6 lg:grid-cols-2">
         <LanguageChart data={data.byLanguage} />
         <EditorChart data={data.byEditor} />

src/app/settings/integrations/github-integration-client.tsx

@@ -173,7 +173,9 @@ export function GitHubIntegrationClient({ initialConnection }: Props) {
               aria-describedby="token-help"
             />
             <p id="token-help" className="text-xs text-muted-foreground">
-              Requires <code>read:org</code> and <code>read:user</code> scopes.
+              Requires <code>read:org</code>, <code>read:user</code>, and{" "}
+              <code>manage_billing:copilot</code> scopes (the last for Copilot
+              billing and usage metrics).
             </p>
           </div>
 
@@ -291,7 +293,16 @@ export function GitHubIntegrationClient({ initialConnection }: Props) {
               placeholder="ghp_..."
               value={updateToken}
               onChange={(e) => setUpdateTokenValue(e.target.value)}
+              aria-describedby="update-token-help"
             />
+            <p
+              id="update-token-help"
+              className="text-xs text-muted-foreground"
+            >
+              Requires <code>read:org</code>, <code>read:user</code>, and{" "}
+              <code>manage_billing:copilot</code> scopes (the last for Copilot
+              billing and usage metrics).
+            </p>
             <div className="flex gap-2">
               <Button
                 size="sm"