@xera-ai/core 0.4.3 → 0.5.0

package/src/bin-internal/auth-setup.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadConfig } from '../config/load';
+
+interface AuthSetupOpts {
+  role?: string;
+  shape: 'web' | 'http' | 'all';
+}
+
+function parseOpts(argv: string[]): AuthSetupOpts {
+  const opts: AuthSetupOpts = { shape: 'all' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    if (a === '--role' && next) {
+      opts.role = next;
+      i++;
+    } else if (a === '--shape' && next) {
+      if (next === 'web' || next === 'http' || next === 'all') opts.shape = next;
+      i++;
+    }
+  }
+  return opts;
+}
+
+export async function authSetupCmd(argv: string[]): Promise<number> {
+  const opts = parseOpts(argv);
+  const cwd = process.cwd();
+  const config = await loadConfig(cwd);
+
+  const authSetupScript = join(cwd, 'shared', 'auth-setup.ts');
+  if (!existsSync(authSetupScript)) {
+    console.error(
+      `[xera:auth-setup] auth-setup.ts not found at ${authSetupScript}. Run 'bunx @xera-ai/cli init' first.`,
+    );
+    return 1;
+  }
+
+  const mod = (await import(pathToFileURL(authSetupScript).href)) as {
+    web?: unknown;
+    http?: unknown;
+  };
+
+  let exitCode = 0;
+
+  // Web roles
+  if (
+    (opts.shape === 'all' || opts.shape === 'web') &&
+    config.web &&
+    typeof mod.web === 'function'
+  ) {
+    const { runAuthSetup } = await import('@xera-ai/web');
+    const { chromium } = await import('@playwright/test');
+    const browser = await chromium.launch();
+    try {
+      for (const [roleName, roleCreds] of Object.entries(config.web.auth.roles)) {
+        if (opts.role && roleName !== opts.role) continue;
+        const email = process.env[roleCreds.envEmail];
+        const password = process.env[roleCreds.envPassword];
+        if (!email || !password) {
+          console.error(
+            `[xera:auth-setup] missing env vars ${roleCreds.envEmail} / ${roleCreds.envPassword} for role '${roleName}'`,
+          );
+          exitCode = 1;
+          continue;
+        }
+        try {
+          await runAuthSetup({
+            role: roleName,
+            creds: { email, password },
+            setupScriptPath: authSetupScript,
+            authDir: join(cwd, '.xera', '.auth'),
+            browser,
+          });
+          console.log(`[xera:auth-setup] ✓ ${roleName}.json (web)`);
+        } catch (e) {
+          console.error(`[xera:auth-setup] ✗ web/${roleName}: ${(e as Error).message}`);
+          exitCode = 1;
+        }
+      }
+    } finally {
+      await browser.close();
+    }
+  }
+
+  // Http roles
+  if (
+    (opts.shape === 'all' || opts.shape === 'http') &&
+    config.http &&
+    typeof mod.http === 'function'
+  ) {
+    // The auth-setup.ts template reads config via globalThis; set it for the user's function.
+    (globalThis as Record<string, unknown>).__XERA_HTTP_CONFIG__ = config.http;
+
+    const { runHttpAuthSetup } = await import('@xera-ai/http');
+    for (const roleName of Object.keys(config.http.auth.roles)) {
+      if (opts.role && roleName !== opts.role) continue;
+      try {
+        await runHttpAuthSetup({
+          authDir: join(cwd, '.xera', '.auth'),
+          role: roleName,
+          config: config.http,
+          setupFn: mod.http as Parameters<typeof runHttpAuthSetup>[0]['setupFn'],
+          creds: { email: '', password: '' },
+        });
+        console.log(`[xera:auth-setup] ✓ http/${roleName}.json`);
+      } catch (e) {
+        console.error(`[xera:auth-setup] ✗ http/${roleName}: ${(e as Error).message}`);
+        exitCode = 1;
+      }
+    }
+  }
+
+  return exitCode;
+}

package/src/bin-internal/disputes.ts

