@usagefleet/cli 1.2.59

package/dist/claude-limits.js

@@ -0,0 +1,217 @@
+const MESSAGES_URL = 'https://api.anthropic.com/v1/messages';
+export function parsePct(v) {
+    if (v == null || v === '') {
+        return null;
+    }
+    const n = Number(v);
+    if (!Number.isFinite(n)) {
+        return null;
+    }
+    // Header is a percent (e.g. "37"); guard the 0–1 fraction form too.
+    const pct = n > 0 && n <= 1 ? n * 100 : n;
+    return Math.min(100, Math.max(0, Math.round(pct)));
+}
+export function parseReset(v) {
+    if (!v) {
+        return null;
+    }
+    const num = Number(v);
+    if (Number.isFinite(num) && num > 1_000_000_000) {
+        // unix seconds (or ms)
+        const ms = num > 1e12 ? num : num * 1000;
+        return new Date(ms).toISOString();
+    }
+    const d = new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+/** Per-model utilization header: `anthropic-ratelimit-unified-<window>-<model>-utilization`
+ *  (the account-wide headers have no `<model>` segment and don't match). */
+const MODEL_UTIL_RE = /^anthropic-ratelimit-unified-(\d+[hdwm])-([a-z0-9][a-z0-9_.-]*)-utilization$/;
+export function parseLimitsHeaders(source, get, names = []) {
+    const modelLimits = [];
+    for (const raw of names) {
+        const m = raw.toLowerCase().match(MODEL_UTIL_RE);
+        if (!m) {
+            continue;
+        }
+        const [, window, model] = m;
+        modelLimits.push({
+            model,
+            pct: parsePct(get(raw)),
+            resetsAt: parseReset(get(`anthropic-ratelimit-unified-${window}-${model}-reset`)),
+            window,
+        });
+    }
+    return {
+        fiveHourPct: parsePct(get('anthropic-ratelimit-unified-5h-utilization')),
+        fiveHourResetsAt: parseReset(get('anthropic-ratelimit-unified-5h-reset')),
+        modelLimits,
+        sevenDayPct: parsePct(get('anthropic-ratelimit-unified-7d-utilization')),
+        sevenDayResetsAt: parseReset(get('anthropic-ratelimit-unified-7d-reset')),
+        source,
+    };
+}
+const OAUTH_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
+/**
+ * Per-model limits for subscription logins. The Messages ping only returns the
+ * account-wide 5h/7d headers; the per-model caps Claude's own UI shows (e.g.
+ * "Fable · 24% used") come from the OAuth usage endpoint Claude Code queries
+ * for /usage. Undocumented — parse defensively and return [] on any surprise.
+ */
+async function fetchOauthModelLimits(token) {
+    const res = await fetch(OAUTH_USAGE_URL, {
+        headers: {
+            'anthropic-beta': 'oauth-2025-04-20',
+            authorization: `Bearer ${token}`,
+            'user-agent': 'claude-code/2.1.5 (usagefleet)',
+        },
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+        return [];
+    }
+    const body = await res.json().catch(() => null);
+    if (process.env.USAGEFLEET_DEBUG_HEADERS) {
+        console.error(`[debug] oauth/usage: ${JSON.stringify(body)}`);
+    }
+    return parseOauthUsage(body);
+}
+/** oauth/usage values are already 0–100 percentages (unlike the 0–1 header
+ *  fractions) — clamp without the fraction heuristic so 1% never reads as 100%. */
+function clampPct(n) {
+    return Math.min(100, Math.max(0, Math.round(n)));
+}
+/** Normalize a scope's model name to a header-safe key ("Fable" → "fable"). */
+function modelKeyOf(name) {
+    return name.toLowerCase().replaceAll(/[^a-z0-9_.-]+/g, '-');
+}
+/**
+ * Extract per-model entries from an oauth/usage payload.
+ *
+ * Preferred source: the `limits[]` array — model-scoped entries (e.g.
+ * `{kind: "weekly_scoped", group: "weekly", percent, resets_at,
+ * scope: {model: {display_name: "Fable"}}}`) are exactly the per-model bars
+ * Claude's own UI renders. Account-wide entries have `scope: null` and are
+ * skipped (the header ping covers them).
+ *
+ * Fallback: legacy top-level `seven_day_<model>` objects with a `utilization`
+ * number (all null on current accounts, but cheap to keep).
+ */
+export function parseOauthUsage(body) {
+    if (typeof body !== 'object' || body === null) {
+        return [];
+    }
+    const root = body;
+    const out = [];
+    const seen = new Set();
+    if (Array.isArray(root.limits)) {
+        for (const item of root.limits) {
+            if (typeof item !== 'object' || item === null) {
+                continue;
+            }
+            const l = item;
+            const scope = (typeof l.scope === 'object' && l.scope !== null ? l.scope : {});
+            const model = (typeof scope.model === 'object' && scope.model !== null ? scope.model : null);
+            const name = (typeof model?.id === 'string' && model.id) ||
+                (typeof model?.display_name === 'string' && model.display_name) ||
+                null;
+            if (!name || typeof l.percent !== 'number') {
+                continue;
+            }
+            const window = l.group === 'session' ? '5h' : l.group === 'weekly' ? '7d' : '7d';
+            const key = modelKeyOf(name);
+            out.push({
+                model: key,
+                pct: clampPct(l.percent),
+                resetsAt: typeof l.resets_at === 'string' ? parseReset(l.resets_at) : null,
+                window,
+            });
+            seen.add(`${window}:${key}`);
+        }
+    }
+    for (const [key, val] of Object.entries(root)) {
+        const m = key.match(/^(five_hour|seven_day)_([a-z0-9_]+)$/);
+        if (!m || typeof val !== 'object' || val === null) {
+            continue;
+        }
+        const entry = val;
+        if (typeof entry.utilization !== 'number') {
+            continue;
+        }
+        const window = m[1] === 'five_hour' ? '5h' : '7d';
+        if (seen.has(`${window}:${m[2]}`)) {
+            continue;
+        }
+        out.push({
+            model: m[2],
+            pct: clampPct(entry.utilization),
+            resetsAt: typeof entry.resets_at === 'string' ? parseReset(entry.resets_at) : null,
+            window,
+        });
+    }
+    return out;
+}
+/**
+ * Read the account's real rate-limit utilization. Sends a 1-token ping to the
+ * Messages API; Anthropic returns the unified 5h/7d utilization in response
+ * headers (same approach as Claude-Usage-Tracker's OAuth path).
+ */
+export async function fetchLimits(creds) {
+    const headers = {
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+    };
+    if (creds.source === 'sub') {
+        headers['authorization'] = `Bearer ${creds.token}`;
+        headers['anthropic-beta'] = 'oauth-2025-04-20';
+        headers['user-agent'] = 'claude-code/2.1.5 (usagefleet)';
+    }
+    else {
+        headers['x-api-key'] = creds.token;
+    }
+    const res = await fetch(MESSAGES_URL, {
+        body: JSON.stringify({
+            max_tokens: 1,
+            messages: [{ role: 'user', content: 'hi' }],
+            model: 'claude-haiku-4-5-20251001',
+        }),
+        headers,
+        method: 'POST',
+        signal: AbortSignal.timeout(15_000),
+    });
+    // The unified rate-limit headers are (historically) present on success AND
+    // error responses — this OAuth/header-scraping path against the public
+    // Messages endpoint is undocumented and may break without notice. If a
+    // rejected response ALSO lacks the headers, the feature is unavailable; throw
+    // so the caller logs it instead of POSTing an all-null report silently.
+    // Diagnostic: dump every rate-limit header so unrecognized per-model names
+    // can be discovered in the field (USAGEFLEET_DEBUG_HEADERS=1).
+    if (process.env.USAGEFLEET_DEBUG_HEADERS) {
+        for (const [k, v] of res.headers.entries()) {
+            if (k.includes('ratelimit')) {
+                console.error(`[debug] ${k}: ${v}`);
+            }
+        }
+    }
+    const report = parseLimitsHeaders(creds.source, n => res.headers.get(n), res.headers.keys());
+    const gotHeaders = report.fiveHourPct != null ||
+        report.sevenDayPct != null ||
+        report.fiveHourResetsAt != null ||
+        report.sevenDayResetsAt != null ||
+        report.modelLimits.length > 0;
+    if (!res.ok && !gotHeaders) {
+        throw new Error(`limits unavailable: HTTP ${res.status} with no rate-limit headers`);
+    }
+    // Subscription logins: merge in the per-model caps from the OAuth usage
+    // endpoint (the ping headers never include them). Best-effort — keep the
+    // header-derived report on any failure.
+    if (creds.source === 'sub' && report.modelLimits.length === 0) {
+        try {
+            report.modelLimits = await fetchOauthModelLimits(creds.token);
+        }
+        catch {
+            /* endpoint unavailable — report account-wide limits only */
+        }
+    }
+    return report;
+}

package/dist/collector.js

@@ -0,0 +1,243 @@
+import { existsSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { sep } from 'node:path';
+import { detectClaudeCreds, macKeychainDenied } from './claude-creds.js';
+import { fetchLimits } from './claude-limits.js';
+import { maybeNotify } from './notifier.js';
+import { detectOs } from './os.js';
+import { RELEASE_VERSION } from './release.js';
+import { listJsonlFiles } from './scanner.js';
+import { readStore, updateStore } from './store.js';
+import { tailFile } from './tailer.js';
+import { postLimits, uploadBatch } from './uploader.js';
+/** Only files inside a `.../.claude/projects/...` subtree are real usage logs.
+ *  Desktop session roots also hold `audit.jsonl` (a full duplicate of the same
+ *  uuids) and other JSONL — restricting to this subtree mirrors Claude Code and
+ *  avoids re-uploading every desktop record twice. */
+const PROJECTS_SUBPATH = `${sep}.claude${sep}projects${sep}`;
+/**
+ * One full scan: tail every JSONL file from its stored offset, upload new usage
+ * records (chunked to batchSize), and commit each file's offset only after all
+ * its chunks are acknowledged (at-least-once; the server dedups on uuid).
+ */
+export async function runOnce(cfg, log = () => {
+    /* empty */
+}) {
+    const { state } = readStore(cfg.storePath);
+    // Each scan root is tagged with the app that owns it. Claude Code's projects
+    // dir is scanned whole; the Claude Desktop sessions root is filtered to its
+    // `.claude/projects` subtree (see PROJECTS_SUBPATH).
+    const roots = [
+        { dir: cfg.projectsDir, onlyProjects: false, source: 'cli' },
+    ];
+    if (cfg.desktopDir) {
+        roots.push({ dir: cfg.desktopDir, onlyProjects: true, source: 'desktop' });
+    }
+    for (const dir of cfg.piDirs) {
+        roots.push({ dir, onlyProjects: false, source: 'pi' });
+    }
+    const files = [];
+    for (const root of roots) {
+        for (const fp of listJsonlFiles(root.dir)) {
+            if (root.onlyProjects && !fp.includes(PROJECTS_SUBPATH)) {
+                continue;
+            }
+            files.push({ fp, source: root.source });
+        }
+    }
+    const result = {
+        accepted: 0,
+        dropped: 0,
+        duplicates: 0,
+        failed: false,
+        files: files.length,
+        sent: 0,
+    };
+    // Defensive: a bad batchSize must never stall the chunk loop.
+    const step = cfg.batchSize > 0 ? Math.floor(cfg.batchSize) : 100;
+    let advanced = false;
+    for (const { fp, source } of files) {
+        let tail;
+        try {
+            tail = tailFile(fp, state.files[fp], source);
+        }
+        catch (error) {
+            // One unreadable/oversized file must not abort the whole cycle.
+            log(`skip ${fp}: ${error.message}`);
+            continue;
+        }
+        if (!tail || tail.consumedBytes === 0) {
+            continue;
+        }
+        if (tail.records.length === 0) {
+            // Consumed only non-usage lines — safe to advance immediately.
+            state.files[fp] = tail.nextState;
+            advanced = true;
+            continue;
+        }
+        // sendChunk absorbs "invalid" by bisecting, so only auth/transient escape.
+        let outcome = 'ok';
+        for (let i = 0; i < tail.records.length; i += step) {
+            outcome = await sendChunk(tail.records.slice(i, i + step), cfg, result, log);
+            if (outcome !== 'ok') {
+                break;
+            }
+        }
+        if (outcome === 'ok') {
+            state.files[fp] = tail.nextState;
+            advanced = true;
+        }
+        else if (outcome === 'auth') {
+            // Token revoked/expired. The data is valid and must NOT be skipped — keep
+            // the offset so it uploads once a fresh token is configured. Retrying the
+            // remaining files would 401 identically, so stop this cycle and surface.
+            log(`auth rejected (401/403) — device token invalid or revoked; re-run \`usagefleet init\` with a fresh token, then restart the service`);
+            result.failed = true;
+            break;
+        }
+        else if (outcome === 'invalid') {
+            // The whole batch was rejected, not individual records (see sendChunk).
+            // Keep the offset: this needs a collector or server fix, not a purge.
+            log(`upload for ${fp} rejected as a whole batch — keeping the offset; check that this collector version and OS are supported by the server`);
+            result.failed = true;
+        }
+        else {
+            // transient (402 outside plan, 5xx, network, timeout): keep the offset and
+            // retry next cycle, but DO NOT break — later files must still get a turn.
+            log(`upload failed for ${fp} (transient) — will retry next cycle`);
+            result.failed = true;
+        }
+    }
+    // One durable write per cycle rather than one per file: the store is fsynced
+    // on every save, and a crash mid-cycle only costs a re-upload the server
+    // dedups. Only our own section is replaced, so a token written by a
+    // concurrent `usagefleet init` survives.
+    if (pruneMissingFiles(state, files) || advanced) {
+        updateStore(cfg.storePath, store => {
+            store.state.files = state.files;
+            store.state.updatedAt = new Date().toISOString();
+        });
+    }
+    return result;
+}
+/**
+ * Upload one chunk and tally it. A 400/422 means the server parsed the request
+ * and rejected the records themselves, so the chunk is split and the halves are
+ * retried: one malformed line then costs one record instead of the whole batch.
+ * Bisection adds ~log2(n) requests and only on the rare malformed line.
+ * Every other failure is handed back untouched so the caller keeps the offset.
+ *
+ * A 400 can also mean the server rejected the *envelope* — an `os` or
+ * `collectorVersion` outside its schema — in which case every record fails and
+ * bisecting would drop the entire batch for a bug that an upgrade fixes. So the
+ * split stops after MAX_DROPPED_PER_CHUNK drops and the rest is handed back as
+ * `invalid`, which keeps the offset. Real malformed lines are rare and isolated;
+ * anything that survives that many splits is not record-shaped.
+ */
+const MAX_DROPPED_PER_CHUNK = 2;
+async function sendChunk(records, cfg, result, log, dropCeiling = result.dropped + MAX_DROPPED_PER_CHUNK) {
+    const res = await uploadBatch({
+        collectorVersion: RELEASE_VERSION,
+        hostname: hostname(),
+        os: detectOs(),
+        records,
+        sentAt: new Date().toISOString(),
+    }, cfg);
+    if (res.ok) {
+        result.sent += records.length;
+        result.accepted += res.accepted ?? 0;
+        result.duplicates += res.duplicates ?? 0;
+        return 'ok';
+    }
+    if (res.fatal !== 'invalid') {
+        return res.fatal;
+    }
+    const single = records[0];
+    if (records.length === 1 && single) {
+        if (result.dropped >= dropCeiling) {
+            // Give up on the record theory. The caller keeps the offset, so the
+            // records counted on the way down are retried, not lost — untally them
+            // rather than report a loss that did not happen.
+            log(`every split of this batch was rejected, so the batch itself is bad, not its records — nothing skipped`);
+            result.dropped = dropCeiling - MAX_DROPPED_PER_CHUNK;
+            return 'invalid';
+        }
+        log(`server rejected record ${single.uuid} as malformed — skipping it`);
+        result.dropped += 1;
+        result.failed = true;
+        return 'ok';
+    }
+    const mid = Math.ceil(records.length / 2);
+    const head = await sendChunk(records.slice(0, mid), cfg, result, log, dropCeiling);
+    return head === 'ok' ? sendChunk(records.slice(mid), cfg, result, log, dropCeiling) : head;
+}
+/**
+ * Drop offsets for logs that no longer exist on disk, so a long-lived install
+ * does not grow its state file by one entry per Claude session forever. Only
+ * paths absent from this cycle's scan are stat'd, and only a real ENOENT prunes
+ * — a root that is merely unconfigured right now keeps its offsets.
+ * Returns whether anything was removed.
+ */
+function pruneMissingFiles(state, scanned) {
+    const seen = new Set(scanned.map(f => f.fp));
+    let removed = false;
+    for (const fp of Object.keys(state.files)) {
+        if (seen.has(fp) || existsSync(fp)) {
+            continue;
+        }
+        // oxlint-disable-next-line typescript/no-dynamic-delete -- state.files is a JSON blob keyed by path
+        delete state.files[fp];
+        removed = true;
+    }
+    return removed;
+}
+/**
+ * Auto-detect the local Claude login, read the real 5h/weekly utilization from
+ * Anthropic's rate-limit headers, and report it to the server. Best-effort —
+ * returns null (and logs) when no login is found or the request fails.
+ */
+export async function reportLimitsOnce(cfg, log = () => {
+    /* empty */
+}) {
+    const creds = await detectClaudeCreds();
+    if (!creds) {
+        if (process.platform === 'darwin' && macKeychainDenied()) {
+            // "Works by hand, broken as a service" signature: a launchd agent can be
+            // denied the login-Keychain read. Make it diagnosable instead of silent.
+            log("limits skipped: login Keychain read for 'Claude Code-credentials' was denied " +
+                '(typical under a background launchd agent). Grant /usr/bin/security access to the ' +
+                'item, or set ANTHROPIC_API_KEY for the service.');
+        }
+        else {
+            log('no usable Claude login — missing, or expired with a refresh that failed; ' +
+                'sign in with `claude` or set ANTHROPIC_API_KEY');
+        }
+        return null;
+    }
+    let report;
+    try {
+        report = await fetchLimits(creds);
+    }
+    catch (error) {
+        log(`limits fetch failed: ${error.message}`);
+        return null;
+    }
+    const ok = await postLimits(report, cfg);
+    if (!ok) {
+        log('limits upload failed');
+    }
+    // Cache the reading so `status` can show current usage without spending
+    // another billable API call.
+    updateStore(cfg.storePath, store => {
+        store.limits = {
+            at: new Date().toISOString(),
+            fiveHourPct: report.fiveHourPct,
+            sevenDayPct: report.sevenDayPct,
+            source: report.source,
+        };
+    });
+    // Local desktop notification on freshly-crossed thresholds. Independent of the
+    // server upload (notify even if the POST failed) and never throws.
+    maybeNotify(report, undefined, log);
+    return report;
+}

package/dist/config.js

@@ -0,0 +1,74 @@
+import { defaultDesktopSessionsDir, defaultPiSessionsDirs, defaultProjectsDir } from './paths.js';
+import { readStore, storePath } from './store.js';
+/** Matches the server's BatchSchema `.max(1000)`. */
+const MAX_BATCH = 1000;
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+/** Resolve config from env first, then the stored settings (see store.ts). */
+export function loadConfig() {
+    const file = readStore();
+    // Use `||` (not `??`) so an empty-string env var falls back to the config
+    // file — launchd/systemd units may inject empty USAGEFLEET_* values.
+    const endpoint = (process.env.USAGEFLEET_ENDPOINT || file.endpoint || '').replace(/\/+$/, '');
+    const token = process.env.USAGEFLEET_TOKEN || file.token || '';
+    if (!endpoint) {
+        throw new Error('USAGEFLEET_ENDPOINT is not set');
+    }
+    if (!token) {
+        throw new Error('USAGEFLEET_TOKEN is not set');
+    }
+    if (!isSecureEndpoint(endpoint)) {
+        throw new Error(`USAGEFLEET_ENDPOINT must be https (got ${endpoint}). It carries the device token on every request and self-update executes a binary fetched from it.`);
+    }
+    // Guard batch size: "0" (infinite loop), NaN (silent drop), fractional → 100.
+    // Clamped to the server's own 1000-record cap, since a larger batch is
+    // rejected as malformed and would cost the whole chunk a bisect to discover.
+    const parsedBatch = Math.floor(Number(process.env.USAGEFLEET_BATCH));
+    const batchSize = Number.isFinite(parsedBatch) && parsedBatch > 0 ? Math.min(parsedBatch, MAX_BATCH) : 100;
+    return {
+        batchSize,
+        desktopDir: resolveOptionalDir(process.env.USAGEFLEET_DESKTOP, file.desktopDir, defaultDesktopSessionsDir()),
+        endpoint,
+        piDirs: resolvePiDirs(process.env.USAGEFLEET_PI, file.piDir),
+        projectsDir: process.env.USAGEFLEET_PROJECTS || file.projectsDir || defaultProjectsDir(),
+        storePath: storePath(),
+        token,
+    };
+}
+/** pi scan roots: env "off"/"0" disables, else a comma-separated env list, else
+ *  the config file's string-or-array, else every auto-detected default. */
+export function resolvePiDirs(env, fromFile) {
+    if (env === '0' || env?.toLowerCase() === 'off') {
+        return [];
+    }
+    const raw = env ? env.split(',') : Array.isArray(fromFile) ? fromFile : fromFile ? [fromFile] : null;
+    if (!raw) {
+        return defaultPiSessionsDirs();
+    }
+    return [...new Set(raw.map(d => d.trim()).filter(d => d.length > 0))];
+}
+/** Optional scan root (USAGEFLEET_DESKTOP / USAGEFLEET_PI): env "off"/"0"
+ *  disables, env or config-file path overrides, else the auto-detected default. */
+function resolveOptionalDir(env, fromFile, fallback) {
+    if (env === '0' || env?.toLowerCase() === 'off') {
+        return null;
+    }
+    return env || fromFile || fallback;
+}
+/**
+ * The endpoint must be https: it carries the device token on every request, and
+ * the payload is a log of what this machine is working on. Loopback is exempt so
+ * local development keeps working.
+ */
+export function isSecureEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol === 'https:') {
+        return true;
+    }
+    return url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname);
+}

