@karpeleslab/teamclaude 1.0.7 → 1.0.9

package/src/mitm.js

@@ -0,0 +1,387 @@
+// MITM forward-proxy support: local cert lifecycle + transparent CONNECT relay.
+//
+// When a claude instance is launched with HTTPS_PROXY pointed at teamclaude it
+// sends `CONNECT api.anthropic.com:443`. We act as a transparent MITM: dial the
+// real upstream first (mirroring SNI + adopting its negotiated ALPN), present
+// claude our locally-minted leaf advertising that same protocol, then relay the
+// decrypted stream — rewriting ONLY the auth header (h2 via our HPACK codec, h1
+// via a plaintext head edit) and reading quota from responses. Everything else
+// is copied as-is. A host routing table decides per-CONNECT behavior:
+//   api.anthropic.com → rewrite,  www.example.org → local test server,
+//   anything else      → blind tunnel.
+
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { X509Certificate } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import net from 'node:net';
+import tls from 'node:tls';
+import { getConfigPath } from './config.js';
+import { generateCertChain } from './x509.js';
+import { h2Relay, h1Relay, rewriteH1Auth } from './h2/relay.js';
+import { AccountUuidPatcher } from './account-uuid-rewrite.js';
+import { makeMitmTap, makeActivityTap, combineTaps } from './request-log.js';
+import { tunnelTls } from './sx.js';
+
+const CA_CERT = 'teamclaude-ca.pem';
+const LEAF_CERT = 'teamclaude-leaf.pem';
+const LEAF_KEY = 'teamclaude-leaf.key';
+
+// A built-in host the MITM proxy always intercepts and answers itself (never
+// forwarded upstream). Lets you verify the proxy + CA end-to-end with no
+// credentials, e.g.:
+//   curl --proxy http://localhost:3456 --cacert <ca.pem> https://www.example.org/
+export const TEST_HOST = 'www.example.org';
+
+const certDir = () => dirname(getConfigPath());
+const fpath = (n) => join(certDir(), n);
+
+/** Path to the CA cert clients should trust via NODE_EXTRA_CA_CERTS. */
+export function caCertPath() {
+  return fpath(CA_CERT);
+}
+
+async function readIf(p) {
+  try { return await readFile(p, 'utf8'); } catch { return null; }
+}
+
+async function atomicWrite(path, data, mode) {
+  const tmp = `${path}.tmp${process.pid}`;
+  await writeFile(tmp, data, { mode });
+  await rename(tmp, path);
+}
+
+// Is the stored leaf signed by the stored CA and valid for every host in `hosts`?
+function leafCovers(caCertPem, leafCertPem, hosts) {
+  try {
+    const ca = new X509Certificate(caCertPem);
+    const leaf = new X509Certificate(leafCertPem);
+    if (!leaf.verify(ca.publicKey)) return false;
+    const names = (leaf.subjectAltName || '').split(',').map((s) => s.trim());
+    return hosts.every((h) => names.includes(`DNS:${h}`));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Ensure a CA cert + a leaf for `host` exist in the config dir, generating them
+ * if missing/mismatched. The CA *private* key is never persisted — we regenerate
+ * the whole chain when needed, so the only on-disk secret is the leaf key (0600),
+ * which only authenticates as `host` to a process that already trusts our CA.
+ * Returns { caPath, caCertPem, leafCertPem, leafKeyPem }.
+ */
+export async function ensureCerts(host) {
+  const hosts = host === TEST_HOST ? [TEST_HOST] : [host, TEST_HOST];
+  const [caCertPem, leafCertPem, leafKeyPem] = await Promise.all([
+    readIf(fpath(CA_CERT)), readIf(fpath(LEAF_CERT)), readIf(fpath(LEAF_KEY)),
+  ]);
+
+  if (caCertPem && leafCertPem && leafKeyPem && leafCovers(caCertPem, leafCertPem, hosts)) {
+    return { caPath: fpath(CA_CERT), caCertPem, leafCertPem, leafKeyPem };
+  }
+
+  const chain = generateCertChain(hosts); // caKeyPem intentionally discarded
+  await mkdir(certDir(), { recursive: true });
+  await atomicWrite(fpath(CA_CERT), chain.caCertPem, 0o644);
+  await atomicWrite(fpath(LEAF_CERT), chain.leafCertPem, 0o644);
+  await atomicWrite(fpath(LEAF_KEY), chain.leafKeyPem, 0o600);
+  return {
+    caPath: fpath(CA_CERT),
+    caCertPem: chain.caCertPem,
+    leafCertPem: chain.leafCertPem,
+    leafKeyPem: chain.leafKeyPem,
+  };
+}
+
+function upstreamHostOf(config) {
+  try { return new URL(config?.upstream || 'https://api.anthropic.com').hostname; }
+  catch { return 'api.anthropic.com'; }
+}
+
+/** Per-CONNECT behavior: 'rewrite' (intercept + token inject), 'test', or 'tunnel'. */
+export function hostMode(host, config) {
+  if (host === TEST_HOST) return 'test';
+  if (host === upstreamHostOf(config)) return 'rewrite';
+  return 'tunnel';
+}
+
+/**
+ * Build a `connect` event handler implementing the transparent MITM described
+ * at the top of this file.
+ * @param ensureLeaf async () => { key, cert }   // current leaf PEMs
+ */
+export function createConnectHandler({ config, accountManager, ensureLeaf, upstreamTlsOptions = {}, logDir = null, hooks = {}, log = () => {}, sx = null }) {
+  return (req, clientSocket, head) => {
+    clientSocket.on('error', () => {});
+    const [host, portStr] = (req.url || '').split(':');
+    const port = parseInt(portStr, 10) || 443;
+    const mode = hostMode(host, config);
+
+    if (mode === 'tunnel') {
+      const up = net.connect(port, host, () => {
+        reply200Raw(clientSocket);
+        if (head && head.length) up.write(head);
+        up.pipe(clientSocket); clientSocket.pipe(up);
+      });
+      up.on('error', () => clientSocket.destroy());
+      return;
+    }
+
+    intercept({ host, port, mode, clientSocket, head, accountManager, ensureLeaf, upstreamTlsOptions, logDir, hooks, log, sx })
+      .catch((err) => { log(`[TeamClaude] MITM ${host}: ${err.message}`); clientSocket.destroy(); });
+  };
+}
+
+async function intercept({ host, port, mode, clientSocket, head, accountManager, ensureLeaf, upstreamTlsOptions, logDir, hooks = {}, log, sx }) {
+  const { key, cert } = await ensureLeaf();
+
+  if (mode === 'test') {
+    reply200Raw(clientSocket);
+    const tlsSock = termClaude(clientSocket, head, key, cert, ['http/1.1']);
+    serveTest(tlsSock);
+    return;
+  }
+
+  // rewrite: be a faithful ALPN mirror. We don't terminate TLS at the byte
+  // level (that's node:tls), so to avoid imposing our own protocol preference we
+  // peek the client's ClientHello, read the exact ALPN list it offers, present
+  // THAT list to the upstream, let the upstream pick, then terminate the client
+  // with whatever the upstream selected. The upstream decides — constrained to
+  // what the client can speak — so an http/1.1-only client (undici/claude) and
+  // an h2 client both negotiate end-to-end exactly as they would directly.
+  const account = accountManager.getActiveAccount();
+  if (!account) { clientSocket.destroy(); return; }
+  await accountManager.ensureTokenFresh(account.index);
+
+  reply200Raw(clientSocket);
+  const offered = await peekClientAlpn(clientSocket, head); // client's ALPN list, or null
+
+  // When sx.org is enabled, dial the upstream THROUGH its proxy (different egress
+  // IP — the IP-based-429 workaround); TLS still terminates end-to-end at the
+  // upstream, so the proxy sees only ciphertext. Otherwise connect directly.
+  // autoSelectFamily (happy-eyeballs) is the default on Node 20+ but not 18; set
+  // it explicitly so a dual-stack upstream whose IPv6 path is unreachable falls
+  // back to IPv4 instead of hanging the connect (option ignored pre-18.13).
+  let upstreamSock;
+  if (sx?.useForConnect()) {
+    upstreamSock = await tunnelTls({
+      proxy: sx.getProxy(), targetHost: host, targetPort: port,
+      tlsOptions: { ...(offered ? { ALPNProtocols: offered } : {}), ...upstreamTlsOptions },
+    });
+  } else {
+    upstreamSock = tls.connect({
+      host, port, servername: host, autoSelectFamily: true,
+      ...(offered ? { ALPNProtocols: offered } : {}),
+      ...upstreamTlsOptions,
+    });
+    await new Promise((resolve, reject) => {
+      upstreamSock.once('secureConnect', resolve);
+      upstreamSock.once('error', reject);
+    });
+  }
+  const upstreamAlpn = upstreamSock.alpnProtocol; // false if none negotiated
+  const alpn = upstreamAlpn || 'http/1.1';        // relay protocol selector
+
+  // Terminate the client advertising exactly what the upstream chose (a subset
+  // of what the client offered, so it always overlaps).
+  const claudeTls = new tls.TLSSocket(clientSocket, {
+    isServer: true, key, cert,
+    ...(upstreamAlpn ? { ALPNProtocols: [upstreamAlpn] } : {}),
+  });
+  claudeTls.on('error', () => { claudeTls.destroy(); upstreamSock.destroy(); });
+  upstreamSock.on('error', () => claudeTls.destroy());
+  await new Promise((resolve, reject) => {
+    claudeTls.once('secure', resolve);
+    claudeTls.once('error', reject);
+  });
+
+  // Per-stream streaming body patcher: align metadata.user_id.account_uuid with
+  // the injected account (same length; no-op if the account has no UUID).
+  const makeBodyPatcher = account.accountUuid
+    ? () => new AccountUuidPatcher(account.accountUuid)
+    : null;
+  // Fan request lifecycle out to the on-disk log (when configured) AND the live
+  // TUI activity feed, so MITM traffic is visible in the TUI like reverse-proxy
+  // traffic — not just on disk.
+  const tap = combineTaps(makeMitmTap(logDir, account.name), makeActivityTap(hooks, account.name));
+
+  if (alpn === 'h2') {
+    h2Relay(claudeTls, upstreamSock, {
+      rewriteRequest: makeRewriteRequest(account),
+      makeBodyPatcher,
+      onResponseHeaders: makeQuotaObserver(accountManager, account, sx),
+      tap,
+      log,
+    });
+  } else {
+    const auth = account.type === 'oauth'
+      ? { authorization: `Bearer ${account.credential}` }
+      : { apiKey: account.credential };
+    h1Relay(claudeTls, upstreamSock, {
+      rewriteHead: (h) => rewriteH1Auth(h, auth),
+      makeBodyPatcher,
+      onResponseHeaders: makeQuotaObserver(accountManager, account, sx),
+      tap,
+    });
+  }
+}
+
+function reply200Raw(sock) { sock.write('HTTP/1.1 200 Connection Established\r\n\r\n'); }
+
+function termClaude(clientSocket, head, key, cert, alpn) {
+  if (head && head.length) clientSocket.unshift(head);
+  const t = new tls.TLSSocket(clientSocket, { isServer: true, key, cert, ALPNProtocols: alpn });
+  t.on('error', () => t.destroy());
+  return t;
+}
+
+// Read the client's first TLS record (the ClientHello) to learn the ALPN
+// protocol list it offers, WITHOUT consuming it: bytes are unshifted back so the
+// real TLS handshake still sees the full ClientHello. Returns the protocol
+// string array, or null if there is no ALPN extension / it can't be parsed (in
+// which case we offer the upstream no ALPN and mirror its no-ALPN result).
+function peekClientAlpn(sock, head) {
+  return new Promise((resolve) => {
+    let buf = head && head.length ? Buffer.from(head) : Buffer.alloc(0);
+    let done = false;
+    const finish = (result) => {
+      if (done) return; done = true;
+      sock.removeListener('readable', onReadable);
+      sock.removeListener('end', onEnd);
+      sock.removeListener('error', onEnd);
+      if (buf.length) sock.unshift(buf); // put the ClientHello back for node:tls
+      resolve(result);
+    };
+    const tryParse = () => {
+      const r = parseClientHelloAlpn(buf);
+      if (r === undefined && buf.length < 16384) return false; // need more bytes
+      finish(Array.isArray(r) ? r : null);
+      return true;
+    };
+    // Read in PAUSED mode (readable/read) — never switch the socket to flowing,
+    // or the TLSSocket we hand it to afterwards won't receive the unshifted bytes.
+    const onReadable = () => {
+      let chunk;
+      while ((chunk = sock.read()) !== null) {
+        buf = Buffer.concat([buf, chunk]);
+        if (tryParse()) return;
+      }
+    };
+    const onEnd = () => finish(null);
+    sock.on('readable', onReadable);
+    sock.once('end', onEnd);
+    sock.once('error', onEnd);
+    if (tryParse()) return; // head may already contain the whole ClientHello
+    onReadable();           // drain anything already buffered
+  });
+}
+
+// Parse the ALPN protocol list out of a TLS ClientHello.
+//   returns string[]  — ALPN extension present
+//   returns null       — parsed far enough to know there is no usable ALPN
+//   returns undefined  — need more bytes to decide
+export function parseClientHelloAlpn(buf) {
+  if (buf.length < 5) return undefined;
+  if (buf[0] !== 0x16) return null;                 // not a handshake record
+  const recEnd = 5 + buf.readUInt16BE(3);
+  if (buf.length < recEnd) return undefined;        // wait for the full record
+  let p = 5;
+  if (buf[p] !== 0x01) return null;                 // not a ClientHello
+  const hsEnd = p + 4 + ((buf[p + 1] << 16) | (buf[p + 2] << 8) | buf[p + 3]);
+  const end = Math.min(hsEnd, recEnd);
+  p += 4;
+  p += 2 + 32;                                      // client_version + random
+  if (p >= end) return null;
+  p += 1 + buf[p];                                  // session_id
+  if (p + 2 > end) return null;
+  p += 2 + buf.readUInt16BE(p);                     // cipher_suites
+  if (p + 1 > end) return null;
+  p += 1 + buf[p];                                  // compression_methods
+  if (p + 2 > end) return null;
+  let extEnd = p + 2 + buf.readUInt16BE(p);
+  p += 2;
+  extEnd = Math.min(extEnd, end);
+  while (p + 4 <= extEnd) {
+    const type = buf.readUInt16BE(p);
+    const len = buf.readUInt16BE(p + 2);
+    p += 4;
+    if (type === 0x0010) {                          // application_layer_protocol_negotiation
+      let q = p + 2;                                // skip ALPN list length
+      const listEnd = Math.min(p + len, extEnd);
+      const protos = [];
+      while (q < listEnd) {
+        const l = buf[q]; q += 1;
+        if (q + l > listEnd) break;
+        protos.push(buf.toString('latin1', q, q + l));
+        q += l;
+      }
+      return protos.length ? protos : null;
+    }
+    p += len;
+  }
+  return null;                                      // no ALPN extension
+}
+
+// Rewrite only the auth field on an h2 request header list (account token in,
+// client's x-api-key out). Preserves order; marks auth never-indexed.
+function makeRewriteRequest(account) {
+  const isOAuth = account.type === 'oauth';
+  return (fields) => {
+    let replaced = false;
+    const out = [];
+    for (const f of fields) {
+      const n = f.name.toString().toLowerCase();
+      if (n === 'x-api-key') continue;
+      if (n === 'authorization') {
+        if (isOAuth) { out.push({ name: f.name, value: Buffer.from(`Bearer ${account.credential}`), sensitive: true }); replaced = true; }
+        continue;
+      }
+      out.push(f);
+    }
+    if (!replaced) {
+      out.push(isOAuth
+        ? { name: Buffer.from('authorization'), value: Buffer.from(`Bearer ${account.credential}`), sensitive: true }
+        : { name: Buffer.from('x-api-key'), value: Buffer.from(account.credential), sensitive: true });
+    }
+    return out;
+  };
+}
+
+function makeQuotaObserver(accountManager, account, sx = null) {
+  return (fields) => {
+    const m = {};
+    for (const f of fields) m[f.name.toString().toLowerCase()] = f.value.toString();
+    if (!m[':status']) return;
+    const rl = {};
+    for (const k in m) if (k.startsWith('anthropic-ratelimit-')) rl[k] = m[k];
+    if (Object.keys(rl).length) accountManager.updateQuota(account.index, rl);
+    if (m[':status'] === '429') {
+      let ra = parseInt(m['retry-after'], 10);
+      if (Number.isNaN(ra)) ra = 60;
+      ra = Math.min(Math.max(ra, 1), 300);
+      accountManager.markRateLimited(account.index, ra);
+      // Arm sx.org sticky routing so the next MITM tunnel uses the proxy (in
+      // '429' mode); no-op in 'off'/'always'.
+      sx?.noteRateLimited(ra);
+    }
+  };
+}
+
+// Answer the built-in test host locally over h1 with a canned JSON response.
+function serveTest(tlsSock) {
+  let buf = Buffer.alloc(0);
+  const onData = (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    const idx = buf.indexOf('\r\n\r\n');
+    if (idx < 0) { if (buf.length > 65536) tlsSock.destroy(); return; }
+    tlsSock.removeListener('data', onData);
+    const reqLine = buf.subarray(0, buf.indexOf('\r\n')).toString('latin1');
+    const path = reqLine.split(' ')[1] || '/';
+    const body = JSON.stringify({ teamclaude: 'mitm-proxy-ok', host: TEST_HOST, path });
+    tlsSock.end(
+      `HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: ${Buffer.byteLength(body)}\r\nconnection: close\r\n\r\n${body}`,
+    );
+  };
+  tlsSock.on('data', onData);
+  tlsSock.on('error', () => tlsSock.destroy());
+}

package/src/oauth.js

@@ -24,6 +24,8 @@ export async function importCredentials(filePath) {
 }
 
 const PROFILE_URL = 'https://api.anthropic.com/api/oauth/profile';
+const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
+const OAUTH_USAGE_BETA = 'oauth-2025-04-20';
 const DEFAULT_TOKEN_ENDPOINT = 'https://platform.claude.com/v1/oauth/token';
 const DEFAULT_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
 
@@ -62,7 +64,13 @@ export async function refreshAccessToken(refreshToken, endpoint = DEFAULT_TOKEN_
           continue;
         }
         const text = await res.text();
-        throw new Error(`Token refresh failed (${res.status}): ${text}`);
+        const err = new Error(`Token refresh failed (${res.status}): ${text}`);
+        // Surface the HTTP status so callers can distinguish a genuine auth
+        // rejection (the refresh token is dead — re-login needed) from a
+        // transient server error. 5xx is retried above; reaching here with a 5xx
+        // means retries were exhausted, which is still transient, not auth.
+        err.status = res.status;
+        throw err;
       }
 
       const data = await res.json();
@@ -140,6 +148,73 @@ export async function fetchProfile(accessToken) {
   }
 }
 
