@timo972/cc-router 0.12.1 → 0.12.2-rc.0

package/dist/cli/index.js

@@ -14,6 +14,8 @@ import { registerLogs } from "./cmd-logs.js";
 import { registerModels } from "./cmd-models.js";
 import { registerCliTargets } from "./cmd-cli-targets.js";
 import { getCurrentVersion, checkForUpdate, printUpdateBanner } from "../utils/self-update.js";
+import { recordApplicationStart, shutdownTelemetryWithin } from "../telemetry/facade.js";
+import { isTelemetryTracingActive } from "../telemetry/runtime.js";
 const program = new Command();
 program
     .name("cc-router")
@@ -63,4 +65,16 @@ if (!process.env["NO_UPDATE_NOTIFIER"] && !process.env["CI"]) {
         }
     }).catch(() => { });
 }
-program.parse();
+// Claimed only once a command action runs: Commander exits synchronously for
+// --version/--help before any action, which would otherwise consume the
+// one-time first-start claim without ever draining it.
+program.hook("preAction", () => { recordApplicationStart(); });
+// Short-lived commands get a bounded flush of whatever they queued. Commands
+// that call process.exit() early simply lose their in-flight telemetry. A
+// `start` that is serving requests keeps its runtime: startServer() resolves
+// once it is listening, and its signal handler owns telemetry shutdown.
+void program.parseAsync().finally(() => {
+    if (isTelemetryTracingActive())
+        return undefined;
+    return shutdownTelemetryWithin(500);
+});

package/dist/config/directory.js

@@ -0,0 +1,14 @@
+import { chmodSync, existsSync, mkdirSync } from "fs";
+import { CONFIG_DIR } from "./paths.js";
+const SECRET_DIR_MODE = 0o700;
+export function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: SECRET_DIR_MODE });
+        return;
+    }
+    // Tighten an existing dir that may predate this hardening. No-op on Windows.
+    try {
+        chmodSync(CONFIG_DIR, SECRET_DIR_MODE);
+    }
+    catch { /* best effort */ }
+}

package/dist/config/telemetry.js

@@ -1,64 +1,215 @@
-import { existsSync, readFileSync, writeFileSync, renameSync } from "fs";
 import { randomUUID } from "crypto";
