@tsa-group/claude-usage 0.3.0

package/dist/install.js

@@ -0,0 +1,263 @@
+/**
+ * 平台安裝層 — 把 `claude-usage daemon-tick` 註冊成背景任務。
+ * **唯一有 per-OS 分支的地方**；核心邏輯（daemon.tick）三個平台共用。
+ *
+ *   macOS   : launchd LaunchAgent (~/Library/LaunchAgents)
+ *   Windows : 工作排程器 schtasks（per-user，每 N 分鐘）—— 碼寫好但**未在真機實測**
+ *   Linux   : systemd --user timer（未實作）
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, platform, userInfo } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { claudeSettingsPath, devicePath, logPath, serverUrl, stateDir } from "./paths.js";
+import { printHealth } from "./daemon.js";
+import { enroll, enrollSecret } from "./upload.js";
+import { readJson, writeJsonAtomic } from "./util.js";
+const LABEL = "com.tsa.claude-usage";
+const WIN_TASK = "ClaudeUsage";
+/** 排程器基礎頻率；真正的採樣間隔由 tick() 自己決定（見 daemon.decide） */
+const BASE_INTERVAL_SEC = 300;
+/**
+ * 背景任務要執行的東西。用 `process.execPath`（node 絕對路徑）+ cli.js 絕對路徑，
+ * 不用 PATH 上的 `claude-usage` shim —— launchd / schtasks 的 PATH 極簡，找不到 shim。
+ *
+ * `npm update` 會就地換掉套件檔案、路徑不變，所以升級後排程仍然有效。若使用者換掉
+ * node（例如 nvm 切版本後刪舊版）則會失效 —— 那會表現成 v_device_health 的
+ * `no_heartbeat`，看得見，重跑一次 install 即可。
+ */
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "cli.js");
+const NODE = process.execPath;
+const HOOK_CMD = `"${NODE}" "${CLI}" sample --hook`;
+const PLIST_PATH = join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+const isDry = (argv) => argv.includes("--dry-run");
+// ─────────────────────────────── macOS ───────────────────────────────
+const plistBody = () => `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${NODE}</string>
+    <string>${CLI}</string>
+    <string>daemon-tick</string>
+  </array>
+  <key>StartInterval</key><integer>${BASE_INTERVAL_SEC}</integer>
+  <key>RunAtLoad</key><true/>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${logPath()}</string>
+  <key>StandardErrorPath</key><string>${logPath()}</string>
+</dict>
+</plist>
+`;
+function macInstall() {
+    mkdirSync(dirname(PLIST_PATH), { recursive: true });
+    writeFileSync(PLIST_PATH, plistBody(), "utf8");
+    const uid = userInfo().uid;
+    // 現代 launchd：bootstrap 進 per-user GUI domain。先 bootout 讓它可重複執行。
+    spawnSync("launchctl", ["bootout", `gui/${uid}`, PLIST_PATH], { stdio: "ignore" });
+    const r = spawnSync("launchctl", ["bootstrap", `gui/${uid}`, PLIST_PATH], {
+        encoding: "utf8",
+    });
+    console.log(`wrote ${PLIST_PATH}`);
+    console.log(`launchctl bootstrap: rc=${r.status} ${(r.stderr ?? "").trim()}`);
+    console.log(`base cadence ${BASE_INTERVAL_SEC}s · RunAtLoad=true · log -> ${logPath()}`);
+    return 0;
+}
+function macUninstall() {
+    const uid = userInfo().uid;
+    spawnSync("launchctl", ["bootout", `gui/${uid}`, PLIST_PATH], { stdio: "ignore" });
+    if (existsSync(PLIST_PATH))
+        rmSync(PLIST_PATH);
+    console.log(`removed ${PLIST_PATH} and unloaded from launchd`);
+    return 0;
+}
+function macStatus() {
+    const uid = userInfo().uid;
+    const r = spawnSync("launchctl", ["print", `gui/${uid}/${LABEL}`], { encoding: "utf8" });
+    if (r.status !== 0) {
+        console.log("bg-task:   NOT installed in launchd");
+        return 1;
+    }
+    for (const line of (r.stdout ?? "").split("\n")) {
+        const s = line.trim();
+        if (/^(state|pid|runs|last exit code) =/.test(s))
+            console.log("  " + s);
+    }
+    console.log(`plist: ${existsSync(PLIST_PATH) ? "present" : "MISSING"}`);
+    return 0;
+}
+// ────────────────────────────── Windows ──────────────────────────────
+// ⚠️ 以下未在真機實測（見 README「已知限制」）。
+/** 隱藏視窗的啟動器：node 沒有 pythonw 那種無 console 的變體，用 VBS 包一層是標準做法。 */
+const VBS_PATH = () => join(stateDir(), "run-hidden.vbs");
+function winInstall() {
+    const vbs = `Set s = CreateObject("Wscript.Shell")\r\n` +
+        `s.Run """${NODE}"" ""${CLI}"" daemon-tick", 0, False\r\n`;
+    writeFileSync(VBS_PATH(), vbs, "utf8");
+    const tr = `wscript.exe //B "${VBS_PATH()}"`;
+    const args = [
+        "/Create", "/TN", WIN_TASK,
+        "/SC", "MINUTE", "/MO", String(Math.max(1, Math.floor(BASE_INTERVAL_SEC / 60))),
+        "/TR", tr,
+        "/RL", "LIMITED", "/F",
+    ];
+    const r = spawnSync("schtasks", args, { encoding: "utf8" });
+    console.log(`wrote ${VBS_PATH()}`);
+    console.log(`schtasks /Create: rc=${r.status} ${(r.stdout ?? r.stderr ?? "").trim()}`);
+    console.log(`uninstall: schtasks /Delete /TN ${WIN_TASK} /F`);
+    console.log("! Windows 路徑尚未在真機驗證過 —— 裝完請跑 claude-usage status 確認有心跳");
+    return r.status ?? 1;
+}
+function winUninstall() {
+    spawnSync("schtasks", ["/Delete", "/TN", WIN_TASK, "/F"], { stdio: "inherit" });
+    if (existsSync(VBS_PATH()))
+        rmSync(VBS_PATH());
+    return 0;
+}
+function winStatus() {
+    const r = spawnSync("schtasks", ["/Query", "/TN", WIN_TASK], { encoding: "utf8" });
+    console.log(r.status === 0 ? (r.stdout ?? "").trim() : "bg-task:   NOT installed (schtasks)");
+    return r.status ?? 1;
+}
+const sessionStartGroups = (s) => s.hooks?.SessionStart ?? [];
+/**
+ * 這條 command 是不是「某個版本的本工具採樣 hook」。
+ *
+ * 比對必須**解析 JSON 之後比對 command 字串**，不能拿 HOOK_CMD 去 substring 比
+ * settings.json 原文：HOOK_CMD 含 `"` 而檔案裡是轉義的 `\"`，永遠比不中 → 誤報
+ * not registered → 害人重跑 install 裝出重複的 hook。這個 bug 真的發生過。
+ */
+function isOurSamplingHook(cmd) {
+    if (!cmd)
+        return false;
+    if (cmd.includes(CLI))
+        return true; // 現行這一份
+    // 歷史版本：Python client（claude-usage 腳本 / poc 的 fetch_usage.py）
+    if (cmd.includes("fetch_usage.py"))
+        return true;
+    if (cmd.includes("claude-usage") && cmd.includes("sample"))
+        return true;
+    return false;
+}
+export function registerHook(argv = []) {
+    const path = claudeSettingsPath();
+    const s = readJson(path) ?? {};
+    s.hooks ??= {};
+    const groups = sessionStartGroups(s);
+    // 先掃掉**所有**舊版採樣 hook 再裝新的。只做「有沒有裝過」的檢查是不夠的：
+    // 從 Python 版升上來時舊 hook 還在，兩個都會在開 session 時各打一次 API。
+    const stale = [];
+    const kept = [];
+    for (const g of groups) {
+        const hooks = (g.hooks ?? []).filter((h) => {
+            const cmd = h.command ?? "";
+            if (cmd !== HOOK_CMD && isOurSamplingHook(cmd)) {
+                stale.push(cmd);
+                return false;
+            }
+            return true;
+        });
+        if (hooks.length)
+            kept.push({ ...g, hooks });
+    }
+    const already = kept.some((g) => (g.hooks ?? []).some((h) => h.command === HOOK_CMD));
+    if (isDry(argv)) {
+        for (const c of stale)
+            console.log(`hook: WOULD remove stale -> ${c.slice(0, 100)}`);
+        console.log(already ? "hook: already registered" : `hook: WOULD add SessionStart -> ${HOOK_CMD}`);
+        return;
+    }
+    if (!already)
+        kept.push({ hooks: [{ type: "command", command: HOOK_CMD, timeout: 12 }] });
+    s.hooks["SessionStart"] = kept;
+    writeJsonAtomic(path, s);
+    for (const c of stale)
+        console.log(`hook: removed stale -> ${c.slice(0, 100)}`);
+    console.log(already ? "hook: already registered" : `hook: registered SessionStart in ${path}`);
+}
+export function unregisterHook() {
+    const path = claudeSettingsPath();
+    const s = readJson(path);
+    if (!s)
+        return;
+    const kept = [];
+    for (const g of sessionStartGroups(s)) {
+        const hooks = (g.hooks ?? []).filter((h) => !isOurSamplingHook(h.command ?? ""));
+        if (hooks.length)
+            kept.push({ ...g, hooks });
+    }
+    s.hooks ??= {};
+    s.hooks["SessionStart"] = kept;
+    writeJsonAtomic(path, s);
+    console.log("hook: removed from settings.json");
+}
+// ──────────────────────────── dispatch ────────────────────────────
+async function enrollStep(argv) {
+    if (existsSync(devicePath())) {
+        console.log("enroll: already enrolled (device.json present)");
+        return;
+    }
+    if (isDry(argv)) {
+        console.log(`enroll: WOULD POST /api/oauth/profile -> ${serverUrl()}/v1/enroll`);
+        return;
+    }
+    try {
+        if ((await enroll(argv)) !== 0)
+            throw new Error("enroll returned non-zero");
+    }
+    catch (e) {
+        console.error(`enroll: FAILED (${e.message}) — hook/背景任務仍會安裝，下次 report 會自動重試`);
+    }
+}
+export async function install(argv = []) {
+    const os = platform();
+    console.log(`claude-usage install (${os})${isDry(argv) ? " [DRY-RUN]" : ""}`);
+    console.log(`  server = ${serverUrl()}   state = ${stateDir()}`);
+    if (!enrollSecret(argv) && !existsSync(devicePath())) {
+        console.log("  ! server 若有設 enroll 密語，請加 --enroll-secret <密語>");
+    }
+    await enrollStep(argv);
+    registerHook(argv);
+    if (isDry(argv)) {
+        console.log("bg-task: WOULD register " +
+            (os === "darwin" ? "launchd" : os === "win32" ? "schtasks" : "systemd (未實作)"));
+        return 0;
+    }
+    if (os === "darwin")
+        return macInstall();
+    if (os === "win32")
+        return winInstall();
+    console.log(`${os}: systemd --user timer 尚未實作`);
+    return 1;
+}
+export function uninstall() {
+    unregisterHook();
+    const os = platform();
+    if (os === "darwin")
+        return macUninstall();
+    if (os === "win32")
+        return winUninstall();
+    return 1;
+}
+export function status() {
+    const os = platform();
+    console.log(`state dir: ${stateDir()}`);
+    console.log(`server:    ${serverUrl()}`);
+    console.log(`enrolled:  ${existsSync(devicePath()) ? "yes" : "no"}`);
+    const s = readJson(claudeSettingsPath()) ?? {};
+    const cmds = sessionStartGroups(s).flatMap((g) => (g.hooks ?? []).map((h) => h.command ?? ""));
+    const ours = cmds.filter((c) => c === HOOK_CMD);
+    const others = cmds.filter((c) => c !== HOOK_CMD && isOurSamplingHook(c));
+    console.log(`hook:      ${ours.length ? "registered" : "not registered"}` +
+        (others.length ? ` (+${others.length} 個其他/過時的採樣 hook)` : ""));
+    for (const c of others)
+        console.log(`           ! 過時或重複: ${c.slice(0, 110)}`);
+    // 「背景任務已註冊且 exit 0」不等於「有資料進來」—— 2026-08-22 的事故就是任務照跑、
+    // log 照寫，但 17.6 小時零快照。所以這裡量測資料本身。
+    const unhealthy = printHealth() !== 0;
+    const rc = os === "darwin" ? macStatus() : os === "win32" ? winStatus() : 1;
+    return rc || (unhealthy ? 1 : 0);
+}