@@ -0,0 +1,88 @@
+import { loadAllEvents } from '../graph/store';
+import type { ClassificationDisputedPayload, Event } from '../graph/types';
+
+function parseDuration(s: string): number {
+  // accepts "7d", "30d", "1h", "5m" — returns ms; returns 0 for invalid input
+  const match = s.match(/^(\d+)([dhm])$/);
+  if (!match) return 0;
+  const n = Number.parseInt(match[1]!, 10);
+  const unit = match[2]!;
+  if (unit === 'd') return n * 86400 * 1000;
+  if (unit === 'h') return n * 3600 * 1000;
+  if (unit === 'm') return n * 60 * 1000;
+  return 0;
+}
+
+interface DisputeRow {
+  ts: string;
+  runId: string;
+  scenarioId: string;
+  originalClassification: string;
+  disputedTo: string;
+  qaActor: string;
+  qaReason?: string;
+}
+
+function eventToRow(e: Event & { type: 'classification.disputed' }): DisputeRow {
+  const p = e.payload as ClassificationDisputedPayload;
+  const row: DisputeRow = {
+    ts: e.ts,
+    runId: p.runId,
+    scenarioId: p.scenarioId,
+    originalClassification: p.originalClassification,
+    disputedTo: p.disputedTo,
+    qaActor: p.qaActor,
+  };
+  if (p.qaReason) row.qaReason = p.qaReason;
+  return row;
+}
+
+function renderText(rows: DisputeRow[]): string {
+  if (rows.length === 0) return 'No disputes recorded.\n';
+  const lines: string[] = [];
+  lines.push(`${rows.length} dispute(s):`);
+  for (const r of rows) {
+    lines.push(
+      `  ${r.ts} | ${r.scenarioId} | ${r.originalClassification} → ${r.disputedTo} | ${r.qaActor}`,
+    );
+    if (r.qaReason) lines.push(`    reason: ${r.qaReason}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export async function disputesCmd(argv: string[]): Promise<number> {
+  let since: string | undefined;
+  let format: 'text' | 'json' = 'text';
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--since') {
+      since = argv[++i];
+    } else if (argv[i] === '--format') {
+      const v = argv[++i];
+      if (v === 'json' || v === 'text') format = v;
+    }
+  }
+
+  const repoRoot = process.cwd();
+  const events = loadAllEvents(repoRoot);
+  const disputes = events.filter(
+    (e): e is Event & { type: 'classification.disputed' } => e.type === 'classification.disputed',
+  );
+
+  let cutoffMs: number | undefined;
+  if (since) {
+    const sinceMs = parseDuration(since);
+    if (sinceMs > 0) cutoffMs = Date.now() - sinceMs;
+  }
+
+  const rows = disputes
+    .filter((e) => cutoffMs === undefined || Date.parse(e.ts) >= cutoffMs)
+    .map(eventToRow)
+    .sort((a, b) => (a.ts < b.ts ? 1 : -1));
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify(rows, null, 2));
+  } else {
+    process.stdout.write(renderText(rows));
+  }
+  return 0;
+}

package/src/bin-internal/doctor.ts

@@ -117,8 +117,9 @@ function checkRootScripts(repoRoot: string): CheckResult[] {
   return missing.map((s) => ({ ok: false, message: `root package.json missing script: ${s}` }));
 }
 
-export async function doctorCmd(_argv: string[], opts: DoctorOpts = {}): Promise<number> {
+export async function doctorCmd(argv: string[], opts: DoctorOpts = {}): Promise<number> {
   const repoRoot = opts.cwd ?? process.cwd();
+  const autoEnrich = argv.includes('--auto-enrich');
   const results: CheckResult[] = [
     ...checkGoldenEvalDir(repoRoot),
     ...checkRubricPrompt(repoRoot),
@@ -156,6 +157,17 @@ export async function doctorCmd(_argv: string[], opts: DoctorOpts = {}): Promise
         console.log(`  These won't participate in v0.6.1+ features (TEST_OUTDATED, /xera-impact).`);
         console.log(`  Run: bun run xera:graph-backfill`);
         console.log(`  (Use --dry-run to preview.)`);
+        if (autoEnrich) {
+          console.log('[doctor] --auto-enrich: running backfill for unbackfilled tickets...');
+          // Lazy import to avoid circular deps
+          const { graphBackfillCmd } = await import('./graph-backfill');
+          const exitCode = await graphBackfillCmd([]);
+          if (exitCode === 0) {
+            console.log(`[doctor] auto-enrich: backfilled ${unbackfilled.length} tickets`);
+          } else {
+            console.error('[doctor] auto-enrich: backfill failed');
+          }
+        }
       }
     }
   }

