tokenphage 2026.7.1-BETA → 2026.8.1

package/README.md

@@ -5,7 +5,7 @@
 
 > 먹어치운 토큰, 이젠 README에 기록하세요!
 
-Claude Code와 Codex의 토큰 사용량을 모아 GitHub README에 붙일 수 있는 배지로 만들어 줍니다.
+Claude Code, Codex, opencode의 토큰 사용량을 모아 GitHub README에 붙일 수 있는 배지로 만들어 줍니다.
 
 ---
 
@@ -20,7 +20,7 @@ Claude Code와 Codex의 토큰 사용량을 모아 GitHub README에 붙일 수
 GitHub README(이미지를 붙일 수 있는 곳이면 어디든)에 아래 한 줄만 넣으면 됩니다. `kobenlys`를 본인 GitHub 아이디로 바꾸세요.
 
 ```markdown
-[![TokenPhage](https://api.tokenphage.com/badge/kobenlys)](https://github.com/TOKENPHAGE/tokenphage-api)
+[![TokenPhage](https://api.tokenphage.com/badge/kobenlys)](https://github.com/TOKENPHAGE)
 ```
 
 **결과 ↓**
@@ -32,11 +32,11 @@ GitHub README(이미지를 붙일 수 있는 곳이면 어디든)에 아래 한
   </tr>
   <tr>
     <td align="center">
-      <a href="https://github.com/TOKENPHAGE/tokenphage-api"><img src="https://api.tokenphage.com/badge/kobenlys?theme=gpu&amp;mode=dark" alt="TokenPhage gpu dark 배지"></a><br/>
+      <a href="https://github.com/TOKENPHAGE"><img src="https://api.tokenphage.com/badge/kobenlys?theme=gpu&amp;mode=dark" alt="TokenPhage gpu dark 배지"></a><br/>
       <code>https://api.tokenphage.com/badge/kobenlys?theme=gpu&amp;mode=dark</code>
     </td>
     <td align="center">
-      <a href="https://github.com/TOKENPHAGE/tokenphage-api"><img src="https://api.tokenphage.com/badge/kobenlys?theme=claude&amp;mode=light" alt="TokenPhage claude light 배지"></a><br/>
+      <a href="https://github.com/TOKENPHAGE"><img src="https://api.tokenphage.com/badge/kobenlys?theme=claude&amp;mode=light" alt="TokenPhage claude light 배지"></a><br/>
       <code>https://api.tokenphage.com/badge/kobenlys?theme=claude&amp;mode=light</code>
     </td>
   </tr>
@@ -54,7 +54,7 @@ npm install -g tokenphage@latest
 
 ### ⬆️ 업데이트
 
-CLI를 실행하면(대시보드를 열거나 `sync` 할 때) 새 버전이 있는지 확인합니다. 매번 조회하지는 않고, 과도한 요청을 막기 위해 **최대 하루 한 번**만 npm에 물어봅니다(24시간 캐시). 새 버전이 확인되면 대시보드 맨 위에 안내 배너가 뜨고, 메뉴에 **⬆ Update to …** 항목이 추가됩니다. 이 항목을 고르면 최신 버전이 자동으로 설치됩니다(전역 설치가 아니면 정확한 수동 명령을 안내).
+대시보드를 열면 새 버전이 있는지 확인합니다. 새 버전이 확인되면 대시보드 맨 위에 안내 배너가 뜨고, 메뉴에 **⬆ Update to …** 항목이 추가됩니다. 이 항목을 고르면 최신 버전이 자동으로 설치됩니다(전역 설치가 아니면 정확한 수동 명령을 안내).
 
 직접 올리고 싶다면 언제든 아래 명령을 실행하면 됩니다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenphage",
-  "version": "2026.7.1-BETA",
+  "version": "2026.8.1",
   "description": "AI 토큰 사용량 GitHub README 뱃지",
   "author": "kobenlys <kobenlys@gmail.com>",
   "license": "MIT",