+import { linkSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "fs";
+import { ensureConfigDir } from "./directory.js";
 import { TELEMETRY_PATH } from "./paths.js";
-import { ensureConfigDir } from "./manager.js";
+/** Records written before consent generations existed keep this fixed marker. */
+const LEGACY_GENERATION = "legacy";
+let pendingFirstStartInstallId;
+let firstStartClaimed = false;
+function errorCode(error) {
+    return typeof error === "object" && error !== null && typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
 function defaultState() {
     return {
-        // Opt-in: telemetry stays off until the user explicitly enables it with
-        // `cc-router telemetry on`. Nothing is sent on first run.
-        enabled: false,
+        enabled: true,
         installId: randomUUID(),
         firstRunAt: new Date().toISOString(),
+        consentGeneration: randomUUID(),
     };
 }
-// Read the telemetry state, creating and persisting a fresh one on first run.
-// Malformed files are treated as missing so a corrupted file can't crash the CLI.
-export function loadTelemetryState() {
-    if (!existsSync(TELEMETRY_PATH)) {
-        const state = defaultState();
-        writeTelemetryState(state);
-        return state;
+function parseState(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return undefined;
+    const candidate = raw;
+    if (typeof candidate.installId !== "string" || candidate.installId.length === 0)
+        return undefined;
+    if (typeof candidate.firstRunAt !== "string" || candidate.firstRunAt.length === 0)
+        return undefined;
+    if (candidate.enabled !== undefined && typeof candidate.enabled !== "boolean")
+        return undefined;
+    const hasGeneration = Object.prototype.hasOwnProperty.call(candidate, "consentGeneration");
+    if (hasGeneration && (typeof candidate.consentGeneration !== "string" || !candidate.consentGeneration)) {
+        return undefined;
     }
+    return {
+        enabled: candidate.enabled ?? true,
+        installId: candidate.installId,
+        firstRunAt: candidate.firstRunAt,
+        // A complete pre-generation record is supported and never rewritten on read.
+        consentGeneration: hasGeneration ? candidate.consentGeneration : LEGACY_GENERATION,
+    };
+}
+/** undefined means missing or malformed (both repairable); an unreadable file throws. */
+function readState() {
+    let raw;
     try {
-        const raw = JSON.parse(readFileSync(TELEMETRY_PATH, "utf-8"));
-        // Fill any missing fields to keep the file forward-compatible. Missing
-        // `enabled` defaults to OFF (opt-in).
-        const state = {
-            enabled: raw.enabled ?? false,
-            installId: raw.installId ?? randomUUID(),
-            firstRunAt: raw.firstRunAt ?? new Date().toISOString(),
-        };
-        if (!raw.installId) {
-            writeTelemetryState(state);
-        }
-        return state;
+        raw = readFileSync(TELEMETRY_PATH, "utf8");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return undefined;
+        // Fail closed: a record we cannot read may hold an opt-out, so it is
+        // never replaced with an enabled default. Callers treat this as disabled.
+        throw new Error(`Telemetry state is unreadable: ${TELEMETRY_PATH}`, { cause: error });
+    }
+    try {
+        return parseState(JSON.parse(raw));
     }
     catch {
-        const state = defaultState();
-        writeTelemetryState(state);
-        return state;
+        return undefined;
+    }
+}
+/** Publish atomically: nobody ever reads a partially written state file. */
+function writeState(state) {
+    ensureConfigDir();
+    const candidate = `${TELEMETRY_PATH}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(candidate, JSON.stringify(state, null, 2), { mode: 0o600 });
+    try {
+        renameSync(candidate, TELEMETRY_PATH);
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (process.platform !== "win32" || (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES")) {
+            try {
+                unlinkSync(candidate);
+            }
+            catch { /* the unique candidate is inert */ }
+            throw error;
+        }
+        renameSync(candidate, TELEMETRY_PATH);
     }
 }
-// Atomic write: .tmp + rename, same pattern as writeAccountsAtomic
-export function writeTelemetryState(state) {
+/**
+ * Publish the initial state exclusively. A hard link fails with EEXIST when
+ * another process published first (possibly an explicit opt-out that landed
+ * between our read and our write), and that winner is adopted rather than
+ * replaced. Only an existing file that cannot be parsed is repaired.
+ */
+function createState() {
     ensureConfigDir();
-    const tmp = TELEMETRY_PATH + ".tmp";
-    writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
-    renameSync(tmp, TELEMETRY_PATH);
+    const fresh = defaultState();
+    const candidate = `${TELEMETRY_PATH}.${process.pid}.${randomUUID()}.init.tmp`;
+    writeFileSync(candidate, JSON.stringify(fresh, null, 2), { mode: 0o600 });
+    let published = false;
+    try {
+        linkSync(candidate, TELEMETRY_PATH);
+        published = true;
+    }
+    catch (error) {
+        if (errorCode(error) !== "EEXIST") {
+            try {
+                unlinkSync(candidate);
+            }
+            catch { /* the unique candidate is inert */ }
+            throw error;
+        }
+    }
+    finally {
+        if (published) {
+            try {
+                unlinkSync(candidate);
+            }
+            catch { /* the unique candidate is inert */ }
+        }
+    }
+    if (!published) {
+        try {
+            unlinkSync(candidate);
+        }
+        catch { /* the unique candidate is inert */ }
+        const winner = readState();
+        if (winner)
+            return winner;
+        // Present but unparseable: not a consent record, so replacing it loses nothing.
+        writeState(fresh);
+    }
+    if (!firstStartClaimed)
+        pendingFirstStartInstallId = fresh.installId;
+    return fresh;
+}
+// Missing or malformed state is (re)initialized enabled; a supported legacy
+// record is normalized in memory only; an unreadable file throws (see readState).
+export function getTelemetrySnapshot() {
+    const state = readState() ?? createState();
+    const environmentDisabled = process.env["DO_NOT_TRACK"] === "1" || process.env["CC_ROUTER_TELEMETRY"] === "0";
+    return { state, environmentDisabled, enabled: !environmentDisabled && state.enabled };
 }
-// Returns true only if the user has not opted out through any mechanism:
-//   - DO_NOT_TRACK=1     (de-facto standard)
-//   - CC_ROUTER_TELEMETRY=0  (project-specific override)
-//   - `cc-router telemetry off` (persisted enabled: false)
+/** Persist one explicit choice. The fresh UUID is the consent authority. */
+export function updateTelemetryConsent(enabled) {
+    const current = readState() ?? defaultState();
+    const next = { ...current, enabled, consentGeneration: randomUUID() };
+    writeState(next);
+    return next;
+}
+/** True only if the user has not opted out through any mechanism. */
 export function isTelemetryEnabled() {
-    if (process.env["DO_NOT_TRACK"] === "1")
-        return false;
-    if (process.env["CC_ROUTER_TELEMETRY"] === "0")
-        return false;
     try {
-        return loadTelemetryState().enabled;
+        return getTelemetrySnapshot().enabled;
     }
     catch {
         return false;
     }
 }
+/**
+ * Bind a runtime to the consent generation observed at startup. Any later
+ * generation means an explicit choice occurred, so the runtime permanently
+ * disables itself and must be restarted before telemetry can resume.
+ */
+export function createTelemetryConsentGate(getSnapshot = getTelemetrySnapshot, onLatch) {
+    let first;
+    try {
+        first = getSnapshot();
+    }
+    catch {
+        first = undefined;
+    }
+    const acceptedGeneration = first?.state.consentGeneration;
+    let latched = acceptedGeneration === undefined;
+    let latchReported = false;
+    const latch = () => {
+        latched = true;
+        if (latchReported)
+            return undefined;
+        latchReported = true;
+        try {
+            onLatch?.();
+        }
+        catch { /* consent never depends on cleanup callbacks */ }
+        return undefined;
+    };
+    return {
+        get latched() { return latched; },
+        getSnapshot() {
+            if (latched)
+                return undefined;
+            let snapshot;
+            try {
+                snapshot = getSnapshot();
+            }
+            catch {
+                return latch();
+            }
+            if (snapshot.state.consentGeneration !== acceptedGeneration)
+                return latch();
+            return snapshot.enabled ? snapshot : undefined;
+        },
+    };
+}
+// Claim the one first-start event belonging to fresh state created by this
+// process. Reading an existing state file in a later process never qualifies.
+export function claimTelemetryFirstStart() {
+    const pending = pendingFirstStartInstallId;
+    if (!pending)
+        return undefined;
+    pendingFirstStartInstallId = undefined;
+    firstStartClaimed = true;
+    try {
+        const snapshot = getTelemetrySnapshot();
+        return snapshot.state.installId === pending ? snapshot : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/providers/anthropic/usage-refresher.js

@@ -1,5 +1,6 @@
 import { UsageRefresher } from "../../proxy/usage-refresher.js";
 import { fetchAnthropicUsage } from "./usage.js";
+import { httpOutcome, recordRuntimeError, recordSafeLog, recordUpstreamStatus, withTelemetrySpan, } from "../../telemetry/facade.js";
 /**
  * The Anthropic instantiation of the shared usage scheduler (see
  * proxy/usage-refresher.ts for the timing/identity guarantees): fetches the
@@ -9,8 +10,41 @@ import { fetchAnthropicUsage } from "./usage.js";
 export class AnthropicUsageRefresher extends UsageRefresher {
     constructor(pool, options = {}) {
         const now = options.now ?? Date.now;
+        const fetchUsage = options.fetchUsage ?? fetchAnthropicUsage;
         super(pool, {
-            fetchUsage: options.fetchUsage ?? fetchAnthropicUsage,
+            fetchUsage: account => withTelemetrySpan("provider.usage_refresh", { provider: "anthropic" }, async (span) => {
+                let result;
+                try {
+                    result = await fetchUsage(account);
+                }
+                catch (error) {
+                    recordRuntimeError(error, { operation: "provider.usage_refresh", provider: "anthropic" });
+                    throw error;
+                }
+                if (!result.ok) {
+                    if (result.status !== undefined) {
+                        recordUpstreamStatus("provider.usage_refresh", "anthropic", result.status);
+                        span.fail({ httpStatusCode: result.status, outcome: httpOutcome(result.status) });
+                    }
+                    else {
+                        // fetchAnthropicUsage resolves transport failures instead of
+                        // throwing, so the unsampled failure log is emitted here.
+                        const reason = result.reason === "timeout" ? "timeout"
+                            : result.reason === "network" ? "network_failure"
+                                : "other";
+                        const outcome = reason === "timeout" ? "timeout" : "upstream_error";
+                        recordSafeLog({
+                            operation: "provider.usage_refresh",
+                            provider: "anthropic",
+                            severity: "error",
+                            reason,
+                            outcome,
+                        });
+                        span.fail({ outcome });
+                    }
+                }
+                return result;
+            }),
             cancelledResult: () => ({ ok: false, reason: "network" }),
             applyResult: (account, result) => {
                 if (result.ok) {

package/dist/providers/model-discovery.js

@@ -1,3 +1,4 @@
+import { classifyExpectedRuntimeFailure, httpOutcome, withTelemetrySpan } from "../telemetry/facade.js";
 export const ANTHROPIC_MODELS_ENDPOINT = "https://api.anthropic.com/v1/models";
 export const OPENAI_CODEX_MODELS_ENDPOINT = "https://chatgpt.com/backend-api/codex/models?client_version=1.0.0";
 export const MODEL_DISCOVERY_TIMEOUT_MS = 3_000;
@@ -12,7 +13,7 @@ export function normalizeModelIds(payload) {
     return [...ids];
 }
 export async function fetchAnthropicModels(account, fetchImpl = fetch) {
-    return fetchModels(ANTHROPIC_MODELS_ENDPOINT, {
+    return fetchModels("anthropic", ANTHROPIC_MODELS_ENDPOINT, {
         method: "GET",
         headers: {
             authorization: `Bearer ${account.tokens.accessToken}`,
@@ -23,7 +24,7 @@ export async function fetchAnthropicModels(account, fetchImpl = fetch) {
     }, fetchImpl);
 }
 export async function fetchOpenAICodexModels(account, fetchImpl = fetch) {
-    return fetchModels(OPENAI_CODEX_MODELS_ENDPOINT, {
+    return fetchModels("openai", OPENAI_CODEX_MODELS_ENDPOINT, {
         method: "GET",
         headers: {
             authorization: `Bearer ${account.accessToken}`,
@@ -32,16 +33,21 @@ export async function fetchOpenAICodexModels(account, fetchImpl = fetch) {
         signal: AbortSignal.timeout(MODEL_DISCOVERY_TIMEOUT_MS),
     }, fetchImpl);
 }
-async function fetchModels(url, init, fetchImpl) {
-    try {
-        const res = await fetchImpl(url, init);
-        if (!res.ok)
+function fetchModels(provider, url, init, fetchImpl) {
+    return withTelemetrySpan("model.discovery", { provider }, async (span) => {
+        try {
+            const res = await fetchImpl(url, init);
+            if (!res.ok) {
+                span.fail({ httpStatusCode: res.status, outcome: httpOutcome(res.status) });
+                return [];
+            }
+            return normalizeModelIds(await res.json());
+        }
+        catch (error) {
+            span.fail({ outcome: classifyExpectedRuntimeFailure(error) === "timeout" ? "timeout" : "upstream_error" });
             return [];
-        return normalizeModelIds(await res.json());
-    }
-    catch {
-        return [];
-    }
+        }
+    });
 }
 function getModelValues(payload) {
     if (Array.isArray(payload))

package/dist/providers/openai/device-oauth.js

@@ -1,4 +1,5 @@
 import { createOpenAIAccountRecord } from "./account-record.js";
+import { SetupDiagnosticError, classifyHttpSetupFailure, classifyNetworkSetupFailure, } from "../../telemetry/setup-diagnostics.js";
 const DEFAULT_ISSUER = "https://auth.openai.com";
 export const DEFAULT_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
 const DEFAULT_SCOPE = "openid profile email offline_access";
@@ -12,13 +13,37 @@ function clientIdOf(opts) {
 function fetchOf(opts) {
     return opts.fetchImpl ?? fetch;
 }
+/** A malformed body is attributed to the stage that received it; the message is unchanged. */
+async function parseJsonAt(stage, res) {
+    try {
+        return await res.json();
+    }
+    catch (error) {
+        throw new SetupDiagnosticError(error instanceof Error ? error.message : String(error), { stage, reason: "unexpected_response_shape", expected: true, httpStatusCode: res.status }, { cause: error });
+    }
+}
 function parseAccessTokenExpiry(accessToken) {
     const [, payload] = accessToken.split(".");
-    if (!payload)
-        throw new Error("OpenAI access token is not a JWT");
-    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
+    if (!payload) {
+        throw new SetupDiagnosticError("OpenAI access token is not a JWT", {
+            stage: "access_token_parse",
+            reason: "unexpected_response_shape",
+            expected: false,
+        });
+    }
+    let claims;
+    try {
+        claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf-8"));
+    }
+    catch (error) {
+        throw new SetupDiagnosticError(error instanceof Error ? error.message : String(error), { stage: "access_token_parse", reason: "unexpected_response_shape", expected: true }, { cause: error });
+    }
     if (typeof claims.exp !== "number" || !Number.isFinite(claims.exp)) {
-        throw new Error("OpenAI access token JWT does not contain a numeric exp claim");
+        throw new SetupDiagnosticError("OpenAI access token JWT does not contain a numeric exp claim", {
+            stage: "access_token_parse",
+            reason: "unexpected_response_shape",
+            expected: true,
+        });
     }
     return claims.exp * 1000;
 }
@@ -32,18 +57,29 @@ async function readError(res) {
 }
 export async function requestOpenAIDeviceCode(opts = {}) {
     const issuer = issuerOf(opts);
-    const res = await fetchOf(opts)(`${issuer}/api/accounts/deviceauth/usercode`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ client_id: clientIdOf(opts) }),
-    });
+    let res;
+    try {
+        res = await fetchOf(opts)(`${issuer}/api/accounts/deviceauth/usercode`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ client_id: clientIdOf(opts) }),
+        });
+    }
+    catch (error) {
+        throw classifyNetworkSetupFailure("device_code_request", error);
+    }
     if (!res.ok) {
-        throw new Error(`OpenAI device code request failed (${res.status}): ${await readError(res)}`);
+        throw classifyHttpSetupFailure("device_code_request", res.status, `OpenAI device code request failed (${res.status}): ${await readError(res)}`);
     }
-    const body = await res.json();
+    const body = await parseJsonAt("device_code_request", res);
     const userCode = body.user_code ?? body.usercode;
     if (!body.device_auth_id || !userCode) {
-        throw new Error("OpenAI device code response is missing device_auth_id or user_code");
+        throw new SetupDiagnosticError("OpenAI device code response is missing device_auth_id or user_code", {
+            stage: "device_code_request",
+            reason: "unexpected_response_shape",
+            expected: true,
+            httpStatusCode: res.status,
+        });
     }
     return {
         verificationUrl: `${issuer}/codex/device`,
@@ -59,26 +95,37 @@ async function pollAuthorizationCode(opts) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const started = now();
     while (now() - started <= timeoutMs) {
-        const res = await fetchOf(opts)(`${issuer}/api/accounts/deviceauth/token`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                device_auth_id: opts.deviceCode.deviceAuthId,
-                user_code: opts.deviceCode.userCode,
-            }),
-        });
+        let res;
+        try {
+            res = await fetchOf(opts)(`${issuer}/api/accounts/deviceauth/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    device_auth_id: opts.deviceCode.deviceAuthId,
+                    user_code: opts.deviceCode.userCode,
+                }),
+            });
+        }
+        catch (error) {
+            throw classifyNetworkSetupFailure("authorization_polling", error);
+        }
         if (res.ok)
