numable-codex-usage 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# Codex 用量采集器
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在电脑上统计 Codex 用量，并按需同步到 Numable。首发版本为 `0.1.0`；各平台验证范围见文末兼容矩阵。
+
+需要 Node.js 18.17 或以上；建议使用当前长期支持版本。采集器不假设 Codex 自带可供外部使用的 Node.js。
+
+## 本机查看
+
+安装后可直接使用 `numable-codex`：
+
+```sh
+npm install -g numable-codex-usage
+numable-codex init
+numable-codex collect
+numable-codex summary
+```
+
+从源码运行：
+
+```sh
+node codex/cli.cjs init
+node codex/cli.cjs collect
+node codex/cli.cjs summary
+node codex/cli.cjs status
+```
+
+`devices` 列出同一空间已接入的电脑；`forget --device <标识>` 删除指定的其他电脑在服务端的用量行，拒绝删除正在采集的本机。
+
+Codex 的设备删除同时清除历史统计和实时视图。删除不撤销该电脑已有的写入凭证，也不清理它的本机历史；仍在同步的电脑有新活动或下一次实时补偿上报时可以重新出现。想持续移除一台电脑，应先在那台电脑运行 `pause` 或 `uninstall`，再从另一台电脑执行 `forget`。服务在 24 小时内保留删除前的实时序号，拒绝旧包复活会话；更新的正常上报仍可恢复。
+
+本机采集默认不联网。配置与历史保存在 `~/.numable/codex-usage/`，目录及文件分别以仅当前用户可访问的权限创建。
+
+首次扫描需要读取现有会话；之后只处理追加的完整行。支持 `sessions/` 与 `archived_sessions/`，gzip 归档可直接读取；zstd 归档需要系统提供 `zstd`。缺少解码器时会标注未读取，不伪装成零用量。
+
+默认读取 `CODEX_HOME` 或 `~/.codex`。可以用多个 `--home` 指定目录，用 `--timezone Asia/Kuala_Lumpur` 固定统计时区。每个命令均支持 `--state-dir` 指定独立状态目录。
+
+```sh
+node codex/cli.cjs init --home /自己的/Codex目录 --timezone Asia/Kuala_Lumpur
+node codex/cli.cjs collect --rebuild
+node codex/cli.cjs export
+```
+
+重算将按现存日志替换历史；已被 Codex 清理的历史无法重建。执行重算前请保留原 `history.json`。
+
+## 额度
+
+日志包含额度时会保留观测快照；额度窗口到期后仍须等待新观测，不自动恢复成满额。
+
+```sh
+node codex/cli.cjs quota
+node codex/cli.cjs quota --codex-binary /自己的/Codex可执行文件
+node codex/cli.cjs quota-auto-on
+```
+
+主动读取通过本机 Codex 协议完成，不创建会话，不要求复制 OpenAI 登录凭证。账号标识在本机匿名化；加入同一空间后使用空间范围的匿名标识，以便服务端合并同账号多台电脑的额度。不能识别账号的日志快照按设备分别展示。
+
+`quota-auto-on` 显式开启每五分钟读取，需后台采集运行；`quota-auto-off` 关闭。多个目录分别连接，单个目录失败会保留其旧观测并标注不完整。macOS 的命令行启动器不可用时，会尝试已安装桌面端的内置可执行文件；也可显式指定路径。
+
+## 手机同步
+
+默认同步地址为 `https://usage.numable.app`。在自己的电脑显式运行 `numable-codex connect` 开启同步，再运行 `numable-codex collect`。在 Numable 海外商店安装「Codex 用量」，将 `numable-codex credentials` 输出的读取凭证绑定到工具。同步默认关闭，安装不会自动上传历史。
+
+以下为独立本机开发示例，不要把夹具发到生产。本地服务可用 `service/scripts/local-codex.mjs` 启动；用 `NUMABLE_TEST_WRANGLER` 指定已经安装的 `wrangler.js`。
+
+```sh
+node codex/cli.cjs init --state-dir /自己的/测试状态目录 --endpoint http://127.0.0.1:8787
+node codex/cli.cjs connect --state-dir /自己的/测试状态目录
+node codex/cli.cjs collect --state-dir /自己的/测试状态目录
+node codex/cli.cjs credentials --state-dir /自己的/测试状态目录
+```
+
+`credentials` 显示手机使用的读取凭证；请直接粘贴到 Numable 的凭证绑定入口，不要贴到公开对话、截图或提交记录。
+
+`pause` 暂停手机同步，`resume` 恢复已绑定的同步。并发采集的晚到响应不会撤销暂停、卸载或额度自动读取关闭；实时请求在发送前会再次检查当前开关。已经发出的网络请求无法撤回，暂停不删除此前同步的数据。所有网络操作有超时，且不会跨重定向发送凭证。已绑定的状态目录不能随意切换服务地址，调试请使用独立目录。
+
+`link` 生成加入串，`join` 从标准输入接收加入串，将自己的另一台电脑加入同一空间。加入串包含写入权限，只在自己的设备间传递，不能当作手机读取凭证分享。
+
+## 自动采集
+
+```sh
+node codex/cli.cjs install
+node codex/cli.cjs live-on
+node codex/cli.cjs start
+node codex/cli.cjs stop
+node codex/cli.cjs uninstall
+```
+
+安装保留已有钩子；升级时仅替换上次安装记录中完整匹配的本工具定义，用户修改过的定义保留。安装之后，需要在 Codex 中检查并信任新增定义才会执行；采集器不会绕过信任检查。卸载只移除完整匹配的本工具定义，保留本机历史并暂停同步。
+
+`uninstall` 不删除服务端已有统计或实时记录，也不等于卸载 npm 程序。需要立即清除实时显示时，可先运行 `live-off` 并确认同步成功，再卸载；删除全部已投递数据需按上面的设备删除流程操作。实时视图正常保留 24 小时，历史投递空间在 90 天无推送后回收。
+
+Windows 安装时，钩子通过系统 `powershell.exe -NoProfile -NonInteractive -EncodedCommand` 启动。编码载荷使用 UTF-16LE，内部以调用运算符和单引号字面量传递 Node、安装目录与状态目录，保留空格、中文及特殊字符；不修改 PowerShell 执行策略。升级后请在 Codex 重新审查发生变化的定义。
+
+事件钩子立即启动不持有原会话输入输出的后台采集进程。`watch` 可在终端保持运行，每 60 秒补偿扫描；`stop` 通过本工具的停止标记请求退出，不根据一个旧 PID 杀进程。
+
+`start` 在后台运行并确认进程取得采集锁，重复启动复用现有进程。实时默认关闭，`live-on` 开启，`live-off` 清除本机实时视图并在下次同步时清空服务端本设备实时视图；`live` 查看当前投影。钩子先脱敏入队，采集锁繁忙时继续排队，不等待采集完成。状态只由真实事件更新，无事件时不会通过扫描伪造心跳。
+
+服务实时视图只保留最近 24 小时、最多 40 个会话与每会话最近 60 轮；传输接近上限时继续裁旧轮并显示省略数量。轮次结束、失败、中断、会话结束分别显示。只有明确目标完成事件才触发目标完成提醒，不保存目标正文。
+
+## 数据与隐私
+
+- 本机只保存数字、匿名身份、模型标识、时间与固定分类，不保存对话、代码、命令原文、工具参数或登录凭证。
+- `--projects on` 显式开启项目文件夹名称；默认关闭。关闭后下次采集会清除本机投影中的项目名。
+- 总量是去重后的输入加输出；缓存读取包含在输入中，推理包含在输出中，两者不额外相加。
+- 主会话数不包含子代理；用量包含子代理响应。分叉和归档副本按响应身份去重。
+- 活跃分钟表示有活动记录的分钟数，同一设备内重叠分钟只算一次；不是人工工作时长。
+- 历史范围是已接入电脑的本地记录，不代表账号所有云端活动。跨时区合并保留各采集器的自然日口径。
+
+## 验证
+
+```sh
+node --test test/codex-collect.test.cjs test/codex-cli.test.cjs test/codex-quota.test.cjs test/codex-service.test.cjs
+```
+
+完整路由测试使用真实 SQLite，需 Node.js 22 或以上：
+
+```sh
+node --test test/codex-worker.test.cjs
+```
+
+已启动独立本机服务时，可运行模拟双电脑接入闭环（临时配置与虚构日志，不修改真实 Codex 设置）：
+
+```sh
+node service/scripts/verify-codex-cli.mjs
+node service/scripts/verify-codex-package.mjs
+```
+
+默认连接 `http://127.0.0.1:8797`，可用 `CODEX_VERIFY_BASE` 改成本机其他端口，脚本拒绝公网端点。这验证协议与命令行协作，不能代替两台真实电脑的操作系统验收。
+
+安装包验收脚本不需要本机服务：先打 tgz，再离线安装到含中文、空格与单引号的临时全局前缀，使用已安装命令完成采集、钩子执行和卸载。当前覆盖 POSIX 安装布局，Windows 安装布局仍需原生验收。
+
+可独立使用真实 Codex 校验安装定义与信任状态（无需登录，不提交模型请求，不修改真实配置）：
+
+```sh
+NUMABLE_CODEX_BINARY=/自己的/codex/可执行文件 node service/scripts/verify-codex-hook-runtime.mjs
+```
+
+此脚本只核对真实协议清单、事件 / 超时 / 异步参数和未信任状态，不代替信任后的生命周期触发验收。定义升级后，Codex 会要求重新审查发生变化的钩子。
+
+Windows 主机可运行钩子命令验收：
+
+```sh
+node --test test/codex-hook-command.test.cjs test/codex-cli.test.cjs
+```
+
+Windows 上默认使用系统 Windows PowerShell，并额外经 cmd / PowerShell 两种外层 shell 执行生成命令。其他系统可通过 `NUMABLE_TEST_POWERSHELL` 指定已有 PowerShell 运行时，验证内部字面量、标准输入和退出码；这不能证明 Windows 外层 shell、npm `.cmd` 入口或原生 Codex 的事件触发已通过。
+
+## 当前兼容证据
+
+| 范围 | 已有证据 | 尚未证明 |
+|---|---|---|
+| macOS 本机采集 | Node.js 24；真实 99 文件增量扫描、gzip / zstd、三种记录版本 | 所有 Codex 版本及所有入口 |
+| 历史版本 | 0.147.0-alpha.6.5、0.159.2、0.163.0-alpha.10.2 的现存日志可解析 | 这些版本完整启动、恢复、分叉与休眠流程 |
+| 额度 | 桌面端内置可执行文件的真实只读协议；多目录失败保留夹具 | 真实账号切换和 Windows 可执行文件发现 |
+| 安装包 | tgz 六文件、离线安装、带空格 / 中文 / 单引号路径、生成钩子命令实际执行、卸载保留历史 | Windows npm 命令入口及钩子执行环境 |
+| Windows 命令生成 | macOS 上官方 PowerShell 7.6.7 实际运行：复杂路径、Unicode 标准输入、0 / 23 退出码 | Windows PowerShell 5.1、cmd / PowerShell 外层、npm 命令入口与启动耗时 |
+| 生命周期钩子 | 官方字段核对、并发进程队列、原始正文不落盘、SessionEnd / Interrupt 三秒上限；真实 app-server 识别全部 11 条定义、未信任状态与卸载后清单为空 | 在 Codex 内经过真实信任流程后触发 |
+| 多设备 | 两份临时配置接真实本机服务的完整加入、合并、暂停恢复与删除 | 两台物理电脑及跨操作系统实操 |
+
+默认后台采集只在当前用户会话中运行；`start` 不注册开机启动服务。电脑重启后需再次运行。真实钩子和定时补偿互补，钩子尚未信任时仍可手动 `collect` 或运行 `start` 采集历史。
+
+Windows、不同 Codex 入口、四端真机与线上发布进度见 meta 仓 `doc/codex-usage-impl-plan.md`，不能用本机测试通过代替。

