@tsa-group/claude-usage 0.3.0

package/README.md

@@ -0,0 +1,216 @@
+# @tsa-group/claude-usage
+
+每人 Claude 用量的本地採集工具。在你的機器上就地量測 **Claude Code 的 token 明細** 與
+**帳號層級的額度水位（5 小時 / 每週 %，含 Claude 網頁 chat）**，在背景非同步回報到你們自己的
+ingest server，彙整成團隊用量儀表。
+
+> 需要一台**相容的 ingest server**（見下方「回報協定」）。這個套件只是 client。
+
+---
+
+## 🔒 隱私（請先看這段）
+
+**送出去的**
+- 你的 Claude 帳號 email / uuid / 組織 uuid（來自 `/api/oauth/profile`，用於識別是誰）
+- 用量數字：per-message 的 token 計數、session 維度、5 小時 / 每週額度百分比
+- client 自身的健康狀態（上次成功採樣時間、連續失敗次數等）
+
+**永遠不送、也永遠不離開這台機器**
+- ❌ 你的 Claude OAuth token
+- ❌ 任何 prompt / 回應 / 對話內容
+- ❌ 原始檔案路徑 —— 專案路徑只送 `SHA256(cwd)` 的前 16 碼
+
+原始碼很短，`src/events.ts` 就是「哪些欄位會被送出去」的唯一權威來源，可以自己讀過再裝。
+
+---
+
+## 需求
+
+- **Node.js >= 20**
+- **Claude Code** 已登入（工具讀它的憑證來認證，見上方隱私說明）
+- macOS：完整支援並實測
+- Windows：程式路徑已備妥但**尚未在真機驗證**（見「已知限制」）
+- Linux：背景任務（systemd timer）未實作，其餘指令可用
+
+---
+
+## 安裝（3 步）
+
+```bash
+npm i -g @tsa-group/claude-usage
+
+# 1) 指向你們的 ingest server
+claude-usage configure --server https://<你們的 ingest host>
+
+# 2) 一鍵安裝：enroll（取得身份）+ 註冊 SessionStart hook + 背景任務
+#    先加 --dry-run 可預覽會做什麼、不動任何系統設定
+claude-usage install --dry-run
+claude-usage install --enroll-secret <管理者給你的密語>
+
+# 3) 確認狀態
+claude-usage status
+```
+
+安裝後會發生：
+
+- **hook**（開 session 時）：抓一筆即時額度快照。註冊在 `~/.claude/settings.json` 的
+  `SessionStart`，**fire-and-forget、失敗永遠安靜、10 分鐘去抖動** —— 採集用量絕不該擋住或
+  拖慢你開 session。
+- **背景任務**（macOS launchd / Windows 工作排程器）：每 5 分鐘喚醒一次，**自我判斷**是否要
+  採樣，並非同步上傳。採樣間隔自適應：有在用 15 分鐘、閒置退避到 60 分鐘。
+- 升級（`npm update -g @tsa-group/claude-usage`）後**請重跑一次 `claude-usage install`**：
+  背景任務與 hook 記的是絕對路徑，換了 Node 版本或安裝位置就要重新註冊。
+
+---
+
+## 平常怎麼看自己的用量
+
+```bash
+claude-usage show              # 目前額度水位（含 Anthropic 自己判定的 severity 燈號）
+claude-usage show --history    # 快照時間序
+claude-usage sessions          # session / token 明細
+claude-usage sessions --json   # 同上，機器可讀
+```
+
+```
+採集 08-24 16:58 (13m ago)  訂閱=team  tier=default_claude_max_5x  creds=keychain
+
+  5 小時窗         3%  🟢 normal   reset in 3h 8m
+  每週(全)        27%  🟢 normal   reset in 17h 48m
+  每週(單模型)     8%  🟢 normal   reset in 17h 48m  [Fable]
+```
+
+三個數字**不是同一件事**：
+
+- **5 小時窗 / 每週(全)** 是**帳號全域**的額度水位，天然包含 claude.ai 網頁 chat。
+- **每週(單模型)** 是 per-model 的週上限，回答「我的週額度是不是被單一模型吃掉的」。
+- `sessions` 的 token 數**只含 Claude Code**，與上面兩個是獨立指標，不可相加。
+
+`severity`（🟢 normal / 🟡 warning / 🔴 critical）是 **Anthropic 自己的判定**，門檻未公開，
+所以照抄不自己算。
+
+---
+
+## 移除
+
+```bash
+claude-usage uninstall     # 移除 hook 與背景任務
+npm rm -g @tsa-group/claude-usage
+```
+
+本機資料（`~/.claude-usage/`）不會被自動刪除，要清就自己刪那個目錄。
+
+---
+
+## 指令一覽
+
+| 指令 | 用途 |
+|---|---|
+| `configure --server <url>` | 設定 ingest server 位址 |
+| `install [--enroll-secret <s>] [--dry-run]` | enroll + hook + 背景任務 |
+| `status` | 裝好了嗎？**採樣真的有在動嗎？** |
+| `uninstall` | 移除 hook 與背景任務 |
+| `show [--history]` | 看自己的額度水位 / 時間序 |
+| `sessions [--json]` | session 與 token 明細 |
+| `sample [--hook]` | 手動抓一筆額度快照 |
+| `daemon-tick [--explain]` | 背景排程器呼叫的單元；`--explain` 只印決策不採樣 |
+| `enroll [--enroll-secret <s>]` | 手動與 server 溝通取得身份 |
+| `report [--full] [--dry-run]` | 手動上報。`--full` 忽略游標整包重送（重送是安全的） |
+| `health` | 背景任務心跳；不健康時 **exit 1**（可接監控） |
+
+`--enroll-secret` **刻意不寫進設定檔**：enroll 是一次性動作，把密語落地在每台機器上只是
+多開一個洩漏面。也可用環境變數 `CLAUDE_USAGE_ENROLL_SECRET`。
+
+---
+
+## 資料存哪
+
+| 路徑 | 內容 |
+|---|---|
+| `~/.claude-usage/config.json` | server URL 等設定 |
+| `~/.claude-usage/device.json` | device_id + device_key（**不含** Claude token） |
+| `~/.claude-usage/usage_snapshots.jsonl` | 本地額度快照 |
+| `~/.claude-usage/cursor.json` | 上報游標（每個 JSONL 檔讀到第幾個 byte） |
+| `~/.claude-usage/health.json` | 背景任務心跳 |
+| `~/.claude-usage/daemon.log` | 背景任務輸出 |
+| `~/.claude/projects/**/*.jsonl` | Claude Code 原生資料（本工具**唯讀**） |
+
+`CLAUDE_USAGE_HOME` 可覆寫狀態目錄位置。
+
+---
+
+## 「裝好了」不等於「有資料進來」
+
+```bash
+claude-usage status    # 不健康時 exit 1
+```
+
+這個工具吃過一次虧，所以特別強調：曾經發生過 token 過期後背景任務**每 5 分鐘照跑、
+log 照寫、作業系統顯示 `runs=556 / last exit code=0`**，但 **17.6 小時一筆快照都沒進來**，
+而使用者完全無感（Claude Code 好得很 —— 它把憑證留在記憶體，不會把刷新後的 token 寫回
+磁碟上的副本）。
+
+**「背景任務已註冊且 exit 0」不能當成「有資料進來」的代理指標，必須量測資料本身。**
+所以 `status` / `health` 看的是「上次**成功採樣**是什麼時候」，而且 client 就算沒有新資料
+也會定期送心跳 —— 否則「機器閒置」與「採樣壞掉」在 server 眼中長得一模一樣。
+
+採樣壞掉時會告訴你原因，常見的是：
+
+```
+status : UNHEALTHY - 已 8.3 小時沒有成功採樣（最後成功 2026-08-22T...）
+         -> access token EXPIRED 5.2h ago — run /login in Claude Code
+```
+
+處置就是在 Claude Code 裡跑 `/login`。工具**刻意不自動 refresh token**：refresh token 若是
+一次性輪替，我們換掉會讓 Claude Code 拿舊的失敗、可能把你登出。這個風險不值得為了背景
+採樣承擔。
+
+---
+
+## 回報協定（給要自建 server 的人）
+
+Client 對 server 只用兩個端點，皆為 `application/json`：
+
+- `POST /v1/enroll` — 送 `{ profile, device_id, os, agent_version, enroll_secret, seat }`，
+  取回 `{ device_id, device_key }`。**token 不上傳**，server 應驗證 `profile.organization.uuid`。
+- `POST /v1/report` — Header `Authorization: Bearer <device_key>`，送
+  `{ agent_version, limit_snapshots[], sessions[], token_events[], health{} }`。
+
+三個 client 端的性質，server 端設計時可以依賴：
+
+1. **上報是增量的**，以 per-file byte offset 游標推進，且**游標只在 HTTP 200 之後才前進** ——
+   非 200 會重送同一批。
+2. **重送必須是安全的。** client 端只在單一批次內去重，跨批次去重是 server 的責任。
+   建議 append-only + 去重 view（去重鍵是 `(message_id, request_id)` 複合鍵，單用
+   `message_id` 會漏掉重試產生的重複）。
+3. **沒有新資料時仍會送 health-only 心跳**，`limit_snapshots` / `sessions` / `token_events`
+   皆為空陣列。
+
+欄位語意見 `src/events.ts` —— 那是本機資料到 wire schema 的唯一權威映射層。
+
+---
+
+## 已知限制
+
+- **非官方 endpoint**：額度 % 來自 Claude Code 內部的 `/api/oauth/usage`，Anthropic 可能變更。
+- **Windows 未實機驗證**：憑證改讀檔案版（mac 走 Keychain）、背景任務用 schtasks +
+  VBS 隱藏視窗啟動器。程式路徑都在，但沒有在真的 Windows 上跑過。裝完請用
+  `claude-usage status` 確認有心跳。
+- **Linux 背景任務未實作**（systemd --user timer）。其餘指令可用。
+- **`session_id` 跨 compaction / resume 不穩定**：session **數**會高估。token 與成本不受影響
+  （那是 per-event 去重的，與 session 身份無關）。
+- **enroll 是 client 自報身份**：可偽造 email / org，共享密語擋得住路過的人，擋不住內部人。
+  要真正的身份保證需要 server 端接 SSO 或人工核准流程。
+
+---
+
+## 開發
+
+```bash
+npm install
+npm test          # node:test，零執行期依賴
+npm run build     # tsc -> dist/
+```
+
+client 端**沒有任何執行期依賴**是刻意的：這東西裝在別人的機器上，每一個 dependency 都是
+一個他們沒同意過的信任關係。