package/dist/guard.js

@@ -0,0 +1,59 @@
+import { loadConfig } from './config.js';
+/** Hooks run on the interactive path — a slow/hung server must not stall a
+ *  prompt for long. On timeout we fail open (see {@link runGuard}). */
+const TIMEOUT_MS = 5000;
+/**
+ * The message shown to the user when the prompt is refused, or null to let it
+ * through. Only an explicit `blocked: true` blocks — anything unexpected
+ * (missing fields, old server, junk) falls through to null on purpose, so a
+ * tracker problem can never stop someone from working.
+ */
+export function blockMessage(view) {
+    if (view.blocked !== true) {
+        return null;
+    }
+    const weekly = view.blockedWindow === 'weekly';
+    const pct = (weekly ? view.weeklyPct : view.sessionPct) ?? 100;
+    const group = view.group ? `"${view.group}"` : 'this group';
+    const until = view.blockedUntil ? new Date(view.blockedUntil) : null;
+    const resets = until && !Number.isNaN(until.getTime())
+        ? ` Resets ${until.toLocaleString([], { dateStyle: 'short', timeStyle: 'short' })}.`
+        : '';
+    return (`usagefleet: ${group} has used ${pct}% of its ${weekly ? 'weekly' : '5h'} budget, ` +
+        `so new prompts are blocked.${resets}`);
+}
+/**
+ * Exit code for `usagefleet guard`, the Claude Code `UserPromptSubmit` hook:
+ * 2 refuses the prompt (stderr is shown to the user), 0 lets it through.
+ * Prints nothing on stdout — on this hook stdout is injected into the model's
+ * context.
+ */
+export async function runGuard() {
+    let cfg;
+    try {
+        cfg = loadConfig();
+    }
+    catch {
+        return 0; // not configured on this machine — nothing to enforce
+    }
+    let view;
+    try {
+        const res = await fetch(`${cfg.endpoint}/api/v1/limits`, {
+            headers: { 'x-api-key': cfg.token },
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            return 0;
+        }
+        view = (await res.json());
+    }
+    catch {
+        return 0; // offline / timeout / bad JSON — fail open
+    }
+    const msg = blockMessage(view);
+    if (!msg) {
+        return 0;
+    }
+    process.stderr.write(`${msg}\n`);
+    return 2;
+}