@@ -19,7 +19,8 @@
   "scripts": {
     "start": "node src/index.js",
     "dev": "cross-env TOKENPHAGE_API=http://localhost:8080 node src/index.js",
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-exclude='test/**' --test-coverage-exclude='src/index.js' --test-coverage-exclude='src/ui.js' --test-coverage-exclude='src/animated-select.js' --test-coverage-exclude='src/gradient.js' --test-coverage-exclude='src/auth.js' --test-coverage-exclude='src/scheduler.js' --test-coverage-exclude='src/parser.js' --test-coverage-lines=80 --test-coverage-functions=80 test/*.test.js"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.5.0",

package/src/auth.js

@@ -93,17 +93,6 @@ export function clearLastSyncDate() {
   saveConfig(rest);
 }
 
-/** 업데이트 캐시(npm 최신버전·마지막 조회시각)를 반환한다. 없으면 각각 null. */
-export function getUpdateCache() {
-  const cfg = loadConfig();
-  return { latestVersion: cfg.latestVersion ?? null, lastUpdateCheck: cfg.lastUpdateCheck ?? null };
-}
-
-/** npm 최신버전과 조회시각(ISO)을 다른 설정을 보존한 채 갱신 저장한다. */
-export function saveUpdateCache(latestVersion, lastUpdateCheck) {
-  saveConfig({ ...loadConfig(), latestVersion, lastUpdateCheck });
-}
-
 // Gist 소유권 검증용 파일명 — 사용자가 이 이름으로 Gist를 만들어야 한다.
 export const VERIFICATION_FILE = 'tokenphage.txt';
 

package/src/hook-reconcile.js

@@ -0,0 +1,53 @@
+/**
+ * auto-sync 등록 정합성 복구.
+ * 설정(config.json)은 켜짐인데 OS 스케줄러에서 예약이 사라진 경우를 감지해 다시 등록한다.
+ *
+ * index.js가 아니라 별 모듈인 이유: index.js는 최상단에서 program.parse()를 실행하므로
+ * 테스트가 import하는 순간 CLI가 시동된다. lib/가 아닌 이유는 ui.js에 의존해
+ * 순수 로직 계층 규약에 맞지 않기 때문이다.
+ */
+import { loadConfig, setHookInstalled } from './auth.js';
+import { installHook, probeHookRegistration } from './scheduler.js';
+import { showError, pauseForEnter } from './ui.js';
+
+const ISSUE_HINT =
+  'Log: ~/.tokenphage/logs/sync.log — please report it: https://github.com/TOKENPHAGE/tokenphage-cli/issues';
+
+/**
+ * 설정은 auto-sync 켜짐인데 OS 스케줄러에 등록이 없으면 재등록한다.
+ *
+ * 헤드리스에서는 절대 재등록하지 않는다 — installMac()이 첫 단계로
+ * launchctlBootout()을 호출하는데, 그 프로세스가 바로 해당 launchd job이라 자기 자신을 내려
+ * SIGTERM으로 죽고 plist 작성에 도달하지 못한다. 그래서 호출 위치에만 의존하지 않고
+ * 함수 안에서 isTTY를 직접 확인해 구조적으로 막는다.
+ *
+ * 의존성은 전부 기본값으로 실제 구현이 배선돼 있다 — 호출부는 인자 없이 부르고 테스트만 대체한다.
+ * @param {{interactive?: boolean, readConfig?: Function, probe?: Function, install?: Function,
+ *          persist?: Function, onError?: Function, onPause?: Function}} [deps]
+ * @returns {Promise<boolean>} 등록을 초록으로 단정할 수 없으면 true (확인 불가 또는 재등록 실패)
+ */
+export async function reconcileHookRegistration({
+  interactive = Boolean(process.stdin.isTTY),
+  readConfig = loadConfig,
+  probe = probeHookRegistration,
+  install = installHook,
+  persist = setHookInstalled,
+  onError = showError,
+  onPause = pauseForEnter,
+} = {}) {
+  if (!interactive) return false;                          // 헤드리스: 자기 예약을 건드리지 않는다
+  if (readConfig().hookInstalled !== true) return false;   // 꺼짐(사용자 의사): 조회조차 하지 않는다
+
+  const state = probe();
+  if (state === 'registered') return false;
+  if (state === 'unknown') return true;                    // 판정 불가에서 재등록하면 정상 예약을 깬다
+
+  try {
+    persist(true, await install());                        // installHook은 멱등이라 그대로 재사용한다
+    return false;
+  } catch (err) {
+    onError('Auto-sync re-registration failed', err.message, ISSUE_HINT);
+    await onPause();
+    return true;                                           // 실패했으므로 초록으로 단정하지 않는다
+  }
+}

package/src/index.js

@@ -6,15 +6,16 @@
  */
 import { Command } from 'commander';
 import { parseAll } from './parser.js';
-import { loadToken, saveToken, getOrCreateDeviceId, gistLogin, setHookInstalled, getLastSyncDate, saveLastSyncDate, clearLastSyncDate } from './auth.js';
+import { loadConfig, loadToken, saveToken, getOrCreateDeviceId, gistLogin, setHookInstalled, getLastSyncDate, saveLastSyncDate, clearLastSyncDate } from './auth.js';
 import { syncRecords, resetData } from './sync.js';
 import { installHook, uninstallHook } from './scheduler.js';
+import { reconcileHookRegistration } from './hook-reconcile.js';
 import { promptFirstRun, promptDashboard, promptAdvanced, confirmReset, pauseForEnter, showError } from './ui.js';
 import { accent } from './gradient.js';
 import { localDateOf } from './lib/dates.js';
 import { claudeDirCandidates } from './parser.js';
 import { checkClaudeRetention, applyRetentionSetting, DEFAULT_CLEANUP_DAYS } from './lib/retention.js';
-import { refreshCache, getUpdateInfo } from './lib/update-check.js';
+import { checkLatestVersion, getUpdateInfo } from './lib/update-check.js';
 import { runUpdate } from './lib/updater.js';
 import { confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
@@ -136,7 +137,7 @@ async function runSync() {
   const lastSyncDate = getLastSyncDate();
   const fromDate = lastSyncDate ?? null;
 
-  console.log(`Parsing local JSONL... (${fromDate ?? 'beginning'} ~ ${today})`);
+  console.log(`Parsing local logs... (${fromDate ?? 'beginning'} ~ ${today})`);
   const records = await parseAll(fromDate);
   console.log(`${records.length} records aggregated (date×model)`);
   if (records.length === 0) {
@@ -149,10 +150,6 @@ async function runSync() {
   await syncRecords(API_BASE, token, deviceId, records);
   saveLastSyncDate(today);
   console.log('Done! Badge will update shortly.');
-
-  // 이미 네트워크를 쓰는 지점이므로 여기서 npm 최신버전 캐시를 갱신한다(TTL 게이트 내장, 실패 무해).
-  // 04:00 자동 sync가 이 경로로 캐시를 채워, 다음 대시보드 진입 시 업데이트 배너가 뜬다.
-  await refreshCache(Date.now());
 }
 
 /**
@@ -243,14 +240,14 @@ program.action(async () => {
       }
     }
 
-    // 인증 이후 메뉴는 최신 설정이 필요하므로 여기서 동적 import (상단 정적 import과 별개)
-    const { loadConfig } = await import('./auth.js');
-    // 업데이트 캐시를 백그라운드로 갱신한다(await 안 함 → startup 지연 0). 결과는 다음 렌더에 반영된다.
-    refreshCache(Date.now()).catch(() => {});
+    // TUI 진입 시 npm 최신버전을 1회 조회(짧은 타임아웃). 세션 동안 재사용해 배너/메뉴에 반영한다.
+    const latest = await checkLatestVersion();
+    // 대시보드 진입 전 1회: 설정만 켜져 있고 OS 스케줄러에서 사라졌으면 여기서 되살린다.
+    const hookUnverified = await reconcileHookRegistration();
     // 대시보드 루프: 액션 수행 후 메인으로 복귀, Exit/Esc 에서만 종료
     while (true) {
       const cfg = loadConfig();
-      const action = await promptDashboard(cfg);
+      const action = await promptDashboard(cfg, latest, hookUnverified);
       if (action === 'exit') break;
       if (action === 'sync') await runSync();
       else if (action === 'install-hook') await runInstallHook();
@@ -258,7 +255,7 @@ program.action(async () => {
       else if (action === 'advanced') await runAdvanced(API_BASE, cfg);
       else if (action === 'update') {
         // 업데이트 성공 시 현재 프로세스는 여전히 구버전 코드 → 재실행 안내 후 종료.
-        const { hasUpdate, latest } = getUpdateInfo(version, cfg);
+        const { hasUpdate } = getUpdateInfo(version, latest);
         if (hasUpdate) {
           const result = await runUpdate(latest);
           await pauseForEnter();
@@ -297,9 +294,9 @@ program.command('login [username]')
     }
   });
 
-// sync: 로컬 Claude/Codex 로그를 파싱해 서버로 업로드한다(배지 갱신). 미인증이면 안내 후 종료.
+// sync: 로컬 Claude Code/Codex/opencode 로그를 파싱해 서버로 업로드한다(배지 갱신). 미인증이면 안내 후 종료.
 program.command('sync')
-  .description('Sync local Claude Code token usage to the server')
+  .description('Sync local token usage (Claude Code, Codex, opencode) to the server')
   .action(async () => {
     try { await runSync(); }
     catch (err) { showError('Sync failed', err.message); process.exitCode = 1; }

package/src/lib/config-schema.js

@@ -84,9 +84,7 @@ export function normalizeConfig(raw, today) {
   dropIf('deviceId', isUuid);                         // 없으면 getOrCreateDeviceId가 재발급
   dropIf('lastSyncDate', (v) => isYmdDate(v, today)); // 없으면 전체 재파싱
   dropIf('hookInstalledAt', isIsoDate);
-  dropIf('lastUpdateCheck', isIsoDate);
   dropIf('hookInstalled', (v) => typeof v === 'boolean');
-  dropIf('latestVersion', (v) => typeof v === 'string');
   dropIf('claudePaths', isStringArray);
   dropIf('hookMeta', (v) => v != null && typeof v === 'object' && !Array.isArray(v));
 

package/src/lib/paths.js

@@ -1,7 +1,9 @@
 import { join, resolve } from 'path';
 
-// Claude 설정 디렉터리 후보를 우선순위 순으로 만든다.
-// 순서: 기본(~/.claude) → XDG($XDG_CONFIG_HOME/claude, 기본 ~/.config/claude) → 사용자 지정.
+// AI 도구별 로컬 디렉터리 후보를 우선순위 순으로 만든다.
+//  - Claude: 설정(config) 디렉터리. 기본(~/.claude) → XDG($XDG_CONFIG_HOME/claude) → 사용자 지정.
+//  - opencode: 데이터(data) 디렉터리. XDG($XDG_DATA_HOME, 기본 ~/.local/share)/opencode → 사용자 지정.
+//    (opencode는 세션을 <data>/opencode/storage/... 에 저장하므로 config가 아니라 data home 기준이다.)
 
 function expandTilde(p, home) {
   if (p === '~') return home;
@@ -9,8 +11,30 @@ function expandTilde(p, home) {
   return p;
 }
 
+// 후보 경로들을 절대경로로 normalize하고 순서를 유지한 채 중복을 제거한다.
+function normalizeUnique(candidates) {
+  const seen = new Set();
+  const dirs = [];
+  for (const candidate of candidates) {
+    const normalized = resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    dirs.push(normalized);
+  }
+  return dirs;
+}
+
+// 외부 입력(config.json 등)의 customPaths를 검증한다: 문자열 배열만 인정, 틸드는 home으로 확장.
+function cleanCustomPaths(customPaths, home) {
+  if (!Array.isArray(customPaths)) return [];
+  return customPaths
+    .filter((p) => typeof p === 'string' && p.trim())
+    .map((p) => expandTilde(p.trim(), home));
+}
+
 /**
  * Claude 설정 디렉터리 후보 목록을 우선순위 순으로 반환한다.
+ * 순서: 기본(~/.claude) → XDG($XDG_CONFIG_HOME/claude, 기본 ~/.config/claude) → 사용자 지정.
  * @param {{ home: string, xdgConfigHome?: string, customPaths?: string[] }} opts
  *   home: 사용자 홈, xdgConfigHome: $XDG_CONFIG_HOME, customPaths: config.json의 claudePaths
  * @returns {string[]} normalize·중복 제거된 절대 경로 목록
@@ -20,24 +44,28 @@ export function resolveClaudeDirs({ home, xdgConfigHome, customPaths } = {}) {
     ? xdgConfigHome
     : join(home, '.config');
 
-  // 외부 입력(config.json) 검증: 문자열 배열만 인정, 그 외는 통째로 무시
-  const custom = Array.isArray(customPaths)
-    ? customPaths.filter((p) => typeof p === 'string' && p.trim())
-    : [];
-
-  const candidates = [
+  return normalizeUnique([
     join(home, '.claude'),
     join(xdgBase, 'claude'),
-    ...custom.map((p) => expandTilde(p.trim(), home)),
-  ];
+    ...cleanCustomPaths(customPaths, home),
+  ]);
+}
 
-  const seen = new Set();
-  const dirs = [];
-  for (const candidate of candidates) {
-    const normalized = resolve(candidate);
-    if (seen.has(normalized)) continue;
-    seen.add(normalized);
-    dirs.push(normalized);
-  }
-  return dirs;
+/**
+ * opencode 데이터 디렉터리 후보 목록을 우선순위 순으로 반환한다.
+ * 순서: XDG($XDG_DATA_HOME/opencode, 기본 ~/.local/share/opencode) → 사용자 지정.
+ * Claude(config home 기준)와 달리 data home 기준임에 주의.
+ * @param {{ home: string, xdgDataHome?: string, customPaths?: string[] }} opts
+ *   home: 사용자 홈, xdgDataHome: $XDG_DATA_HOME, customPaths: 사용자 지정 opencode 디렉터리
+ * @returns {string[]} normalize·중복 제거된 절대 경로 목록
+ */
+export function resolveOpencodeDirs({ home, xdgDataHome, customPaths } = {}) {
+  const xdgBase = typeof xdgDataHome === 'string' && xdgDataHome.trim()
+    ? xdgDataHome
+    : join(home, '.local', 'share');
+
+  return normalizeUnique([
+    join(xdgBase, 'opencode'),
+    ...cleanCustomPaths(customPaths, home),
+  ]);
 }

package/src/lib/update-check.js

@@ -1,53 +1,19 @@
 /**
- * CLI 업데이트 검사: npm 레지스트리에서 최신버전을 조회해 config.json에 캐시하고,
- * 현재 버전과 비교해 업데이트 여부를 판정한다.
+ * CLI 업데이트 검사: TUI(대시보드) 진입 시 npm 레지스트리에서 latest를 1회 조회하고,
+ * 현재 버전과 문자열이 다르면 업데이트가 있다고 판정한다.
  *
  * 설계 원칙
- *  - 화면(메인 대시보드)은 캐시(getUpdateInfo)만 읽어 즉시 렌더 → startup 지연 0.
- *  - 네트워크 조회(refreshCache)는 백그라운드/sync 시점에 돌아 캐시를 채우고, 결과는 "다음 렌더"에 반영된다.
- *  - 어떤 실패(네트워크·404·파싱·옵트아웃)도 조용히 흘려보내 본 기능(대시보드)을 절대 막지 않는다.
+ *  - update 제안은 대화형 TUI에서만 뜬다. 비대화형(sync·스크립트)은 대상 아님 → 캐시/TTL 불필요.
+ *  - checkLatestVersion()을 TUI 진입 시 1회 await로 호출(짧은 타임아웃), 결과를 세션 메모리에 담아 배너 판정에 쓴다.
+ *  - 어떤 실패(네트워크·404·파싱·옵트아웃)도 조용히 null로 흘려보내 대시보드를 절대 막지 않는다.
  */
-import { loadConfig, saveUpdateCache } from '../auth.js';
 
 // 배포 패키지명 — 레지스트리 URL과 `npm i -g` 대상에서 공유한다.
 export const PACKAGE_NAME = 'tokenphage';
 // npm 레지스트리 latest 매니페스트(공개·무인증). { "version": "", ... } 반환, 미배포면 404.
 export const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
 
-const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h TTL — 하루 1회만 조회
-const FETCH_TIMEOUT_MS = 2500;                 // 레지스트리 지연이 sync를 끌지 않도록 상한
-
-/**
- * CalVer "YYYY.M.PATCH" 두 버전을 숫자 3파트로 비교한다.
- * @returns {-1|0|1} a<b → -1, a==b → 0, a>b → 1. 어느 한쪽이라도 비숫자(dev 등)면 0(=차이 없음)으로 안전 폴백.
- */
-export function compareVersion(a, b) {
-  const pa = String(a).split('.').map(Number);
-  const pb = String(b).split('.').map(Number);
-  // CalVer는 정확히 3파트여야 한다. 형식이 어긋나면(2파트/4파트/dev 등) 비교 불가로 보고 0(=업데이트 없음) 폴백.
-  if (pa.length !== 3 || pb.length !== 3) return 0;
-  for (let i = 0; i < 3; i++) {
-    const x = pa[i];
-    const y = pb[i];
-    if (Number.isNaN(x) || Number.isNaN(y)) return 0; // 비CalVer → 비교 불가 → 업데이트 없음
-    if (x > y) return 1;
-    if (x < y) return -1;
-  }
-  return 0;
-}
-
-/**
- * 마지막 조회 이후 TTL(24h)이 지났는지 판정한다. now는 인자로 주입해 테스트 결정성을 확보한다.
- * @param {string|null} lastUpdateCheck 마지막 조회 ISO 시각 (없으면 null)
- * @param {number} now 현재 epoch ms
- * @returns {boolean} 조회가 필요하면 true
- */
-export function shouldCheck(lastUpdateCheck, now) {
-  if (!lastUpdateCheck) return true;
-  const last = Date.parse(lastUpdateCheck);
-  if (Number.isNaN(last)) return true; // 손상된 시각 → 재조회
-  return now - last >= CHECK_INTERVAL_MS;
-}
+const FETCH_TIMEOUT_MS = 1500; // TUI 진입 조회 상한 — 오프라인/지연 시 이 시간 후 배너 없이 진행
 
 /** 업데이트 알림을 끄는 환경인지. 옵트아웃 env 또는 dev(TOKENPHAGE_API 세팅)면 조회·표시 모두 스킵. */
 export function isUpdateNotifierDisabled() {
@@ -55,23 +21,27 @@ export function isUpdateNotifierDisabled() {
 }
 
 /**
- * 캐시(cfg.latestVersion)와 현재 버전을 비교해 업데이트 정보를 반환한다. 네트워크를 쓰지 않는 동기 함수.
+ * 조회한 latest와 현재 버전을 비교해 업데이트 정보를 반환한다. 순수 함수(네트워크·env·캐시 없음).
+ * update 액션은 항상 `@latest`를 설치하므로 "설치본 ≠ latest"가 곧 "업데이트하면 바뀜"과 일치한다.
+ * 프리릴리스 접미사(-BETA)도 파싱 없이 문자열 비교라 안전하다.
  * @param {string} currentVersion 현재 설치 버전(package.json)
- * @param {object} cfg loadConfig() 결과(또는 동등한 객체)
+ * @param {string|null|undefined} latest checkLatestVersion() 결과(조회 실패/옵트아웃 시 null)
  * @returns {{hasUpdate:boolean, latest?:string, current?:string}}
  */
-export function getUpdateInfo(currentVersion, cfg) {
-  if (isUpdateNotifierDisabled()) return { hasUpdate: false };
-  const latest = cfg?.latestVersion;
-  if (!latest) return { hasUpdate: false };
-  if (compareVersion(latest, currentVersion) > 0) {
+export function getUpdateInfo(currentVersion, latest) {
+  if (latest && latest !== currentVersion) {
     return { hasUpdate: true, latest, current: currentVersion };
   }
   return { hasUpdate: false };
 }
 
-/** npm 레지스트리에서 latest 버전 문자열을 조회한다. 실패(타임아웃·404·파싱)는 모두 null. */
-async function fetchLatestFromNpm() {
+/**
+ * npm 레지스트리에서 latest 버전 문자열을 1회 조회한다. TUI 진입 시 한 번 await로 호출해 세션 동안 재사용한다.
+ * 옵트아웃/실패(타임아웃·404·파싱)는 모두 null — 절대 throw하지 않는다.
+ * @returns {Promise<string|null>}
+ */
+export async function checkLatestVersion() {
+  if (isUpdateNotifierDisabled()) return null; // 옵트아웃/dev → 조회 스킵
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   try {
@@ -85,20 +55,3 @@ async function fetchLatestFromNpm() {
     clearTimeout(timer);
   }
 }
-
-/**
- * TTL이 지났으면 npm 최신버전을 조회해 config 캐시를 갱신한다. 절대 throw하지 않는다.
- * @param {number} now 현재 epoch ms (Date.now()를 주입)
- */
-export async function refreshCache(now) {
-  try {
-    if (isUpdateNotifierDisabled()) return;
-    const cfg = loadConfig();
-    if (!shouldCheck(cfg.lastUpdateCheck, now)) return;
-    const latest = await fetchLatestFromNpm();
-    if (!latest) return;
-    saveUpdateCache(latest, new Date(now).toISOString());
-  } catch {
-    // 캐시 갱신 실패는 무해 — 다음 기회에 재시도한다.
-  }
-}

package/src/parser.js

@@ -2,7 +2,8 @@ import { glob } from 'glob';
 import { homedir } from 'os';
 import { parseClaudeFiles } from './parsers/claude.js';
 import { parseCodexFiles } from './parsers/codex.js';
-import { resolveClaudeDirs } from './lib/paths.js';
+import { parseOpencodeFiles } from './parsers/opencode.js';
+import { resolveClaudeDirs, resolveOpencodeDirs } from './lib/paths.js';
 import { getCustomClaudePaths } from './auth.js';
 
 /**
@@ -41,6 +42,14 @@ export function claudeDirCandidates() {
   });
 }
 
+/** opencode 데이터 디렉터리 후보(XDG data home 기준)를 우선순위 순으로 반환한다. */
+export function opencodeDirCandidates() {
+  return resolveOpencodeDirs({
+    home: homedir(),
+    xdgDataHome: process.env.XDG_DATA_HOME,
+  });
+}
+
 export async function parseAll(fromDate = null) {
   // 경로가 겹쳐도 파일 간 first-wins dedup이 흡수하므로 순서만 보장하면 된다.
   const claudeFiles = [];
@@ -55,9 +64,19 @@ export async function parseAll(fromDate = null) {
     ...(await globSorted(`${codexHome}/archived_sessions/**/*.jsonl`)),
   ];
 
-  const [claudeEntries, codexEntries] = await Promise.all([
+  // opencode는 message(모델·시각)와 part(step-finish 토큰)를 모두 읽어야 조인할 수 있다.
+  // parseOpencodeFiles가 내용으로 분류하므로 두 목록을 합쳐 넘긴다(순서 무관).
+  const opencodeFiles = [];
+  for (const dir of opencodeDirCandidates()) {
+    const base = dir.replaceAll('\\', '/');
+    opencodeFiles.push(...await globSorted(`${base}/storage/message/**/*.json`));
+    opencodeFiles.push(...await globSorted(`${base}/storage/part/**/*.json`));
+  }
+
+  const [claudeEntries, codexEntries, opencodeEntries] = await Promise.all([
     parseClaudeFiles(claudeFiles),
     parseCodexFiles(codexFiles),
+    parseOpencodeFiles(opencodeFiles),
   ]);
-  return aggregateRecords([...claudeEntries, ...codexEntries], fromDate);
+  return aggregateRecords([...claudeEntries, ...codexEntries, ...opencodeEntries], fromDate);
 }

package/src/parsers/opencode.js

@@ -0,0 +1,65 @@
+import { readFile } from 'fs/promises';
+import { localDateOf } from '../lib/dates.js';
+
+// opencode(sst) 세션 저장 파서.
+// opencode는 턴당 assistant 메시지 1개에 스텝마다 tokens를 덮어써(=) 마지막 스텝만 남기므로,
+// 스텝별 토큰이 보존된 step-finish part(storage/part/<messageID>/*.json)를 전부 합산해야 정확하다.
+// 전략:
+//  - message(role==='assistant')에서 id→{model, date}를 모으고, step-finish part를 messageID로 조인한다.
+//  - 입력 파일 목록에 message/part가 섞여 오고 순서 보장이 없으므로, 두 맵을 모은 뒤 마지막에 조인한다.
+//  - 필드 매핑(claude/codex와 정합): opencode getUsage가 input은 캐시 제외로, output은 reasoning 제외로
+//    저장하므로 → inputTok은 그대로, outputTok은 output+reasoning으로 reasoning을 되살린다.
+//    cache.write는 cacheCreate로 둔다(opencode는 Anthropic cacheCreation을 여기 담는다).
+//  - 손상 파일·부모 없는 part·모델/날짜 없는 메시지는 집계에서 제외한다.
+
+// step-finish part의 tokens를 tokenphage 레코드 4필드로 매핑한다. 음수 방어로 max(…,0).
+function entryOf(date, model, tokens) {
+  const cache = tokens.cache ?? {};
+  return {
+    date,
+    model,
+    inputTok: Math.max(tokens.input ?? 0, 0),
+    // opencode는 output에서 reasoning을 미리 뺐으므로 되살려 청구 기준(claude/codex)과 맞춘다.
+    outputTok: Math.max(tokens.output ?? 0, 0) + Math.max(tokens.reasoning ?? 0, 0),
+    cacheReadTok: Math.max(cache.read ?? 0, 0),
+    cacheCreateTok: Math.max(cache.write ?? 0, 0),
+  };
+}
+
+/**
+ * opencode message/part 파일들을 스텝(step-finish) 단위 usage 목록으로 파싱한다.
+ * @param {string[]} files 메시지·파트 JSON 파일 경로 목록 (섞여 있어도 됨)
+ * @returns {Promise<Array<{date: string, model: string, inputTok: number, outputTok: number, cacheReadTok: number, cacheCreateTok: number}>>}
+ */
+export async function parseOpencodeFiles(files) {
+  const messageMeta = new Map(); // messageID → { model, date }
+  const stepParts = [];          // { messageID, tokens }
+
+  for (const file of files) {
+    let obj;
+    try {
+      obj = JSON.parse(await readFile(file, 'utf8'));
+    } catch { continue; } // 읽기 실패·손상 JSON skip
+    if (!obj) continue;
+
+    if (obj.role === 'assistant') {
+      // 모델·날짜를 못 만들면 이 메시지의 파트는 귀속 불가 → 맵에 넣지 않는다.
+      if (!obj.id || !obj.modelID) continue;
+      const date = localDateOf(obj.time?.created);
+      if (!date) continue;
+      messageMeta.set(obj.id, { model: obj.modelID, date });
+    } else if (obj.type === 'step-finish') {
+      if (!obj.messageID || !obj.tokens) continue;
+      stepParts.push({ messageID: obj.messageID, tokens: obj.tokens });
+    }
+    // 그 외(user 메시지, 다른 part, session/project 파일)는 무시
+  }
+
+  const entries = [];
+  for (const part of stepParts) {
+    const meta = messageMeta.get(part.messageID);
+    if (!meta) continue; // 부모 메시지 없음/모델·날짜 무효 → skip
+    entries.push(entryOf(meta.date, meta.model, part.tokens));
+  }
+  return entries;
+}

package/src/scheduler.js

@@ -493,10 +493,11 @@ function hasCrontab() {
 // 현재 사용자 crontab 전체를 반환한다. '확정된 빈 crontab'만 ''로 취급하고,
 // 그 외 읽기 실패는 fail-closed로 throw한다 — 이 값이 crontab 전체 재기록의 base가
 // 되므로, 애매한 실패를 ''로 흡수하면 사용자의 기존 항목을 통째로 덮어쓸 수 있다.
-function readCrontab() {
+// run/timeout은 조회 경로와 테스트를 위한 주입 지점이다 — 기본값이 실제 동작이라 설치 경로는 그대로다.
+function readCrontab(run = execFileSync, timeout = undefined) {
   try {
     // maxBuffer 상향: 대형(정상) crontab이 기본 1MB를 넘겨 ENOBUFS로 오인 실패하는 것을 막는다.
-    return execFileSync('crontab', ['-l'], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+    return run('crontab', ['-l'], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, timeout });
   } catch (err) {
     // 빈 crontab: exit≠0 + stderr 'no crontab for <user>' → 이때만 빈 문자열(잃을 항목 없음).
     const stderr = (err.stderr?.toString() || '').toLowerCase();
@@ -588,6 +589,68 @@ function uninstallLinux() {
   return { platform: 'linux', removed };
 }
 
+// ─── 등록 상태 조회 ───────────────────────────────────────────────────────────
+
+// 조회가 멈추면 CLI 진입이 그대로 블로킹된다 (update-check.js의 FETCH_TIMEOUT_MS와 같은 이유).
+const PROBE_TIMEOUT_MS = 3000;
+
+/**
+ * launchctl 실패를 등록 상태로 분류한다. 113(서비스 없음)만 확정적 미등록이며,
+ * 112(도메인 없음 — SSH 등 비 GUI 세션)·ENOENT(명령 부재)·timeout(SIGTERM)은 판정 불가다.
+ * 판정 불가를 미등록으로 오해하면 살아있는 예약에 재등록을 걸어 bootout으로 내려버린다.
+ * @returns {'missing'|'unknown'}
+ */
+export function classifyLaunchctlProbe(err) {
+  return err?.status === 113 ? 'missing' : 'unknown';
+}
+
+// 설치가 bootstrap gui/<uid>이므로 조회도 같은 도메인을 명시한다.
+// launchctl list는 호출자의 암묵 도메인만 조회해 비 GUI 세션에서 오탐한다.
+function probeMac(run) {
+  const uid = userInfo().uid;
+  try {
+    run('launchctl', ['print', `gui/${uid}/${TASK_LABEL}`],
+      { stdio: 'ignore', timeout: PROBE_TIMEOUT_MS });
+    return 'registered';
+  } catch (err) {
+    return classifyLaunchctlProbe(err);
+  }
+}
+
+// 종료코드만 판정 근거로 쓴다 — 출력 메시지는 현지화·OEM 코드페이지 탓에 파싱할 수 없다.
+function probeWindows(run) {
+  try {
+    run('schtasks', ['/Query', '/TN', WIN_TASK_NAME],
+      { stdio: 'ignore', timeout: PROBE_TIMEOUT_MS, windowsHide: true });
+    return 'registered';
+  } catch (err) {
+    return err.status === 1 ? 'missing' : 'unknown';
+  }
+}
+
+// readCrontab()을 재사용하고 그 함수의 fail-closed throw만 판정 불가로 흡수한다
+// 조회는 CLI 시작을 블로킹하므로 설치 경로와 달리 타임아웃을 반드시 건넨다.
+function probeLinux(run) {
+  try {
+    return readCrontab(run, PROBE_TIMEOUT_MS).includes(CRON_BEGIN) ? 'registered' : 'missing';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * 자동 sync 스케줄이 OS 스케줄러에 실제로 등록돼 있는지 조회한다(읽기 전용).
+ * 라벨·작업명은 완전 일치로만 찾는다 — 같은 홈에 다른 dev.tokenphage.* 작업이 있을 수 있다.
+ * @param {{ platform?: string, run?: Function }} [deps]
+ * @returns {'registered'|'missing'|'unknown'}
+ */
+export function probeHookRegistration({ platform = process.platform, run = execFileSync } = {}) {
+  if (platform === 'darwin') return probeMac(run);
+  if (platform === 'win32') return probeWindows(run);
+  if (platform === 'linux') return probeLinux(run);
+  return 'unknown'; // 미지원 OS는 throw 대신 판정 불가 — 조회 실패로 CLI가 죽지 않게 한다.
+}
+
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 /** 현재 OS에 맞는 자동 sync 스케줄을 설치한다 (macOS=launchd / Windows=schtasks / Linux=cron). 그 외 OS는 throw. */

package/src/ui.js

@@ -127,14 +127,16 @@ export async function promptFirstRun() {
 
 /**
  * 인증된 사용자를 위한 대시보드 메뉴.
- * @param {{ token: string, lastSyncDate: string|null, hookInstalled: boolean, hookMeta: object|null, latestVersion?: string }} cfg
+ * @param {{ token: string, lastSyncDate: string|null, hookInstalled: boolean, hookMeta: object|null }} cfg
+ * @param {string|null} latest TUI 진입 시 조회한 npm 최신버전(조회 실패/옵트아웃 시 null)
+ * @param {boolean} [hookUnverified] OS 스케줄러 등록 여부를 확인할 수 없었으면 true
  * @returns {'update' | 'sync' | 'install-hook' | 'uninstall-hook' | 'advanced' | 'exit'}
  */
-export async function promptDashboard(cfg) {
+export async function promptDashboard(cfg, latest, hookUnverified = false) {
   printWelcome();
 
-  // 캐시된 npm 최신버전과 현재 버전을 비교해, 새 버전이 있을 때만 민트 배너를 출력한다(네트워크 X).
-  const update = getUpdateInfo(version, cfg);
+  // TUI 진입 시 조회한 npm 최신버전과 현재 버전을 비교해, 다를 때만 민트 배너를 출력한다.
+  const update = getUpdateInfo(version, latest);
   if (update.hasUpdate) {
     const bar = accent('  ┃ ');
     console.log(bar + accent(`⬆  Update available  v${update.current} → v${update.latest}`));
@@ -144,9 +146,14 @@ export async function promptDashboard(cfg) {
 
   const username = decodeJwtUsername(cfg.token) ?? '(unknown)';
   const lastSync = cfg.lastSyncDate ?? 'never';
-  const hookStatus = cfg.hookInstalled
-    ? chalk.green('  Auto-sync enabled') + chalk.gray(` (${cfg.hookMeta?.scheduleSpec ?? 'daily 04:00'})`)
-    : chalk.yellow('  Auto-sync not configured');
+  // 설정 상태를 먼저 보고, 켜진 경우에만 검증 결과를 반영한다
+  // (순서를 뒤집으면 방금 auto-sync를 끈 사용자에게도 "enabled"가 남는다).
+  // 등록을 확인하지 못했거나 재등록이 실패했으면 초록으로 단정하지 않고 노랑으로 유보한다.
+  const hookStatus = !cfg.hookInstalled
+    ? chalk.yellow('  Auto-sync not configured')
+    : hookUnverified
+      ? chalk.yellow('  Auto-sync enabled') + chalk.gray(' (could not verify — see message above)')
+      : chalk.green('  Auto-sync enabled') + chalk.gray(` (${cfg.hookMeta?.scheduleSpec ?? 'daily 04:00'})`);
 
   console.log(chalk.green('  Authenticated as ') + chalk.bold(`@${username}`));
   console.log(chalk.gray(`  Last sync: ${lastSync}`));