+// Normalize one usage bucket from the /api/oauth/usage payload into
+// { utilization: 0-1, resetAt: ms-epoch }. The endpoint reports utilization
+// as a percentage in the 0-100 range, so 1 means 1%, not 100%.
+export function normalizeUsageBucket(bucket) {
+  if (!bucket || typeof bucket !== 'object') return null;
+
+  const rawPct = bucket.used_percentage ?? bucket.utilization ?? bucket.usedPercentage;
+  const parsedPct = typeof rawPct === 'number' ? rawPct : parseFloat(rawPct);
+  const utilization = Number.isFinite(parsedPct)
+    ? parsedPct / 100
+    : null;
+
+  const rawReset = bucket.resets_at ?? bucket.resetsAt ?? bucket.reset_at ?? bucket.resetAt;
+  let resetAt = null;
+  if (typeof rawReset === 'number') {
+    resetAt = rawReset < 1e12 ? rawReset * 1000 : rawReset;
+  } else if (typeof rawReset === 'string') {
+    const asNum = Number(rawReset);
+    if (Number.isFinite(asNum) && rawReset.trim() !== '') {
+      resetAt = asNum < 1e12 ? asNum * 1000 : asNum;
+    } else {
+      const parsed = Date.parse(rawReset);
+      if (Number.isFinite(parsed)) resetAt = parsed;
+    }
+  }
+
+  return { utilization, resetAt };
+}
+
+/**
+ * Fetch OAuth subscription usage from the usage endpoint. This reports quota
+ * utilization WITHOUT spending message quota, which is what makes it safe to
+ * poll. Returns normalized { fiveHour, sevenDay, sevenDaySonnet } buckets, or
+ * { error, status } on failure.
+ */
+export async function fetchUsage(accessToken) {
+  try {
+    const res = await fetch(USAGE_URL, {
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'anthropic-beta': OAUTH_USAGE_BETA,
+        'Accept': 'application/json',
+      },
+    });
+
+    if (!res.ok) {
+      let detail = '';
+      try {
+        const body = await res.json();
+        detail = body?.error?.message || JSON.stringify(body).slice(0, 200);
+      } catch {
+        detail = await res.text().catch(() => '');
+      }
+      return { error: `HTTP ${res.status}${detail ? ': ' + detail : ''}`, status: res.status };
+    }
+
+    const data = await res.json();
+    return {
+      fiveHour: normalizeUsageBucket(data?.five_hour),
+      sevenDay: normalizeUsageBucket(data?.seven_day),
+      sevenDaySonnet: normalizeUsageBucket(data?.seven_day_sonnet),
+    };
+  } catch (err) {
+    return { error: err.message || String(err), status: null };
+  }
+}
+
 // OAuth config (extracted from Claude Code)
 const OAUTH_CLIENT_ID = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
 const OAUTH_AUTHORIZE = 'https://claude.ai/oauth/authorize';