package/dist/paths.js

@@ -0,0 +1,57 @@
+/**
+ * 共用路徑 + 設定。執行期狀態存在使用者家目錄，**不是安裝目錄** —— npm 全域安裝
+ * 目錄可能唯讀、也可能在 `npm update` 時被整個換掉。
+ * Windows 走 %USERPROFILE%\.claude-usage。
+ *
+ * ★ 這裡刻意全部是**函式**而不是模組層常數。Python 版是 `STATE_DIR = os.environ.get(...)`
+ * 在 import 時求值，測試只要在 import 前設環境變數就能改指向；ESM 的 import 會被
+ * 提升，測試沒有「import 之前」可用。做成函式後測試可以隨時 `process.env.
+ * CLAUDE_USAGE_HOME = tmp` 再呼叫 —— 否則每個測試檔都得靠子行程隔離。
+ */
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readJson, writeJsonAtomic } from "./util.js";
+const ensured = new Set();
+export function stateDir() {
+    const d = process.env["CLAUDE_USAGE_HOME"] || join(homedir(), ".claude-usage");
+    if (!ensured.has(d)) {
+        mkdirSync(d, { recursive: true });
+        ensured.add(d);
+    }
+    return d;
+}
+/** 額度快照（本機 append-only JSONL，上報的來源） */
+export const snapPath = () => join(stateDir(), "usage_snapshots.jsonl");
+/** device_id + device_key。**絕不含 Claude token** */
+export const devicePath = () => join(stateDir(), "device.json");
+/** { server_url } */
+export const configPath = () => join(stateDir(), "config.json");
+/** daemon 自身心跳/失敗狀態 */
+export const healthPath = () => join(stateDir(), "health.json");
+/** 上報游標：每個 JSONL 檔讀到第幾個 byte */
+export const cursorPath = () => join(stateDir(), "cursor.json");
+/** daemon 的 stdout/stderr（背景任務寫的） */
+export const logPath = () => join(stateDir(), "daemon.log");
+/** Claude Code 的 OAuth 憑證檔。**唯讀、永不上傳**（且在 mac 上只是過時副本，見 creds.ts） */
+export const credsPath = () => join(homedir(), ".claude", ".credentials.json");
+/** Claude Code 的 session JSONL 根目錄。唯讀 */
+export const projectsDir = () => join(homedir(), ".claude", "projects");
+/** Claude Code 設定（SessionStart hook 註冊在這） */
+export const claudeSettingsPath = () => join(homedir(), ".claude", "settings.json");
+export const DEFAULT_SERVER = "http://127.0.0.1:8787";
+export function config() {
+    return readJson(configPath()) ?? {};
+}
+export function serverUrl() {
+    return config().server_url || DEFAULT_SERVER;
+}
+export function setConfig(patch) {
+    const c = { ...config(), ...patch };
+    for (const k of Object.keys(c)) {
+        if (c[k] === undefined || c[k] === null)
+            delete c[k];
+    }
+    writeJsonAtomic(configPath(), c);
+    return c;
+}

