agy-cli-usage 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -10,6 +10,21 @@
 
 * use plain v* tags in release-please ([#12](https://github.com/abruption/agy-cli-usage/issues/12)) ([74b648d](https://github.com/abruption/agy-cli-usage/commit/74b648df24967f71a43095a80e7340a6b5ac2e39)), closes [#9](https://github.com/abruption/agy-cli-usage/issues/9)
 
+## [0.4.5](https://github.com/abruption/agy-cli-usage/compare/v0.4.4...v0.4.5) (2026-07-03)
+
+
+### Bug Fixes
+
+* derive UA from package version, name error classes, bound update-check timeouts, document env vars in --help, show cache freshness in watch mode ([62becdc](https://github.com/abruption/agy-cli-usage/commit/62becdcf4175d2cda3cec8dc3f5bba13005c0d59)), closes [#32](https://github.com/abruption/agy-cli-usage/issues/32)
+* UA version, error class names, update-check timeouts, --help env vars, watch/cache indicator ([#37](https://github.com/abruption/agy-cli-usage/issues/37)) ([62becdc](https://github.com/abruption/agy-cli-usage/commit/62becdcf4175d2cda3cec8dc3f5bba13005c0d59))
+
+## [0.4.4](https://github.com/abruption/agy-cli-usage/compare/v0.4.3...v0.4.4) (2026-07-03)
+
+
+### Bug Fixes
+
+* PTY cleanup, duration parsing, email extraction, render clamping, test coverage ([#35](https://github.com/abruption/agy-cli-usage/issues/35)) ([de886a2](https://github.com/abruption/agy-cli-usage/commit/de886a2a5fdf9c7777f485fd94eab0f1a13d215f))
+
 ## [0.4.3](https://github.com/abruption/agy-cli-usage/compare/v0.4.2...v0.4.3) (2026-07-02)
 
 

package/README.ko.md

@@ -131,6 +131,7 @@ npm test          # 빌드 후 node --test (자격증명·네트워크 불필요
 ## 주의
 
 - `v1internal:retrieveUserQuotaSummary`는 **비공개·비문서 내부 엔드포인트**입니다. 스키마/호스트가 예고 없이 바뀔 수 있으며, 그때의 안전망이 PTY 폴백입니다. 본인 계정의 사용량 조회 용도로만 사용하세요.
+- **최상위 티어 구독자는 API 경로에서 `account`가 `null`입니다.** API 경로는 `loadCodeAssist` 응답의 `currentTier.upgradeSubscriptionUri`에 붙은 `Email=` 파라미터에서 계정 이메일을 추출하는데, 이미 최상위 티어인 계정은 "업그레이드" URL 자체가 없어 추출할 대상이 없습니다. 이는 비공개 엔드포인트의 알려진 제약이며, `--source pty`(agy 자체가 렌더링한 `/usage` 패널에서 `Account: …`를 직접 읽어오므로 영향받지 않음) 외에는 다른 우회 플래그가 없습니다.
 - 자격증명은 OS 저장소에서 **읽기만** 하며, refresh 토큰을 되쓰지 않아 `agy` 세션과 충돌하지 않습니다.
 - 코드에 포함된 OAuth client_id/secret은 `agy` 바이너리의 **installed-app(public)** 값으로, [Google 문서](https://developers.google.com/identity/protocols/oauth2)상 기밀이 아닙니다. 사용자 식별은 각자의 키링 토큰으로 이뤄집니다.
 
@@ -198,6 +199,7 @@ npm test          # 빌드 후 node --test (자격증명·네트워크 불필요
 - `remainingFraction`(잔여 비율 0–1)을 우선 사용. `available`이 `true`면 풀 쿼타로 간주(패널은 "Quota available" 표시).
 - `resetsInSeconds`는 `fetchedAt` 기준 상대값, `resetAt`은 절대값. 둘 다 `null` 가능.
 - `kind`는 인식 시 `weekly`/`5h`로 정규화, 아니면 원본 window/label 문자열.
+- `"source": "api"`로 성공한 응답에서도 `account`가 `null`일 수 있습니다 — 위 주의 섹션 참고(최상위 티어 구독자는 API 경로에 이메일 소스가 없음). 계정 이메일이 반드시 필요하면 `--source pty` 또는 PTY 기반 스냅샷을 사용하세요.
 
 ## HTTP API (`npm run serve` / `dist/src/server.js`)
 

package/README.md

@@ -131,6 +131,7 @@ npm test          # build, then node --test (no credentials/network; pure logic)
 ## Caveats
 
 - `v1internal:retrieveUserQuotaSummary` is a **private, undocumented endpoint**. Its schema/host may change without notice; the PTY fallback is the safety net. Use it only to check your own account's usage.
+- **`account` is `null` via the API path for top-tier subscribers.** The API path derives the account email from the `Email=` param on `currentTier.upgradeSubscriptionUri` in the `loadCodeAssist` response — accounts already on the top tier have no "upgrade" URL, so there's nothing to extract from. This is a known limitation of the undocumented endpoint, not a bug you can work around via flags other than `--source pty`, which reads `Account: …` straight off agy's own rendered `/usage` panel and isn't affected.
 - Credentials are **read-only** from the OS store; the refresh token is never written back, so it never conflicts with `agy`'s own session.
 - The OAuth client_id/secret embedded in the code are `agy`'s **installed-app (public)** values — per [Google's docs](https://developers.google.com/identity/protocols/oauth2) these are not treated as secret. Per-user identity comes from your keyring token, not the client_id.
 
@@ -198,6 +199,7 @@ Notes for parsing:
 - Prefer `remainingFraction` (fraction remaining, 0–1). When `available` is `true`, treat as full quota (the panel shows "Quota available").
 - `resetsInSeconds` is relative to `fetchedAt`; `resetAt` is absolute. Either may be `null`.
 - `kind` is normalized to `weekly` / `5h` where recognized, otherwise the raw window/label string.
+- `account` may be `null` even on a successful `"source": "api"` response — see the Caveats section above (top-tier subscribers have no email source in the API path). Use `--source pty` / a PTY-sourced snapshot if you need the account email reliably.
 
 ## HTTP API (`npm run serve` / `dist/src/server.js`)
 

package/dist/src/api.d.ts

@@ -1,4 +1,6 @@
 import type { FetchResult } from './types.js';
+/** Exported for direct unit testing — keeps the UA tied to the real package name/version. */
+export declare function buildUserAgent(): string;
 declare class ApiError extends Error {
     status: number;
     constructor(message: string, status: number);

package/dist/src/api.js

@@ -8,7 +8,12 @@
 //
 // Captured from live agy traffic (mitmproxy). The internal endpoint is undocumented;
 // the PTY fallback exists for when it changes.
-const UA = `antigravity-usage-monitor/0.1 ${process.platform}/${process.arch}`;
+import { currentVersion } from './update.js';
+/** Exported for direct unit testing — keeps the UA tied to the real package name/version. */
+export function buildUserAgent() {
+    return `agy-cli-usage/${currentVersion()} ${process.platform}/${process.arch}`;
+}
+const UA = buildUserAgent();
 // Antigravity ships against the "daily" Cloud Code host; stable builds use the
 // plain host. Try daily first (matches current CLI), fall back to prod.
 const HOSTS = ['daily-cloudcode-pa.googleapis.com', 'cloudcode-pa.googleapis.com'];
@@ -16,9 +21,20 @@ class ApiError extends Error {
     status;
     constructor(message, status) {
         super(message);
+        this.name = 'ApiError';
         this.status = status;
     }
 }
+// Known limitation: this is the only email source `loadCodeAssist` exposes —
+// the `Email=` query param on `currentTier.upgradeSubscriptionUri`. Accounts
+// already on the top tier have nothing left to upgrade to, so that URI (and
+// therefore `account`) is `null` for them via the API path even though the
+// PTY path can still show `Account: …` (it reads it straight off agy's own
+// rendered panel, which has an in-app session it can draw on that this
+// unauthenticated-beyond-the-token API response doesn't provide). There is no
+// alternative email field in either `loadCodeAssist` or
+// `retrieveUserQuotaSummary` today — see README Caveats. Use `--source pty`
+// if you need the account email for a top-tier subscriber.
 function extractEmail(uri) {
     const m = uri?.match(/[?&]Email=([^&]+)/);
     if (!m)

package/dist/src/credentials.d.ts

@@ -1,4 +1,5 @@
 declare class CredentialError extends Error {
+    constructor(message: string);
 }
 interface Cred {
     accessToken: string;

package/dist/src/credentials.js

@@ -35,6 +35,10 @@ const KEYRING_SERVICE = 'gemini';
 const KEYRING_ACCOUNT = 'antigravity';
 const B64_PREFIX = 'go-keyring-base64:';
 class CredentialError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CredentialError';
+    }
 }
 // --- raw keyring read --------------------------------------------------------
 async function readViaNapiEsm() {

package/dist/src/main.js

@@ -82,6 +82,15 @@ const HELP = `agy-cli-usage — Antigravity CLI (agy) usage/quota monitor
   agy-cli-usage --no-cache | --refresh
   agy-cli-usage update [--check]  self-update via npm (--check: report only)
   agy-cli-usage --version | -v
+
+Environment variables:
+  AGY_OAUTH_TOKEN_FILE  Override the token file path (headless fallback).
+  AGY_BIN               Path to the agy binary (PTY source). Else resolved from
+                        PATH, then ~/.local/bin.
+  XDG_CACHE_HOME        Cache base dir (cache lives at
+                        <base>/agy-usage/quota.json; default ~/.cache).
+  NO_COLOR              Disable ANSI color in the rendered panel.
+  PORT / HOST           HTTP server bind (server mode only).
 `;
 /** Exported for direct unit testing via an injected `cacheFile` — not part of the CLI's public surface. */
 export function readCache(source, channel, cacheFile = CACHE_FILE) {

package/dist/src/pty-fallback.js

@@ -12,7 +12,7 @@
 // Windows (ConPTY). agy shows a welcome screen first, so `/usage` is sent after
 // a delay and the session is held open long enough to render.
 import { spawn } from 'node:child_process';
-import { writeFileSync, readFileSync, mkdtempSync, existsSync } from 'node:fs';
+import { writeFileSync, readFileSync, mkdtempSync, existsSync, rmSync } from 'node:fs';
 import { tmpdir, homedir } from 'node:os';
 import { join, delimiter } from 'node:path';
 // Resolve the agy binary: explicit AGY_BIN, then PATH, then common install dir.
@@ -79,10 +79,14 @@ async function captureViaNodePty() {
 async function captureViaPython() {
     if (process.platform === 'win32')
         return null;
+    // Cleaned up in `finally` below regardless of success/failure so repeated
+    // `--watch` runs or repeated fallback triggers don't leak a directory per
+    // capture (each holds a helper script + the captured PTY bytes).
     const dir = mkdtempSync(join(tmpdir(), 'agy-usage-'));
-    const helper = join(dir, 'drive.py');
-    const outFile = join(dir, 'out.bin');
-    writeFileSync(helper, `import os, pty, time, select, signal, struct, fcntl, termios
+    try {
+        const helper = join(dir, 'drive.py');
+        const outFile = join(dir, 'out.bin');
+        writeFileSync(helper, `import os, pty, time, select, signal, struct, fcntl, termios
 AGY = ${JSON.stringify(AGY_BIN)}
 out = open(${JSON.stringify(outFile)}, "wb")
 pid, fd = pty.fork()
@@ -107,18 +111,25 @@ try: os.kill(pid, signal.SIGTERM)
 except Exception: pass
 out.close()
 `);
-    return new Promise((resolve) => {
-        const proc = spawn('python3', [helper], { stdio: 'ignore' });
-        proc.on('error', () => resolve(null));
-        proc.on('exit', () => {
-            try {
-                resolve(readFileSync(outFile));
-            }
-            catch {
-                resolve(null);
-            }
+        return await new Promise((resolve) => {
+            const proc = spawn('python3', [helper], { stdio: 'ignore' });
+            proc.on('error', () => resolve(null));
+            proc.on('exit', () => {
+                try {
+                    resolve(readFileSync(outFile));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
         });
-    });
+    }
+    finally {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* best-effort cleanup */ }
+    }
 }
 // --- VT reconstruction --------------------------------------------------------
 async function reconstructScreen(raw) {
@@ -139,7 +150,11 @@ async function reconstructScreen(raw) {
 // --- parse --------------------------------------------------------------------
 function parseDuration(text) {
     let seconds = 0;
-    const d = text.match(/(\d+)\s*day/i);
+    // Matches both the spelled-out form ("3 days", "1 day") and the abbreviated
+    // form ("3d") that agy's panel may render instead — without the `\b`
+    // fallback, only "day"/"days" was recognized and a bare "3d 2h" silently
+    // dropped the day component.
+    const d = text.match(/(\d+)\s*d(?:ays?)?\b/i);
     const h = text.match(/(\d+)\s*h(?:our)?/i);
     const m = text.match(/(\d+)\s*m(?:in)?/i);
     if (d)

package/dist/src/render.d.ts

@@ -1,3 +1,3 @@
 import type { Snapshot } from './types.js';
-/** Returns the full panel as a string. */
-export declare function renderPanel(snap: Snapshot): string;
+/** Returns the full panel as a string. `nowMs` is injectable for testing. */
+export declare function renderPanel(snap: Snapshot, nowMs?: number): string;

package/dist/src/render.js

@@ -16,8 +16,15 @@ function barColor(remaining) {
         return '33'; // yellow
     return '31'; // red
 }
+// Clamp to [0,1] — remainingFraction comes from an undocumented private
+// endpoint (or PTY-parsed text), so an out-of-range value must not be shown
+// as-is. Shared by the bar and the percentage text so they never disagree
+// (e.g. bar capped at 100% while the text next to it reads "150.00%").
+function clampFraction(remainingFraction) {
+    return remainingFraction == null ? null : Math.max(0, Math.min(1, remainingFraction));
+}
 function bar(remainingFraction) {
-    const frac = remainingFraction == null ? 0 : Math.max(0, Math.min(1, remainingFraction));
+    const frac = clampFraction(remainingFraction) ?? 0;
     const filled = Math.round(frac * BAR_WIDTH);
     const body = '█'.repeat(filled) + '░'.repeat(BAR_WIDTH - filled);
     return useColor() ? `\x1b[${barColor(remainingFraction)}m${body}\x1b[0m` : body;
@@ -29,8 +36,9 @@ function bucketLine(b) {
         lines.push(`    [${bar(1)}] ${c('32', 'Quota available')}`);
     }
     else {
-        const pct = b.remainingFraction == null ? '—' : `${(b.remainingFraction * 100).toFixed(2)}%`;
-        const remainPct = b.remainingFraction == null ? '' : `${Math.round(b.remainingFraction * 100)}% remaining`;
+        const clamped = clampFraction(b.remainingFraction);
+        const pct = clamped == null ? '—' : `${(clamped * 100).toFixed(2)}%`;
+        const remainPct = clamped == null ? '' : `${Math.round(clamped * 100)}% remaining`;
         const dur = formatDuration(b.resetsInSeconds);
         const reset = dur ? ` · ${dim(`Refreshes in ${dur}`)}` : '';
         lines.push(`    [${bar(b.remainingFraction)}] ${pct}`);
@@ -38,14 +46,40 @@ function bucketLine(b) {
     }
     return lines.join('\n');
 }
-/** Returns the full panel as a string. */
-export function renderPanel(snap) {
+// `--watch`'s default interval (60s) is faster than the 5-minute quota cache
+// TTL, so most refreshes just re-render a cached snapshot with no visual
+// sign the fetch didn't actually happen. `fetchedAt` is set once, when the
+// data was truly fetched (see quota.ts), and carried through untouched on a
+// cache hit — so comparing it to "now" at render time is enough to tell the
+// two cases apart without threading extra state through Snapshot/the cache.
+// A small skew is tolerated so a genuinely fresh fetch isn't mislabeled
+// "cached" just because rendering happened slightly after fetching.
+const FRESHNESS_SKEW_MS = 3_000;
+function formatAge(totalSeconds) {
+    const s = Math.max(0, Math.round(totalSeconds));
+    if (s < 60)
+        return `${s}s`;
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    if (h > 0)
+        return `${h}h ${m}m`;
+    return `${m}m ${s % 60}s`;
+}
+function freshnessSuffix(fetchedAt, nowMs) {
+    const ageMs = nowMs - new Date(fetchedAt).getTime();
+    if (!Number.isFinite(ageMs) || ageMs < FRESHNESS_SKEW_MS)
+        return '';
+    return dim(` (cached, refreshed ${formatAge(ageMs / 1000)} ago)`);
+}
+/** Returns the full panel as a string. `nowMs` is injectable for testing. */
+export function renderPanel(snap, nowMs = Date.now()) {
     const out = [];
     out.push('');
     out.push(bold('  Models & Quota'));
     if (snap.account)
         out.push(`  ${dim('Account:')} ${snap.account}`);
-    out.push(`  ${dim(`source: ${snap.source}${snap.host ? ` · ${snap.host}` : ''} · ${snap.fetchedAt}`)}`);
+    out.push(`  ${dim(`source: ${snap.source}${snap.host ? ` · ${snap.host}` : ''} · ${snap.fetchedAt}`)}` +
+        freshnessSuffix(snap.fetchedAt, nowMs));
     out.push('');
     for (const g of snap.groups) {
         out.push(bold(`  ${g.name.toUpperCase()}`));

package/dist/src/server.d.ts

@@ -1,2 +1,16 @@
 #!/usr/bin/env node
+import { type Server } from 'node:http';
+import type { Snapshot } from './types.js';
+type SnapshotFetcher = (opts: {
+    source: 'auto';
+    channel: 'auto';
+    cache: boolean;
+}) => Promise<Snapshot>;
+/**
+ * Builds the HTTP server without binding a port.
+ * `fetchSnapshot` defaults to the real `getSnapshot` (network/keyring/PTY) —
+ * exposed as a parameter purely so tests can inject a stub and exercise the
+ * routing/response-shape logic without live credentials or a PTY.
+ */
+export declare function createApp(fetchSnapshot?: SnapshotFetcher): Server;
 export {};

package/dist/src/server.js

@@ -7,37 +7,64 @@
 //   GET /quota   -> normalized snapshot JSON
 //   GET /healthz -> { ok: true }
 import { createServer } from 'node:http';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { getSnapshot } from './main.js';
 const PORT = Number(process.env.PORT) || 3007;
 const HOST = process.env.HOST || '127.0.0.1';
-const server = createServer(async (req, res) => {
-    const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
-    if (url.pathname === '/healthz') {
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ ok: true }));
-        return;
-    }
-    if (url.pathname === '/quota') {
-        try {
-            const noCache = url.searchParams.get('refresh') === '1';
-            const snap = await getSnapshot({ source: 'auto', channel: 'auto', cache: !noCache });
-            res.writeHead(200, {
-                'Content-Type': 'application/json',
-                'Access-Control-Allow-Origin': '*',
-                'Cache-Control': 'public, max-age=300',
-            });
-            res.end(JSON.stringify(snap));
+/**
+ * Builds the HTTP server without binding a port.
+ * `fetchSnapshot` defaults to the real `getSnapshot` (network/keyring/PTY) —
+ * exposed as a parameter purely so tests can inject a stub and exercise the
+ * routing/response-shape logic without live credentials or a PTY.
+ */
+export function createApp(fetchSnapshot = getSnapshot) {
+    return createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+        if (url.pathname === '/healthz') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true }));
+            return;
         }
-        catch (err) {
-            res.writeHead(502, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        if (url.pathname === '/quota') {
+            try {
+                const noCache = url.searchParams.get('refresh') === '1';
+                const snap = await fetchSnapshot({ source: 'auto', channel: 'auto', cache: !noCache });
+                res.writeHead(200, {
+                    'Content-Type': 'application/json',
+                    'Access-Control-Allow-Origin': '*',
+                    'Cache-Control': 'public, max-age=300',
+                });
+                res.end(JSON.stringify(snap));
+            }
+            catch (err) {
+                res.writeHead(502, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+            }
+            return;
         }
-        return;
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'not found' }));
+    });
+}
+// Only bind a real port when this file is executed directly (the `serve`
+// script's entry point) — guarded the same way as main.ts's isMainModule()
+// so `createApp` can be imported for unit testing without the import itself
+// starting a live server as a side effect.
+function isMainModule() {
+    if (!process.argv[1])
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
     }
-    res.writeHead(404, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error: 'not found' }));
-});
-server.listen(PORT, HOST, () => {
-    process.stdout.write(`agy-usage server on http://${HOST}:${PORT}  (GET /quota)\n`);
-});
+}
+if (isMainModule()) {
+    const server = createApp();
+    server.listen(PORT, HOST, () => {
+        process.stdout.write(`agy-usage server on http://${HOST}:${PORT}  (GET /quota)\n`);
+    });
+}
 //# sourceMappingURL=server.js.map

package/dist/src/update.d.ts

@@ -9,8 +9,15 @@ export declare function currentVersion(): string;
  * Returns negative if a<b, 0 if equal, positive if a>b.
  */
 export declare function semverCompare(a: string, b: string): number;
+export declare const NPM_VIEW_TIMEOUT_MS = 8000;
+export declare const REGISTRY_FETCH_TIMEOUT_MS = 8000;
+/** Exported for direct unit testing via injection — not part of the public surface. */
+export interface LatestVersionDeps {
+    execNpmView?: (pkgName: string, timeoutMs: number) => string;
+    fetchRegistry?: (pkgName: string, timeoutMs: number) => Promise<Response>;
+}
 /** Latest published version: prefer the user's configured registry (npm view), fall back to public. */
-export declare function latestVersion(): Promise<string | null>;
+export declare function latestVersion(deps?: LatestVersionDeps): Promise<string | null>;
 /** Run the update flow. Returns the intended process exit code. */
 export declare function runUpdate({ checkOnly }?: {
     checkOnly?: boolean;

package/dist/src/update.js

@@ -34,26 +34,42 @@ export function semverCompare(a, b) {
     }
     return 0;
 }
+// Both the `npm view` child process and the registry fetch fallback are
+// bounded so a slow/unreachable registry can't hang the update check
+// indefinitely — a timed-out attempt is treated the same as "unavailable"
+// and falls through to the next strategy (or to `latestVersion` returning
+// null, which `runUpdate` reports as "could not determine the latest version").
+export const NPM_VIEW_TIMEOUT_MS = 8_000;
+export const REGISTRY_FETCH_TIMEOUT_MS = 8_000;
+function defaultExecNpmView(pkgName, timeoutMs) {
+    return execFileSync('npm', ['view', pkgName, 'version'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: timeoutMs,
+    });
+}
+function defaultFetchRegistry(pkgName, timeoutMs) {
+    return fetch(`https://registry.npmjs.org/${pkgName}/latest`, { signal: AbortSignal.timeout(timeoutMs) });
+}
 /** Latest published version: prefer the user's configured registry (npm view), fall back to public. */
-export async function latestVersion() {
+export async function latestVersion(deps = {}) {
+    const execNpmView = deps.execNpmView ?? defaultExecNpmView;
+    const fetchRegistry = deps.fetchRegistry ?? defaultFetchRegistry;
     try {
-        const out = execFileSync('npm', ['view', PKG_NAME, 'version'], {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
+        const out = execNpmView(PKG_NAME, NPM_VIEW_TIMEOUT_MS).trim();
         if (out)
             return out;
     }
     catch {
-        // npm missing or offline — try the public registry directly
+        // npm missing, offline, or timed out — try the public registry directly
     }
     try {
-        const res = await fetch(`https://registry.npmjs.org/${PKG_NAME}/latest`);
+        const res = await fetchRegistry(PKG_NAME, REGISTRY_FETCH_TIMEOUT_MS);
         if (res.ok)
             return (await res.json()).version;
     }
     catch {
-        // offline
+        // offline or timed out
     }
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-cli-usage",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Headless usage/quota monitor for the Antigravity CLI (agy) — reads Cloud Code quota directly, with a PTY fallback. No IDE required.",
   "type": "module",
   "types": "dist/src/main.d.ts",
@@ -11,6 +11,7 @@
   "scripts": {
     "build": "tsc",
     "check": "tsc --noEmit",
+    "lint": "eslint .",
     "pretest": "tsc",
     "test": "node --test dist/test/unit.test.js",
     "start": "tsc && node dist/src/main.js",
@@ -55,7 +56,10 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^26.0.0",
-    "typescript": "^6.0.3"
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^18.19.0",
+    "eslint": "^9.39.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1"
   }
 }