@tsa-group/claude-usage 0.4.5 → 0.4.7

package/README.md

@@ -332,6 +332,21 @@ Client 對 server 只用兩個端點，皆為 `application/json`：
 
 ---
 
+## 自動更新
+
+v0.4.7 起支援自我更新，但**由伺服器決定**，不是去問 npm：
+
+- 版本資訊搭 `/v1/report` 的回應回來，**零額外網路呼叫**（daemon 每 5 分鐘一次，
+  若各自去問 npm registry 會變成每台每天 288 次）
+- 伺服器指定**確切版本號**，不是 `@latest` —— 有人拿到 npm token 亂發版本也裝不進來
+- 只在**沒有採樣**的那一輪執行，不拖慢本業
+- 24 小時內同一個目標版本只試一次；**不跨 major**
+- npm 全域目錄不可寫（node 裝在系統目錄）時不嘗試，改在 `doctor` 提示人工升級
+
+想關掉：設環境變數 `CU_NO_AUTOUPDATE=1`。
+
+`status` 與 `doctor` 都會顯示是否有新版，用的是上次回報快取的結果，不另外打網路。
+
 ## 已知限制
 
 - **非官方 endpoint**：額度 % 來自 Claude Code 內部的 `/api/oauth/usage`，Anthropic 可能變更。
@@ -340,8 +355,13 @@ Client 對 server 只用兩個端點，皆為 `application/json`：
   `oauth:tokenCacheV2`，以 Chromium 的 `v10` 方案（DPAPI + AES-256-GCM）加密。
   這是**未公開的內部格式**，Anthropic 改版就可能失效 —— 與 `/api/oauth/usage` 同一個
   風險類別。失效時會在 `claude-usage doctor` 顯示卡在哪一步，不會靜默。
-- **Windows 背景任務未完整實機驗證**：schtasks + VBS 隱藏視窗啟動器。裝完請用
-  `claude-usage status` 確認有心跳。
+- **Windows 筆電請確認電源設定**：`schtasks` 建立的工作預設「只在接上電源時執行」、
+  「拔電就中斷」、且「錯過的排程不補跑」。v0.4.6 起 `install` 會自動放寬這三項並讀回
+  驗證；**v0.4.5 以前註冊的工作不會自動修正**，請重跑一次 `claude-usage install`。
+  `claude-usage status` 會在設定不對時明講。
+  （實測：2026-08-29 四台 Win11 因此全數斷線 10.7–18.1 小時，其中一台累計只跑過 7 次。）
+- **重疊的 tick 尚未互斥**：VBS 以非阻塞方式啟動 node，工作排程器認為任務瞬間完成，
+  所以 `MultipleInstances` 擋不住重疊的 node 行程。極少數情況下會競寫 `health.json`。
 - **PowerShell 執行原則**：預設 `Restricted` 會同時擋掉 `npm.ps1`（安裝時）與
   `claude-usage.ps1`（執行時）。處理方式見上面 **Windows → 第 0 步**。
 - **Linux 背景任務未實作**（systemd --user timer）。其餘指令可用。

package/dist/daemon.js

@@ -11,7 +11,8 @@ import { existsSync } from "node:fs";
 import { EXIT, loadToken } from "./creds.js";
 import { healthWarning, lastSnapshot, loadHealth, saveHealth, } from "./health.js";
 import { devicePath, projectsDir } from "./paths.js";
-import { enroll, report } from "./upload.js";
+import { agentChannel, enroll, report } from "./upload.js";
+import { maybeSelfUpdate, updateNotice } from "./selfupdate.js";
 import { sample } from "./usage.js";
 import { nowIso, parseIso } from "./util.js";
 // ── 自適應策略 ──
@@ -200,6 +201,19 @@ export async function tick(opts = {}) {
     }
     const upload = explain ? "(skipped)" : await flushUploads();
     h.last_upload_state = upload;