package/src/bin-internal/exec.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { chromium } from '@playwright/test';
 import { runAuthSetup, runPlaywright, stagePlaywrightState } from '@xera-ai/web';
+import { readMeta } from '../artifact/meta';
 import { generateRunId, resolveArtifactPaths } from '../artifact/paths';
 import { needsRefresh } from '../auth/refresh';
 import { readAuthState } from '../auth/state';
@@ -15,6 +16,8 @@ export async function execCmd(argv: string[]): Promise<number> {
     console.error('[xera:exec] usage: exec <TICKET>');
     return 1;
   }
+  const grepIdx = argv.indexOf('--grep');
+  const grep = grepIdx > -1 ? argv[grepIdx + 1] : undefined;
   const cwd = process.cwd();
   const config = await loadConfig(cwd);
   const paths = resolveArtifactPaths(cwd, ticket);
@@ -40,16 +43,48 @@ export async function execCmd(argv: string[]): Promise<number> {
 
   const t0 = Date.now();
   try {
+    const meta = readMeta(paths.metaPath);
+    const adapter = meta?.adapter ?? 'web';
+
+    if (adapter === 'http') {
+      if (!config.http) {
+        throw new Error('http adapter requires http config block');
+      }
+      const env = process.env['XERA_ENV'] ?? config.http.defaultEnv;
+      const { HttpAdapter } = await import('@xera-ai/http');
+      const result = await HttpAdapter.execute({
+        ticketDir: paths.ticketDir,
+        config,
+        runId,
+        env,
+      });
+      log.log({
+        step: 'exec.complete',
+        runId,
+        outcome: result.outcome,
+        elapsedMs: Date.now() - t0,
+      });
+      console.log(`[xera:exec] runId=${runId} outcome=${result.outcome}`);
+      // Exit 3 means "test failed" (expected vs infra error); lock released in finally
+      return result.outcome === 'PASS' ? 0 : 3;
+    }
+
+    // adapter === 'web' — existing path below unchanged
+    if (!config.web) {
+      throw new Error('web adapter requires web config block');
+    }
+    const webConfig = config.web;
+
     // Auth refresh per role declared in xera.config.ts
-    if (config.web.auth.strategy === 'storageState' && config.web.auth.setupScript) {
+    if (webConfig.auth.strategy === 'storageState' && webConfig.auth.setupScript) {
       const browser = await chromium.launch();
       try {
-        for (const [roleName, roleCreds] of Object.entries(config.web.auth.roles)) {
+        for (const [roleName, roleCreds] of Object.entries(webConfig.auth.roles)) {
           const entry = readAuthState(paths.authDir, roleName);
           if (
             needsRefresh(entry, {
-              ttl: config.web.auth.ttl,
-              refreshBuffer: config.web.auth.refreshBuffer,
+              ttl: webConfig.auth.ttl,
+              refreshBuffer: webConfig.auth.refreshBuffer,
             })
           ) {
             const email = process.env[roleCreds.envEmail];
@@ -63,7 +98,7 @@ export async function execCmd(argv: string[]): Promise<number> {
             await runAuthSetup({
               role: roleName,
               creds: { email, password },
-              setupScriptPath: join(cwd, config.web.auth.setupScript),
+              setupScriptPath: join(cwd, webConfig.auth.setupScript),
               authDir: paths.authDir,
               browser,
             });
@@ -78,8 +113,8 @@ export async function execCmd(argv: string[]): Promise<number> {
     // Stage Playwright storageState files at predictable paths
     // (.xera/.auth/.cache/<role>.json) — generated spec.ts references these
     // via test.use({ storageState }) when an authenticated session is needed.
-    if (config.web.auth.strategy === 'storageState') {
-      for (const roleName of Object.keys(config.web.auth.roles)) {
+    if (webConfig.auth.strategy === 'storageState') {
+      for (const roleName of Object.keys(webConfig.auth.roles)) {
         if (readAuthState(paths.authDir, roleName)) {
           stagePlaywrightState(paths.authDir, roleName);
         }
@@ -99,8 +134,8 @@ export async function execCmd(argv: string[]): Promise<number> {
     const runDir = paths.runPath(runId).runDir;
     mkdirSync(runDir, { recursive: true });
 
-    const envName = process.env.XERA_ENV ?? config.web.defaultEnv;
-    const baseURL = config.web.baseUrl[envName] ?? config.web.baseUrl[config.web.defaultEnv]!;
+    const envName = process.env.XERA_ENV ?? webConfig.defaultEnv;
+    const baseURL = webConfig.baseUrl[envName] ?? webConfig.baseUrl[webConfig.defaultEnv]!;
 
     const reportJsonPath = join(runDir, 'report.json');
 
@@ -117,6 +152,7 @@ export async function execCmd(argv: string[]): Promise<number> {
         // path to read.
         PLAYWRIGHT_JSON_OUTPUT_NAME: reportJsonPath,
       },
+      ...(grep && { grep }),
     });
     log.log({ step: 'exec.done', runId, exit: r.exitCode, ms: Date.now() - t0 });
 

package/src/bin-internal/graph-record-script.ts

@@ -30,18 +30,49 @@ const mk = <T extends Event['type']>(
     payload,
   }) as Event;
 
+const P0_KEYWORDS = [
+  'log in',
+  'login',
+  'sign in',
+  'signin',
+  'sign up',
+  'signup',
+  'auth',
+  'authentic',
+  'payment',
+  'pay ',
+  'checkout',
+  'purchase',
+  'charge',
+  'password',
+  'credential',
+  'admin',
+  'permission',
+  'role',
+  'must ',
+  'critical',
+];
+
+function inferPriority(name: string, gherkin: string): 'p0' | 'p1' {
+  const haystack = `${name} ${gherkin}`.toLowerCase();
+  for (const kw of P0_KEYWORDS) {
+    if (haystack.includes(kw)) return 'p0';
+  }
+  return 'p1';
+}
+
 function parseFeature(
   text: string,
 ): Array<{ name: string; priority: 'p0' | 'p1' | 'p2'; gherkin: string }> {
   const scenarios: Array<{ name: string; priority: 'p0' | 'p1' | 'p2'; gherkin: string }> = [];
   const lines = text.split('\n');
-  let currentTagPriority: 'p0' | 'p1' | 'p2' = 'p1';
+  let explicitTag: 'p0' | 'p1' | 'p2' | null = null;
   let i = 0;
   while (i < lines.length) {
     const line = lines[i]!.trim();
     if (line.startsWith('@')) {
       const tag = line.slice(1).split(/\s+/)[0]!.toLowerCase();
-      if (tag === 'p0' || tag === 'p1' || tag === 'p2') currentTagPriority = tag;
+      if (tag === 'p0' || tag === 'p1' || tag === 'p2') explicitTag = tag;
       i++;
       continue;
     }
@@ -55,12 +86,10 @@ function parseFeature(
         !lines[i]!.trim().startsWith('@')
       )
         i++;
-      scenarios.push({
-        name,
-        priority: currentTagPriority,
-        gherkin: lines.slice(start, i).join('\n'),
-      });
-      currentTagPriority = 'p1';
+      const gherkin = lines.slice(start, i).join('\n');
+      const priority = explicitTag !== null ? explicitTag : inferPriority(name, gherkin);
+      scenarios.push({ name, priority, gherkin });
+      explicitTag = null;
       continue;
     }
     i++;

package/src/bin-internal/graph-record.ts

@@ -261,6 +261,9 @@ export async function graphRecordCmd(argv: string[]): Promise<number> {
         'FLAKY',
         'PASS',
         'TEST_OUTDATED',
+        'CONTRACT_DRIFT',
+        'RATE_LIMITED',
+        'AUTH_EXPIRED',
       ];
       if (!validClass.includes(from) || !validClass.includes(to)) {
         console.error(

package/src/bin-internal/index.ts

@@ -1,3 +1,5 @@
+import { authSetupCmd } from './auth-setup';
+import { disputesCmd } from './disputes';
 import { doctorCmd } from './doctor';
 import { evalDeterministicCmd } from './eval-deterministic';
 import { evalPrepareCmd } from './eval-prepare';
@@ -24,6 +26,8 @@ import { validateFeatureCmd } from './validate-feature';
 import { verifyPromptsCmd } from './verify-prompts';
 
 const COMMANDS: Record<string, (argv: string[]) => Promise<number>> = {
+  'auth-setup': authSetupCmd,
+  disputes: disputesCmd,
   doctor: doctorCmd,
   'eval-deterministic': evalDeterministicCmd,
   'eval-prepare': evalPrepareCmd,

package/src/bin-internal/normalize.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { normalizeRun } from '@xera-ai/web';
+import { readMeta } from '../artifact/meta';
 import { resolveArtifactPaths } from '../artifact/paths';
 
 export async function normalizeCmd(argv: string[]): Promise<number> {
@@ -26,6 +26,18 @@ export async function normalizeCmd(argv: string[]): Promise<number> {
     console.error(`[xera:normalize] runs/${runId} missing`);
     return 1;
   }
+
+  const meta = readMeta(paths.metaPath);
+  const adapter = meta?.adapter ?? 'web';
+
+  if (adapter === 'http') {
+    const { normalizeHttpRun } = await import('@xera-ai/http');
+    await normalizeHttpRun({ runId, runDir });
+    console.log(`[xera:normalize] wrote normalized.json (http)`);
+    return 0;
+  }
+
+  const { normalizeRun } = await import('@xera-ai/web');
   const r = await normalizeRun({ runId, runDir });
   console.log(
     `[xera:normalize] wrote normalized.json (scrubbed_fields_count=${r.scrubbed_fields_count})`,

package/src/bin-internal/report.ts

@@ -1,8 +1,14 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { readMeta } from '../artifact/meta';
 import { resolveArtifactPaths } from '../artifact/paths';
+import { readAuthState } from '../auth/state';
 import { aggregateScenarios } from '../classifier/aggregate';
+import { type AuthFileSummary, classifyAuthExpired } from '../classifier/auth-expired';
+import { classifyContractDrift } from '../classifier/contract-drift';
+import { classifyRateLimited } from '../classifier/rate-limited';
 import type { ScenarioClassification } from '../classifier/types';
+import { loadConfig } from '../config/load';
 import type { OutdatedDecision } from '../graph/classify';
 import { enhanceClassification } from '../graph/classify';
 import { deriveSnapshot, loadAllEvents } from '../graph/store';
@@ -22,10 +28,96 @@ export async function reportCmd(argv: string[]): Promise<number> {
     console.error('[xera:report] usage: report <TICKET> --input=<classifier-output.json>');
     return 1;
   }
-  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  const cwd = process.cwd();
+  const paths = resolveArtifactPaths(cwd, ticket);
   const input = JSON.parse(readFileSync(inputArg.slice('--input='.length), 'utf8')) as ReportInput;
 
-  const aggregated = aggregateScenarios(input.scenarios);
+  // v0.7: apply deterministic HTTP classifier rules before aggregation.
+  // When adapter === 'http', scan normalized.json http.calls for rate-limit,
+  // auth-expired, and contract-drift signals and override failing scenario classes.
+  interface HttpRuleOverride {
+    class: ScenarioClassification['class'];
+    rationale: string;
+  }
+  let httpRuleOverride: HttpRuleOverride | null = null;
+
+  const meta = readMeta(paths.metaPath);
+  if (meta?.adapter === 'http') {
+    const config = await loadConfig(cwd);
+    if (config.http) {
+      const normalizedPath = join(paths.ticketDir, 'runs', input.runId, 'normalized.json');
+      if (existsSync(normalizedPath)) {
+        const norm = JSON.parse(readFileSync(normalizedPath, 'utf8')) as {
+          http?: {
+            calls?: Array<{ method: string; url: string; status: number; respBody?: unknown }>;
+          };
+        };
+        const calls = norm.http?.calls ?? [];
+
+        // RATE_LIMITED
+        const rate = classifyRateLimited({ calls });
+        if (rate) httpRuleOverride = rate;
+
+        // AUTH_EXPIRED — needs auth files
+        if (!httpRuleOverride) {
+          const authFiles: Record<string, AuthFileSummary> = {};
+          const httpAuthDir = join(cwd, '.xera', '.auth', 'http');
+          for (const role of Object.keys(config.http.auth.roles)) {
+            const entry = readAuthState(httpAuthDir, role);
+            if (entry) {
+              const p = entry.payload as {
+                token: string;
+                type: 'bearer' | 'apiKey' | 'basic' | 'cookie';
+              };
+              if (typeof p.token === 'string' && typeof p.type === 'string') {
+                authFiles[role] = {
+                  token: p.token,
+                  type: p.type as AuthFileSummary['type'],
+                  expires_at: entry.expires_at,
+                };
+              }
+            }
+          }
+          const authExp = classifyAuthExpired({ calls, authFiles });
+          if (authExp) httpRuleOverride = authExp;
+        }
+
+        // CONTRACT_DRIFT — needs openapi
+        if (!httpRuleOverride && config.http.spec) {
+          const { loadOpenApi } = await import('@xera-ai/http');
+          const openapi = await loadOpenApi(config.http.spec);
+          if (openapi) {
+            const drift = classifyContractDrift({
+              calls: calls.map((c) => ({
+                method: c.method,
+                url: c.url,
+                status: c.status,
+                respBody: c.respBody,
+              })),
+              openapi,
+            });
+            if (drift) httpRuleOverride = drift;
+          }
+        }
+      }
+    }
+  }
+
+  // Apply override: if a deterministic rule fired, stamp every FAIL scenario with it.
+  const scenariosForAggregation: ScenarioClassification[] = httpRuleOverride
+    ? input.scenarios.map((s) =>
+        s.outcome === 'FAIL'
+          ? {
+              ...s,
+              class: httpRuleOverride.class,
+              rationale: httpRuleOverride.rationale,
+              confidence: 'high' as const,
+            }
+          : s,
+      )
+    : input.scenarios;
+
+  const aggregated = aggregateScenarios(scenariosForAggregation);
 
   // v0.6.1: TEST_OUTDATED enhancement.
   // The /xera-report skill writes outdated-decisions.json BEFORE invoking this subcommand,

package/src/bin-internal/verify-prompts.ts

@@ -8,7 +8,8 @@ export interface CheckResult {
 
 const IN_SCOPE_PROMPTS = [
   'feature-from-story.md',
-  'script-from-feature.md',
+  'script-from-feature-web.md',
+  'script-from-feature-http.md',
   'heal-locator.md',
   'extract-areas.md',
   'similarity-match.md',

package/src/classifier/aggregate.ts

@@ -2,6 +2,9 @@ import type { ClassifyOutput, Confidence, ScenarioClassification } from './types
 
 const CLASS_PRIORITY: Array<ClassifyOutput['overall']> = [
   'REAL_BUG',
+  'CONTRACT_DRIFT',
+  'AUTH_EXPIRED',
+  'RATE_LIMITED',
   'TEST_OUTDATED',
   'TEST_BUG',
   'SELECTOR_DRIFT',

package/src/classifier/auth-expired.ts

@@ -0,0 +1,44 @@
+import type { ClassifyResult, HttpCallSummary } from './rate-limited';
+
+export interface AuthFileSummary {
+  token: string;
+  type: 'bearer' | 'apiKey' | 'basic' | 'cookie';
+  expires_at: string;
+}
+
+export interface ClassifyAuthExpiredInput {
+  calls: readonly HttpCallSummary[];
+  authFiles: Record<string, AuthFileSummary>;
+}
+
+function jwtExpPast(jwt: string, now: number): boolean {
+  const parts = jwt.split('.');
+  if (parts.length !== 3) return false;
+  try {
+    const payloadB64 = parts[1];
+    if (!payloadB64) return false;
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8')) as {
+      exp?: number;
+    };
+    return typeof payload.exp === 'number' && payload.exp * 1000 < now;
+  } catch {
+    return false;
+  }
+}
+
+export function classifyAuthExpired(input: ClassifyAuthExpiredInput): ClassifyResult | null {
+  const has401 = input.calls.some((c) => c.status === 401);
+  if (!has401) return null;
+  const now = Date.now();
+  for (const [role, entry] of Object.entries(input.authFiles)) {
+    const fileExpired = new Date(entry.expires_at).getTime() < now;
+    const jwtExpired = entry.type === 'bearer' && jwtExpPast(entry.token, now);
+    if (fileExpired || jwtExpired) {
+      return {
+        class: 'AUTH_EXPIRED',
+        rationale: `HTTP 401 captured; auth file for role '${role}' is past expiry. Run: bun run xera:auth-setup --role ${role}`,
+      };
+    }
+  }
+  return null;
+}