package/cli.cjs

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { spawn } = require('node:child_process');
+const { collect, initialState, atomicWrite, hash } = require('./lib/collect.cjs');
+const { readQuotaHomes } = require('./lib/quota.cjs');
+const { sanitizeHook, absorbHook, buildLive } = require('./lib/live.cjs');
+
+function parse(args) {
+  const out = { command: args[0] || 'status', homes: [] };
+  for (let i = 1; i < args.length; i++) {
+    const key = args[i];
+    if (['--home', '--state-dir', '--timezone', '--endpoint', '--projects', '--codex-binary', '--device'].includes(key)) {
+      const value = args[++i]; if (!value || value.startsWith('--')) throw new Error('选项缺少参数');
+      if (key === '--home') out.homes.push(path.resolve(value));
+      else out[key.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = value;
+    } else if (['--json', '--quiet', '--rebuild', '--hook-worker'].includes(key)) out[key.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = true;
+    else throw new Error('无法识别选项，请运行 help 查看用法');
+  }
+  return out;
+}
+function paths(args) {
+  const dir = path.resolve(args.stateDir || process.env.NUMABLE_CODEX_STATE_DIR || path.join(os.homedir(), '.numable', 'codex-usage'));
+  return { dir, config: path.join(dir, 'config.json'), history: path.join(dir, 'history.json'), snapshot: path.join(dir, 'snapshot.json'), lock: path.join(dir, 'collect.lock') };
+}
+function read(file, fallback) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return fallback; throw new Error('本机记录无法读取，请先备份后运行重算'); }
+}
+function endpoint(value) {
+  let url; try { url = new URL(value); } catch { throw new Error('服务地址无效'); }
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/' ||
+      url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))) {
+    throw new Error('服务地址需要使用 HTTPS，本机调试可使用回环地址');
+  }
+  return url.origin;
+}
+const configBaselines = new WeakMap();
+function configFor(args, p) {
+  const saved = read(p.config, null);
+  const homes = [...new Set((args.homes.length ? args.homes : saved?.homes || [path.resolve(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'))]).map((h) => path.resolve(h)))];
+  const timezone = args.timezone || saved?.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
+  try { new Intl.DateTimeFormat('en', { timeZone: timezone }).format(); } catch { throw new Error('时区无效'); }
+  if (args.projects && !['on', 'off'].includes(args.projects)) throw new Error('项目名称选项必须是 on 或 off');
+  const projects = args.projects ? args.projects === 'on' : saved?.projects || false;
+  const target = endpoint(args.endpoint || saved?.endpoint || process.env.NUMABLE_USAGE_ENDPOINT || 'https://usage.numable.app');
+  if (saved?.writeToken && saved.endpoint !== target) throw new Error('已绑定的凭证不能发送到另一个服务，请使用独立状态目录');
+  const config = { version: 1, ...saved, homes, timezone, projects, endpoint: target, live: saved?.live === true,
+    salt: saved?.salt || crypto.randomBytes(32).toString('hex'),
+    device: saved?.device || crypto.randomBytes(12).toString('hex'), sync: saved?.sync || false };
+  configBaselines.set(config, structuredClone(saved || {}));
+  return config;
+}
+function lock(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  for (let i = 0; i < 2; i++) {
+    try {
+      const fd = fs.openSync(file, 'wx', 0o600);
+      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid })); fs.closeSync(fd);
+      return () => { try { fs.unlinkSync(file); } catch {} };
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      const previous = read(file, {});
+      if (!Number.isSafeInteger(previous.pid) || previous.pid <= 0) throw new Error('采集锁无效，请检查本机状态');
+      try { process.kill(previous.pid, 0); throw Object.assign(new Error('已有采集正在进行'), { code: 'LOCK_BUSY' }); }
+      catch (err) { if (err.code !== 'ESRCH') throw err; }
+      fs.unlinkSync(file);
+    }
+  }
+  throw new Error('无法取得采集锁');
+}
+// 所有配置回写共享短锁；只合并本次实际修改的字段，旧采集不能覆盖并发的暂停、卸载或隐私开关。
+async function saveConfig(p, config) {
+  let release;
+  for (let i = 0; ; i++) {
+    try { release = lock(path.join(p.dir, 'config.lock')); break; }
+    catch (error) {
+      if (error.code !== 'LOCK_BUSY' || i >= 100) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+  try {
+    const baseline = configBaselines.get(config) || {}, current = read(p.config, {});
+    const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+    const merged = { ...current };
+    for (const [key, value] of Object.entries(config)) {
+      if (!same(value, baseline[key]) && same(current[key], baseline[key])) merged[key] = value;
+    }
+    atomicWrite(p.config, merged);
+    Object.assign(config, merged);
+    configBaselines.set(config, structuredClone(merged));
+  } finally { release(); }
+}
+async function request(config, route, body, token) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 10000);
+  try {
+    const r = await fetch(config.endpoint + route, { method: body === undefined ? 'GET' : 'POST', redirect: 'error', signal: controller.signal,
+      headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    if (!r.ok) throw new Error(`服务请求失败（${r.status}），请检查连接后重试`);
+    return await r.json();
+  } finally { clearTimeout(timer); }
+}
+function hookCommand({ stateDir, node = process.execPath, cli = __filename, platform = process.platform }) {
+  const args = [node, cli, 'hook', '--state-dir', stateDir];
+  if (platform === 'win32') {
+    // 外层 cmd / PowerShell 都只解析固定程序名与 Base64，路径仅在内层按字面量传递。
+    // 不使用 Invoke-Expression，也不修改执行策略；调用运算符负责启动带空格的可执行路径。
+    const quote = (s) => `'${s.replace(/'/g, "''")}'`;
+    const script = `$ErrorActionPreference='Stop'; & ${args.map(quote).join(' ')}; exit $LASTEXITCODE`;
+    return `powershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand ${Buffer.from(script, 'utf16le').toString('base64')}`;
+  }
+  const quote = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+  return args.map(quote).join(' ');
+}
+function hookDefinitions(p) {
+  const command = hookCommand({ stateDir: p.dir });
+  return ['SessionStart', 'SessionEnd', 'Stop', 'UserPromptSubmit', 'PermissionRequest', 'PreToolUse', 'PostToolUse', 'PreCompact', 'SubagentStart', 'SubagentStop', 'Interrupt'].map((event) => ({ event,
+    group: { hooks: [{ type: 'command', command, ...(event === 'SessionEnd' ? {} : { async: true }), timeout: ['SessionEnd', 'Interrupt'].includes(event) ? 3 : 10 }] } }));
+}
+function installHooks(config, p) {
+  const installed = [];
+  for (const home of config.homes) {
+    const file = path.join(home, 'hooks.json'), doc = read(file, {});
+    if (doc.hooks && (typeof doc.hooks !== 'object' || Array.isArray(doc.hooks))) throw new Error('已有事件钩子的格式无效，未覆盖原配置');
+    doc.hooks ||= {};
+    for (const { event, group } of hookDefinitions(p)) {
+      let groups = doc.hooks[event] || [];
+      if (!Array.isArray(groups)) throw new Error('已有事件钩子的格式无效，未覆盖原配置');
+      // 升级仅替换上次安装记录中完整匹配的定义，用户修改过的定义保留。
+      const previous = (config.installed || []).filter((h) => h.file === file && h.event === event).map((h) => JSON.stringify(h.group));
+      groups = groups.filter((g) => !previous.includes(JSON.stringify(g)));
+      const serialized = JSON.stringify(group);
+      if (!groups.some((g) => JSON.stringify(g) === serialized)) groups.push(group);
+      doc.hooks[event] = groups;
+      installed.push({ file, event, group });
+    }
+    atomicWrite(file, doc);
+  }
+  return installed;
+}
+function uninstallHooks(config) {
+  for (const file of new Set((config.installed || []).map((h) => h.file))) {
+    const doc = read(file, null); if (!doc?.hooks) continue;
+    for (const h of config.installed.filter((h) => h.file === file)) {
+      if (!Array.isArray(doc.hooks[h.event])) continue;
+      doc.hooks[h.event] = doc.hooks[h.event].filter((g) => JSON.stringify(g) !== JSON.stringify(h.group));
+      if (!doc.hooks[h.event].length) delete doc.hooks[h.event];
+    }
+    atomicWrite(file, doc);
+  }
+}
+function pendingEvents(p) {
+  try { return fs.readdirSync(path.join(p.dir, 'events')).some((f) => f.endsWith('.json')); } catch { return false; }
+}
+function spawnEventWorker(p) {
+  const child = spawn(process.execPath, [__filename, 'collect', '--state-dir', p.dir, '--quiet', '--hook-worker'], { detached: true, stdio: 'ignore', windowsHide: true });
+  child.on('error', () => {}); child.unref();
+}
+async function scan(args, p, config) {
+  const unlock = lock(p.lock);
+  try {
+    // 等锁的期间可能已有其他采集更新序号或开关；取得锁后再读权威配置。
+    if (fs.existsSync(p.config)) config = configFor(args, p);
+    const projectionSettings = JSON.stringify([config.homes, config.timezone, config.projects, config.live, config.writeToken]);
+    let existing;
+    try { existing = read(p.history, null); }
+    catch (error) {
+      if (!args.rebuild) throw error;
+      const backup = path.join(p.dir, `history.corrupt-${Date.now()}.json`);
+      fs.copyFileSync(p.history, backup); fs.chmodSync(backup, 0o600);
+      existing = null;
+    }
+    if (existing?.salt) config.salt = existing.salt;
+    const state = args.rebuild ? { ...initialState(), salt: config.salt } : existing || { ...initialState(), salt: config.salt };
+    const queueDir = path.join(p.dir, 'events');
+    let queued = []; try { queued = fs.readdirSync(queueDir).filter((name) => /^[a-zA-Z0-9.-]+\.json$/.test(name)).map((name) => ({ file: path.join(queueDir, name), event: read(path.join(queueDir, name), null) })); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    const r = await collect(config.homes, state, { timezone: config.timezone, projects: config.projects, live: config.live });
+    let activeQuota = read(path.join(p.dir, 'quota.json'), null);
+    if (config.quotaAuto && Date.now() - (config.lastQuotaAttempt || 0) >= 300000) {
+      config.lastQuotaAttempt = Date.now();
+      try {
+        activeQuota = await readQuotaHomes({ binary: config.quotaBinary, homes: config.homes, salt: config.writeToken || state.salt, profileSalt: state.salt, previous: activeQuota });
+        atomicWrite(path.join(p.dir, 'quota.json'), activeQuota);
+        config.quotaStatus = activeQuota.supported ? activeQuota.failures ? 'partial' : 'ready' : 'unavailable';
+      } catch { config.quotaStatus = 'unavailable'; }
+    }
+    if (activeQuota?.supported && activeQuota.scope === hash(config.writeToken || state.salt, 'quota-scope')) {
+      const allowedProfiles = new Set(config.homes.map((home) => hash(state.salt, `profile:${path.resolve(home)}`)));
+      const profiles = new Set(activeQuota.quotas.filter((q) => allowedProfiles.has(q.profile)).map((q) => q.profile));
+      for (const profile of profiles) {
+        const latestLog = Math.max(0, ...r.snapshot.quotas.filter((q) => q.profile === profile).map((q) => q.observedAt));
+        const active = activeQuota.quotas.filter((q) => q.profile === profile);
+        if (active.length && Math.max(...active.map((q) => q.observedAt)) >= latestLog) r.snapshot.quotas = [...r.snapshot.quotas.filter((q) => q.profile !== profile), ...active];
+      }
+    }
+    r.snapshot.quotaDiagnostics = { failures: activeQuota?.failures || 0, profiles: activeQuota?.profileCount || config.homes.length };
+    if (config.live) {
+      r.state.liveHooks ||= { sessions: {} };
+      for (const q of queued.sort((a, b) => (a.event?.at || 0) - (b.event?.at || 0))) absorbHook(r.state.liveHooks, q.event);
+      for (const [id, s] of Object.entries(r.state.liveHooks.sessions)) if (s.lastAt < Date.now() - 24 * 3600e3) delete r.state.liveHooks.sessions[id];
+    } else delete r.state.liveHooks;
+    if (!config.projects) {
+      for (const f of Object.values(r.state.files)) { f.projectName = null; if (f.live) f.live.projectName = null; }
+      for (const s of Object.values(r.state.liveHooks?.sessions || {})) s.projectName = null;
+    }
+    const live = config.live ? buildLive(r.state, { projects: config.projects }) : { tier: 1, devNow: Date.now(), sessions: [] };
+    atomicWrite(p.history, r.state);
+    atomicWrite(p.snapshot, { ...r.snapshot, collection: r.stats });
+    atomicWrite(path.join(p.dir, 'live.json'), live);
+    for (const q of queued) try { fs.unlinkSync(q.file); } catch {}
+    config.lastCollect = r.snapshot.collectedAt; await saveConfig(p, config);
+    if (config.sync && config.writeToken && projectionSettings === JSON.stringify([config.homes, config.timezone, config.projects, config.live, config.writeToken])) {
+      const background = args.hookWorker || args.command === 'watch';
+      const pending = []; let syncError = null;
+      if (!background || Date.now() - (config.lastStatsPush || 0) >= 60000) {
+        pending.push((async () => {
+          try {
+            await request(config, '/ingest', { source: 'codex', device: config.device, snapshot: { ...r.snapshot, collection: r.stats } }, config.writeToken);
+            config.lastStatsPush = Date.now();
+          } catch (error) { syncError ||= error; }
+        })());
+      }
+      const fingerprint = crypto.createHash('sha256').update(JSON.stringify({ tier: live.tier, sessions: live.sessions })).digest('hex');
+      if ((config.live || config.liveClearPending) && (fingerprint !== config.lastLiveFingerprint || Date.now() - (config.lastLivePush || 0) >= 60000)) {
+        config.lastLiveSequence = (config.lastLiveSequence || 0) + 1;
+        await saveConfig(p, config);
+        const seq = config.lastLiveSequence;
+        pending.push((async () => {
+          try {
+            const wait = (config.lastLivePush || 0) + 2000 - Date.now();
+            if (args.hookWorker && wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+            const latest = configFor(args, p);
+            // 两秒合并窗口内也可能暂停 / 换空间 / 关闭实时；尚未发出的请求应取消。
+            if (!latest.sync || projectionSettings !== JSON.stringify([latest.homes, latest.timezone, latest.projects, latest.live, latest.writeToken])) return;
+            await request(config, `/live?source=codex&dev=${config.device}`, { ...live, seq }, config.writeToken);
+            config.lastLivePush = Date.now(); config.lastLiveFingerprint = fingerprint; config.liveClearPending = false;
+          } catch (error) { syncError ||= error; }
+        })());
+      }
+      await Promise.all(pending); config.syncError = !!syncError;
+      await saveConfig(p, config);
+      if (syncError) throw syncError;
+    }
+    return { ...r.snapshot, collection: r.stats };
+  } finally { unlock(); }
+}
+async function main(argv = process.argv.slice(2)) {
+  const args = parse(argv), p = paths(args);
+  if (args.command === 'help' || args.command === '--help') {
+    console.log('Codex 用量\ninit：初始化本机采集（默认不同步）\ncollect：增量采集；--rebuild：重算\nsummary：查看统计；--json：导出纯数字快照\nstatus：查看采集与同步状态\nquota：主动读取额度；--codex-binary 指定 Codex\nquota-auto-on/off：开启或关闭每五分钟读取额度\nlive-on/off：开启或关闭匿名实时状态；live：查看实时投影\ndevices：列出已接入电脑\nforget：删除 --device 指定的其他电脑数据\nconnect：创建读取凭证并开启同步\ncredentials：显示手机使用的读取凭证\npause：暂停同步\nresume：恢复已绑定的同步\njoin：从标准输入读取另一台电脑生成的加入串\nlink：生成供自己另一台电脑使用的加入串\ninstall：安装事件钩子（之后需在 Codex 中信任）\nuninstall：仅移除本工具安装的钩子，保留本机记录\nstart：后台启动并确认运行；watch：在前台每 60 秒补充采集；stop：请求停止后台采集\n通用选项：--home 目录（可重复）、--state-dir 目录、--timezone 时区、--endpoint 服务地址、--projects on|off');
+    return;
+  }
+  const config = configFor(args, p);
+  const output = (data) => { if (!args.quiet) console.log(typeof data === 'string' ? data : JSON.stringify(data, null, 2)); };
+  if (args.command === 'hook') {
+    // 先在父进程丢掉敏感字段，原始输入既不落盘，也不出现在进程参数中。
+    let text = '', overflow = false;
+    for await (const chunk of process.stdin) { if (!overflow) { text += chunk; if (text.length > 2 * 1024 * 1024) { overflow = true; text = ''; } } }
+    if (!fs.existsSync(p.config)) { process.stdout.write('{}\n'); return; }
+    let event = null; try { if (config.live && !overflow) event = sanitizeHook(JSON.parse(text), config.salt, { projects: config.projects }); } catch {}
+    atomicWrite(path.join(p.dir, 'events', `${Date.now()}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.json`), event || { scan: true, at: Date.now() });
+    let workerRunning = false;
+    try { const lease = read(path.join(p.dir, 'event-worker.lock'), null); if (lease?.pid) { process.kill(lease.pid, 0); workerRunning = true; } } catch {}
+    if (!workerRunning) spawnEventWorker(p);
+    process.stdout.write('{}\n');
+    return;
+  }
+  if (args.command === 'init') { await saveConfig(p, config); output('本机采集已初始化，手机同步尚未开启'); return; }
+  if (args.command === 'collect') {
+    if (args.hookWorker) {
+      let release;
+      try { release = lock(path.join(p.dir, 'event-worker.lock')); } catch (error) { if (error.code === 'LOCK_BUSY') return; throw error; }
+      try {
+        for (let i = 0; i < 600; i++) {
+          if (!pendingEvents(p)) return;
+          try { await scan(args, p, configFor(args, p)); }
+          catch (error) { if (error.code !== 'LOCK_BUSY') throw error; await new Promise((resolve) => setTimeout(resolve, 100)); }
+        }
+      } finally { release(); if (pendingEvents(p)) spawnEventWorker(p); }
+      return;
+    }
+    output(await scan(args, p, config)); return;
+  }
+  if (args.command === 'live-on' || args.command === 'live-off') {
+    config.live = args.command === 'live-on'; config.liveClearPending = !config.live;
+    await saveConfig(p, config); await scan(args, p, config);
+    output(config.live ? '实时状态已开启；手机同步沿用当前开关' : '实时状态已关闭'); return;
+  }
+  if (args.command === 'live') { output(read(path.join(p.dir, 'live.json'), { tier: 1, sessions: [] })); return; }
+  if (args.command === 'quota') {
+    const unlock = lock(p.lock);
+    try {
+      const state = read(p.history, null) || { ...initialState(), salt: config.salt };
+      config.salt = state.salt;
+      const result = await readQuotaHomes({ binary: args.codexBinary || config.quotaBinary, homes: config.homes, salt: config.writeToken || state.salt, profileSalt: state.salt,
+        previous: read(path.join(p.dir, 'quota.json'), null) });
+      atomicWrite(p.history, state); await saveConfig(p, config); atomicWrite(path.join(p.dir, 'quota.json'), result);
+      const snapshot = read(p.snapshot, null);
+      if (snapshot && result.supported) atomicWrite(p.snapshot, { ...snapshot, quotas: result.quotas });
+      output(result);
+    } finally { unlock(); }
+    return;
+  }
+  if (args.command === 'quota-auto-on' || args.command === 'quota-auto-off') {
+    config.quotaAuto = args.command === 'quota-auto-on';
+    if (args.codexBinary) config.quotaBinary = args.codexBinary;
+    if (config.quotaAuto) config.lastQuotaAttempt = 0;
+    await saveConfig(p, config); if (config.quotaAuto) await scan(args, p, config);
+    output(config.quotaAuto ? '额度自动读取已开启，每五分钟检查一次；请保持后台采集运行' : '额度自动读取已关闭'); return;
+  }
+  if (['summary', 'export'].includes(args.command)) {
+    const snapshot = read(p.snapshot, null);
+    if (!snapshot) throw new Error('还没有用量记录，请先运行 collect');
+    output(snapshot); return;
+  }
+  if (args.command === 'status') {
+    const snapshot = read(p.snapshot, null);
+    output({ initialized: fs.existsSync(p.config), sync: config.sync, paired: !!config.writeToken, live: config.live,
+      quotaAuto: config.quotaAuto === true, quotaStatus: config.quotaStatus || null, syncError: config.syncError || null,
+      collectedAt: snapshot?.collectedAt || null, timezone: config.timezone, projects: config.projects,
+      coverage: snapshot?.coverage || [], diagnostics: snapshot?.diagnostics || null, collection: snapshot?.collection || null,
+      hooksInstalled: !!config.installed?.length, hooksTrust: config.installed?.length ? 'check-in-codex' : null });
+    return;
+  }
+  if (args.command === 'connect') {
+    if (!config.writeToken) {
+      const result = await request(config, '/space', {});
+      if (!result.spaceId || !result.writeToken || !result.readToken) throw new Error('服务返回的接入信息不完整');
+      Object.assign(config, { spaceId: result.spaceId, writeToken: result.writeToken, readToken: result.readToken });
+    }
+    config.sync = true; await saveConfig(p, config);
+    output('手机同步已开启。运行 collect 上传统计，再运行 credentials 查看读取凭证'); return;
+  }
+  if (args.command === 'credentials') {
+    if (!config.readToken) throw new Error('尚未接入手机，请先运行 connect');
+    output(config.readToken); return;
+  }
+  if (args.command === 'link') {
+    if (!config.writeToken) throw new Error('尚未接入手机，请先运行 connect');
+    output(Buffer.from(JSON.stringify({ v: 1, endpoint: config.endpoint, spaceId: config.spaceId, writeToken: config.writeToken, readToken: config.readToken })).toString('base64url')); return;
+  }
+  if (args.command === 'devices') {
+    if (!config.readToken) throw new Error('尚未接入手机，请先运行 connect');
+    const result = await request(config, '/s?source=codex&lite=1', undefined, config.readToken);
+    output((result.merged?.devices || []).map((d) => ({ device: d.device, current: d.device === config.device,
+      collectedAt: d.collectedAt, receivedAt: d.receivedAt, timezone: d.timezone, coverage: d.coverage })));
+    return;
+  }
+  if (args.command === 'forget') {
+    if (!config.writeToken) throw new Error('尚未接入手机，请先运行 connect');
+    if (!args.device || !/^[a-f0-9]{4,32}$/.test(args.device)) throw new Error('请使用 --device 指定要删除的设备标识');
+    if (args.device === config.device) throw new Error('不能删除正在采集的本机，请先暂停同步并在另一台电脑操作');
+    const result = await request(config, '/forget', { source: 'codex', device: args.device }, config.writeToken);
+    output({ removed: result.removed, liveRemoved: result.liveRemoved || 0 }); return;
+  }
+  if (args.command === 'join') {
+    let text = ''; for await (const part of process.stdin) { text += part; if (text.length > 4096) throw new Error('加入串过长'); }
+    let data; try { data = JSON.parse(Buffer.from(text.trim(), 'base64url').toString('utf8')); } catch { throw new Error('加入串无效'); }
+    if (data.v !== 1 || endpoint(data.endpoint) !== config.endpoint || typeof data.spaceId !== 'string' || typeof data.writeToken !== 'string' || typeof data.readToken !== 'string') throw new Error('加入串与当前服务不匹配');
+    // 用只读请求验证后再保存，未打印写入凭证。
+    await request({ ...config, endpoint: data.endpoint }, '/s?source=codex&lite=1', undefined, data.readToken);
+    Object.assign(config, { spaceId: data.spaceId, writeToken: data.writeToken, readToken: data.readToken, sync: true });
+    await saveConfig(p, config); output('已加入同一个用量空间'); return;
+  }
+  if (args.command === 'pause' || args.command === 'resume') {
+    if (args.command === 'resume' && !config.writeToken) throw new Error('尚未接入手机，请先运行 connect');
+    config.sync = args.command === 'resume'; await saveConfig(p, config); output(config.sync ? '手机同步已恢复' : '手机同步已暂停，本机统计继续保留'); return;
+  }
+  if (args.command === 'install') {
+    config.installed = installHooks(config, p); await saveConfig(p, config);
+    output('事件钩子已安装。请在 Codex 中检查并信任新增钩子，信任后才会自动采集'); return;
+  }
+  if (args.command === 'uninstall') {
+    uninstallHooks(config); config.installed = []; config.sync = false; await saveConfig(p, config);
+    atomicWrite(path.join(p.dir, 'stop.json'), { at: Date.now() }); output('已移除本工具的事件钩子并暂停同步，本机记录仍保留'); return;
+  }
+  if (args.command === 'stop') { atomicWrite(path.join(p.dir, 'stop.json'), { at: Date.now() }); output('已请求停止后台采集'); return; }
+  if (args.command === 'start') {
+    if (!fs.existsSync(p.config)) throw new Error('请先运行 init 初始化本机采集');
+    const watchLock = path.join(p.dir, 'watch.lock'), previous = read(watchLock, null);
+    if (previous?.pid) {
+      try { process.kill(previous.pid, 0); output('后台采集已在运行'); return; }
+      catch (e) { if (e.code !== 'ESRCH') throw e; }
+    }
+    const child = spawn(process.execPath, [__filename, 'watch', '--state-dir', p.dir, '--quiet'], { detached: true, stdio: 'ignore', windowsHide: true });
+    let failed = false; child.once('error', () => { failed = true; }); child.unref();
+    for (let i = 0; i < 40 && !failed; i++) {
+      if (read(watchLock, null)?.pid === child.pid) { output('后台采集已启动'); return; }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error('未能确认后台采集启动，请运行 watch 查看状态');
+  }
+  if (args.command === 'watch') {
+    const release = lock(path.join(p.dir, 'watch.lock')), startedAt = Date.now();
+    let stopped = false;
+    process.once('SIGINT', () => { stopped = true; }); process.once('SIGTERM', () => { stopped = true; });
+    try {
+      while (!stopped) {
+        if ((read(path.join(p.dir, 'stop.json'), {})?.at || 0) >= startedAt) break;
+        try { await scan(args, p, configFor(args, p)); } catch { if (!args.quiet) console.error('本轮采集未完成，将在下一轮重试'); }
+        for (let i = 0; i < 60 && !stopped; i++) {
+          if ((read(path.join(p.dir, 'stop.json'), {})?.at || 0) >= startedAt) { stopped = true; break; }
+          await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+      }
+    } finally { release(); }
+    return;
+  }
+  throw new Error('无法识别命令，请运行 help 查看用法');
+}
+if (require.main === module) main().catch((e) => {
+  if (process.argv[2] === 'hook') { process.stdout.write('{}\n'); return; }
+  if (process.argv.includes('--quiet')) return;
+  console.error(e.message && !/ENOENT|EACCES|ENOSPC|fetch failed/.test(e.message) ? e.message : '操作未完成，请检查本机目录、网络与可用空间后重试');
+  process.exitCode = 1;
+});
+module.exports = { parse, paths, endpoint, configFor, lock, installHooks, uninstallHooks, scan, request, main, hookCommand };

package/lib/collect.cjs

@@ -0,0 +1,294 @@
+'use strict';
+
+// 日志只在本机解析；持久化投影不含正文、代码、命令、工具参数或登录凭证。
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const zlib = require('node:zlib');
+const { spawn } = require('node:child_process');
+const { absorbLog } = require('./live.cjs');
+
+const VERSION = 1;
+const MODEL = /^[a-zA-Z0-9._-]{1,80}$/;
+const LIMIT = /^[a-zA-Z0-9._-]{1,64}$/;
+const n = (x) => Number.isSafeInteger(x) && x >= 0 ? x : null;
+const hash = (salt, value) => crypto.createHmac('sha256', salt).update(String(value)).digest('hex').slice(0, 24);
+const emptyUsage = () => ({ input: 0, output: 0, cached: 0, reasoning: 0, total: 0 });
+function usage(u) {
+  if (!u || n(u.input_tokens) === null || n(u.output_tokens) === null) return null;
+  const input = n(u.input_tokens), output = n(u.output_tokens);
+  const cached = n(u.cached_input_tokens), reasoning = n(u.reasoning_output_tokens);
+  const total = input + output;
+  if (!Number.isSafeInteger(total) || (n(u.total_tokens) !== null && u.total_tokens !== total)) return null;
+  if (cached > input || reasoning > output) return null;
+  return { input, output, cached, reasoning, total };
+}
+function addUsage(to, u) {
+  for (const k of Object.keys(emptyUsage())) {
+    // 可选细项缺失时保留未知；总量不受它们影响。
+    to[k] = to[k] === null || u[k] === null ? null : to[k] + u[k];
+  }
+}
+function quota(raw, at) {
+  if (!raw || !Number.isFinite(at)) return null;
+  const id = raw.limit_id || raw.limitId || 'codex';
+  if (typeof id !== 'string' || !LIMIT.test(id)) return null;
+  const window = (w) => {
+    if (!w || typeof w.used_percent !== 'number' && typeof w.usedPercent !== 'number') return null;
+    const usedPercent = w.used_percent ?? w.usedPercent;
+    const windowDurationMins = w.window_minutes ?? w.windowDurationMins;
+    const resetsAt = w.resets_at ?? w.resetsAt;
+    if (!Number.isFinite(usedPercent) || usedPercent < 0 || usedPercent > 100 ||
+      !Number.isFinite(windowDurationMins) || windowDurationMins <= 0 || n(resetsAt) === null || resetsAt <= 0) return null;
+    return { usedPercent, windowDurationMins, resetsAt };
+  };
+  const primary = window(raw.primary), secondary = window(raw.secondary);
+  return primary || secondary ? { id, observedAt: at, primary, secondary } : null;
+}
+const formatters = new Map();
+function dateAt(at, timezone) {
+  if (!formatters.has(timezone)) formatters.set(timezone, new Intl.DateTimeFormat('en-CA', { timeZone: timezone, year: 'numeric', month: '2-digit', day: '2-digit' }));
+  const parts = formatters.get(timezone).formatToParts(at);
+  const get = (key) => parts.find((x) => x.type === key).value;
+  return `${get('year')}-${get('month')}-${get('day')}`;
+}
+function initialState() {
+  return { version: VERSION, salt: crypto.randomBytes(32).toString('hex'), files: {} };
+}
+function projection() {
+  return { offset: 0, identity: '', head: '', session: null, project: null, projectName: null,
+    source: 'unknown', version: null, subagent: false, fork: false, model: 'unknown', turn: null,
+    records: {}, legacy: {}, turns: {}, prompts: {}, activity: {}, quotas: {},
+    cumulative: null, diagnostics: { invalidRows: 0, invalidUsage: 0, missingIdentity: 0 }, lastAt: 0 };
+}
+function processRow(file, row, salt, options = {}) {
+  const p = row && row.payload;
+  if (!p || typeof p !== 'object') return;
+  const at = Date.parse(row.timestamp || p.timestamp);
+  if (row.type === 'session_meta') {
+    const id = p.id || p.session_id;
+    if (typeof id === 'string') file.session = hash(salt, `session:${id}`);
+    if (typeof p.cwd === 'string') {
+      file.project = hash(salt, `project:${p.cwd.replace(/\\/g, '/').replace(/\/$/, '')}`);
+      if (options.projects) file.projectName = p.cwd.replace(/\\/g, '/').split('/').filter(Boolean).pop()?.slice(0, 40) || null;
+    }
+    const src = p.source;
+    file.subagent = !!(src && typeof src === 'object' && src.subagent) || !!p.parent_thread_id;
+    file.fork = !!(p.forked_from_id || p.forked_from);
+    file.source = file.subagent ? 'subagent' : ['cli', 'vscode', 'exec', 'appServer'].includes(src) ? src : 'unknown';
+    file.version = typeof p.cli_version === 'string' && /^[a-zA-Z0-9.+_-]{1,64}$/.test(p.cli_version) ? p.cli_version : null;
+    return;
+  }
+  if (row.type === 'turn_context') {
+    file.turn = typeof p.turn_id === 'string' ? hash(salt, `turn:${p.turn_id}`) : file.turn;
+    file.model = typeof p.model === 'string' && MODEL.test(p.model) ? p.model : 'unknown';
+    return;
+  }
+  if (!Number.isFinite(at) || !file.session) return;
+  file.lastAt = Math.max(file.lastAt, at);
+  const turn = typeof p.turn_id === 'string' ? hash(salt, `turn:${p.turn_id}`) : file.turn;
+  const base = { at, session: file.session, project: file.project, model: file.model, turn, subagent: file.subagent };
+  if (options.live) absorbLog(file, row, { ...base, projectName: options.projects ? file.projectName : null }, (value) => hash(salt, value));
+  if (row.type === 'token_usage_record') {
+    const u = usage(p.usage);
+    if (!u) { file.diagnostics.invalidUsage++; return; }
+    if (typeof p.response_id !== 'string') { file.diagnostics.missingIdentity++; return; }
+    const key = hash(salt, `response:${p.response_id}`);
+    file.records[key] = { ...base, ...(typeof p.session_id === 'string' ? { session: hash(salt, `session:${p.session_id}`) } : {}), usage: u };
+    file.activity[String(Math.floor(at / 60000))] = 1;
+  }
+  if (row.type !== 'event_msg') return;
+  if (p.type === 'token_count') {
+    const q = quota(p.rate_limits, at);
+    if (q) file.quotas[q.id] = q;
+    const total = usage(p.info?.total_token_usage), last = usage(p.info?.last_token_usage);
+    if (!total) return;
+    const previous = file.cumulative;
+    // 累计计数完全相同的通知不能重复统计；计数回落视为新代，绝不产生负数。
+    if (previous && total.input === previous.input && total.output === previous.output) return;
+    let u;
+    if (previous && total.input >= previous.input && total.output >= previous.output) {
+      u = emptyUsage();
+      for (const k of Object.keys(u)) u[k] = total[k] === null || previous[k] === null ? null : Math.max(0, total[k] - previous[k]);
+    } else {
+      // 恢复或分叉首条累计值可能含继承历史，只认这次响应的 last。
+      u = last;
+    }
+    file.cumulative = total;
+    if (!u) { file.diagnostics.invalidUsage++; return; }
+    const key = hash(salt, `legacy:${file.session}:${turn || ''}:${total.input}:${total.output}`);
+    file.legacy[key] = { ...base, usage: u };
+    file.activity[String(Math.floor(at / 60000))] = 1;
+  }
+  if (p.type === 'task_started' && turn) {
+    file.turn = turn;
+    file.turns[turn] = { at, session: file.session, subagent: file.subagent };
+  }
+  if (p.type === 'user_message' || p.type === 'item_completed' && p.item?.type === 'UserMessage') {
+    // 只判断结构，不读正文；有事件身份才去重，没有身份按轮计一次。
+    const id = p.item?.id || turn;
+    if (id) file.prompts[hash(salt, `prompt:${file.session}:${id}`)] = { at, subagent: file.subagent };
+    file.activity[String(Math.floor(at / 60000))] = 1;
+  }
+}
+
+async function discover(roots) {
+  const result = [], skipped = { compressedUnavailable: 0, unreadableDirectories: 0 };
+  async function walk(dir) {
+    let entries;
+    try { entries = await fs.promises.readdir(dir, { withFileTypes: true }); }
+    catch (e) { if (e.code !== 'ENOENT') skipped.unreadableDirectories++; return; }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const p = path.join(dir, entry.name);
+      if (entry.isDirectory()) await walk(p);
+      else if (entry.isFile() && /\.jsonl(?:\.gz|\.zst)?$/.test(entry.name)) result.push(p);
+    }
+  }
+  for (const root of roots) {
+    await walk(path.join(root, 'sessions'));
+    await walk(path.join(root, 'archived_sessions'));
+  }
+  return { paths: [...new Set(result)], skipped };
+}
+
+async function readFile(filePath, old, salt, options) {
+  const stat = await fs.promises.stat(filePath);
+  const compressed = /\.(gz|zst)$/.test(filePath);
+  const handle = await fs.promises.open(filePath, 'r');
+  const first = Buffer.alloc(Math.min(256, stat.size));
+  await handle.read(first, 0, first.length, 0);
+  await handle.close();
+  const head = crypto.createHash('sha256').update(first).digest('hex');
+  const identity = `${stat.dev}:${stat.ino}`;
+  // 小文件首段会随追加变化；只有旧文件已超过 256 字节才用首段判断替换。
+  const reset = !old || old.identity !== identity || old.offset > stat.size || old.offset >= 256 && old.head !== head || old.projectsEnabled !== (options.projects === true) || old.liveEnabled !== (options.live === true) || old.profile !== options.profile;
+  const f = reset ? projection() : structuredClone(old);
+  f.identity = identity; f.head = head; f.projectsEnabled = options.projects === true; f.liveEnabled = options.live === true; f.profile = options.profile;
+  if (!reset && (compressed ? f.size === stat.size && f.mtime === stat.mtimeMs : f.offset === stat.size)) return { file: f, rows: 0 };
+  if (compressed && !reset) Object.assign(f, projection(), { identity, head, projectsEnabled: options.projects === true, liveEnabled: options.live === true, profile: options.profile });
+  const start = compressed ? 0 : f.offset;
+  if (!stat.size) return { file: f, rows: 0 };
+  let stream, child, childDone;
+  if (filePath.endsWith('.zst')) {
+    child = spawn(options.zstd || 'zstd', ['-d', '-q', '-c', filePath], { stdio: ['ignore', 'pipe', 'ignore'] });
+    childDone = new Promise((resolve, reject) => { child.on('error', reject); child.on('close', (code) => code === 0 ? resolve() : reject(new Error('压缩日志解码失败'))); });
+    // 先挂拒绝处理，稍后统一等待，避免流结束前出现未处理拒绝。
+    childDone.catch(() => {});
+    stream = child.stdout;
+  } else {
+    stream = fs.createReadStream(filePath, { start, end: stat.size - 1 });
+    if (filePath.endsWith('.gz')) stream = stream.pipe(zlib.createGunzip());
+  }
+  let pending = Buffer.alloc(0), rows = 0, bytes = start;
+  for await (const chunk of stream) {
+    pending = Buffer.concat([pending, chunk]);
+    let begin = 0, end;
+    while ((end = pending.indexOf(10, begin)) !== -1) {
+      const line = pending.subarray(begin, end);
+      bytes += end - begin + 1; begin = end + 1;
+      if (!line.length) continue;
+      let row;
+      try { row = JSON.parse(line.toString('utf8')); } catch { f.diagnostics.invalidRows++; continue; }
+      processRow(f, row, salt, options); rows++;
+    }
+    pending = pending.subarray(begin);
+    if (pending.length > 32 * 1024 * 1024) throw new Error('单条日志超过读取上限');
+  }
+  if (childDone) await childDone;
+  f.offset = compressed ? stat.size : bytes;
+  f.size = stat.size; f.mtime = stat.mtimeMs;
+  return { file: f, rows };
+}
+
+async function collect(roots, previous = initialState(), options = {}) {
+  if (previous.version !== VERSION || typeof previous.salt !== 'string') throw new Error('历史格式不兼容，请执行重算');
+  const state = structuredClone(previous);
+  const found = await discover(roots);
+  const stats = { files: found.paths.length, scanned: 0, rows: 0, unreadableFiles: 0, ...found.skipped };
+  const profiles = roots.map((root) => ({ root: path.resolve(root), id: hash(state.salt, `profile:${path.resolve(root)}`) }));
+  for (const p of found.paths) {
+    const key = hash(state.salt, `file:${p}`);
+    try {
+      const profile = profiles.filter((entry) => p.startsWith(entry.root + path.sep)).sort((a, b) => b.root.length - a.root.length)[0]?.id;
+      const r = await readFile(p, state.files[key], state.salt, { ...options, profile });
+      state.files[key] = r.file; stats.rows += r.rows; stats.scanned += r.rows > 0 ? 1 : 0;
+    } catch (e) {
+      if (e.code === 'ENOENT' && p.endsWith('.zst')) stats.compressedUnavailable++;
+      else stats.unreadableFiles++;
+    }
+  }
+  // 旧文件被上游清理后仍保留数字历史；归档副本由响应身份去重。
+  return { state, stats, snapshot: summarize(state, { ...options, activeProfiles: profiles.map((p) => p.id) }) };
+}
+
+function summarize(state, options = {}) {
+  const timezone = options.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const now = options.now || Date.now();
+  const cutoff = now - 400 * 864e5;
+  const records = new Map(), legacy = new Map(), turns = new Map(), prompts = new Map(), projects = new Map();
+  const sessions = new Map(), quotas = new Map(), activity = new Set(), modernTurns = new Set(), modernSessions = new Set();
+  const diagnostics = { invalidRows: 0, invalidUsage: 0, missingIdentity: 0, unknownFiles: 0, legacyRecords: 0, unassignedLegacy: 0 };
+  const coverage = new Map();
+  for (const f of Object.values(state.files)) {
+    for (const k of ['invalidRows', 'invalidUsage', 'missingIdentity']) diagnostics[k] += f.diagnostics[k];
+    if (!f.session || !f.version) diagnostics.unknownFiles++;
+    const ckey = `${f.source}:${f.version || 'unknown'}`;
+    coverage.set(ckey, { source: f.source, version: f.version, files: (coverage.get(ckey)?.files || 0) + 1 });
+    for (const [key, r] of Object.entries(f.records)) {
+      if (!records.has(key) || r.at > records.get(key).at || r.at === records.get(key).at && r.usage.total > records.get(key).usage.total) records.set(key, r);
+      modernSessions.add(r.session);
+      if (r.turn) modernTurns.add(r.turn);
+    }
+    for (const [key, r] of Object.entries(f.legacy)) if (!legacy.has(key) || r.at < legacy.get(key).at) legacy.set(key, r);
+    for (const [key, r] of Object.entries(f.turns)) if (!turns.has(key) || r.at < turns.get(key).at) turns.set(key, r);
+    for (const [key, r] of Object.entries(f.prompts)) if (!prompts.has(key) || r.at < prompts.get(key).at) prompts.set(key, r);
+    for (const minute of Object.keys(f.activity)) activity.add(Number(minute));
+    if (f.project) projects.set(f.project, options.projects ? f.projectName : null);
+    if (!options.activeProfiles || options.activeProfiles.includes(f.profile)) for (const q of Object.values(f.quotas)) {
+      const key = `${f.profile || 'default'}:${q.id}`;
+      if (!quotas.has(key) || q.observedAt > quotas.get(key).observedAt) quotas.set(key, { ...q, profile: f.profile || null });
+    }
+  }
+  const events = [...records.values()];
+  for (const r of legacy.values()) {
+    if (r.turn && modernTurns.has(r.turn)) continue;
+    if (!r.turn && modernSessions.has(r.session)) { diagnostics.unassignedLegacy++; continue; }
+    events.push(r); diagnostics.legacyRecords++;
+  }
+  const days = new Map();
+  const day = (at) => {
+    const date = dateAt(at, timezone);
+    if (!days.has(date)) days.set(date, { date, ...emptyUsage(), responses: 0, turns: 0, sessions: 0, prompts: 0, activeMinutes: 0, models: {}, projects: {} });
+    return days.get(date);
+  };
+  for (const r of events.sort((a, b) => a.at - b.at)) {
+    if (r.at < cutoff || r.at > now + 60000) continue;
+    const d = day(r.at); addUsage(d, r.usage); d.responses++;
+    if (!d.models[r.model]) d.models[r.model] = { ...emptyUsage(), responses: 0 };
+    addUsage(d.models[r.model], r.usage); d.models[r.model].responses++;
+    if (r.project) {
+      if (!d.projects[r.project]) d.projects[r.project] = { ...emptyUsage(), responses: 0, ...(options.projects && projects.get(r.project) ? { name: projects.get(r.project) } : {}) };
+      addUsage(d.projects[r.project], r.usage); d.projects[r.project].responses++;
+    }
+    if (!r.subagent) sessions.set(`${r.session}:${d.date}`, r.at);
+  }
+  for (const t of turns.values()) if (!t.subagent && t.at >= cutoff && t.at <= now + 60000) {
+    const d = day(t.at); d.turns++; sessions.set(`${t.session}:${d.date}`, t.at);
+  }
+  for (const t of prompts.values()) if (!t.subagent && t.at >= cutoff && t.at <= now + 60000) day(t.at).prompts++;
+  for (const at of sessions.values()) day(at).sessions++;
+  for (const minute of activity) if (minute * 60000 >= cutoff && minute * 60000 <= now + 60000) day(minute * 60000).activeMinutes++;
+  return { v: 1, collectedAt: now, timezone, privacy: { projects: options.projects === true }, coverage: [...coverage.values()], diagnostics,
+    sessionCount: new Set([...sessions.keys()].map((key) => key.split(':')[0])).size,
+    days: [...days.values()].sort((a, b) => a.date.localeCompare(b.date)),
+    quotas: [...quotas.values()].map((q) => ({ ...q, account: null, origin: 'log', expired: [q.primary, q.secondary].filter(Boolean).every((w) => w.resetsAt * 1000 <= now) })) };
+}
+
+function atomicWrite(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  try { fs.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600, flag: 'wx' }); fs.renameSync(tmp, file); }
+  finally { try { fs.unlinkSync(tmp); } catch {} }
+}
+
+module.exports = { VERSION, usage, quota, dateAt, initialState, processRow, projection, collect, summarize, atomicWrite, hash };

package/lib/live.cjs

@@ -0,0 +1,237 @@
+'use strict';
+// 实时投影只保存匿名身份、时间与固定分类。原始钩子对象不能落盘或传给子进程。
+const crypto = require('node:crypto');
+const HASH = /^[a-f0-9]{24}$/;
+const MODEL = /^[a-zA-Z0-9._-]{1,64}$/;
+const EVENTS = ['SessionStart', 'SessionEnd', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PermissionRequest', 'Stop', 'Interrupt', 'PreCompact', 'SubagentStart', 'SubagentStop'];
+const KEEP = 24 * 3600e3;
+const anon = (salt, value) => crypto.createHmac('sha256', salt).update(String(value)).digest('hex').slice(0, 24);
+const finite = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+const cleanName = (s) => typeof s === 'string' ? s.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 40) : null;
+function category(name) {
+  if (typeof name !== 'string') return 'o';
+  if (/^(Bash|exec_command|write_stdin|shell|shell_command)$/.test(name)) return 's';
+  if (/^(apply_patch|Edit|Write)$/.test(name)) return 'e';
+  if (/^(Read|Glob|Grep|read_file)$/.test(name)) return 'r';
+  if (/^(spawn_agent|Agent|Task)$/.test(name)) return 'a';
+  if (/web|search_query|fetch_url/i.test(name)) return 'w';
+  if (/browser|chrome|cua_/i.test(name)) return 'b';
+  if (/device|simulator|android|ios_/i.test(name)) return 'd';
+  if (/^mcp__/.test(name)) return 'm';
+  if (/request_user_input|AskUserQuestion/.test(name)) return 'q';
+  return 'o';
+}
+function sanitizeHook(raw, salt, options = {}, now = Date.now()) {
+  if (!raw || !EVENTS.includes(raw.hook_event_name) || typeof raw.session_id !== 'string' || !raw.session_id || !finite(now)) return null;
+  const r = { event: raw.hook_event_name, at: now, session: anon(salt, `session:${raw.session_id}`),
+    turn: typeof raw.turn_id === 'string' && raw.turn_id ? anon(salt, `turn:${raw.turn_id}`) : null,
+    tool: typeof raw.tool_use_id === 'string' ? anon(salt, `tool:${raw.tool_use_id}`) : null,
+    category: category(raw.tool_name), model: typeof raw.model === 'string' && MODEL.test(raw.model) ? raw.model : null };
+  if (typeof raw.cwd === 'string') {
+    const normalized = raw.cwd.replace(/\\/g, '/').replace(/\/$/, '');
+    r.project = anon(salt, `project:${normalized}`);
+    if (options.projects) r.projectName = cleanName(normalized.split('/').filter(Boolean).pop());
+  }
+  // 不解析工具结果正文，只有明确的结构化错误信号才标记失败。
+  if (raw.hook_event_name === 'PostToolUse') {
+    const response = raw.tool_response;
+    r.failed = raw.is_error === true || response?.is_error === true || response?.isError === true ||
+      typeof response?.exit_code === 'number' && response.exit_code !== 0;
+  }
+  if (['SubagentStart', 'SubagentStop'].includes(r.event) && typeof raw.agent_id === 'string') r.agent = anon(salt, `agent:${raw.agent_id}`);
+  return r;
+}
+function createSession(context) {
+  return { session: context.session, project: context.project || null, projectName: context.projectName || null,
+    model: context.model || null, state: 'lost', changedAt: context.at, changeKind: 'start', startAt: context.at,
+    lastAt: context.at, endAt: null, permSince: null, turn: null, nextN: 1, turns: {}, agents: {}, evidence: 'log' };
+}
+function turnFor(s, key, at) {
+  if (!key) return null;
+  if (!s.turns[key]) s.turns[key] = { key, n: s.nextN++, s: at, e: null, end: null, perm: 0,
+    waitingSince: null, tools: {}, compactions: 0, lastAt: at };
+  return s.turns[key];
+}
+function transition(s, state, kind, at) {
+  if (at < s.changedAt) return;
+  s.state = state; s.changeKind = kind; s.changedAt = at;
+  if (state === 'ended') s.endAt = at;
+}
+function finish(s, t, end, at) {
+  if (t && (!t.e || at >= t.lastAt)) {
+    if (t.waitingSince) t.perm += Math.max(0, at - t.waitingSince);
+    t.waitingSince = null; t.e = at; t.end = end; t.lastAt = at;
+  }
+  if (at >= s.changedAt) s.permSince = null;
+  transition(s, 'input', end === 'interrupt' ? 'interrupt' : end === 'error' ? 'error' : 'done', at);
+}
+function observe(s, event) {
+  const at = event.at;
+  if (!finite(at) || !HASH.test(event.session || '')) return;
+  s.startAt = Math.min(s.startAt, at); s.lastAt = Math.max(s.lastAt, at);
+  if (event.project) s.project = event.project;
+  if (event.projectName) s.projectName = event.projectName;
+  if (event.model) s.model = event.model;
+  const key = event.turn || s.turn;
+  const t = turnFor(s, key, at);
+  if (event.turn && at >= s.changedAt) s.turn = event.turn;
+  if (event.event === 'SessionStart') {
+    // 打开已有会话不代表它正在运行；保留有证据的在途轮，否则只记可见。
+    if (!t || t.e) transition(s, 'input', 'resume', at);
+  }
+  if (event.event === 'UserPromptSubmit' || event.event === 'task_started') {
+    const previous = Object.values(s.turns).find((x) => x.key !== key && !x.e);
+    if (previous && at >= previous.lastAt) { previous.e = at; previous.end = 'interrupt'; previous.lastAt = at; }
+    if (at >= s.changedAt) { s.endAt = null; s.permSince = null; }
+    if (!t?.e) transition(s, 'running', 'turn', at);
+  }
+  if (event.event === 'PermissionRequest' && t && !t.e && at >= s.changedAt) {
+    if (!t.waitingSince) t.waitingSince = at;
+    s.permSince = t.waitingSince; transition(s, 'perm', 'perm', at);
+  }
+  if (event.event === 'PreToolUse' || event.event === 'PostToolUse') {
+    if (t && event.tool) {
+      const tool = t.tools[event.tool] || { category: event.category || 'o', s: at, e: null, failed: false };
+      if (event.event === 'PreToolUse') tool.s = Math.min(tool.s, at);
+      else { tool.e = Math.max(tool.e || 0, at); tool.failed = !!event.failed; }
+      t.tools[event.tool] = tool;
+    }
+    // PreToolUse 可能紧邻授权请求且异步乱序；只有结果能证明等待已结束。
+    if (event.event === 'PostToolUse' && t && !t.e && at >= s.changedAt) {
+      if (t.waitingSince) { t.perm += Math.max(0, at - t.waitingSince); t.waitingSince = null; }
+      s.permSince = null; transition(s, 'running', s.state === 'perm' ? 'approved' : 'turn', at);
+    } else if (event.event === 'PreToolUse' && t && !t.e && s.state !== 'perm') transition(s, event.category === 'q' ? 'input' : 'running', 'turn', at);
+  }
+  if (event.event === 'Stop' || event.event === 'task_complete') finish(s, t, 'ok', at);
+  if (event.event === 'Interrupt' || event.event === 'turn_aborted') finish(s, t, 'interrupt', at);
+  if (event.event === 'turn_failed') finish(s, t, 'error', at);
+  if (event.event === 'SessionEnd') {
+    if (t && !t.e && at >= t.lastAt) { t.e = at; t.end = 'ended'; t.lastAt = at; }
+    if (at >= s.changedAt) s.permSince = null;
+    transition(s, 'ended', 'end', at);
+  }
+  if (event.event === 'PreCompact' && t) t.compactions++;
+  if (event.event === 'SubagentStart' && event.agent) s.agents[event.agent] ||= { s: at, e: null };
+  if (event.event === 'SubagentStop' && event.agent && s.agents[event.agent]) s.agents[event.agent].e = at;
+  if (t) t.lastAt = Math.max(t.lastAt, at);
+  const keys = Object.keys(s.turns).sort((a, b) => s.turns[a].s - s.turns[b].s);
+  for (const key of keys.slice(0, Math.max(0, keys.length - 60))) delete s.turns[key];
+}
+function absorbHook(store, event) {
+  if (!event || !EVENTS.includes(event.event) || !HASH.test(event.session || '') || !finite(event.at)) return;
+  // 即使本机队列文件被改过，也只接收结构投影，不能把任意文本混入历史。
+  event = { event: event.event, session: event.session, at: event.at,
+    turn: HASH.test(event.turn || '') ? event.turn : null, tool: HASH.test(event.tool || '') ? event.tool : null,
+    project: HASH.test(event.project || '') ? event.project : null, projectName: cleanName(event.projectName),
+    category: 'reasawbdmqo'.includes(event.category) && event.category?.length === 1 ? event.category : 'o',
+    model: MODEL.test(event.model || '') ? event.model : null, failed: event.failed === true,
+    agent: HASH.test(event.agent || '') ? event.agent : null };
+  store.sessions ||= {};
+  const s = store.sessions[event.session] ||= createSession(event);
+  s.evidence = 'hook'; observe(s, event);
+}
+function absorbLog(file, row, context, anonymize) {
+  if (!context.session || !finite(context.at)) return;
+  if (!file.live || file.live.session !== context.session) file.live = createSession(context);
+  const p = row.payload || {}, s = file.live;
+  if (context.model && context.model !== 'unknown') s.model = context.model;
+  let event = null;
+  if (row.type === 'event_msg') {
+    if (p.type === 'thread_goal_updated' && ['active', 'paused', 'blocked', 'usageLimited', 'budgetLimited', 'complete'].includes(p.goal?.status)) {
+      if (!s.goalUpdatedAt || context.at >= s.goalUpdatedAt) {
+        s.goalStatus = p.goal.status; s.goalUpdatedAt = context.at;
+        s.goalCompleteAt = p.goal.status === 'complete' ? context.at : null;
+        s.lastAt = Math.max(s.lastAt, context.at);
+      }
+    }
+    if (p.type === 'thread_goal_cleared' && (!s.goalUpdatedAt || context.at >= s.goalUpdatedAt)) {
+      s.goalStatus = null; s.goalUpdatedAt = context.at; s.goalCompleteAt = null;
+    }
+    if (['task_started', 'task_complete', 'turn_aborted'].includes(p.type)) event = { event: p.type };
+    if (p.type === 'turn_failed' || p.type === 'error' && p.fatal === true) event = { event: 'turn_failed' };
+    if (p.type === 'item_completed') {
+      const item = p.item || {};
+      const categories = { CommandExecution: 's', FileChange: 'e', McpToolCall: 'm', WebSearch: 'w', ImageView: 'r' };
+      if (categories[item.type] && typeof item.id === 'string') event = { event: 'PostToolUse', category: categories[item.type], tool: anonymize(`tool:${item.id}`),
+        failed: item.status === 'failed' || typeof item.exit_code === 'number' && item.exit_code !== 0 };
+      if (item.type === 'ContextCompaction') event = { event: 'PreCompact' };
+    }
+  }
+  if (row.type === 'token_usage_record') {
+    // token 本身由同一文件的去重响应表投影；这里仅记录最近活动，不能用它断言一轮完成。
+    s.lastAt = Math.max(s.lastAt, context.at);
+  }
+  if (event) observe(s, { ...context, ...event });
+}
+function mergeSession(a, b) {
+  if (!a) return structuredClone(b);
+  const latest = b.lastAt > a.lastAt || b.lastAt === a.lastAt && b.evidence === 'hook' ? b : a;
+  const merged = { ...latest, startAt: Math.min(a.startAt, b.startAt), turns: {} };
+  for (const source of [a, b]) for (const [key, t] of Object.entries(source.turns)) {
+    const prev = merged.turns[key];
+    if (!prev) merged.turns[key] = structuredClone(t);
+    else {
+      const newer = t.lastAt >= prev.lastAt ? t : prev;
+      merged.turns[key] = { ...newer, n: Math.max(prev.n, t.n), s: Math.min(prev.s, t.s),
+        e: Math.max(prev.e || 0, t.e || 0) || null, tools: { ...prev.tools, ...t.tools }, perm: Math.max(prev.perm, t.perm), compactions: Math.max(prev.compactions, t.compactions) };
+    }
+  }
+  merged.agents = { ...a.agents, ...b.agents };
+  const goal = (a.goalUpdatedAt || 0) > (b.goalUpdatedAt || 0) ? a : b;
+  if (goal.goalUpdatedAt) { merged.goalStatus = goal.goalStatus; merged.goalUpdatedAt = goal.goalUpdatedAt; merged.goalCompleteAt = goal.goalCompleteAt; }
+  return merged;
+}
+function sequence(tools) {
+  const groups = [];
+  for (const t of tools) { const prev = groups.at(-1); if (prev && prev[0] === t.category && prev[1] < 9999) prev[1]++; else groups.push([t.category, 1]); }
+  return groups.slice(-40).map((g) => g.join('')).join('');
+}
+function buildLive(state, options = {}) {
+  const now = options.now || Date.now(), sessions = new Map(), records = new Map();
+  for (const f of Object.values(state.files || {})) {
+    if (f.live) sessions.set(f.live.session, mergeSession(sessions.get(f.live.session), f.live));
+    for (const [id, r] of Object.entries(f.records || {})) if (!records.has(id) || r.at >= records.get(id).at) records.set(id, r);
+  }
+  for (const s of Object.values(state.liveHooks?.sessions || {})) sessions.set(s.session, mergeSession(sessions.get(s.session), s));
+  const tokenTotals = new Map();
+  for (const r of records.values()) {
+    if (r.at < now - KEEP || !r.turn) continue;
+    const key = `${r.session}:${r.turn}`, total = tokenTotals.get(key) || { input: 0, output: 0 };
+    total.input += r.usage.input; total.output += r.usage.output; tokenTotals.set(key, total);
+  }
+  const payload = [];
+  for (const s of sessions.values()) {
+    if (s.lastAt < now - KEEP || s.lastAt > now + 300000) continue;
+    const turns = Object.values(s.turns).sort((a, b) => a.s - b.s).slice(-60).map((t, i) => {
+      const tools = Object.values(t.tools).sort((a, b) => a.s - b.s);
+      const { input = 0, output = 0 } = tokenTotals.get(`${s.session}:${t.key}`) || {};
+      const longest = tools.filter((x) => x.e).sort((a, b) => (b.e - b.s) - (a.e - a.s))[0];
+      return { id: t.key.slice(0, 16), n: t.n, s: t.s, e: t.e, end: t.end, perm: t.perm + (t.waitingSince ? Math.max(0, now - t.waitingSince) : 0),
+        tools: tools.length, seq: sequence(tools), cells: tools.slice(-90).map((x) => x.category).join(''),
+        long: longest ? [longest.category, longest.e - longest.s] : null, in: input, out: output, cw: 0,
+        err: tools.filter((x) => x.failed).length, cmp: t.compactions };
+    });
+    const current = Object.values(s.turns).find((t) => t.key === s.turn);
+    const lastTools = Object.values(current?.tools || {}).sort((a, b) => a.s - b.s);
+    let failures = 0; for (const tool of [...lastTools].reverse()) { if (!tool.failed) break; failures++; }
+    payload.push({ sid: s.session.slice(0, 16), proj: s.project?.slice(0, 16) || null,
+      state: s.state, changedAt: s.changedAt, changeKind: s.changeKind, startAt: s.startAt, lastAt: s.lastAt,
+      // 扫描器仍在运行不能证明 Codex 会话仍在运行；心跳只使用真实事件时刻。
+      beatAt: s.lastAt, endAt: s.endAt, permSince: s.permSince, model: s.model, turns,
+      tools: turns.reduce((n, t) => n + t.tools, 0), errors: turns.reduce((n, t) => n + t.err, 0),
+      compactions: turns.reduce((n, t) => n + t.cmp, 0), fs: failures, subs: Object.values(s.agents).map((a) => [a.s, a.e || 0, 0]),
+      ...(s.goalStatus ? { goalStatus: s.goalStatus, goalCompleteAt: s.goalCompleteAt || null } : {}),
+      ...(options.projects && s.projectName ? { pname: s.projectName } : {}) });
+  }
+  payload.sort((a, b) => Number(['ended', 'lost'].includes(a.state)) - Number(['ended', 'lost'].includes(b.state)) || b.lastAt - a.lastAt);
+  const body = { tier: options.projects ? 2 : 1, devNow: now, sessions: payload.slice(0, 40) };
+  // 保留每个会话的当前轮，再裁旧轮；绝不因为体积大而整批永远上传失败。
+  while (Buffer.byteLength(JSON.stringify(body)) > 60 * 1024) {
+    const largest = body.sessions.filter((s) => s.turns.length > 1).sort((a, b) => b.turns.length - a.turns.length)[0];
+    if (largest) { largest.turns.shift(); largest.clippedTurns = (largest.clippedTurns || 0) + 1; }
+    else if (body.sessions.length > 1) body.sessions.pop();
+    else break;
+  }
+  return body;
+}
+module.exports = { EVENTS, category, sanitizeHook, createSession, observe, absorbHook, absorbLog, buildLive };

package/lib/quota.cjs

@@ -0,0 +1,80 @@
+'use strict';
+const { spawn } = require('node:child_process');
+const readline = require('node:readline');
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+const { quota, hash } = require('./collect.cjs');
+
+// 只建立协议连接并读取额度，不创建、恢复或修改会话，不读取登录凭证文件。
+function readQuota({ binary = process.env.NUMABLE_CODEX_BINARY || 'codex', home, salt, timeoutMs = 15000, prefixArgs = [] } = {}) {
+  if (!salt) return Promise.reject(new Error('读取额度缺少本机匿名化配置'));
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, [...prefixArgs, 'app-server', '--listen', 'stdio://'], {
+      env: { ...process.env, ...(home ? { CODEX_HOME: home } : {}) }, stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true,
+    });
+    const lines = readline.createInterface({ input: child.stdout });
+    let done = false;
+    const timer = setTimeout(() => finish(new Error('额度读取超时，请稍后重试')), timeoutMs);
+    const finish = (error, result) => {
+      if (done) return; done = true;
+      clearTimeout(timer); lines.close(); child.stdin.end();
+      const killTimer = setTimeout(() => child.kill(), 1000); killTimer.unref();
+      child.once('close', () => clearTimeout(killTimer));
+      error ? reject(error) : resolve(result);
+    };
+    const send = (message) => { if (!done) child.stdin.write(JSON.stringify(message) + '\n'); };
+    child.once('error', () => finish(new Error('Codex 命令无法启动，请检查安装或指定可执行文件')));
+    child.stdin.on('error', () => finish(new Error('Codex 协议连接已关闭，请检查安装后重试')));
+    child.once('close', () => { if (!done) finish(new Error('Codex 在返回额度前退出')); });
+    lines.on('line', (line) => {
+      if (done || line.length > 1024 * 1024) return;
+      let r; try { r = JSON.parse(line); } catch { return; }
+      if (r.id === 1) {
+        if (r.error) return finish(new Error('当前 Codex 不支持额度协议初始化'));
+        send({ method: 'initialized', params: {} });
+        send({ id: 2, method: 'account/rateLimits/read' });
+      }
+      if (r.id === 2) {
+        if (r.error) return finish(new Error('当前账号无法读取额度，请检查 Codex 登录状态'));
+        const result = r.result || {}, observedAt = Date.now();
+        const buckets = result.rateLimitsByLimitId && typeof result.rateLimitsByLimitId === 'object'
+          ? Object.entries(result.rateLimitsByLimitId).map(([key, bucket]) => ({ ...bucket, limitId: bucket?.limitId || key }))
+          : [result.rateLimits];
+        const account = typeof result.accountId === 'string' && result.accountId ? hash(salt, `account:${result.accountId}`) : null;
+        const quotas = buckets.map((bucket) => quota(bucket, observedAt)).filter(Boolean).map((q) => ({ ...q, account, origin: 'rpc' }));
+        finish(null, { observedAt, scope: hash(salt, 'quota-scope'), supported: quotas.length > 0, quotas });
+      }
+    });
+    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'numable_codex_usage', version: '0.1.0' }, capabilities: { experimentalApi: true } } });
+  });
+}
+async function readQuotaHomes({ homes, salt, profileSalt = salt, previous, ...options }) {
+  const readOne = async (home) => {
+    try { return await readQuota({ ...options, home, salt }); }
+    catch (error) {
+      if (options.binary || process.env.NUMABLE_CODEX_BINARY || process.platform !== 'darwin') throw error;
+      const relative = 'ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex';
+      const candidates = [path.join('/Applications', relative), path.join(os.homedir(), 'Applications', relative)];
+      for (const binary of candidates) if (fs.existsSync(binary)) {
+        try { return await readQuota({ ...options, binary, home, salt }); } catch {}
+      }
+      throw error;
+    }
+  };
+  const results = await Promise.allSettled(homes.map(readOne));
+  const quotas = [];
+  let failures = 0;
+  results.forEach((r, i) => {
+    const profile = hash(profileSalt, `profile:${path.resolve(homes[i])}`);
+    if (r.status !== 'fulfilled') {
+      failures++;
+      if (previous?.scope === hash(salt, 'quota-scope')) quotas.push(...(previous.quotas || []).filter((q) => q.profile === profile));
+      return;
+    }
+    quotas.push(...r.value.quotas.map((q) => ({ ...q, profile })));
+  });
+  return { observedAt: Date.now(), scope: hash(salt, 'quota-scope'), supported: quotas.length > 0,
+    failures, profileCount: homes.length, quotas };
+}
+module.exports = { readQuota, readQuotaHomes };

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "numable-codex-usage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "在本机统计 Codex 用量，并按需同步到 Numable",
+  "license": "MIT",
+  "engines": { "node": ">=18.17" },
+  "bin": { "numable-codex": "cli.cjs" },
+  "files": ["cli.cjs", "lib/", "README.md"],
+  "scripts": { "test": "node --test ../test/codex-*.test.cjs" }
+}