@sejuneoh/aitop 0.0.0-stage → 0.21.2

package/src/json.mjs

@@ -0,0 +1,57 @@
+import { projectBudget } from './budget.mjs';
+import { toolsJson } from './doctor.mjs';
+
+// aitop --json 출력. 다른 스크립트나 AI 가 읽기 쉬운 모양으로 세션 목록과 사용량 합계를 담는다.
+// 텍스트는 수집 단계에서 이미 비밀값 가림이 적용돼 있다.
+
+const pickTokens = (t = {}) => ({ total: t.total ?? 0, input: t.input ?? 0, output: t.output ?? 0, cacheRead: t.cacheRead ?? 0, cacheWrite: t.cacheWrite ?? 0, main: t.main ?? null, sub: t.sub ?? null, subCount: t.subCount ?? null });
+
+const iso = (ms) => (ms ? new Date(ms).toISOString() : null);
+// 비용(달러)은 소수 넷째 자리까지 반올림한다.
+const money = (x) => (typeof x === 'number' ? Math.round(x * 1e4) / 1e4 : (x ?? null));
+// 최근 1시간 비용 (5분 칸 단위 근사).
+const lastHourOf = (h) => (h ? { cost: money(h.cost), costNoCache: money(h.costNoCache), unknown: Boolean(h.unknown) } : null);
+// last7days.daily: 날짜별 API 환산 비용 (오래된 날 → 오늘). unknown 은 가격표에 없는 모델이 섞인 날.
+const dailyOf = (days) => (days ? { daily: days.map((d) => ({ date: d.date, cost: money(d.cost), unknown: Boolean(d.unknown) })) } : {});
+const usageOf = (u) => (u ? { ...u, ...('cost' in u ? { cost: money(u.cost) } : {}) } : u);
+
+// version 은 aitop 버전, tools 는 aitop --doctor 와 같은 도구별 점검 결과다.
+// opts.showRequests: 응답 대기 요청 전체(waitDetail)를 넣는다. 기본은 꺼져 있다.
+// opts.budgetDay: 하루 예산. 있으면 usage.budget 에 예산, 오늘 끝 예상 비용(API 정가 환산, 화면과 같은 기준), 단계를 넣는다.
+export function toJson(data, version = null, opts = {}) {
+  const b = data.usage ? projectBudget(data.usage, opts.budgetDay, { now: data.at ?? Date.now() }) : null;
+  return {
+    version,
+    at: iso(data.at),
+    tools: toolsJson(data.tools?.tools),
+    usage: data.usage ? { today: usageOf(data.usage.today), last7days: { ...usageOf(data.usage.week), ...dailyOf(data.usage.days7) }, lastHour: lastHourOf(data.usage.lastHour), complete: data.usage.loading == null, ...(b ? { budget: { day: b.day, projected: money(b.projected), unknown: b.unknown, level: b.level } } : {}) } : null,
+    sessions: data.sessions.map((s) => ({
+      tool: s.tool,
+      id: s.id,
+      name: s.name ?? null,
+      project: s.project ?? null,
+      cwd: s.cwd ?? null,
+      branch: s.branch ?? null,
+      model: s.model ?? null,
+      kind: s.kind ?? null,
+      pid: s.pid ?? null,
+      live: Boolean(s.live),
+      status: s.status,
+      phase: s.phase?.text ?? null,
+      waitingFor: s.waitingFor ?? null,
+      // 허락을 기다리는 요청의 전체 내용 (Bash 명령, 파일 경로 등). --show-requests 를 켰을 때만 넣는다. 비밀값 가림은 최선을 다할 뿐이다.
+      ...(opts.showRequests ? { waitDetail: s.waitDetail ?? null } : {}),
+      now: s.now || null,
+      startedAt: iso(s.startedAt),
+      updatedAt: iso(s.updatedAt),
+      tokens: pickTokens(s.tokens),
+      cost: money(s.cost),
+      costNoCache: money(s.costNoCache),
+      costUnknown: Boolean(s.costUnknown),
+      context: { used: s.context?.used ?? 0, window: s.context?.window ?? null },
+      // 변경 내용(diff)은 넣지 않고 파일별 통계만 넣는다. 줄 수는 편집마다 더한 누적값이다 (git diff 아님).
+      files: (s.files ?? []).map((f) => ({ path: f.path, created: Boolean(f.created), edits: f.edits, writtenLines: f.add, deletedLines: f.del, updatedAt: iso(f.at), agents: f.agents ?? [] })),
+      members: (s.members ?? []).map((m) => ({ name: m.name, task: m.task ?? null, model: m.model ?? null, status: m.status, phase: m.phase?.text ?? null, tokens: m.tokens ?? 0, cost: money(m.cost) })),
+    })),
+  };
+}