package/dist/upload.js

@@ -0,0 +1,188 @@
+/**
+ * Client uploader — enroll 一次，之後**增量**回報給 ingest server。
+ *
+ * 永不傳送 Claude token；只送身份（來自 profile）與數字。
+ *
+ * 四個設計約束：
+ *
+ * 1. **憑證讀 Keychain**（透過 creds.loadToken）。舊版直接讀 .credentials.json ——
+ *    那是過時的 legacy 副本，實測可過期 17.6 小時而使用者完全無感。
+ *
+ * 2. **游標只在上傳成功（HTTP 200）後才前進**。先存游標再上傳失敗 = 永久丟掉那批
+ *    資料，本機 JSONL 是唯一來源，沒有第二次機會。
+ *
+ * 3. **client 不自報 user_id**。身份由 server 從 device_key 反查。client 自報
+ *    email/org 是已知的偽造漏洞，送得越少越好。
+ *
+ * 4. **沒有新資料時仍送 health-only 心跳**。否則「機器閒置」與「採樣壞掉」在 server
+ *    眼中一模一樣（都是沒有新資料），而後者正是 2026-08-22 靜默 17.6 小時的形狀。
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { platform, release } from "node:os";
+import { authHeaders, loadToken } from "./creds.js";
+import * as events from "./events.js";
+import { devicePath, serverUrl } from "./paths.js";
+import { readJson, writeJsonAtomic } from "./util.js";
+import { VERSION } from "./version.js";
+async function post(path, obj, bearer) {
+    const headers = { "Content-Type": "application/json" };
+    if (bearer)
+        headers["Authorization"] = `Bearer ${bearer}`;
+    try {
+        const r = await fetch(serverUrl() + path, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(obj),
+            signal: AbortSignal.timeout(30_000),
+        });
+        const text = await r.text();
+        let body = {};
+        try {
+            body = text ? JSON.parse(text) : {};
+        }
+        catch {
+            body = { error: text.slice(0, 300) };
+        }
+        return { status: r.status, body };
+    }
+    catch (e) {
+        // status 0 = 根本沒連上（離線 / server 掛了）。與 4xx/5xx 分開，呼叫端才知道
+        // 這是「該重試」還是「該修設定」。
+        return { status: 0, body: { error: `${e.name}: ${e.message}` } };
+    }
+}
+// ─────────────────────────────── enroll ───────────────────────────────
+/**
+ * /api/oauth/profile。token 走 creds.loadToken（Keychain 優先）。
+ *
+ * `organization.seat_tier` 是**組織方案層級**（team_tier_1），Keychain 的
+ * `rateLimitTier` 才是**個人實際額度層級**（default_claude_max_5x）—— 那個才是
+ * utilization% 的分母，做席次判讀要用它。兩個欄位語意不同，別混。
+ */
+async function fetchProfile() {
+    const tok = loadToken();
+    const r = await fetch("https://api.anthropic.com/api/oauth/profile", {
+        headers: authHeaders(tok.token),
+        signal: AbortSignal.timeout(20_000),
+    });
+    if (!r.ok)
+        throw new Error(`/api/oauth/profile -> HTTP ${r.status}`);
+    return { profile: (await r.json()), tok };
+}
+/**
+ * 管理者發的共享密語（server 端 CU_ENROLL_SECRET）。
+ *
+ * **刻意不寫進 config.json。** enroll 是一次性動作，把密語落地在每台機器上只是
+ * 多開一個洩漏面，換不到任何東西 —— 需要重新 enroll 時再問管理者一次即可。
+ */
+export function enrollSecret(argv = []) {
+    const i = argv.indexOf("--enroll-secret");
+    if (i >= 0 && argv[i + 1])
+        return argv[i + 1];
+    return process.env["CLAUDE_USAGE_ENROLL_SECRET"] || null;
+}
+export async function enroll(argv = []) {
+    const { profile, tok } = await fetchProfile();
+    const dev = readJson(devicePath()) ?? {};
+    const deviceId = dev.device_id || randomUUID(); // 隨機，非 hostname（不洩漏人名）
+    const { status, body } = await post("/v1/enroll", {
+        profile,
+        device_id: deviceId,
+        os: platform(),
+        os_version: release(),
+        agent_version: VERSION,
+        install_channel: "npm",
+        enroll_secret: enrollSecret(argv),
+        // client 自動回報個人額度層級 -> 填 users_seat，讓 utilization% 有分母。
+        // source 標明來源；管理端匯出可作為覆寫層（client 自報可偽造）。
+        seat: { seat_tier: tok.tier, subscription: tok.subscription, source: tok.source },
+    });
+    if (status !== 200) {
+        console.error(`enroll failed ${status}: ${JSON.stringify(body)}`);
+        return 1;
+    }
+    writeJsonAtomic(devicePath(), {
+        device_id: body["device_id"],
+        device_key: body["device_key"],
+    });
+    const acct = (profile["account"] ?? {});
+    const org = (profile["organization"] ?? {});
+    console.log(`enrolled: user=${acct["email"]} org=${org["name"]}`);
+    console.log(`  seat_tier=${tok.tier} subscription=${tok.subscription} (creds_from=${tok.source})`);
+    console.log(`  device_id=${body["device_id"]}  device_key stored (no claude token)`);
+    if (body["status"] === "pending") {
+        console.log(`  ! ${body["note"] ?? "待管理者核准後才會收下回報"}`);
+    }
+    return 0;
+}
+/**
+ * full=true 忽略游標整包重送。重送是安全的：BQ 是 append-only + stg view 去重，
+ * 實測 raw 7,203 列而去重 view 穩定在 842 → ingest 可以無腦重試，不需要冪等鍵。
+ */
+export function buildPayload(state, full = false) {
+    const filesCur = full ? {} : state.files;
+    const snapOff = full ? 0 : state.snapshots;
+    const { events: ev, newCursor } = events.extractIncremental(filesCur);
+    const snaps = events.snapshotsIncremental(snapOff);
+    return {
+        payload: {
+            agent_version: VERSION,
+            limit_snapshots: snaps.rows,
+            sessions: events.sessionsFrom(ev),
+            token_events: ev,
+            // health 不走游標：它是**當下狀態**而不是事件流，每次都送最新的一份。
+            health: events.healthPayload(),
+        },
+        newState: { files: newCursor, snapshots: snaps.offset },
+    };
+}
+export async function report(argv = []) {
+    const full = argv.includes("--full");
+    const dry = argv.includes("--dry-run");
+    if (!existsSync(devicePath()) && !dry) {
+        console.error("not enrolled — run: claude-usage enroll");
+        return 1;
+    }
+    const state = events.loadCursor();
+    const { payload, newState } = buildPayload(state, full);
+    const n = {
+        limit_snapshots: payload.limit_snapshots.length,
+        sessions: payload.sessions.length,
+        token_events: payload.token_events.length,
+    };
+    const hasHealth = payload.health !== null;
+    if (dry) {
+        console.log(`[dry-run] would send: ${JSON.stringify(n)}  health=${hasHealth ? "yes" : "no"}  (full=${full})`);
+        console.log(`[dry-run] cursor would advance: snapshots ${state.snapshots}->${newState.snapshots}, ` +
+            `files tracked ${Object.keys(newState.files).length}`);
+        return 0;
+    }
+    const anyRows = n.limit_snapshots + n.sessions + n.token_events > 0;
+    // 沒有新事件時**仍然回報**（health-only 心跳）。舊版在這裡直接 return，於是
+    // 「機器閒置」與「採樣壞掉」在 server 眼中完全一樣。
+    if (!anyRows && !hasHealth) {
+        console.log("nothing to report (no new data, no health file)");
+        return 0;
+    }
+    const dev = readJson(devicePath());
+    if (!dev?.device_key) {
+        console.error("device.json 不完整 — 請重跑 claude-usage enroll");
+        return 1;
+    }
+    payload.device_id = dev.device_id;
+    const { status, body } = await post("/v1/report", payload, dev.device_key);
+    const kind = anyRows ? "report" : "heartbeat";
+    console.log(`${kind} -> ${status}: ${JSON.stringify(body)}`);
+    console.log(`  sent: ${n.limit_snapshots} snapshots, ${n.sessions} sessions, ` +
+        `${n.token_events} token_events, health=${hasHealth ? "yes" : "no"}`);
+    if (status !== 200) {
+        console.error("  cursor NOT advanced — will retry the same batch next run");
+        return 1;
+    }
+    // 只有這裡才前進游標。順序很重要：上傳成功 -> 存游標。
+    events.saveCursor(newState);
+    console.log(`  cursor advanced (snapshots@${newState.snapshots}, ` +
+        `${Object.keys(newState.files).length} files tracked)`);
+    return 0;
+}

