@sejuneoh/aitop 0.0.0-stage → 0.21.2

package/src/cache.mjs

@@ -0,0 +1,78 @@
+// 큰 세션 기록을 매번 처음부터 다시 읽지 않도록, 파일별로 "어디까지 읽었고 그때 합계가 얼마였는지"를
+// ~/.cache/aitop 에 저장한다. 이 프로그램이 디스크에 쓰는 곳은 여기와 --debug 때의 디버그 로그(log.mjs)뿐이다.
+import { readFileSync, writeFileSync, mkdirSync, renameSync, statSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { PRICE_TAG } from './pricing.mjs';
+import { debug, debugIo } from './log.mjs';
+
+// 캐시 형식이 바뀌면 VERSION 을, 가격표가 바뀌면 PRICE_TAG 가 폴더 이름을 바꿔서 예전 캐시를 버린다.
+const VERSION = 13;
+const ROOT = join(process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'), 'aitop');
+const NAME = `v${VERSION}-${PRICE_TAG}`;
+const DIR = join(ROOT, NAME);
+export const CACHE_DIR = DIR;
+const dirty = new Map();
+let cleaned = false;
+
+// 다른 버전의 aitop 이 같이 쓰고 있을 수 있으니, 같은 형식의 다른 폴더는 일주일 넘게 손대지 않았을 때만 지운다.
+const STALE_DIR_MS = 7 * 24 * 3600 * 1000;
+
+function removeOldDirs() {
+  cleaned = true;
+  try {
+    for (const d of readdirSync(ROOT)) {
+      if (d === NAME) continue;
+      const p = join(ROOT, d);
+      // 이 버전보다 낮은 형식(v2, v6-… 등)은 더 이상 어떤 버전도 쓰지 않으므로 바로 지운다.
+      const ver = Number(/^v(\d+)(?:-|$)/.exec(d)?.[1]);
+      if (ver < VERSION || Date.now() - statSync(p).mtimeMs > STALE_DIR_MS) rmSync(p, { recursive: true, force: true });
+    }
+  } catch (e) {
+    debugIo('cache', 'old cache cleanup failed', e);
+  }
+}
+
+// kind: 같은 기록 파일을 다른 용도로 읽는 tracker 가 각자 캐시를 갖도록 구분한다 (예: 세션 화면용, 날짜별 사용량용).
+const keyOf = (path, kind) => createHash('sha1').update(`${kind}\0${path}`).digest('hex');
+
+// 파일이 바뀌지 않고 뒤에만 붙었을 때(크기가 같거나 커졌고 inode 가 같을 때)만 캐시를 쓴다.
+export function loadCache(path, kind = '') {
+  try {
+    const c = JSON.parse(readFileSync(join(DIR, keyOf(path, kind) + '.json'), 'utf8'));
+    const st = statSync(path);
+    if (c.path !== path || c.ino !== st.ino || st.size < c.offset) return null;
+    return c;
+  } catch (e) {
+    debugIo('cache', 'cache load failed', e);
+    return null;
+  }
+}
+
+export function markDirty(path, snapshot, kind = '') {
+  dirty.set(keyOf(path, kind), { path, build: snapshot });
+}
+
+export function flushCache() {
+  if (!dirty.size) return;
+  try {
+    mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  } catch (e) {
+    debug('cache', 'cache folder create failed', e);
+    return;
+  }
+  if (!cleaned) removeOldDirs();
+  for (const [key, { path, build }] of dirty) {
+    try {
+      const data = build();
+      if (!data) continue;
+      const file = join(DIR, key + '.json');
+      writeFileSync(file + '.tmp', JSON.stringify({ ...data, path, ino: statSync(path).ino }), { mode: 0o600 });
+      renameSync(file + '.tmp', file);
+    } catch (e) {
+      debugIo('cache', 'cache write failed', e);
+    }
+  }
+  dirty.clear();
+}

package/src/collect.mjs

@@ -0,0 +1,51 @@
+import { collectClaude } from './sources/claude.mjs';
+import { collectCodex } from './sources/codex.mjs';
+import { collectGemini } from './sources/gemini.mjs';
+import { collectAgy } from './sources/antigravity.mjs';
+import { collectLedger } from './sources/claude-ledger.mjs';
+import { createBudget } from './tail.mjs';
+
+const RANK = { waiting: 0, busy: 1, shell: 2, live: 3, idle: 4, ended: 5 };
+
+// 상태 순서가 먼저다. 같은 상태 안에서는 갱신마다 자리가 바뀌지 않도록 바뀌지 않는 값으로 줄 세운다:
+// 늦게 시작한 세션이 위, 시작 시각이 없으면 아래, 그다음 도구·id 순.
+// 종료 세션은 더 바뀌지 않으므로 최근에 끝난 세션이 위로 오게 마지막 활동 시각으로 줄 세운다.
+export function bySession(a, b) {
+  const at = (s) => (s.status === 'ended' ? s.updatedAt : s.startedAt) ?? -Infinity;
+  return (
+    (RANK[a.status] ?? 9) - (RANK[b.status] ?? 9) ||
+    at(b) - at(a) ||
+    String(a.tool ?? '').localeCompare(String(b.tool ?? '')) ||
+    String(a.id ?? '').localeCompare(String(b.id ?? ''))
+  );
+}
+
+// budgetBytes·budgetMs: 이번 갱신에서 세션 기록을 읽을 최대 바이트와 시간. 실시간 화면은 작게 잡아 큰 기록을 여러 번에 나눠 읽는다.
+// 돌려주는 more 가 true 면 한도 때문에 덜 읽은 기록이 있다.
+// 도구마다, 그리고 날짜별 사용량 장부에 한도를 따로 줘서 서로의 읽기를 막지 않게 한다.
+export function collect({ budgetBytes = Infinity, budgetMs = Infinity, ...opts } = {}) {
+  const budgets = [];
+  const budgetOf = (bytes, ms) => {
+    const b = createBudget(bytes, ms);
+    budgets.push(b);
+    return b;
+  };
+  const sessions = [];
+  const errors = [];
+  for (const [tool, fn] of [['claude', collectClaude], ['codex', collectCodex], ['gemini', collectGemini], ['agy', collectAgy]]) {
+    try {
+      sessions.push(...fn({ ...opts, budget: budgetOf(budgetBytes, budgetMs) }));
+    } catch (err) {
+      errors.push(`${tool}: ${err.message}`);
+    }
+  }
+  // 장부는 세션 화면보다 덜 급하니 한 번 갱신에 세션 한도의 1/3 만 읽는다 (처음 한 번 다 읽은 뒤에는 캐시와 새 줄만 읽는다).
+  let usage = null;
+  try {
+    usage = collectLedger({ budget: budgetOf(budgetBytes / 3, budgetMs / 2) });
+  } catch (err) {
+    errors.push(`usage: ${err.message}`);
+  }
+  sessions.sort(bySession);
+  return { sessions, usage, errors, at: Date.now(), more: budgets.some((b) => b.exhausted) };
+}

package/src/config.mjs

@@ -0,0 +1,169 @@
+// 설정: 옵션마다 명령줄 옵션(flag) > 환경 변수(env) > 설정 파일(file) > 기본값(default) 순서로 고른다.
+// 설정 파일은 $XDG_CONFIG_HOME/aitop/config.json (없으면 ~/.config/aitop/config.json). aitop 은 이 파일을 읽기만 한다.
+// 잘못된 JSON, 모르는 키, 잘못된 값은 그 키만 무시하고 problems 에 남긴다 (--doctor 와 --print-config 가 보인다).
+// 화면 모듈은 불러올 때 테마·아이콘을 고르므로, 이 모듈은 다른 aitop 모듈을 불러오지 않는다.
+import { closeSync, constants, fstatSync, openSync, readSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { stripControl } from './text.mjs';
+
+const bool = (v) => typeof v === 'boolean';
+const oneOf = (...xs) => (v) => xs.includes(v);
+// 달러 금액 글자("50", "12.5", "$50")를 0 보다 큰 수로 바꾼다. 아니면 null.
+const usd = (v) => {
+  const t = String(v).trim().replace(/^\$/, '');
+  const n = /^\d+(\.\d+)?$|^\.\d+$/.test(t) ? Number(t) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : null;
+};
+
+// argv 에서 --budget-day <usd>, --budget-day=<usd>, --no-budget-day 를 꺼낸다. 뒤에 준 쪽을 따른다.
+// value: 금액, null(이번 실행만 끔), undefined(주지 않음). 나머지 인자는 rest 로 돌려준다.
+export function budgetDayOption(argv) {
+  let value;
+  let error = null;
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--no-budget-day') {
+      value = null;
+      continue;
+    }
+    const m = /^--budget-day(?:=(.*))?$/.exec(a);
+    if (!m) {
+      rest.push(a);
+      continue;
+    }
+    // 다음 인자가 옵션이면 값으로 먹지 않는다. -5 처럼 수로 보이면 값으로 받아 잘못된 값으로 알린다.
+    const next = argv[i + 1];
+    const raw = m[1] ?? (next == null || (next.startsWith('-') && !/^-[\d.]/.test(next)) ? '' : argv[++i]);
+    const n = usd(raw);
+    if (n == null) error ??= raw === '' ? '--budget-day 값이 없습니다 (하루 예산, 달러)' : `--budget-day 값 ${JSON.stringify(raw)} 이 잘못되었습니다 (0 보다 큰 수)`;
+    else value = n;
+  }
+  return { value, rest, error };
+}
+
+// env: 환경 변수 이름과 그 값을 옵션 값으로 바꾸는 함수 (undefined 면 설정하지 않은 것으로 본다).
+// envProblem: 환경 변수 값이 잘못되면 무시하고 problems 에 남긴다 (--doctor, --print-config 가 보인다).
+// notify, onWaiting 은 응답 대기 알림(notify.mjs)이 쓴다. debug 는 디버그 로그(log.mjs)를 켠다. budgetDay 는 하루 예산(달러)으로, 헤더와 --json 의 예상 비용 경고(budget.mjs)가 쓴다.
+export const KEYS = {
+  theme: { ok: oneOf('light', 'dark'), expect: 'light 또는 dark', def: null, env: ['AITOP_THEME', (v) => (v === 'light' || v === 'dark' ? v : undefined)] },
+  icons: { ok: oneOf('plain', 'ascii'), expect: 'plain 또는 ascii', def: 'full', env: ['AITOP_ICONS', (v) => (v === 'plain' || v === 'ascii' ? v : undefined)] },
+  bell: { ok: bool, expect: 'true 또는 false', def: false },
+  showRequests: { ok: bool, expect: 'true 또는 false', def: false, env: ['AITOP_SHOW_REQUESTS', (v) => (v === '1' ? true : v === '0' ? false : undefined)] },
+  all: { ok: bool, expect: 'true 또는 false', def: false },
+  notify: { ok: bool, expect: 'true 또는 false', def: false },
+  onWaiting: { ok: (v) => typeof v === 'string' && v.trim() !== '', expect: '실행할 명령 문자열', def: null },
+  debug: { ok: bool, expect: 'true 또는 false', def: false, env: ['AITOP_DEBUG', (v) => (v === '1' ? true : v === '0' ? false : undefined)], envProblem: true, envExpect: '1 또는 0' },
+  budgetDay: { ok: (v) => typeof v === 'number' && Number.isFinite(v) && v > 0, expect: '0 보다 큰 수', def: null, env: ['AITOP_BUDGET_DAY', (v) => usd(v) ?? undefined], envProblem: true },
+  // colorBlind 는 적록 색약 팔레트(ui/theme.mjs)를 고른다. theme(밝기)과 따로 정한다.
+  colorBlind: { ok: bool, expect: 'true 또는 false', def: false, env: ['AITOP_COLOR_BLIND', (v) => (v === '1' ? true : v === '0' ? false : undefined)], envProblem: true, envExpect: '1 또는 0' },
+  // 실행 중 세션이 없고 7일 동안 쓰지 않은 도구를 도구 줄에서 숨긴다. false 면 늘 셋 다 보인다.
+  hideIdleTools: { ok: bool, expect: 'true 또는 false', def: true },
+  // 폭이 모호한 기호(·, →, ─, ● 등)를 2칸으로 그리는 터미널이면 wide. 표 칸이 밀리지 않게 1칸 기호로 바꾸고 폭을 2칸으로 센다.
+  ambiguous: { ok: oneOf('narrow', 'wide'), expect: 'narrow 또는 wide', def: 'narrow', env: ['AITOP_AMBIGUOUS', (v) => (v === 'narrow' || v === 'wide' ? v : undefined)], envProblem: true },
+};
+
+export function configPath(env = process.env, home = homedir()) {
+  const xdg = env.XDG_CONFIG_HOME;
+  return join(xdg && isAbsolute(xdg) ? xdg : join(home, '.config'), 'aitop', 'config.json');
+}
+
+// 설정 파일은 작다. 이보다 크면 읽지 않는다.
+export const MAX_BYTES = 64 * 1024;
+
+const show = (v) => JSON.stringify(v)?.slice(0, 60) ?? String(v);
+
+// 파일을 읽어 올바른 키만 values 에 담는다. uid: 현재 사용자 (테스트에서 바꿔 끼운다).
+export function readConfigFile(path, { uid = process.getuid?.() } = {}) {
+  const res = { path, exists: false, values: {}, problems: [] };
+  let fd;
+  let text;
+  let st;
+  const notFile = () => res.problems.push('설정 파일이 일반 파일이 아니라 읽지 않습니다');
+  const tooBig = () => res.problems.push(`설정 파일이 ${MAX_BYTES / 1024}KB 를 넘어 읽지 않습니다`);
+  try {
+    // FIFO 나 장치 파일을 열면 멈출 수 있으므로 열기 전에 확인하고, 열 때도 기다리지 않게 연다.
+    st = statSync(path);
+    res.exists = true;
+    if (!st.isFile()) return (notFile(), res);
+    if (st.size > MAX_BYTES) return (tooBig(), res);
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+    st = fstatSync(fd);
+    if (!st.isFile()) return (notFile(), res);
+    if (st.size > MAX_BYTES) return (tooBig(), res);
+    // 확인한 뒤에 파일이 커져도 한도 + 1 바이트까지만 읽는다.
+    const buf = Buffer.alloc(MAX_BYTES + 1);
+    let n = 0;
+    for (let got; n < buf.length && (got = readSync(fd, buf, n, buf.length - n, n)) > 0; ) n += got;
+    if (n > MAX_BYTES) return (tooBig(), res);
+    text = buf.subarray(0, n).toString('utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      res.exists = err.code !== 'ENOTDIR';
+      res.problems.push(`설정 파일을 읽을 수 없습니다 (${err.code ?? err.message})`);
+    }
+    return res;
+  } finally {
+    if (fd != null) closeSync(fd);
+  }
+  let obj;
+  try {
+    obj = JSON.parse(text);
+  } catch (err) {
+    // 오류 문구에 파일 내용 일부가 들어가므로 제어문자를 지우고 줄인다.
+    res.problems.push(`설정 파일이 올바른 JSON 이 아니라 무시합니다 (${stripControl(err.message).slice(0, 120)})`);
+    return res;
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    res.problems.push('설정 파일의 맨 위는 JSON 객체({ ... })여야 합니다');
+    return res;
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const spec = Object.hasOwn(KEYS, key) ? KEYS[key] : null;
+    if (!spec) res.problems.push(`모르는 키 ${show(key)} 는 무시합니다`);
+    else if (!spec.ok(value)) res.problems.push(`${key} 값 ${show(value)} 이 잘못되어 무시합니다 (${spec.expect})`);
+    else res.values[key] = value;
+  }
+  // 응답 대기 때 실행할 명령은 다른 사용자가 바꿀 수 없는 파일에서만 받는다.
+  if ('onWaiting' in res.values) {
+    const mine = uid == null || st.uid === uid;
+    const shared = (st.mode & 0o022) !== 0;
+    if (!mine || shared) {
+      delete res.values.onWaiting;
+      const why = [!mine && '파일 소유자가 현재 사용자가 아님', shared && `그룹·다른 사용자가 쓸 수 있음 (mode ${(st.mode & 0o777).toString(8).padStart(3, '0')})`].filter(Boolean).join(', ');
+      res.problems.push(`onWaiting 은 무시합니다: ${why}. chmod 600 으로 고치세요`);
+    }
+  }
+  return res;
+}
+
+// flags: 명령줄에서 정한 값만 담는다 (주지 않은 옵션은 넣지 않는다).
+export function resolveConfig({ flags = {}, env = process.env, file } = {}) {
+  file ??= readConfigFile(configPath(env));
+  const values = {};
+  const problems = [...file.problems];
+  for (const [key, spec] of Object.entries(KEYS)) {
+    const fromEnv = spec.env && env[spec.env[0]] != null ? spec.env[1](env[spec.env[0]]) : undefined;
+    if (spec.envProblem && env[spec.env[0]] != null && fromEnv === undefined) problems.push(`환경 변수 ${spec.env[0]} 값 ${show(env[spec.env[0]])} 이 잘못되어 무시합니다 (${spec.envExpect ?? spec.expect})`);
+    if (flags[key] !== undefined) values[key] = { value: flags[key], source: 'flag' };
+    else if (fromEnv !== undefined) values[key] = { value: fromEnv, source: 'env' };
+    else if (key in file.values) values[key] = { value: file.values[key], source: 'file' };
+    else values[key] = { value: spec.def, source: 'default' };
+  }
+  return { path: file.path, exists: file.exists, values, problems };
+}
+
+// --print-config 의 사람용 출력.
+export function configText(cfg) {
+  const out = [`설정 파일: ${stripControl(cfg.path)} (${cfg.exists ? '있음' : '없음'})`, ''];
+  for (const [key, { value, source }] of Object.entries(cfg.values)) {
+    const v = value == null ? (key === 'theme' ? 'auto' : '-') : typeof value === 'string' ? JSON.stringify(value) : String(value);
+    out.push(`${key.padEnd(14)}${v.padEnd(12)} ${source}`);
+  }
+  if (cfg.problems.length) out.push('', ...cfg.problems.map((p) => `! ${stripControl(p)}`));
+  return out.join('\n');
+}
+
+// --print-config --json, --doctor --json 용.
+export const configJson = (cfg) => ({ path: cfg.path, exists: cfg.exists, values: cfg.values, problems: cfg.problems });

package/src/doctor.mjs

@@ -0,0 +1,218 @@
+// 도구별 연결 점검: 기록 폴더를 찾았는지, 기록이 몇 개이고 언제 마지막으로 쓰였는지, 지금 몇 개가 실행 중인지,
+// 가장 최근 기록을 읽을 수 있는지. aitop --doctor, 빈 화면, --json 의 tools 가 같은 결과를 쓴다.
+// 기록 내용은 읽어 내보내지 않는다 (Gemini 는 형식 확인용으로 JSON 키 이름만 보인다).
+import { readdirSync, statSync, existsSync, openSync, readSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { findProcesses, isCodex, isGemini, isAgy, canListProcesses, isAlive } from './procs.mjs';
+import { AGY_ROOT } from './sources/antigravity.mjs';
+import { loadSqlite, openReadOnly } from './sqlite.mjs';
+import { fmtAgo, pad, stripControl } from './text.mjs';
+import { BRAND } from './brand.mjs';
+import { findNotifier, isWsl } from './notify.mjs';
+
+const UNIT = { s: '초', m: '분', h: '시간', d: '일' };
+const ago = (ms) => fmtAgo(ms).replace(/[smhd]$/, (u) => UNIT[u]);
+
+const HOME = homedir();
+const CLAUDE = process.env.CLAUDE_CONFIG_DIR ?? join(HOME, '.claude');
+const CODEX = join(process.env.CODEX_HOME ?? join(HOME, '.codex'), 'sessions');
+const GEMINI = join(process.env.GEMINI_HOME ?? join(HOME, '.gemini'), 'tmp');
+
+const tilde = (p) => (p.startsWith(HOME + '/') ? '~' + p.slice(HOME.length) : p);
+const ls = (dir) => {
+  try {
+    return readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+};
+
+// 폴더 아래 depth 단계까지 내려가며 조건에 맞는 파일을 모은다.
+function walk(dir, depth, match, out = []) {
+  for (const e of ls(dir)) {
+    const p = join(dir, e.name);
+    if (e.isDirectory() && depth > 0) walk(p, depth - 1, match, out);
+    else if (e.isFile() && match(e.name)) out.push(p);
+  }
+  return out;
+}
+
+function newest(files) {
+  let best = null;
+  for (const path of files) {
+    try {
+      const m = statSync(path).mtimeMs;
+      if (!best || m > best.mtime) best = { path, mtime: m };
+    } catch {}
+  }
+  return best;
+}
+
+// 파일 첫 줄이 JSON 으로 읽히면 true, 아니면 false. 비어 있거나 첫 줄이 64KB 를 넘으면 판정하지 않는다(null).
+function firstLineIsJson(path) {
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const buf = Buffer.alloc(65536);
+    const n = readSync(fd, buf, 0, buf.length, 0);
+    const text = buf.subarray(0, n).toString('utf8');
+    const end = text.indexOf('\n');
+    if (!n || (end < 0 && n === buf.length)) return null;
+    JSON.parse(end < 0 ? text : text.slice(0, end));
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (fd != null) closeSync(fd);
+  }
+}
+
+// 키 이름도 사용자 글이나 경로일 수 있으므로 식별자처럼 생긴 것만 보인다.
+const KEY_NAME = /^[A-Za-z_][\w.-]{0,40}$/;
+
+// JSON 파일 맨 위 키 이름만 (값은 보지 않는다). 앞 64KB 로 읽지 못하면(큰 파일) 맨 위 수준 들여쓰기의 "키": 줄에서 찾는다.
+function topKeys(path) {
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const buf = Buffer.alloc(65536);
+    const n = readSync(fd, buf, 0, buf.length, 0);
+    const text = buf.subarray(0, n).toString('utf8');
+    let keys;
+    try {
+      let obj = JSON.parse(text);
+      if (Array.isArray(obj)) obj = obj[0];
+      keys = obj && typeof obj === 'object' ? Object.keys(obj) : [];
+    } catch {
+      try {
+        keys = Object.keys(JSON.parse(text.split('\n')[0]));
+      } catch {
+        keys = [...text.matchAll(/^ {0,2}\t?"([^"\n]{1,60})"\s*:/gm)].map((m) => m[1]);
+      }
+    }
+    return [...new Set(keys)].filter((k) => KEY_NAME.test(k)).slice(0, 12);
+  } catch {
+    return [];
+  } finally {
+    if (fd != null) closeSync(fd);
+  }
+}
+
+function claude() {
+  const dir = join(CLAUDE, 'projects');
+  const files = existsSync(dir) ? walk(dir, 1, (n) => n.endsWith('.jsonl')) : null;
+  const last = files && newest(files);
+  const running = canListProcesses()
+    ? ls(join(CLAUDE, 'sessions')).filter((e) => /^\d+\.json$/.test(e.name) && isAlive(Number(e.name.split('.')[0]))).length
+    : null;
+  if (!files) return { tool: 'claude', state: 'missing', path: tilde(dir), records: 0, lastAt: null, running, readable: null, hint: 'claude 를 한 번 실행하면 생깁니다' };
+  return { tool: 'claude', state: 'ok', path: tilde(dir), records: files.length, lastAt: last?.mtime ?? null, running, readable: last ? firstLineIsJson(last.path) : null, hint: null };
+}
+
+function codex() {
+  const files = existsSync(CODEX) ? walk(CODEX, 3, (n) => n.startsWith('rollout-') && n.endsWith('.jsonl')) : null;
+  const last = files && newest(files);
+  const running = canListProcesses() ? findProcesses(isCodex).length : null;
+  if (!files) return { tool: 'codex', state: 'missing', path: tilde(CODEX), records: 0, lastAt: null, running, readable: null, hint: 'codex 를 한 번 실행하면 생깁니다' };
+  return { tool: 'codex', state: 'ok', path: tilde(CODEX), records: files.length, lastAt: last?.mtime ?? null, running, readable: last ? firstLineIsJson(last.path) : null, hint: null };
+}
+
+// Gemini 는 세션 기록 형식을 아직 모른다. 프로세스만 세고, 기록 폴더가 있으면 형식 확인용 키 이름을 남긴다.
+function gemini() {
+  const files = existsSync(GEMINI) ? walk(GEMINI, 3, (n) => n.endsWith('.json') || n.endsWith('.jsonl')) : null;
+  const last = files && newest(files);
+  return {
+    tool: 'gemini',
+    state: 'limited',
+    path: tilde(GEMINI),
+    found: Boolean(files),
+    records: files?.length ?? 0,
+    lastAt: last?.mtime ?? null,
+    running: canListProcesses() ? findProcesses(isGemini).length : null,
+    readable: null,
+    keys: last ? topKeys(last.path) : [],
+    hint: '프로세스만 감지합니다 (세션·토큰은 아직 지원하지 않음)',
+  };
+}
+
+// Antigravity CLI: 요약 DB 를 열어 대화 목록을 읽을 수 있는지 본다. node:sqlite 가 없으면 프로세스만 센다.
+function agy() {
+  const dir = join(AGY_ROOT, 'conversations');
+  const running = canListProcesses() ? findProcesses(isAgy).length : null;
+  const files = existsSync(dir) ? walk(dir, 0, (n) => n.endsWith('.db')) : null;
+  if (!files) return { tool: 'agy', state: 'missing', path: tilde(AGY_ROOT), records: 0, lastAt: null, running, readable: null, hint: 'agy 를 한 번 실행하면 생깁니다 (Gemini 탭에 보입니다)' };
+  const last = newest(files.flatMap((f) => [f, `${f}-wal`]).filter((f) => existsSync(f)));
+  if (!loadSqlite()) return { tool: 'agy', state: 'limited', path: tilde(AGY_ROOT), records: files.length, lastAt: last?.mtime ?? null, running, readable: null, hint: `Node ${process.versions.node} 에서는 기록을 읽기 전용으로 열 수 없어 프로세스만 감지합니다 (Node 22.15 이상 필요)` };
+  let readable = false;
+  let db;
+  try {
+    db = openReadOnly(join(AGY_ROOT, 'conversation_summaries.db'));
+    db.prepare('select count(*) n from conversation_summaries').get();
+    readable = true;
+  } catch {
+  } finally {
+    db?.close();
+  }
+  return { tool: 'agy', state: 'ok', path: tilde(AGY_ROOT), records: files.length, lastAt: last?.mtime ?? null, running, readable, hint: null };
+}
+
+export function checkTools() {
+  const tools = {};
+  for (const fn of [claude, codex, gemini, agy]) {
+    const r = fn();
+    tools[r.tool] = r;
+  }
+  const n = findNotifier();
+  return { platform: platform(), processes: canListProcesses(), tools, notifier: n ? { kind: n.kind, path: tilde(n.path) } : null };
+}
+
+// --notify 에 쓸 데스크톱 알림 도구.
+export function notifierText(n, plat = platform()) {
+  if (n) return `✓ 알림    ${n.kind} (${n.path}) · --notify 로 켬`;
+  const want = plat === 'darwin' ? 'osascript' : 'notify-send';
+  const wsl = plat === 'linux' && isWsl() ? ' (WSL 은 notify-send 만 쓴다)' : '';
+  return `○ 알림    ${want} 없음 · --notify 를 켜도 알림을 건너뜀${wsl}`;
+}
+
+// JSON 용: 시각은 ISO 문자열로.
+export function toolsJson(tools) {
+  if (!tools) return null;
+  return Object.fromEntries(Object.entries(tools).map(([k, t]) => [k, { ...t, lastAt: t.lastAt ? new Date(t.lastAt).toISOString() : null }]));
+}
+
+// 점검 결과를 사람이 읽는 조각으로 바꾼다. 빈 화면과 --doctor 가 같은 문구를 쓴다.
+export const MARK = { ok: '✓', missing: '✗', limited: '○' };
+export const STATE_TEXT = { ok: '찾음', missing: '없음', limited: '일부 지원' };
+
+export function describe(t, now = Date.now()) {
+  const parts = [];
+  if (t.found === false && t.state === 'limited') parts.push('기록 폴더 없음');
+  else if (t.state !== 'missing') parts.push(`기록 ${t.records.toLocaleString('en-US')}개`);
+  if (t.lastAt) parts.push(`마지막 ${ago(now - t.lastAt)} 전`);
+  parts.push(t.running == null ? '실행 수 확인 불가 (Linux·WSL·macOS 만 지원)' : `실행 ${t.running}`);
+  if (t.readable === false) parts.push('최근 기록 읽기 실패');
+  if (t.keys?.length) parts.push(`키: ${t.keys.join(', ')}`);
+  return { mark: MARK[t.state], state: STATE_TEXT[t.state], path: t.path, detail: parts.join(' · '), hint: t.hint };
+}
+
+// aitop --doctor 의 사람용 출력.
+export function doctorText(result, version, now = Date.now()) {
+  const os = `${result.platform}, 프로세스 ${result.processes ? '확인 가능' : '확인 불가'}`;
+  const out = [`${BRAND.logo} aitop ${version} 연결 점검 (${os})`, ''];
+  for (const t of Object.values(result.tools)) {
+    const d = describe(t, now);
+    out.push(`${d.mark} ${pad(t.tool, 7)}${pad(d.state, 10)}${d.path}`);
+    out.push(`         ${d.detail}`);
+    if (d.hint) out.push(`         → ${d.hint}`);
+  }
+  if ('notifier' in result) out.push('', notifierText(result.notifier, result.platform));
+  // 설정 파일: 무시한 키와 값, 받지 않은 onWaiting 을 알린다.
+  const cfg = result.config;
+  if (cfg) {
+    out.push('', `${cfg.problems.length ? '!' : '✓'} 설정   ${pad(cfg.exists ? '있음' : '없음 (기본값)', 10)}${tilde(cfg.path)}`);
+    for (const p of cfg.problems) out.push(`         ! ${p}`);
+  }
+  if (result.log) out.push('', `${result.log.on ? '✓' : '○'} 디버그 ${pad(result.log.on ? '켬' : '꺼짐', 10)}${tilde(result.log.path)}${result.log.on ? '' : ' · --debug 로 켬'}`);
+  return stripControl(out.join('\n'));
+}

package/src/frames.mjs

@@ -0,0 +1,24 @@
+// 실시간 화면의 애니메이션 타이머. 움직이는 표시가 있을 때만 ms 마다 onFrame 을 부르고, 없으면 멈춘다.
+// sync() 는 화면을 그릴 때마다 불러 상태에 맞춰 타이머를 켜고 끈다. timers 는 테스트에서 바꿔 끼운다.
+export function frameTimer({ animating, onFrame, ms = 120, timers = globalThis }) {
+  let id = null;
+  const stop = () => {
+    if (id == null) return;
+    timers.clearInterval(id);
+    id = null;
+  };
+  const fire = () => {
+    if (!animating()) return stop();
+    onFrame();
+  };
+  return {
+    sync() {
+      if (!animating()) stop();
+      else if (id == null) id = timers.setInterval(fire, ms);
+    },
+    stop,
+    get running() {
+      return id != null;
+    },
+  };
+}

package/src/help.mjs

@@ -0,0 +1,111 @@
+// 키 안내의 한 곳: 화면 안 도움말(ui/chrome.mjs 의 help)과 aitop --help 의 키 줄이 이 표에서 만들어진다.
+// 화면 모듈을 불러오지 않는다 (bin 이 색·테마를 정하기 전에 불러도 되게).
+
+// 화면별 키. [키, 설명, 짧은 이름, --help 에 쓸 키(없으면 첫 글자 묶음)]
+export const VIEWS = {
+  table: {
+    title: '세션 표',
+    keys: [
+      ['/', '세션 검색 (이름·폴더·모델). Enter 적용, Esc 지우기', '검색'],
+      ['↑↓ j k', '세션 선택', '선택', '↑↓/jk'],
+      ['n', '다음 볼 세션으로 (응답 대기 → 완료 · 확인 전)', '다음 볼 세션'],
+      ['s', '정렬: 기본 → 비용순 → 컨텍스트순 → 최근순. 응답 대기는 늘 맨 위', '정렬'],
+      ['g', '묶기: 없음 → 프로젝트 → 도구. 묶음 머리에 세션 수·비용', '묶기'],
+      ['c', '비용 기준: API 환산 ↔ 캐시 제외. 표·헤더·상세가 같이 바뀐다 (예산은 늘 API 환산)', '비용 기준'],
+      ['p', '고른 세션을 맨 위(응답 대기 아래)에 고정·해제. 여러 개는 고정한 순서, 이번 실행에만', '고정'],
+      ['f Tab', '고른 세션의 변경 파일 목록으로', '변경 파일'],
+      ['d', '상세 패널 열기·닫기', '상세'],
+      ['e', '종료된 세션(24시간) 보이기·숨기기', '종료 세션 토글'],
+      ['Esc', '한 단계 뒤로 (도움말·검색 닫기, diff → 파일 목록 → 세션). 종료하지 않음', '뒤로'],
+    ],
+  },
+  detail: {
+    title: '상세 패널',
+    keys: [
+      ['↑↓ j k', '다른 세션을 고르면 상세도 따라 바뀐다', '세션 바꾸기', '↑↓/jk'],
+      ['f Tab', '변경 파일 목록으로', '변경 파일'],
+      ['d', '상세 패널 닫기', '닫기'],
+    ],
+  },
+  files: {
+    title: '변경 파일 목록',
+    keys: [
+      ['↑↓ j k', '파일 고르기', '고르기', '↑↓/jk'],
+      ['←→', '지시 탭: 이번 지시 · 편집이 있던 이전 지시 T번호 · 전체', '지시 탭'],
+      ['Enter l', '고른 파일의 diff 보기', 'diff'],
+      ['Esc h f Tab', '세션 표로', '뒤로'],
+    ],
+  },
+  diff: {
+    title: 'diff',
+    keys: [
+      ['↑↓ j k', '한 줄씩 스크롤', '스크롤', '↑↓/jk'],
+      ['space PgDn PgUp', '한 페이지씩', '페이지', 'space'],
+      ['[ ]', '이전·다음 파일', '이전·다음 파일', '[ ]'],
+      ['Esc h ← f Tab', '파일 목록으로', '뒤로'],
+    ],
+  },
+  filtered: {
+    title: '검색어가 걸린 표',
+    keys: [
+      ['↑↓ j k', '검색 결과 안에서 세션 선택', '선택', '↑↓/jk'],
+      ['Esc', '검색어 지우기 (표 전체로)', '검색어 지우기'],
+      ['/', '지금 검색어를 지우고 새로 입력', '새 검색'],
+    ],
+  },
+  // 검색어를 입력하는 동안은 ? 도 검색어로 들어가므로 도움말에서는 '다른 화면' 과 --help 에만 나온다.
+  search: {
+    title: '검색 입력 중',
+    keys: [
+      ['글자', '검색어 입력 (이름·폴더·모델, 대소문자 무시)', '입력'],
+      ['Backspace', '한 글자 지우기', '지우기'],
+      ['Enter', '검색어를 남기고 표로', '적용'],
+      ['Esc', '검색 취소 (검색어 지우기)', '취소'],
+    ],
+  },
+};
+
+// 어느 화면에서나 듣는 키. 화면마다 되풀이하지 않고 도움말에서는 지금 화면 키 바로 아래 한 번만 보인다.
+export const COMMON = {
+  title: '어디서나',
+  keys: [
+    ['?', '이 도움말 열기·닫기', '도움말'],
+    ['q Ctrl-C', '나가기', '나가기'],
+  ],
+};
+
+// 화면 안 도움말의 옵션 묶음. 자세한 설명은 aitop --help.
+export const OPTIONS = [
+  ['--notify', '응답 대기가 생기면 데스크톱 알림'],
+  ['--on-waiting <명령>', '응답 대기가 생기면 명령 실행'],
+  ['--budget-day <달러>', '하루 예산. 헤더에 예상 비용 경고'],
+  ['--show-requests', '응답 대기 요청 전체를 상세·--json 에'],
+  ['--color-blind', '적록 색약용 색 (대기·돈·경고를 노랑·파랑 계열로)'],
+  ['--debug', '디버그 로그를 남긴다'],
+  ['--print-config', '설정 값과 출처, 설정 파일 위치'],
+  ['AITOP_AMBIGUOUS=wide', '·→─● 를 2칸으로 그리는 터미널용 (1칸 기호로)'],
+];
+
+// 지금 보는 화면: 파일 목록·diff 에 들어가 있으면 그 화면, 아니면 세션 표. 검색어는 표에 붙는 것이라 helpSections 가 따로 본다.
+export function helpContext(view) {
+  if (view.focus === 'diff' || view.focus === 'files') return view.focus;
+  return 'table';
+}
+
+const cliKey = ([k, , , cli]) => cli ?? k.split(' ')[0];
+// 한 화면의 키를 한 줄로: '/ 검색 · ↑↓/jk 선택 · ...'
+// 'common' 은 어디서나 쓰는 키. 없는 화면 이름은 예전처럼 오류로 드러낸다.
+export const keysLine = (name) => (name === 'common' ? COMMON : VIEWS[name]).keys.map((e) => `${cliKey(e)} ${e[2]}`).join(' · ');
+
+// aitop --help 끝의 키 안내.
+export function keysText() {
+  return [`키: ${keysLine('table')} · ${keysLine('common')}`, ...['files', 'diff', 'filtered', 'search'].map((n) => `  ${VIEWS[n].title}: ${keysLine(n)}`)].join('\n');
+}
+
+// 지금 설정 값 한 줄 (예: 예산 $50 · 알림 켜짐 · 디버그 꺼짐). settings 가 없으면 null.
+export function settingsLine(s) {
+  if (!s) return null;
+  const onOff = (v) => (v ? '켜짐' : '꺼짐');
+  const usd = (x) => (Number.isInteger(x) ? `$${x}` : `$${x.toFixed(2)}`);
+  return [`예산 ${s.budgetDay > 0 ? usd(s.budgetDay) : '없음'}`, `알림 ${onOff(s.notify)}`, ...(s.onWaiting ? ['대기 명령 있음'] : []), `디버그 ${onOff(s.debug)}`].join(' · ');
+}