package/src/keys.mjs

@@ -0,0 +1,154 @@
+// 키 입력 처리. 화면 상태(view)를 바꾸고, 종료·갱신·세션 이동처럼 밖에서 해야 할 일은 act 로 부른다.
+// view.focus: null(세션 선택) → 'files'(변경 파일 목록) → 'diff'(고른 파일의 변경 내용). Esc 는 한 단계씩 뒤로 가고 종료하지 않는다.
+// view.tab: 변경 파일을 보는 지시 탭 ('now' 이번 지시, 지시 번호, 'all' 전체). turns.mjs 참고.
+import { turnTabs, visibleFiles } from './turns.mjs';
+import { detailOpen } from './ui/chrome.mjs';
+import { nextGroup, nextSort, togglePin } from './order.mjs';
+
+export const KEY = { up: '\x1b[A', down: '\x1b[B', right: '\x1b[C', left: '\x1b[D', pageUp: '\x1b[5~', pageDown: '\x1b[6~', esc: '\x1b', enter: '\r', tab: '\t', ctrlC: '\x03', backspace: '\x7f' };
+
+const isUp = (k) => k === KEY.up || k === 'k';
+const isDown = (k) => k === KEY.down || k === 'j';
+const isBack = (k) => k === KEY.esc || k === 'h';
+
+export function selectedSession(view) {
+  return view.data?.sessions.find((s) => s.id === view.selectedId) ?? null;
+}
+
+const hasFiles = (view) => Boolean(selectedSession(view)?.files?.length);
+// 지금 탭에 보이는 파일
+const filesOf = (view) => visibleFiles(selectedSession(view), view.tab);
+
+// 갱신 뒤에 고른 파일이 탭에서 빠졌거나 세션에 고친 파일이 없어졌으면 포커스를 맞춘다.
+export function fixFocus(view) {
+  if (!view.focus) return;
+  if (!hasFiles(view) || !view.showDetail) {
+    view.focus = null;
+    return;
+  }
+  const files = filesOf(view);
+  if (files.some((f) => f.path === view.filePath)) return;
+  // 보던 diff 의 파일이 탭에서만 빠졌으면(새 지시가 들어와 이번 지시가 바뀜) 닫지 않고 전체 탭으로 옮긴다.
+  if (view.focus === 'diff' && selectedSession(view).files.some((f) => f.path === view.filePath)) {
+    view.tab = 'all';
+    return;
+  }
+  view.filePath = files[0]?.path ?? null;
+  view.focus = 'files';
+}
+
+// 이번 지시에 고친 파일이 없어도 목록에는 들어간다. ←/→ 로 다른 지시를 볼 수 있다.
+function enterFiles(view) {
+  if (!hasFiles(view)) return;
+  view.showDetail = true;
+  view.focus = 'files';
+  const files = filesOf(view);
+  if (!files.some((f) => f.path === view.filePath)) view.filePath = files[0]?.path ?? null;
+}
+
+function stepTab(view, delta) {
+  const tabs = turnTabs(selectedSession(view));
+  const i = Math.max(0, tabs.findIndex((t) => t.key === (view.tab ?? 'now')));
+  view.tab = tabs[Math.min(tabs.length - 1, Math.max(0, i + delta))].key;
+  const files = filesOf(view);
+  if (!files.some((f) => f.path === view.filePath)) view.filePath = files[0]?.path ?? null;
+}
+
+function stepFile(view, delta) {
+  const files = filesOf(view);
+  const i = Math.max(0, files.findIndex((f) => f.path === view.filePath));
+  view.filePath = files[Math.min(files.length - 1, Math.max(0, i + delta))]?.path ?? null;
+}
+
+function filesKey(view, key) {
+  if (isUp(key)) stepFile(view, -1);
+  else if (isDown(key)) stepFile(view, 1);
+  else if (key === KEY.left || key === KEY.right) stepTab(view, key === KEY.left ? -1 : 1);
+  else if (key === KEY.enter || key === 'l') {
+    if (!view.filePath) return true;
+    view.focus = 'diff';
+    view.diffScroll = 0;
+  } else if (isBack(key) || key === 'f' || key === KEY.tab) view.focus = null;
+  else return false;
+  return true;
+}
+
+function diffKey(view, key) {
+  const page = view.diffPage ?? 10;
+  if (isUp(key)) view.diffScroll = Math.max(0, (view.diffScroll ?? 0) - 1);
+  else if (isDown(key)) view.diffScroll = (view.diffScroll ?? 0) + 1;
+  else if (key === ' ' || key === KEY.pageDown) view.diffScroll = (view.diffScroll ?? 0) + page;
+  else if (key === KEY.pageUp) view.diffScroll = Math.max(0, (view.diffScroll ?? 0) - page);
+  else if (key === '[' || key === ']') {
+    stepFile(view, key === '[' ? -1 : 1);
+    view.diffScroll = 0;
+  } else if (isBack(key) || key === KEY.left) view.focus = 'files';
+  else return false;
+  return true;
+}
+
+// 검색 중에는 글자를 검색어로 받는다. Enter 는 검색어를 남기고 목록으로, Esc 는 검색을 지운다.
+function searchKey(view, key, act) {
+  if (key === KEY.enter) view.searching = false;
+  else if (key === KEY.esc) {
+    view.searching = false;
+    view.filter = '';
+  } else if (key === KEY.backspace || key === '\b') view.filter = [...(view.filter ?? '')].slice(0, -1).join('');
+  else if (!/[\x00-\x1f\x7f]/.test(key)) view.filter = (view.filter ?? '') + key;
+  act.keepVisible();
+}
+
+// 도움말은 모달이다: 열려 있는 동안은 스크롤(↑↓ j k space PgUp PgDn), 닫기(? Esc), 나가기(q)만 듣고 나머지 키는 버린다.
+// 스크롤 끝과 한 페이지 줄 수는 마지막으로 그린 도움말이 정한다 (view.helpMax, view.helpPage).
+function helpKey(view, key, act) {
+  if (key === '?' || key === KEY.esc) view.help = false;
+  else if (key === 'q') act.quit();
+  else {
+    const page = view.helpPage ?? 10;
+    const step = isUp(key) ? -1 : isDown(key) ? 1 : key === ' ' || key === KEY.pageDown ? page : key === KEY.pageUp ? -page : 0;
+    if (step) view.helpScroll = Math.min(view.helpMax ?? 0, Math.max(0, (view.helpScroll ?? 0) + step));
+  }
+}
+
+export function onKey(view, key, act) {
+  if (key === KEY.ctrlC) return act.quit();
+  if (view.help) return helpKey(view, key, act);
+  if (view.searching) return searchKey(view, key, act);
+  if (key === '?') {
+    view.help = true;
+    view.helpScroll = 0;
+    return;
+  }
+  if (key === 'q') return act.quit();
+  if (view.focus === 'diff' && diffKey(view, key)) return;
+  if (view.focus === 'files' && filesKey(view, key)) return;
+  if (key === KEY.esc) {
+    view.filter = '';
+    return;
+  }
+  if (key === 'f' || key === KEY.tab) return enterFiles(view);
+  if (key === '/') {
+    view.searching = true;
+    view.filter = '';
+    view.focus = null;
+  } else if (isUp(key)) act.move(-1);
+  else if (isDown(key)) act.move(1);
+  else if (key === 'n') act.next();
+  // 정렬·묶기는 순서만 바꾸고 선택은 같은 세션 id 에 남는다.
+  else if (key === 's') view.sort = nextSort(view.sort);
+  else if (key === 'g') view.group = nextGroup(view.group);
+  // 고정(p)은 이번 실행에만 기억한다. 고른 세션은 그대로 남고 자리만 위로 옮긴다.
+  // 파일 목록·diff 에 들어가 있을 때는 키 안내에 없으므로 받지 않는다.
+  else if (key === 'p') {
+    if (view.selectedId != null && !view.focus) view.pins = togglePin(view.pins, view.selectedId);
+  }
+  else if (key === 'c') view.costMode = view.costMode === 'net' ? 'api' : 'net';
+  else if (key === 'd') {
+    // view.rows: 마지막으로 그린 화면 높이. 'auto' 일 때 지금 보이는 상태를 뒤집는 데 쓴다.
+    view.showDetail = !detailOpen(view, view.rows ?? Infinity);
+    if (!view.showDetail) view.focus = null;
+  } else if (key === 'e') {
+    view.showEnded = !view.showEnded;
+    act.refresh();
+  }
+}