package/dist/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * claude-usage — per-user Claude usage collector.
+ *
+ * 隱私：只送用量數字 + 你的 Claude 帳號 email/uuid。你的 OAuth token 與所有
+ * prompt / 回應內容**永遠不離開這台機器**。
+ */
+import { printHealth, tick } from "./daemon.js";
+import { install, status, uninstall } from "./install.js";
+import { DEFAULT_SERVER, configPath, setConfig } from "./paths.js";
+import { enroll, report } from "./upload.js";
+import { sample } from "./usage.js";
+import { showHistory, showLatest, showSessions } from "./view.js";
+import { VERSION } from "./version.js";
+const HELP = `claude-usage v${VERSION} — per-user Claude usage collector
+
+安裝（3 步）
+  claude-usage configure --server https://<ingest host>
+  claude-usage install [--enroll-secret <密語>] [--dry-run]
+  claude-usage status
+
+平常（多半是自動的）
+  show [--history]        看自己的額度水位 / 時間序
+  sessions [--json]       session 與 token 明細
+  sample [--hook]         手動抓一筆額度快照
+  daemon-tick [--explain] 背景排程器呼叫的單元（採樣 + 上傳）
+  enroll [--enroll-secret <密語>]
+  report [--full] [--dry-run]
+  health                  背景任務心跳；不健康時 exit 1
+  uninstall               移除 hook 與背景任務
+
+隱私：Claude OAuth token 與 prompt/回應內容永不離開本機。只送數字與帳號 email/uuid。`;
+function configure(argv) {
+    const i = argv.indexOf("--server");
+    const server = i >= 0 ? argv[i + 1] : undefined;
+    if (i >= 0 && !server) {
+        console.error("--server 後面要接位址，例如 --server https://ingest.example.com");
+        return 2;
+    }
+    const c = setConfig(server ? { server_url: server } : {});
+    console.log(`config -> ${configPath()}`);
+    console.log(`  server_url = ${c.server_url ?? DEFAULT_SERVER}`);
+    return 0;
+}
+async function main() {
+    const [cmd = "", ...argv] = process.argv.slice(2);
+    switch (cmd) {
+        case "":
+        case "-h":
+        case "--help":
+        case "help":
+            console.log(HELP);
+            return 0;
+        case "-v":
+        case "--version":
+        case "version":
+            console.log(VERSION);
+            return 0;
+        case "configure":
+            return configure(argv);
+        case "install":
+            return await install(argv);
+        case "uninstall":
+            return uninstall();
+        case "status":
+            return status();
+        case "sample": {
+            const hook = argv.includes("--hook");
+            const r = await sample({ hook });
+            // hook 模式一律安靜且 exit 0 —— 採集用量絕不該擋住或拖慢開 session。
+            if (hook)
+                return 0;
+            console[r.code === 0 ? "log" : "error"](r.code === 0 ? `sampled: ${r.message}` : `sample failed (${r.code}): ${r.message}`);
+            return r.code;
+        }
+        case "daemon-tick":
+            await tick({ explain: argv.includes("--explain") });
+            return 0;
+        case "health":
+            return printHealth();
+        case "enroll":
+            return await enroll(argv);
+        case "report":
+            return await report(argv);
+        case "show":
+            return argv.includes("--history") ? showHistory() : showLatest();
+        case "sessions":
+            return showSessions(argv);
+        default:
+            console.error(`unknown command: ${cmd}\n`);
+            console.error(HELP);
+            return 2;
+    }
+}
+main()
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((e) => {
+    // 未預期的錯誤要**大聲**，但 server 位址錯這類常見狀況已經在各指令裡處理過了。
+    const err = e;
+    console.error(`claude-usage: ${err.name ?? "Error"}: ${err.message}`);
+    process.exitCode = typeof err.code === "number" ? err.code : 1;
+});