package/dist/usage.js

@@ -0,0 +1,112 @@
+/**
+ * 採一筆官方額度快照：GET /api/oauth/usage，寫進 ~/.claude-usage/usage_snapshots.jsonl。
+ *
+ * 這個數字是**帳號全域**的（天然含 claude.ai 網頁 chat），與 token_events 是兩個
+ * 獨立指標，不可相加。
+ *
+ * SECURITY：token 用於認證，**永不列印、永不寫入快照**。寫進檔案的只有數字。
+ */
+import { appendFileSync } from "node:fs";
+import { CuError, EXIT, authHeaders, loadToken } from "./creds.js";
+import { lastSnapshot } from "./health.js";
+import { snapPath } from "./paths.js";
+import { nowIso, parseIso } from "./util.js";
+const URL_USAGE = "https://api.anthropic.com/api/oauth/usage";
+/** hook 模式下，距上一筆快照未滿這麼多分鐘就跳過（開 session 不該每次都打 API） */
+export const DEBOUNCE_MIN = 10;
+/** hook 模式：距上一筆太近就跳過 */
+export function debounced() {
+    const snap = lastSnapshot();
+    const t = parseIso(snap?.["collected_at"]);
+    if (!t)
+        return false;
+    return Date.now() - t.getTime() < DEBOUNCE_MIN * 60_000;
+}
+async function fetchUsage(token) {
+    let r;
+    try {
+        r = await fetch(URL_USAGE, {
+            method: "GET",
+            headers: { ...authHeaders(token), "User-Agent": "claude-usage/0.3" },
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (e) {
+        throw new CuError(`network error: ${e.message}`, EXIT.NETWORK);
+    }
+    const headers = {};
+    r.headers.forEach((v, k) => {
+        headers[k] = v;
+    });
+    return { status: r.status, headers, body: await r.text() };
+}
+/**
+ * 採樣一次。回傳可區分的結束碼（daemon 靠它把失敗原因分開記錄）：
+ *   0=ok 2=token_expired 3=no_token 4=http_error 5=network_error
+ *
+ * hook 模式（開 session 時觸發）**一律回 0 且安靜** —— 採集用量絕不該擋住或拖慢
+ * 使用者開 session。
+ */
+export async function sample(opts = {}) {
+    const hook = opts.hook === true;
+    const fail = (code, message) => ({
+        code: hook ? EXIT.OK : code,
+        status: null,
+        message,
+    });
+    if (hook && debounced())
+        return { code: EXIT.OK, status: null, message: "debounced" };
+    let tok;
+    try {
+        tok = loadToken();
+    }
+    catch (e) {
+        const err = e;
+        return fail(err.code ?? EXIT.NO_TOKEN, err.message);
+    }
+    let res;
+    try {
+        res = await fetchUsage(tok.token);
+    }
+    catch (e) {
+        const err = e;
+        return fail(err.code ?? EXIT.NETWORK, err.message);
+    }
+    if (res.status !== 200) {
+        return {
+            ...fail(EXIT.HTTP, `endpoint returned ${res.status}: ${res.body.slice(0, 200)}`),
+            status: res.status,
+        };
+    }
+    let data;
+    try {
+        data = JSON.parse(res.body);
+    }
+    catch {
+        return fail(EXIT.HTTP, "response was not JSON");
+    }
+    // 回應 headers 也帶即時的統一額度資訊，一併留存（不含任何機密）
+    const rl = {};
+    for (const [k, v] of Object.entries(res.headers)) {
+        if (k.toLowerCase().startsWith("anthropic-ratelimit"))
+            rl[k] = v;
+    }
+    const snap = {
+        collected_at: nowIso(),
+        http_status: res.status,
+        subscription: tok.subscription, // 例 "team"
+        tier: tok.tier, // 例 "default_claude_max_5x" -- utilization% 的分母
+        cred_source: tok.source, // keychain | file -- 資料裡要看得出讀了哪個儲存
+        usage: data, // 官方數字，無機密
+        ratelimit_headers: rl,
+    };
+    appendFileSync(snapPath(), JSON.stringify(snap) + "\n", "utf8");
+    const u = (data ?? {});
+    const fh = (u["five_hour"] ?? {});
+    const sd = (u["seven_day"] ?? {});
+    return {
+        code: EXIT.OK,
+        status: res.status,
+        message: `5h=${fh["utilization"]}% week=${sd["utilization"]}% (creds_from=${tok.source})`,
+    };
+}