package/src/log.mjs

@@ -0,0 +1,130 @@
+// 디버그 로그: --debug (AITOP_DEBUG=1, 설정 파일 debug) 일 때만 $XDG_STATE_HOME/aitop/aitop.log 에 남긴다.
+// 기록 형식이 바뀌어 값이 비는 원인을 찾기 위한 것이라, 오류 이름·코드와 짧은 맥락(출처, 파일 이름)만 쓴다.
+// 기록 내용·도구 입력은 쓰지 않고, 쓰는 글은 모두 mask() 와 stripControl() 을 거친다.
+// 꺼져 있으면 파일을 만들지 않고 debug() 는 바로 돌아간다.
+import { closeSync, constants, fchmodSync, fstatSync, mkdirSync, openSync, renameSync, statSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { mask, stripControl } from './text.mjs';
+
+// 이 크기를 넘으면 aitop.log.1 로 옮기고 새로 쓴다 (이전 것 하나만 남긴다).
+// aitop 여럿이 같은 파일에 쓸 수 있다: 덧붙이기(O_APPEND)로만 쓰고, 옮기기 전에 그 이름이 아직 내가 연 파일인지와 실제 크기를 다시 본다.
+export const MAX_BYTES = 1024 * 1024;
+// 같은 출처·같은 문구는 이 간격에 한 번만 쓴다.
+export const REPEAT_MS = 60_000;
+const MAX_KEYS = 1000;
+
+export function logPath(env = process.env, home = homedir()) {
+  const xdg = env.XDG_STATE_HOME;
+  return join(xdg && isAbsolute(xdg) ? xdg : join(home, '.local', 'state'), 'aitop', 'aitop.log');
+}
+
+let state = { on: false, path: null };
+
+export const logState = () => ({ on: state.on, path: state.path });
+
+// 오류에서 원인만 꺼낸다. JSON.parse 의 SyntaxError 문구에는 읽던 내용 일부가 들어가므로 이름만 쓴다.
+function errText(err) {
+  if (err == null) return '';
+  if (typeof err !== 'object') return String(err);
+  // node:sqlite 오류의 문구("database is locked", "no such table: …")는 SQLite 가 정한 말이라 함께 쓴다.
+  if (err.code === 'ERR_SQLITE_ERROR') return [err.code, err.errcode, err.errstr, err.message].filter((x) => x != null && x !== '').join(' ').slice(0, 200);
+  if (err.code) return [err.code, err.syscall].filter(Boolean).join(' ');
+  if (err instanceof SyntaxError) return 'SyntaxError';
+  return `${err.name ?? 'Error'}: ${err.message ?? ''}`;
+}
+
+const clean = (s, max) => mask(stripControl(String(s ?? '').replace(/[\r\n\t]+/g, ' '))).slice(0, max);
+
+function openLog(path) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const fd = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0), 0o600);
+  try {
+    // 예전에 다른 권한으로 만들어진 파일이어도 나만 읽게 한다.
+    fchmodSync(fd, 0o600);
+    const st = fstatSync(fd);
+    return { fd, size: st.size, ino: st.ino, dev: st.dev };
+  } catch (err) {
+    closeSync(fd);
+    throw err;
+  }
+}
+
+// enabled 가 아니면 아무것도 만들지 않는다. now·maxBytes 는 테스트에서 바꿔 끼운다.
+export function initLog({ enabled = false, path = logPath(), maxBytes = MAX_BYTES, now = Date.now, version = '' } = {}) {
+  closeLog();
+  state = { on: false, path };
+  if (!enabled) return logState();
+  try {
+    const { fd, size } = openLog(path);
+    state = { on: true, path, fd, size, maxBytes, now, seen: new Map() };
+    write(`aitop ${clean(version, 40)} 디버그 로그 시작 (pid ${process.pid}, node ${process.versions.node})`);
+  } catch (err) {
+    state = { on: false, path, error: errText(err) };
+  }
+  return logState();
+}
+
+export function closeLog() {
+  if (state.fd != null) {
+    try {
+      closeSync(state.fd);
+    } catch {}
+  }
+  state = { on: false, path: state.path };
+}
+
+// 다른 aitop 이 먼저 옮겼으면(이름이 가리키는 파일이 바뀌었거나 없으면) 옮기지 않고 새 파일을 다시 연다.
+// 둘이 거의 같이 옮기면 이전 로그 하나를 잃을 수는 있어도, 로그가 꺼지거나 새 로그를 덮지는 않는다.
+function rotate(add) {
+  const mine = fstatSync(state.fd);
+  closeSync(state.fd);
+  state.fd = null;
+  try {
+    const now = statSync(state.path);
+    const same = now.ino === mine.ino && now.dev === mine.dev;
+    if (same && now.size > 0 && now.size + add > state.maxBytes) renameSync(state.path, state.path + '.1');
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+  Object.assign(state, openLog(state.path));
+}
+
+function write(text) {
+  const line = Buffer.from(`${new Date(state.now()).toISOString()} ${text}\n`);
+  if (state.size + line.length > state.maxBytes && state.size > 0) rotate(line.length);
+  writeSync(state.fd, line);
+  state.size += line.length;
+}
+
+// source: 'codex', 'claude' 처럼 어디서 났는지. message: 무엇이 실패했는지 (고정 문구). err: 잡은 오류. file: 경로면 파일 이름만 쓴다.
+export function debug(source, message, err, file) {
+  if (!state.on) return;
+  try {
+    const key = `${source}\0${message}`;
+    const t = state.now();
+    const prev = state.seen.get(key);
+    if (prev && t - prev.at < REPEAT_MS) {
+      prev.skipped++;
+      return;
+    }
+    if (state.seen.size >= MAX_KEYS) state.seen.clear();
+    state.seen.set(key, { at: t, skipped: 0 });
+    const parts = [`[${clean(source, 32)}] ${clean(message, 200)}`];
+    const why = errText(err);
+    if (why) parts.push(`: ${clean(why, 300)}`);
+    if (file) parts.push(` (${clean(basename(String(file)), 120)})`);
+    if (prev?.skipped) parts.push(` (+${prev.skipped}번 생략)`);
+    write(parts.join(''));
+  } catch (e) {
+    // 로그를 쓸 수 없으면 끄고 조용히 계속한다. 화면은 로그 때문에 멈추지 않는다.
+    closeLog();
+    state.error = errText(e);
+  }
+}
+
+// 파일이 없거나(지워졌거나 아직 안 생김) 경로 중간이 폴더가 아닌 경우는 늘 있는 일이라 남기지 않는다.
+const ROUTINE = new Set(['ENOENT', 'ENOTDIR']);
+export function debugIo(source, message, err, file) {
+  if (state.on && !ROUTINE.has(err?.code)) debug(source, message, err, file);
+}

package/src/notify.mjs

@@ -0,0 +1,251 @@
+// 응답 대기 알림: --notify (데스크톱 알림), --on-waiting <명령> (사용자 명령 실행).
+// 세션 정보는 명령 문자열에 넣지 않는다. 알림 도구에는 인자로, 사용자 명령에는 AITOP_* 환경변수로만 넘긴다.
+import { spawn } from 'node:child_process';
+import { accessSync, constants, readFileSync } from 'node:fs';
+import { join, delimiter } from 'node:path';
+import { mask, stripControl } from './text.mjs';
+
+export const HOOK_TIMEOUT_MS = 10_000;
+const LABEL_MAX = 120;
+
+// 옵션 해석은 여기 한 곳에서 한다. config 에는 설정 파일 값(notify, onWaiting)을 넘기고, 명령줄 옵션이 그 위를 덮는다.
+// argv 에서 --notify, --no-notify, --on-waiting <cmd>, --on-waiting=<cmd>, --no-on-waiting 을 꺼내고 나머지는 rest 로 돌려준다.
+// 값을 따로 받는 다른 옵션(valueOpts)의 값은 건드리지 않고 그대로 넘긴다 (그 옵션의 해석과 같게 - 로 시작하지 않는 다음 인자).
+export const VALUE_OPTS = ['--theme'];
+export function notifyOptions(argv, config = {}, valueOpts = VALUE_OPTS) {
+  let notify = config.notify === true;
+  let onWaiting = typeof config.onWaiting === 'string' && config.onWaiting.trim() ? config.onWaiting : null;
+  let error = null;
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (valueOpts.includes(a)) {
+      rest.push(a);
+      if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) rest.push(argv[++i]);
+      continue;
+    }
+    if (a === '--notify') {
+      notify = true;
+      continue;
+    }
+    if (a === '--no-notify') {
+      notify = false;
+      continue;
+    }
+    if (a === '--no-on-waiting') {
+      onWaiting = null;
+      continue;
+    }
+    const m = /^--on-waiting(?:=([\s\S]*))?$/.exec(a);
+    if (!m) {
+      rest.push(a);
+      continue;
+    }
+    const v = m[1] ?? (i + 1 < argv.length ? argv[++i] : '');
+    if (!v.trim()) error = '--on-waiting 값이 없습니다 (실행할 명령)';
+    else if (m[1] == null && v.startsWith('-')) error = `--on-waiting 값이 - 로 시작합니다 (${v}). 명령이 맞으면 --on-waiting='${v}' 처럼 = 로 붙여 쓴다`;
+    else onWaiting = v;
+  }
+  return { notify, onWaiting, rest, error };
+}
+
+function executable(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function which(name, envPath = process.env.PATH ?? '') {
+  for (const dir of envPath.split(delimiter)) {
+    if (!dir) continue;
+    const p = join(dir, name);
+    if (executable(p)) return p;
+  }
+  return null;
+}
+
+export function isWsl(env = process.env) {
+  if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) return true;
+  try {
+    return /microsoft/i.test(readFileSync('/proc/version', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+// 쓸 수 있는 데스크톱 알림 도구. 없으면 null (조용히 건너뛴다).
+// Linux·WSL 은 notify-send 만 쓴다. WSL 에서 없으면 powershell 로 대신하지 않는다.
+export function findNotifier({ platform = process.platform, env = process.env } = {}) {
+  if (platform === 'darwin') {
+    const path = which('osascript', env.PATH);
+    return path ? { kind: 'osascript', path } : null;
+  }
+  if (platform === 'linux') {
+    const path = which('notify-send', env.PATH);
+    return path ? { kind: 'notify-send', path } : null;
+  }
+  return null;
+}
+
+// 알림 도구 실행 인자. 제목·본문은 인자로만 넘긴다 (셸·AppleScript 문자열에 넣지 않는다).
+export function notifierCommand(notifier, title, body) {
+  if (notifier.kind === 'osascript') {
+    return [notifier.path, ['-e', 'on run argv', '-e', 'display notification (item 2 of argv) with title (item 1 of argv)', '-e', 'end run', title, body]];
+  }
+  // notify-send 는 본문을 마크업으로 읽으므로 <, >, & 를 바꿔 넣는다.
+  return [notifier.path, ['--app-name=aitop', '--', escapeMarkup(title), escapeMarkup(body)]];
+}
+
+const escapeMarkup = (t) => String(t).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// 세션에서 짧은 대기 사유. "응답 대기 · Bash" → "Bash". 비밀값처럼 보이는 것은 가린다.
+export function waitingLabel(s) {
+  const text = String(s.phase?.kind === 'waiting' ? (s.phase.text ?? '') : '').replace(/^응답 대기(?: · )?/, '');
+  const one = stripControl(text).replace(/\s+/g, ' ').trim();
+  return mask(one.length > LABEL_MAX ? one.slice(0, LABEL_MAX - 1) + '…' : one);
+}
+
+// --on-waiting 명령에 넘기는 환경변수.
+export function waitingEnv(s) {
+  return {
+    AITOP_TOOL: String(s.tool ?? ''),
+    AITOP_PROJECT: String(s.project ?? ''),
+    AITOP_SESSION_ID: String(s.id ?? ''),
+    AITOP_CWD: String(s.cwd ?? ''),
+    AITOP_WAITING_FOR: waitingLabel(s),
+  };
+}
+
+export function notifyText(sessions) {
+  if (sessions.length === 1) {
+    const s = sessions[0];
+    const label = waitingLabel(s);
+    return { title: `aitop: 응답 대기 (${s.tool ?? '?'})`, body: stripControl(`${s.project ?? s.id ?? ''}${label ? ' · ' + label : ''}`) };
+  }
+  return { title: 'aitop: 응답 대기', body: `${sessions.length}개 세션이 응답을 기다립니다` };
+}
+
+// 한 번에 하나만 실행하는 자식 프로세스 실행기.
+// 실행 중에 새 일이 오면 하나만 대기열에 두고(가장 최근 것으로 덮어씀), 끝나면 그것을 실행한다.
+// 출력은 버리고, timeoutMs 가 지나면 프로세스 그룹째(셸과 그 자식) SIGKILL 한다.
+// 자식은 'exit' 를 받아 거두므로 좀비가 남지 않는다. UI 루프는 기다리지 않는다.
+function killGroup(c, sig) {
+  try {
+    process.kill(-c.pid, sig);
+  } catch {
+    try {
+      c.kill(sig);
+    } catch {}
+  }
+}
+
+// 실행 중인 모든 자식(이 모듈이 띄운 것). 자식은 따로 프로세스 그룹이라 aitop 이 끝나도 같이 죽지 않으므로,
+// 끝날 때(process 'exit') 그룹째 SIGKILL 한다. 'exit' 안에서는 동기 호출만 되므로 process.kill 만 쓴다.
+const liveChildren = new Set();
+let exitHooked = false;
+
+export function killAllChildren() {
+  for (const c of liveChildren) killGroup(c, 'SIGKILL');
+  liveChildren.clear();
+}
+
+function track(c) {
+  liveChildren.add(c);
+  if (!exitHooked) {
+    exitHooked = true;
+    process.on('exit', killAllChildren);
+  }
+}
+
+export function createRunner({ timeoutMs = HOOK_TIMEOUT_MS, spawnFn = spawn } = {}) {
+  let child = null;
+  let pending = null;
+  const stats = { started: 0, dropped: 0, timedOut: 0 };
+
+  function start(job) {
+    let c;
+    try {
+      c = spawnFn(job.file, job.args, { env: job.env, stdio: 'ignore', detached: true });
+    } catch {
+      return next();
+    }
+    child = c;
+    if (c.pid) track(c);
+    stats.started++;
+    // 셸이 아직 살아 있을 때만 그룹을 죽이므로 그룹 id 가 다른 프로세스 것으로 바뀌어 있을 일이 없다.
+    const timer = setTimeout(() => {
+      stats.timedOut++;
+      killGroup(c, 'SIGKILL');
+    }, timeoutMs);
+    timer.unref?.();
+    let finished = false;
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      liveChildren.delete(c);
+      if (child === c) child = null;
+      next();
+    };
+    c.once('exit', finish);
+    c.once('error', finish);
+  }
+
+  function next() {
+    if (!pending) return;
+    const job = pending;
+    pending = null;
+    start(job);
+  }
+
+  return {
+    run(job) {
+      if (child) {
+        if (pending) stats.dropped++;
+        pending = job;
+        return false;
+      }
+      start(job);
+      return true;
+    },
+    get busy() {
+      return child != null;
+    },
+    // 대기열을 비우고 실행 중인 자식을 그룹째 SIGKILL 한다 (aitop 이 끝날 때).
+    killAll() {
+      pending = null;
+      if (child) {
+        killGroup(child, 'SIGKILL');
+        liveChildren.delete(child);
+        child = null;
+      }
+    },
+    stats,
+  };
+}
+
+// --notify, --on-waiting 을 묶은 알리미. 새로 응답 대기가 된 세션 목록을 받는다.
+export function createNotifier({ notify = false, onWaiting = null, notifier = notify ? findNotifier() : null, env = process.env, timeoutMs = HOOK_TIMEOUT_MS, spawnFn = spawn } = {}) {
+  const hook = onWaiting ? createRunner({ timeoutMs, spawnFn }) : null;
+  const desk = notify && notifier ? createRunner({ timeoutMs, spawnFn }) : null;
+  return {
+    hook,
+    desk,
+    killAll() {
+      hook?.killAll();
+      desk?.killAll();
+    },
+    fire(fresh) {
+      if (!fresh.length) return;
+      if (desk) {
+        const { title, body } = notifyText(fresh);
+        const [file, args] = notifierCommand(notifier, title, body);
+        desk.run({ file, args, env });
+      }
+      if (hook) for (const s of fresh) hook.run({ file: '/bin/sh', args: ['-c', onWaiting], env: { ...env, ...waitingEnv(s) } });
+    },
+  };
+}

package/src/order.mjs

@@ -0,0 +1,69 @@
+// 세션 표의 정렬(s)과 묶기(g). 기본 순서는 받은 목록의 순서 그대로다 (collect.mjs 가 bySession 으로 줄 세워 넘긴다).
+// 응답 대기 세션은 사람이 할 일이므로 어떤 정렬·묶기에서도 맨 위에 둔다.
+// 묶을 때는 대기 세션을 프로젝트·도구 묶음에 섞지 않고 맨 위 '응답 대기' 묶음 하나로 모은다.
+// 대기 세션이 제 프로젝트 묶음 안에 흩어지면 맨 위라는 약속이 깨지고, 묶음 머리 위에 따로 두면 어느 묶음 소속인지 헷갈린다.
+// 고정(p)한 세션은 응답 대기 바로 아래에 고정한 순서대로 둔다. 정렬을 바꿔도 그 순서는 바뀌지 않고, 묶을 때는 '고정' 묶음 하나로 모은다.
+// 응답 대기를 고정보다 위에 두는 것은 사람이 할 일이 고정 목록에 가려지지 않게 하려는 것이다. 고정한 세션이 응답 대기가 되면 대기 쪽으로 올라간다.
+import { costOf } from './ui/draw.mjs';
+
+export const SORTS = ['default', 'cost', 'context', 'recent'];
+export const GROUPS = ['none', 'project', 'tool'];
+export const SORT_LABEL = { default: '기본', cost: '비용', context: '컨텍스트', recent: '최근' };
+export const GROUP_LABEL = { none: '없음', project: '프로젝트', tool: '도구' };
+export const WAITING_GROUP = '응답 대기';
+export const PINNED_GROUP = '고정';
+
+// pins 에 id 가 있으면 빼고, 없으면 끝에 붙인다 (고정한 순서를 지킨다). 새 배열을 돌려준다.
+export const togglePin = (pins = [], id) => (pins.includes(id) ? pins.filter((x) => x !== id) : [...pins, id]);
+
+const next = (list, cur) => list[(Math.max(0, list.indexOf(cur)) + 1) % list.length];
+export const nextSort = (sort) => next(SORTS, sort ?? 'default');
+export const nextGroup = (group) => next(GROUPS, group ?? 'none');
+
+const ctxPct = (s) => (s.context?.window > 0 ? (s.context.used ?? 0) / s.context.window : -1);
+const KEYS = {
+  cost: (s, mode) => costOf(s, mode) ?? -1,
+  context: ctxPct,
+  recent: (s) => s.updatedAt ?? -Infinity,
+};
+
+// 종료 세션은 어떤 정렬에서도 (묶음 안에서도) 아래에 둔다. 그다음 큰 값이 위. 값이 같으면 받은 순서(기본 순서)를 지켜 갱신마다 자리가 흔들리지 않게 한다 (Array.prototype.sort 는 안정 정렬).
+export function compare(sort, costMode = 'api') {
+  const key = KEYS[sort];
+  if (!key) return () => 0;
+  const ended = (s) => (s.status === 'ended' ? 1 : 0);
+  return (a, b) => ended(a) - ended(b) || key(b, costMode) - key(a, costMode);
+}
+
+const projectOf = (s) => s.project || String(s.cwd ?? '').split('/').filter(Boolean).at(-1) || '(폴더 없음)';
+const GROUP_KEY = { project: projectOf, tool: (s) => s.tool ?? '?' };
+
+// 돌려주는 sessions 는 화면에 그리는 순서 그대로다 (↑↓·n 도 이 순서를 따른다).
+// groups 는 묶을 때만 있다: { name, count, cost, unknown, waiting, pinned, sessions }. 묶음은 그 안의 첫 세션이 정렬에서 앞선 순으로 놓인다.
+// pins: 고정한 세션 id (고정한 순서). 화면에 없는 id 는 건너뛴다.
+export function arrange(sessions, { sort = 'default', group = 'none', costMode = 'api', pins = [] } = {}) {
+  const cmp = compare(sort, costMode);
+  const rank = new Map((pins ?? []).map((id, i) => [id, i]));
+  const waiting = sessions.filter((s) => s.status === 'waiting').sort(cmp);
+  const pinned = sessions.filter((s) => s.status !== 'waiting' && rank.has(s.id)).sort((a, b) => rank.get(a.id) - rank.get(b.id));
+  const rest = sessions.filter((s) => s.status !== 'waiting' && !rank.has(s.id)).sort(cmp);
+  const keyOf = GROUP_KEY[group];
+  if (!keyOf) return { sessions: [...waiting, ...pinned, ...rest], groups: null };
+  const byName = new Map();
+  for (const s of rest) {
+    const name = keyOf(s);
+    if (!byName.has(name)) byName.set(name, []);
+    byName.get(name).push(s);
+  }
+  const head = [...(waiting.length ? [[WAITING_GROUP, waiting, 'waiting']] : []), ...(pinned.length ? [[PINNED_GROUP, pinned, 'pinned']] : [])];
+  const groups = [...head, ...[...byName].map(([name, list]) => [name, list, null])].map(([name, list, kind]) => ({
+    name,
+    count: list.length,
+    cost: list.reduce((a, s) => a + (costOf(s, costMode) ?? 0), 0),
+    unknown: list.some((s) => s.costUnknown),
+    waiting: kind === 'waiting',
+    pinned: kind === 'pinned',
+    sessions: list,
+  }));
+  return { sessions: groups.flatMap((g) => g.sessions), groups };
+}