package/dist/creds.js

@@ -0,0 +1,103 @@
+/**
+ * Claude Code OAuth 憑證讀取。
+ *
+ * ★ mac 上**主儲存是 Keychain**，`~/.claude/.credentials.json` 只是過時副本。
+ * 實測 2026-08-23：檔案版過期 17.6 小時而使用者完全無感（Claude Code 好得很 ——
+ * 它把憑證留在記憶體、不會把刷新後的 token 寫回那個檔），Keychain 版有效 +5.2h，
+ * 且**額外帶 subscriptionType / rateLimitTier**（檔案版沒有）。同一個資料源錯誤
+ * 同時造成了「daemon 靜默死亡」與「拿不到 seat_tier」兩個問題。
+ *
+ * SECURITY：token 只用於認證，**永不列印、永不寫入快照、永不上傳**。
+ */
+import { spawnSync } from "node:child_process";
+import { userInfo } from "node:os";
+import { credsPath } from "./paths.js";
+import { readJson } from "./util.js";
+/** 可區分的結束碼 —— daemon 靠這個把「token 過期」和「網路壞掉」分開記錄。
+ *  過去兩者都是 exit 1，daemon 只能寫 sample-failed，於是 2026-08-22 那次
+ *  token 過期靜默死了 17.6 小時沒人發現。 */
+export const EXIT = {
+    OK: 0,
+    TOKEN_EXPIRED: 2,
+    NO_TOKEN: 3,
+    HTTP: 4,
+    NETWORK: 5,
+};
+export class CuError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "CuError";
+    }
+}
+const KEYCHAIN_SERVICE = "Claude Code-credentials";
+function fromKeychain() {
+    if (process.platform !== "darwin")
+        return [null, "not-macos"];
+    let r;
+    try {
+        r = spawnSync("security", ["find-generic-password", "-w", "-s", KEYCHAIN_SERVICE, "-a", userInfo().username], { encoding: "utf8", timeout: 10_000 });
+    }
+    catch (e) {
+        return [null, `keychain-error:${e.name}`];
+    }
+    if (r.status !== 0 || !r.stdout?.trim()) {
+        // rc 語意取自 Claude Code 自身實作（bin/claude 字串表）：
+        //   44 = item 不存在（沒登入過，或帳號名不符）→ 要 /login
+        //   36 = keychain 被鎖住 → 要解鎖，**不是**重新登入
+        // 兩者處置完全不同，必須分開記錄。
+        const by = { 44: "keychain-no-item", 36: "keychain-locked" };
+        return [null, by[r.status ?? -1] ?? `keychain-rc${r.status}`];
+    }
+    try {
+        return [(JSON.parse(r.stdout).claudeAiOauth ?? {}), "keychain"];
+    }
+    catch {
+        return [null, "keychain-not-json"];
+    }
+}
+function fromFile() {
+    const o = readJson(credsPath());
+    if (!o)
+        return [null, "file-error:unreadable"];
+    return [(o.claudeAiOauth ?? {}), "file"];
+}
+/**
+ * 讀 access token。**刻意不做 refresh**：refresh token 若是一次性輪替，我們換完之後
+ * Claude Code 拿舊的去用會失敗，可能把使用者登出。這個風險不值得為了背景採樣承擔
+ * —— 過期就大聲回報，讓使用者自己 /login。
+ */
+export function loadToken() {
+    let [o, source] = fromKeychain();
+    if (!o?.accessToken) {
+        const kcWhy = source;
+        [o, source] = fromFile();
+        if (!o?.accessToken) {
+            const hint = kcWhy === "keychain-locked"
+                ? " -> 解鎖 login keychain（不是重新登入）"
+                : kcWhy === "keychain-no-item"
+                    ? " -> 在 Claude Code 跑 /login"
+                    : "";
+            throw new CuError(`cannot read credentials (keychain: ${kcWhy}; file: ${source})${hint}`, EXIT.NO_TOKEN);
+        }
+    }
+    if (o.expiresAt && Date.now() >= o.expiresAt) {
+        const hrs = (Date.now() - o.expiresAt) / 3_600_000;
+        throw new CuError(`access token EXPIRED ${hrs.toFixed(1)}h ago — run /login in Claude Code ` +
+            `(Claude Code 不會把刷新後的 token 寫回這個檔案)`, EXIT.TOKEN_EXPIRED);
+    }
+    return {
+        token: o.accessToken,
+        subscription: o.subscriptionType ?? null,
+        tier: o.rateLimitTier ?? null,
+        source,
+    };
+}
+/** 打 Anthropic OAuth API 用的共同 headers。token 只出現在這裡。 */
+export const authHeaders = (token) => ({
+    Authorization: `Bearer ${token}`,
+    "anthropic-beta": "oauth-2025-04-20",
+    "anthropic-version": "2023-06-01",
+    Accept: "application/json",
+});