+    // ★ 只在**沒有採樣**的那一輪自我更新。採樣是本業，不能為了自我維護被 npm
+    //   拖上幾十秒。skip 的 tick 本來就閒著，那才是做這件事的位置。
+    //   也必須在 flushUploads 之後 —— 版本頻道是那次 report 的回應帶回來的。
+    let updateNote = "";
+    if (!explain && !should) {
+        try {
+            updateNote = maybeSelfUpdate(agentChannel());
+        }
+        catch (e) {
+            // 更新絕不能影響 tick。吞掉並記錄，不往上拋。
+            updateNote = `update: 例外 ${e?.message ?? e}`;
+        }
+    }
     const warn = healthWarning(h);
     h.unhealthy = Boolean(warn);
     h.warning = warn;
@@ -207,6 +221,9 @@ export async function tick(opts = {}) {
         saveHealth(h);
     console.log(`[${ts}] activity=${actS} cadence=${interval}m -> ${action.padEnd(22)} ` +
         `upload=${upload}  . ${reason}`);
+    // 只在真的做了什麼時才印，否則每 5 分鐘一行 "skip" 會把 log 洗掉。
+    if (updateNote && !updateNote.startsWith("update: skip"))
+        console.log(`  ${updateNote}`);
     if (warn) {
         // 前綴固定，方便 grep daemon.log 或讓 status 指令抓
         console.error(`[${ts}] UNHEALTHY: ${warn}`);
@@ -235,5 +252,9 @@ export function printHealth() {
     if (h.last_error)
         row("last_error", h.last_error);
     row("status", warn ? `UNHEALTHY - ${warn}` : "ok");
+    // 版本提示用上次 report 快取下來的結果，不為了顯示這一行去打網路。
+    const note = updateNotice();
+    if (note)
+        console.log(`  ${"update".padEnd(20)}: ${note}`);
     return warn ? 1 : 0;
 }

package/dist/doctor.js

@@ -19,6 +19,7 @@ import { claudeDir, claudeSettingsPath, configPath, credsPath, devicePath, proje
 import { healthWarning, loadHealth } from "./health.js";
 import { readJson } from "./util.js";
 import { VERSION } from "./version.js";
+import { updateNotice } from "./selfupdate.js";
 const ok = (s) => `  [ok]   ${s}`;
 const bad = (s) => `  [BAD]  ${s}`;
 const info = (s) => `  [info] ${s}`;
@@ -60,6 +61,10 @@ export async function doctor() {
     const problems = [];
     const out = [];
     out.push(`claude-usage doctor  v${VERSION}`);
+    // 舊版是很多疑難雜症的根因，所以擺在最上面而不是埋在結論裡。
+    const upd = updateNotice();
+    if (upd)
+        out.push(`  ! ${upd}`);
     out.push("");
     out.push("環境");
     out.push(info(`平台        ${platform()} ${release()}  node ${process.version}`));

package/dist/install.js

@@ -90,9 +90,57 @@ function macStatus() {
     return 0;
 }
 // ────────────────────────────── Windows ──────────────────────────────
-// ⚠️ 以下未在真機實測（見 README「已知限制」）。
+// 實機狀態（2026-08-29，四台 Win11 10.0.26200）：
+//   ✅ 已驗證：工作註冊成功、VBS 隱藏視窗可用、tick 會執行並成功上傳
+//   ✅ 已修正：電源預設值害它在電池下不執行（見 winHardenTask）
+//   ⚠️ 未驗證：winHardenTask 本身 —— 寫完當下沒有 Windows 機器可測，所以它**讀回設定
+//      並印出結果**，讓第一個安裝的人一眼看得出有沒有生效。
+//
+// ⚠️ 已知且**本次未解決**：VBS 用 s.Run(..., 0, False) 非阻塞啟動 node，wscript 立刻
+//    返回，所以工作排程器認為任務瞬間完成。這代表 -MultipleInstances IgnoreNew
+//    擋不住重疊的 **node** 行程（它擋的是重疊的「工作」，而工作早就結束了）。
+//    重疊的 tick 會競寫 health.json —— 那正是先前 consecutive_failures 卡在 152 的成因。
+//    要真正解決得在 daemon 內加檔案鎖，不屬於這次的範圍。
 /** 隱藏視窗的啟動器：node 沒有 pythonw 那種無 console 的變體，用 VBS 包一層是標準做法。 */
 const VBS_PATH = () => join(stateDir(), "run-hidden.vbs");
+/**
+ * schtasks.exe 建立的工作有三個**預設值會讓它在筆電上幾乎不執行**，而 schtasks 沒有
+ * 任何旗標可以覆蓋它們 —— 只能事後用 PowerShell 的 ScheduledTasks cmdlet 改。
+ *
+ *   DisallowStartIfOnBatteries = True  → 靠電池時**根本不啟動**
+ *   StopIfGoingOnBatteries     = True  → 執行中拔掉電源就中斷
+ *   StartWhenAvailable         = False → 錯過的排程不補跑，開機後不會自己追上
+ *
+ * ★ 這不是臆測，是實機資料逼出來的：2026-08-29 四台 Windows 全數斷線 10.7–18.1
+ *   小時，其中一台安裝後累計只跑過 7 次 tick（約 35 分鐘）。同一時間唯一存活的是
+ *   macOS 那台（launchd 沒有這些預設）。症狀完全吻合「大部分時間用電池」。
+ *
+ * ★ 為什麼要讀回來驗證：我們沒有 Windows 機器可以測這段。`Set-ScheduledTask` 失敗
+ *   時未必回非零，所以不能只看 rc —— 讓它自己把結果印出來，成不成一眼可見。
+ *
+ * 失敗不是致命的：工作本身還在，只是接上電源時才會跑。所以回 boolean 由呼叫端決定
+ * 要不要當成錯誤，而不是在這裡 return 1 把整個 install 判定成失敗。
+ */
+function winHardenTask() {
+    const cmd = `$ErrorActionPreference='Stop';` +
+        `Set-ScheduledTask -TaskName '${WIN_TASK}' -Settings (New-ScheduledTaskSettingsSet ` +
+        `-AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable ` +
+        `-MultipleInstances IgnoreNew -ExecutionTimeLimit (New-TimeSpan -Minutes 10)) | Out-Null;` +
+        `$s=(Get-ScheduledTask -TaskName '${WIN_TASK}').Settings;` +
+        `"$($s.DisallowStartIfOnBatteries)|$($s.StopIfGoingOnBatteries)|$($s.StartWhenAvailable)"`;
+    const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", cmd], { encoding: "utf8", timeout: 20_000, windowsHide: true });
+    const got = (r.stdout ?? "").trim();
+    // 期望 False|False|True。任何其他值都代表沒真的套用上去。
+    if (r.status === 0 && got === "False|False|True") {
+        console.log("schtasks: 已放寬電源限制（電池下照跑、錯過會補跑）");
+        return true;
+    }
+    console.error(`! 電源設定沒有套用成功（rc=${r.status}, 讀回 "${got || "無輸出"}"）。\n` +
+        "  工作仍然存在，但**只有接上電源時才會執行**。手動補上（單行，別換行）：\n" +
+        `    Set-ScheduledTask -TaskName ${WIN_TASK} -Settings (New-ScheduledTaskSettingsSet ` +
+        "-AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable)");
+    return false;
+}
 function winInstall() {
     const vbs = `Set s = CreateObject("Wscript.Shell")\r\n` +
         `s.Run """${NODE}"" ""${CLI}"" daemon-tick", 0, False\r\n`;
@@ -110,6 +158,7 @@ function winInstall() {
     console.log(`wrote ${VBS_PATH()}`);
     if (r.status === 0) {
         console.log(`schtasks: 已建立工作 "${WIN_TASK}"，每 ${Math.max(1, Math.floor(BASE_INTERVAL_SEC / 60))} 分鐘執行一次`);
+        winHardenTask(); // 建立完才能改設定；失敗只警告，工作本身仍可用
     }
     else {
         // 失敗才印原始輸出。用 latin1 至少保證位元組不失真，並告訴使用者怎麼看到真訊息。
@@ -119,9 +168,8 @@ function winInstall() {
         console.error(`  手動執行這行可看到正確訊息: schtasks ${args.map((a) => (a.includes(" ") ? `"${a}"` : a)).join(" ")}`);
     }
     console.log(`uninstall: schtasks /Delete /TN ${WIN_TASK} /F`);
-    console.log("! 憑證與採樣已於 2026-08-28 在 Windows 實機驗證通過（含桌面版加密憑證庫）。\n" +
-        "  尚未完整驗證的是背景任務本身（schtasks + VBS 隱藏視窗）——\n" +
-        "  裝完請跑 claude-usage status 確認有心跳。");
+    console.log("! 裝完請跑 claude-usage status 確認有心跳，並確認電源設定那一行沒有警告。\n" +
+        "  若你是筆電使用者，這一步特別重要 —— 舊版的排程在電池下不會執行。");
     return r.status ?? 1;
 }
 function winUninstall() {
@@ -150,18 +198,39 @@ function winStatus() {
         `$i=Get-ScheduledTaskInfo -TaskName '${WIN_TASK}';` +
         `$last=if($i.LastRunTime){$i.LastRunTime.ToString('yyyy-MM-dd HH:mm')}else{'-'};` +
         `$next=if($i.NextRunTime){$i.NextRunTime.ToString('yyyy-MM-dd HH:mm')}else{'-'};` +
-        `"$($t.State)|$($i.LastTaskResult)|$last|$next"}`;
+        // 電源設定一併帶回來：已經裝好的機器不會再跑 install，若不在 status 顯示，
+        // 那些工作會永遠停在「只有插電才跑」而沒有任何地方看得出來。
+        `$s=$t.Settings;` +
+        `"$($t.State)|$($i.LastTaskResult)|$last|$next` +
+        `|$($s.DisallowStartIfOnBatteries)|$($s.StopIfGoingOnBatteries)|$($s.StartWhenAvailable)"}`;
     const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", cmd], { encoding: "utf8", timeout: 15_000, windowsHide: true });
     const line = (r.stdout ?? "").trim();
     if (r.status !== 0 || !line || line === "MISSING") {
         console.log(`bg-task:   NOT installed —— 跑 claude-usage install 重新註冊`);
         return 1;
     }
-    const [state, resultRaw, last, next] = line.split("|");
+    const [state, resultRaw, last, next, noBatt, stopBatt, catchUp] = line.split("|");
     const result = Number(resultRaw);
     const meaning = TASK_RESULT[result] ?? `結束碼 ${resultRaw}`;
     console.log(`bg-task:   已註冊 "${WIN_TASK}"  狀態=${state}  上次=${last}  下次=${next}`);
     console.log(`           ${meaning}`);
+    // 舊版 client 註冊的工作沒有放寬電源限制 —— 那會表現成「白天在辦公室有心跳、
+    // 拔線後整段消失」。這裡把它講成可行動的一句話，而不是留給人去猜為什麼會斷。
+    // 欄位可能不存在（極舊的 PowerShell 或未來格式變動）→ 缺欄位就安靜跳過。
+    if (noBatt !== undefined) {
+        const bad = [];
+        if (noBatt === "True")
+            bad.push("靠電池時不啟動");
+        if (stopBatt === "True")
+            bad.push("拔電源就中斷");
+        if (catchUp === "False")
+            bad.push("錯過的排程不補跑");
+        if (bad.length) {
+            console.log(`           ! 電源設定會讓它在筆電上幾乎不執行：${bad.join("、")}`);
+            console.log(`             修正： claude-usage install   （會就地重新註冊並放寬限制）`);
+            return 1;
+        }
+    }
     // 只有「成功」與「還沒跑過」算正常；其餘代表背景任務其實沒在做事。
     if (result !== 0 && result !== 267011 && result !== 267009) {
         console.log(`           ! 背景任務上次沒有正常結束 —— 細節: schtasks /Query /TN ${WIN_TASK} /V /FO LIST`);

package/dist/paths.js

@@ -31,6 +31,8 @@ export const configPath = () => join(stateDir(), "config.json");
 export const healthPath = () => join(stateDir(), "health.json");
 /** 上報游標：每個 JSONL 檔讀到第幾個 byte */
 export const cursorPath = () => join(stateDir(), "cursor.json");
+/** 自我更新的節流狀態。**必須落地**：daemon 每次 tick 都是新行程，記憶體留不住。 */
+export const updatePath = () => join(stateDir(), "update.json");
 /** daemon 的 stdout/stderr（背景任務寫的） */
 export const logPath = () => join(stateDir(), "daemon.log");
 /**

package/dist/selfupdate.js

@@ -0,0 +1,185 @@
+/**
+ * 自我更新 —— 由 server 指定版本，client 執行。
+ *
+ * ★ 為什麼版本由 server 給，而不是 client 去問 npm：
+ *   1. **安全**：`npm i -g pkg@latest` 等於「誰能發布 npm，誰就決定同事機器上跑什麼」。
+ *      由 server 指定確切版本號，權威在我們手上 —— 有人拿到 npm token 發了新版，
+ *      只要 server 沒說要，沒有任何一台會裝。
+ *   2. **煞車**：發現壞版本時改一個環境變數就全隊停住，比 npm deprecate 快得多。
+ *   3. **成本**：版本資訊搭 /v1/report 的回應，零額外網路呼叫。daemon 每 5 分鐘跑一次，
+ *      去問 npm registry 會變成每台每天 288 次。
+ *   4. **可達性**：公司網路擋 npmjs 時仍然運作（我們的 server 本來就通）。
+ *
+ * ⚠️ 這個檔案讓「能發布 npm 套件」變成「能在同事機器上執行程式碼」。所有護欄都是
+ *    為了這件事存在的，刪任何一條之前先想清楚。
+ */
+import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { join } from "node:path";
+import { updatePath } from "./paths.js";
+import { readJson, writeJsonAtomic, nowIso } from "./util.js";
+import { VERSION } from "./version.js";
+/** 兩次自我更新嘗試的最小間隔。壞版本會讓它每 5 分鐘重裝一次，把機器打爛。 */
+export const RETRY_COOLDOWN_HOURS = 24;
+export const loadUpdateState = () => readJson(updatePath()) ?? {};
+export const saveUpdateState = (s) => writeJsonAtomic(updatePath(), s);
+/**
+ * 語意化版本比較。回 -1 / 0 / 1。
+ * 只比對 major.minor.patch 的數字部分；預發行標籤（-beta.1）一律當成比正式版小。
+ */
+export function cmpVersion(a, b) {
+    const parse = (v) => {
+        const [core = "", pre = ""] = v.split("-", 2);
+        const nums = core.split(".").map((x) => Number.parseInt(x, 10) || 0);
+        return { nums, pre };
+    };
+    const A = parse(a), B = parse(b);
+    for (let i = 0; i < 3; i++) {
+        const d = (A.nums[i] ?? 0) - (B.nums[i] ?? 0);
+        if (d !== 0)
+            return d > 0 ? 1 : -1;
+    }
+    if (A.pre === B.pre)
+        return 0;
+    if (!A.pre)
+        return 1; // 正式版 > 預發行
+    if (!B.pre)
+        return -1;
+    return A.pre > B.pre ? 1 : -1;
+}
+/** npm 全域安裝目錄。拿不到就回 null（代表我們無從判斷可不可寫）。 */
+function globalPrefix() {
+    const r = spawnSync("npm", ["prefix", "-g"], {
+        encoding: "utf8", timeout: 20_000, windowsHide: true, shell: process.platform === "win32",
+    });
+    if (r.error || r.status !== 0)
+        return null;
+    return (r.stdout ?? "").trim() || null;
+}
+/**
+ * 全域目錄可不可寫。
+ *
+ * ★ 為什麼一定要先檢查：node 裝在 /usr/local 或 Program Files 時，`npm i -g` 需要
+ *   sudo/系統管理員。從 daemon 跑必定失敗，而且是每 24 小時失敗一次、永遠不會好。
+ *   偵測得出來就不該去撞牆 —— 改成在 status/doctor 提示人工升級。
+ */
+export function prefixWritable() {
+    const p = globalPrefix();
+    if (!p)
+        return null;
+    try {
+        accessSync(p, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 要不要更新。**純函式，不做 I/O**，所以護欄邏輯測得到 —— 這是整個功能最需要被測的部分。
+ */
+export function decideUpdate(ch, st, now, opts = {}) {
+    const cur = opts.current ?? VERSION;
+    if (opts.disabled)
+        return { act: false, reason: "CU_NO_AUTOUPDATE=1（本機關閉）" };
+    if (!ch?.latest)
+        return { act: false, reason: "server 未啟用版本頻道" };
+    if (ch.autoupdate !== true)
+        return { act: false, reason: "server 只告知、未授權自動更新" };
+    const c = cmpVersion(ch.latest, cur);
+    if (c <= 0)
+        return { act: false, reason: `已是最新（本機 ${cur}）` };
+    // ★ 不跨 major：major 依定義有破壞性變更，該由人決定何時承受。
+    const majFrom = Number.parseInt(cur.split(".")[0] ?? "0", 10) || 0;
+    const majTo = Number.parseInt(ch.latest.split(".")[0] ?? "0", 10) || 0;
+    if (majTo !== majFrom) {
+        return { act: false, reason: `跨 major（${cur} → ${ch.latest}）需人工升級` };
+    }
+    // ★ 節流。目標版本換了就重置 —— 否則發了修正版還要再等滿 24 小時才會裝。
+    if (st.last_attempt_at && st.last_attempt_version === ch.latest) {
+        const hrs = (now.getTime() - Date.parse(st.last_attempt_at)) / 3_600_000;
+        if (Number.isFinite(hrs) && hrs < RETRY_COOLDOWN_HOURS) {
+            return { act: false, reason: `${RETRY_COOLDOWN_HOURS}h 內已試過 ${ch.latest}（${hrs.toFixed(1)}h 前）` };
+        }
+    }
+    return { act: true, from: cur, to: ch.latest };
+}
+/** 實際執行 npm 安裝。**釘死版本號**，不用 @latest —— 見檔頭。 */
+function runInstall(version) {
+    const pkg = `@tsa-group/claude-usage@${version}`;
+    const r = spawnSync("npm", ["install", "-g", pkg, "--no-fund", "--no-audit"], {
+        encoding: "utf8", timeout: 300_000, windowsHide: true,
+        shell: process.platform === "win32", // Windows 上 npm 是 .cmd，需要 shell 才找得到
+    });
+    if (r.error)
+        return { ok: false, detail: `spawn 失敗: ${r.error.message}` };
+    if (r.status !== 0) {
+        const tail = ((r.stderr ?? "") + (r.stdout ?? "")).trim().split("\n").slice(-3).join(" / ");
+        return { ok: false, detail: `npm rc=${r.status}: ${tail.slice(0, 300)}` };
+    }
+    return { ok: true, detail: `installed ${version}` };
+}
+/**
+ * 檢查並（在允許時）自我更新。回一句給 daemon.log 的話。
+ *
+ * ★ 絕不拋例外：daemon 的本業是採樣，不是自我維護。更新壞掉不能影響 tick。
+ */
+export function maybeSelfUpdate(ch) {
+    let st;
+    try {
+        st = loadUpdateState();
+    }
+    catch {
+        st = {};
+    }
+    // 不論要不要更新，都把 server 說的最新版存起來 —— status/doctor 靠它顯示提示，
+    // 而它們不該為了知道版本而自己去打網路。
+    if (ch?.latest && st.latest !== ch.latest) {
+        st.latest = ch.latest;
+        try {
+            saveUpdateState(st);
+        }
+        catch { /* 存不了就算了，下次還會再存 */ }
+    }
+    const d = decideUpdate(ch, st, new Date(), {
+        disabled: process.env["CU_NO_AUTOUPDATE"] === "1",
+    });
+    if (!d.act)
+        return `update: skip (${d.reason})`;
+    const w = prefixWritable();
+    if (w === false) {
+        return "update: skip (npm 全域目錄不可寫 —— 需要人工升級，見 doctor)";
+    }
+    st.last_attempt_at = nowIso();
+    st.last_attempt_version = d.to;
+    const res = runInstall(d.to);
+    st.last_result = res.ok ? "ok" : res.detail.slice(0, 200);
+    try {
+        saveUpdateState(st);
+    }
+    catch { /* 同上 */ }
+    return res.ok
+        // 不重啟自己：排程指向絕對路徑，npm 就地換檔，下一個 tick 自然用新版。
+        ? `update: ${d.from} → ${d.to} 成功（下次 tick 起生效）`
+        : `update: ${d.from} → ${d.to} 失敗 — ${res.detail}`;
+}
+/** 給 status / doctor 用的一行提示。沒有新版就回 null。 */
+export function updateNotice() {
+    let st;
+    try {
+        st = loadUpdateState();
+    }
+    catch {
+        return null;
+    }
+    if (!st.latest || cmpVersion(st.latest, VERSION) <= 0)
+        return null;
+    const how = prefixWritable() === false
+        ? "npm 全域目錄需要權限，請用系統管理員身分執行"
+        : "npm i -g @tsa-group/claude-usage@latest";
+    const failed = st.last_result && st.last_result !== "ok"
+        ? `  (自動更新上次失敗: ${st.last_result})` : "";
+    return `有新版 ${st.latest}（本機 ${VERSION}）—— ${how}${failed}`;
+}
+/** 供測試覆寫用的路徑組裝（正式路徑在 paths.ts） */
+export const _updateFileName = (dir) => join(dir, "update.json");

package/dist/upload.js

@@ -25,6 +25,9 @@ import * as events from "./events.js";
 import { devicePath, serverUrl } from "./paths.js";
 import { readJson, writeJsonAtomic } from "./util.js";
 import { VERSION } from "./version.js";
+/** 最近一次 report 回應帶回來的版本頻道。null = server 未啟用或尚未回報過。 */
+let lastAgentChannel = null;
+export const agentChannel = () => lastAgentChannel;
 async function post(path, obj, bearer) {
     const headers = { "Content-Type": "application/json" };
     if (bearer)
@@ -172,6 +175,9 @@ export async function report(argv = []) {
     }
     payload.device_id = dev.device_id;
     const { status, body } = await post("/v1/report", payload, dev.device_key);
+    // server 會在回應帶版本頻道（沒啟用時整個欄位不存在）。存起來給 daemon 決策用 ——
+    // 這是**唯一**的版本來源，client 永遠不自己去問 npm registry。見 selfupdate.ts 檔頭。
+    lastAgentChannel = body?.agent ?? null;
     const kind = anyRows ? "report" : "heartbeat";
     console.log(`${kind} -> ${status}: ${JSON.stringify(body)}`);
     console.log(`  sent: ${n.limit_snapshots} snapshots, ${n.sessions} sessions, ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Per-user Claude usage collector — measures Claude Code token detail and account-level rate-limit utilization locally, reports to your own ingest server.",
   "type": "module",
   "bin": {