package/src/prober.js

@@ -0,0 +1,82 @@
+// Opt-in background quota probe.
+//
+// DISABLED BY DEFAULT. When enabled (config.quotaProbeSeconds > 0), periodically
+// reads each OAuth account's quota from the zero-spend /api/oauth/usage endpoint
+// so idle accounts' utilization/reset stay fresh without waiting to be rotated
+// to — and without consuming any message quota. This is the one sanctioned
+// active-upstream feature; the proxy is otherwise passive.
+
+import { fetchUsage } from './oauth.js';
+
+export class Prober {
+  constructor(accountManager, { intervalMs = 0, probeFn = fetchUsage, timeoutMs = 10_000, log = console.log } = {}) {
+    this.am = accountManager;
+    this.intervalMs = intervalMs;
+    this.probeFn = probeFn;
+    this.timeoutMs = timeoutMs;
+    this.log = log;
+    this.timer = null;
+    this._running = false;
+  }
+
+  start() {
+    if (this.intervalMs > 0) this.reschedule(this.intervalMs);
+  }
+
+  /** Change the interval at runtime (0 = off). Probes once immediately when on. */
+  reschedule(intervalMs) {
+    const wasOn = this.intervalMs > 0 && this.timer;
+    this.intervalMs = intervalMs;
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+
+    if (intervalMs > 0) {
+      // Probe right away so quota populates without waiting a full cycle.
+      this.probeAll().catch(() => {});
+      this.timer = setInterval(() => this.probeAll().catch(() => {}), intervalMs);
+      this.timer.unref?.();
+      this.log(`[TeamClaude] Quota probe enabled (every ${Math.round(intervalMs / 1000)}s)`);
+    } else if (wasOn) {
+      this.log('[TeamClaude] Quota probe disabled');
+    }
+  }
+
+  stop() {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+  }
+
+  /** Probe every OAuth account once. Overlapping cycles are skipped. */
+  async probeAll() {
+    if (this._running) return;
+    this._running = true;
+    try {
+      const accounts = this.am.accounts.filter(a => a.type === 'oauth' && a.credential);
+      await Promise.all(accounts.map(a => this.probeOne(a)));
+    } finally {
+      this._running = false;
+    }
+  }
+
+  async probeOne(account) {
+    try {
+      await this.am.ensureTokenFresh(account.index);
+      let usage = await this._withTimeout(this.probeFn(account.credential));
+      if (usage?.status === 401) {
+        // Token rejected — force a refresh and retry once.
+        await this.am.ensureTokenFresh(account.index, true);
+        usage = await this._withTimeout(this.probeFn(account.credential));
+      }
+      if (!usage || usage.error) return; // transient — try again next cycle
+      this.am.applyUsageData(account.index, usage);
+    } catch { /* best-effort; never let a probe throw */ }
+  }
+
+  _withTimeout(promise) {
+    return Promise.race([
+      promise,
+      new Promise(resolve => {
+        const t = setTimeout(() => resolve(null), this.timeoutMs);
+        t.unref?.();
+      }),
+    ]);
+  }
+}