package/dist/daemon.js

@@ -0,0 +1,217 @@
+/**
+ * Daemon — 自適應背景採樣 + 上傳 + 自我健康判斷。
+ *
+ * 設計：作業系統排程器（launchd / schtasks / systemd）以**固定基礎頻率**呼叫
+ * tick()，由 tick() 自己決定這一輪要不要真的採樣。自適應間隔因此活在**一個
+ * 跨平台函式**裡，不需要常駐行程，也不需要在三個排程器上各實作一次間隔邏輯。
+ */
+import { statSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { EXIT } from "./creds.js";
+import { healthWarning, lastSnapshot, loadHealth, saveHealth, } from "./health.js";
+import { devicePath, projectsDir } from "./paths.js";
+import { report } from "./upload.js";
+import { sample } from "./usage.js";
+import { nowIso, parseIso } from "./util.js";
+// ── 自適應策略 ──
+/** 多少分鐘內有 JSONL 被動過就算「使用中」 */
+export const ACTIVE_WINDOW_MIN = 30;
+/** 使用中的採樣節奏 */
+export const INTERVAL_ACTIVE = 15;
+/** 閒置時的採樣節奏 */
+export const INTERVAL_IDLE = 60;
+/** 窗剛 reset 後補一筆的寬限期 */
+export const RESET_GRACE_MIN = 3;
+/** 排程器的基礎頻率（秒） */
+export const BASE_TICK_SEC = 300;
+/**
+ * Pre-reset 對時採樣。窗內 utilization 單調遞增、到 reset 才歸零，所以
+ * **reset 前最後一筆約等於該窗真實峰值** —— 峰值偵測靠「對時」而不是高頻採樣。
+ *
+ * 必須 > BASE_TICK_SEC/60（=5），否則排程抖動時可能沒有任何一個 tick 落在窗內。
+ * 實測動機：舊版只在 reset **之後**補一筆（拿到新窗的低值，方向剛好錯），9 個 5h
+ * 窗有 3 個最後一筆距 reset 超過 60 分鐘，峰值沒抓到。
+ */
+export const PRERESET_MIN = 8;
+/** 距最近一次 JSONL 修改幾分鐘（Claude 活動訊號）。沒有任何檔案時回 null。 */
+export function lastActivityMin() {
+    let newest = 0;
+    const walk = (dir, depth) => {
+        if (depth > 3)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = join(dir, e.name);
+            if (e.isDirectory())
+                walk(p, depth + 1);
+            else if (e.isFile() && e.name.endsWith(".jsonl")) {
+                try {
+                    newest = Math.max(newest, statSync(p).mtimeMs);
+                }
+                catch {
+                    // 檔案在走訪途中被換掉是正常的
+                }
+            }
+        }
+    };
+    walk(projectsDir(), 0);
+    if (!newest)
+        return null;
+    return (Date.now() - newest) / 60_000;
+}
+/**
+ * 已知窗即將 reset 且我們還沒在 pre-reset 窗內採過樣 -> 強制採一筆。
+ * 5h 與 weekly 都要檢查：weekly 是升降級判斷的主要訊號。
+ */
+function preresetDue(snap, snapT) {
+    const usage = (snap["usage"] ?? {});
+    for (const [label, key] of [
+        ["5h", "five_hour"],
+        ["weekly", "seven_day"],
+    ]) {
+        const w = (usage[key] ?? {});
+        const reset = parseIso(w["resets_at"]);
+        if (!reset)
+            continue;
+        const minsUntil = (reset.getTime() - Date.now()) / 60_000;
+        if (minsUntil > 0 &&
+            minsUntil <= PRERESET_MIN &&
+            snapT.getTime() < reset.getTime() - PRERESET_MIN * 60_000) {
+            return `${label} 窗 ${minsUntil.toFixed(1)}m 後 reset — 搶在歸零前抓峰值`;
+        }
+    }
+    return null;
+}
+export function decide() {
+    const act = lastActivityMin();
+    const active = act !== null && act <= ACTIVE_WINDOW_MIN;
+    const interval = active ? INTERVAL_ACTIVE : INTERVAL_IDLE;
+    const snap = lastSnapshot();
+    if (snap === null)
+        return { should: true, reason: "no prior snapshot", interval };
+    const snapT = parseIso(snap["collected_at"]);
+    if (snapT === null)
+        return { should: true, reason: "last snapshot unparseable", interval };
+    const ageMin = (Date.now() - snapT.getTime()) / 60_000;
+    // 1. 最高優先：搶在 reset 前抓峰值（否則該窗峰值永久遺失）
+    const pre = preresetDue(snap, snapT);
+    if (pre)
+        return { should: true, reason: pre, interval };
+    // 2. reset 剛過 -> 補一筆確認窗邊界（對峰值無用，但便宜且能對齊窗）
+    const usage = (snap["usage"] ?? {});
+    const fh = (usage["five_hour"] ?? {});
+    const reset = parseIso(fh["resets_at"]);
+    if (reset) {
+        const passedMin = (Date.now() - reset.getTime()) / 60_000;
+        if (passedMin >= 0 && passedMin <= RESET_GRACE_MIN && snapT.getTime() < reset.getTime()) {
+            return {
+                should: true,
+                reason: `5h window reset ${passedMin.toFixed(1)}m ago — capture the drop`,
+                interval,
+            };
+        }
+    }
+    // 3. 一般節奏
+    if (ageMin >= interval) {
+        return {
+            should: true,
+            reason: `${active ? "active" : "idle"}: last snap ${ageMin.toFixed(0)}m ago >= ${interval}m cadence`,
+            interval,
+        };
+    }
+    return {
+        should: false,
+        reason: `debounced: last snap ${ageMin.toFixed(0)}m ago < ${interval}m cadence`,
+        interval,
+    };
+}
+/**
+ * Best-effort 把本機資料推給 ingest server。任何失敗（離線、未 enroll、server 掛掉）
+ * 都只記錄不拋出 —— daemon 絕不能因為上傳失敗就整個死掉。
+ */
+async function flushUploads() {
+    if (!existsSync(devicePath()))
+        return "not-enrolled";
+    try {
+        return (await report([])) === 0 ? "uploaded" : "upload-failed";
+    }
+    catch {
+        return "upload-error";
+    }
+}
+export async function tick(opts = {}) {
+    const explain = opts.explain === true;
+    const { should, reason, interval } = decide();
+    const act = lastActivityMin();
+    const actS = act === null ? "-" : `${act.toFixed(0)}m`;
+    const ts = new Date().toLocaleTimeString();
+    const h = loadHealth();
+    h.last_tick_at = nowIso();
+    h.ticks = (h.ticks ?? 0) + 1;
+    let action;
+    if (should && !explain) {
+        const res = await sample();
+        const status = res.code === EXIT.OK ? "ok" : ({ 2: "token_expired", 3: "no_token", 4: "http_error", 5: "network_error" }[res.code] ??
+            `unknown_exit_${res.code}`);
+        h.last_sample_at = nowIso();
+        h.last_sample_status = status;
+        // 只在失敗時記 last_error —— 成功時也把訊息存進去，會讓 health 顯示
+        // 「錯誤: 5h=8%」這種自相矛盾的內容。
+        h.last_error = status === "ok" ? null : res.message.slice(0, 200);
+        if (status === "ok") {
+            h.last_ok_at = nowIso();
+            h.consecutive_failures = 0;
+            delete h.first_failure_at;
+            delete h.last_ok_at_backfilled; // 有真的成功紀錄了，回填標記該退場
+        }
+        else {
+            h.consecutive_failures = (h.consecutive_failures ?? 0) + 1;
+            h.first_failure_at ??= nowIso();
+        }
+        action = status === "ok" ? "SAMPLED" : `FAILED:${status}`;
+    }
+    else {
+        action = should && explain ? "would-sample" : "skip";
+    }
+    const upload = explain ? "(skipped)" : await flushUploads();
+    h.last_upload_state = upload;
+    const warn = healthWarning(h);
+    h.unhealthy = Boolean(warn);
+    h.warning = warn;
+    if (!explain)
+        saveHealth(h);
+    console.log(`[${ts}] activity=${actS} cadence=${interval}m -> ${action.padEnd(22)} ` +
+        `upload=${upload}  . ${reason}`);
+    if (warn) {
+        // 前綴固定，方便 grep daemon.log 或讓 status 指令抓
+        console.error(`[${ts}] UNHEALTHY: ${warn}`);
+    }
+    return should;
+}
+/** `claude-usage status` 與 `daemon --health` 共用。不健康時回 1。 */
+export function printHealth() {
+    const h = loadHealth();
+    if (Object.keys(h).length === 0) {
+        console.log("no health data yet (daemon has never ticked)");
+        return 1;
+    }
+    const warn = healthWarning(h);
+    const row = (k, v) => console.log(`  ${k.padEnd(20)}: ${v ?? "-"}`);
+    row("last_tick_at", h.last_tick_at);
+    row("last_sample_at", h.last_sample_at);
+    row("last_sample_status", h.last_sample_status);
+    row("last_ok_at", h.last_ok_at + (h.last_ok_at_backfilled ? "  (從既有快照回填，非真的成功紀錄)" : ""));
+    row("consecutive_failures", h.consecutive_failures ?? 0);
+    row("last_upload_state", h.last_upload_state);
+    if (h.last_error)
+        row("last_error", h.last_error);
+    row("status", warn ? `UNHEALTHY - ${warn}` : "ok");
+    return warn ? 1 : 0;
+}