-            return await res.json();
+            return await parseJsonAt("authorization_polling", res);
         if (res.status !== 403 && res.status !== 404) {
-            throw new Error(`OpenAI device authorization failed (${res.status}): ${await readError(res)}`);
+            throw classifyHttpSetupFailure("authorization_polling", res.status, `OpenAI device authorization failed (${res.status}): ${await readError(res)}`);
         }
         await sleep(Math.max(1, opts.deviceCode.intervalSeconds) * 1000);
     }
-    throw new Error("OpenAI device authorization timed out");
+    throw new SetupDiagnosticError("OpenAI device authorization timed out", {
+        stage: "authorization_polling",
+        reason: "timeout",
+        expected: true,
+    });
 }
 export async function exchangeOpenAIDeviceCodeForTokens(opts) {
     const issuer = issuerOf(opts);
     const code = await pollAuthorizationCode(opts);
+    opts.onStageCompleted?.("authorization_polling");
     const form = new URLSearchParams({
         grant_type: "authorization_code",
         code: code.authorization_code,
@@ -86,24 +133,34 @@ export async function exchangeOpenAIDeviceCodeForTokens(opts) {
         client_id: clientIdOf(opts),
         code_verifier: code.code_verifier,
     });
-    const res = await fetchOf(opts)(`${issuer}/oauth/token`, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: form.toString(),
-    });
+    let res;
+    try {
+        res = await fetchOf(opts)(`${issuer}/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: form.toString(),
+        });
+    }
+    catch (error) {
+        throw classifyNetworkSetupFailure("token_exchange", error);
+    }
     if (!res.ok) {
-        throw new Error(`OpenAI token exchange failed (${res.status}): ${await readError(res)}`);
+        throw classifyHttpSetupFailure("token_exchange", res.status, `OpenAI token exchange failed (${res.status}): ${await readError(res)}`);
     }
-    const tokens = await res.json();
+    const tokens = await parseJsonAt("token_exchange", res);
+    opts.onStageCompleted?.("token_exchange");
+    const expiresAt = parseAccessTokenExpiry(tokens.access_token);
+    opts.onStageCompleted?.("access_token_parse");
     return {
         idToken: tokens.id_token,
         accessToken: tokens.access_token,
         refreshToken: tokens.refresh_token,
-        expiresAt: parseAccessTokenExpiry(tokens.access_token),
+        expiresAt,
     };
 }
 export async function loginOpenAIWithDeviceCode(opts) {
     const deviceCode = await requestOpenAIDeviceCode(opts);
+    opts.onStageCompleted?.("device_code_request");
     opts.onDeviceCode?.(deviceCode);
     const tokens = await exchangeOpenAIDeviceCodeForTokens({ ...opts, deviceCode });
     return createOpenAIAccountRecord({

package/dist/providers/openai/token-refresher.js

@@ -3,6 +3,7 @@ import { createHeaderDeadline } from "../../proxy/transport-timing.js";
 import { logError } from "../../proxy/logger.js";
 import { createCorrelationId, formatTransportDiagnostic, safeCauseCode, } from "../../proxy/transport-diagnostics.js";
 import { DEFAULT_CLIENT_ID } from "./device-oauth.js";
+import { classifyExpectedRuntimeFailure, httpOutcome, recordRuntimeError, recordUpstreamStatus, withTelemetrySpan, } from "../../telemetry/facade.js";
 const TOKEN_ENDPOINT = "https://auth.openai.com/oauth/token";
 const REFRESH_BUFFER_MS = 10 * 60 * 1000;
 const CHECK_INTERVAL_MS = 5 * 60 * 1000;
@@ -71,7 +72,12 @@ export async function refreshOpenAISubscriptionToken(account) {
     const existing = refreshLocks.get(account);
     if (existing)
         return existing;
-    const promise = doRefresh(account);
+    const promise = withTelemetrySpan("oauth.refresh", { provider: "openai" }, async (span) => {
+        const refreshed = await doRefresh(account, span);
+        if (!refreshed)
+            span.fail();
+        return refreshed;
+    });
     refreshLocks.set(account, promise);
     try {
         return await promise;
@@ -180,7 +186,7 @@ function logRefreshFailure(account, correlationId, status, error) {
         causeCode: safeCauseCode(error),
     }));
 }
-async function doRefresh(account) {
+async function doRefresh(account, span) {
     const body = new URLSearchParams({
         grant_type: "refresh_token",
         refresh_token: account.refreshToken,
@@ -208,6 +214,8 @@ async function doRefresh(account) {
             }
             catch { /* intentionally do not retain response bodies */ }
             markRefreshFailure(account, rejectIsPermanent(res.status, payload));
+            recordUpstreamStatus("oauth.refresh", "openai", res.status);
+            span.fail({ httpStatusCode: res.status, outcome: httpOutcome(res.status) });
             logRefreshFailure(account, correlationId, res.status);
             return false;
         }
@@ -217,6 +225,8 @@ async function doRefresh(account) {
         // Network failure (or malformed response body) must resolve to `false`,
         // exactly like a non-ok HTTP response — never propagate as a rejection.
         markRefreshFailure(account, false);
+        recordRuntimeError(error, { operation: "oauth.refresh", provider: "openai" });
+        span.fail({ outcome: classifyExpectedRuntimeFailure(error) === "timeout" ? "timeout" : "upstream_error" });
         logRefreshFailure(account, correlationId, responseStatus, error);
         return false;
     }