pleumrouter 0.2.1 → 0.3.0

package/README.md

@@ -2,6 +2,20 @@
 
 PleumRouter 공식 터미널 CLI. 쓰던 코딩 에이전트를 한 줄로 PleumRouter에 붙여 실행한다.
 
+## 설치
+
+Node.js 18 이상 필요(순수 Node CLI라 별도 바이너리 없음).
+
+```bash
+curl -fsSL https://router.pleum.ai/install | sh   # 원라이너(npm 전역 설치를 감쌈)
+npm install -g pleumrouter                          # npm
+bun install -g pleumrouter                          # bun
+```
+
+설치 없이 `npx pleumrouter <명령>` 으로 바로 실행할 수도 있다.
+
+## 빠른 시작
+
 ```bash
 npx pleumrouter login                          # 브라우저 로그인 + 키 자동 저장
 npx pleumrouter launch claude --model claude-sonnet-4
@@ -18,9 +32,13 @@ cat error.log | npx pleumrouter run gpt-4.1 "원인은?"   # 파이프
 | `pleum login [--device]` | 브라우저로 로그인 → CLI가 API 키를 자동 발급·저장(`~/.pleum/config.json`). `--device`는 SSH·CI |
 | `pleum logout` | 저장된 키 삭제 |
 | `pleum launch [tool] [--model id] [-- args]` | 에이전트 실행. `--` 뒤 인자는 도구로 그대로 전달. 도구 생략 시 지원 목록·설치 여부 표시 |
-| `pleum run [model] ["프롬프트"]` | 채팅 — 대화형 REPL, 1회 실행, stdin 파이프. 모델 생략 시 인터랙티브 선택 |
+| `pleum run [model] ["프롬프트"]` | 채팅 — 대화형 REPL, 1회 실행, stdin 파이프. 모델 생략 시 화살표로 선택 |
 | `pleum models [query] [--json]` | 모델 목록(공개) — provider·컨텍스트·가격(₩/1M) 컬럼, `--json`은 스크립트용 |
+| `pleum models <id> --info` | 모델 상세 — 가격·컨텍스트·provider별 지연/처리량/업타임·주간 사용량·형제 모델 |
+| `pleum top [--period daily\|weekly\|monthly]` | 라우터 전체 모델 리더보드 + 제공자 점유율(공개 통계) |
 | `pleum balance` | 크레딧 잔액 조회 |
+| `pleum usage [--by model\|provider\|api_key\|day] [--days N]` | 내 지출 리포트(막대 차트) — 최신 로그인 키 필요(`usage:read`) |
+| `pleum health` | 게이트웨이 연결·DB·Redis·환율·로그인 상태 점검(셀프호스트 진단용) |
 | `pleum completion <zsh\|bash>` | 셸 자동완성 스크립트 출력 |
 | `pleum upgrade` | 최신 버전으로 재설치 |
 | `pleum version` | 버전 출력 |
@@ -32,7 +50,7 @@ cat error.log | npx pleumrouter run gpt-4.1 "원인은?"   # 파이프
 | 명령 | 설명 |
 |------|------|
 | `/help`, `/?` | 명령 도움말 |
-| `/model [id]` | **세션 유지한 채 모델 전환**(여러 모델을 한 대화에서 비교) |
+| `/model [id]` | **세션 유지한 채 모델 전환**(인자 없으면 화살표 셀렉터) |
 | `/system [텍스트]` | 시스템 프롬프트 설정/확인 |
 | `/clear` | 대화 컨텍스트 초기화 |
 | `/models [검색어]` | 모델 목록 보기 |
@@ -40,9 +58,13 @@ cat error.log | npx pleumrouter run gpt-4.1 "원인은?"   # 파이프
 | `/verbose` | 토큰·속도 통계 토글 |
 | `/exit`, `/quit` | 종료 |
 
+- 응답은 **마크다운 스트리밍 렌더**(굵게·코드블록 하이라이트·리스트) — 파이프로 빼면 자동으로 원문 그대로
+- 응답 후 비용이 PLM으로 표시(스트리밍 마지막 청크 기준)
+- **Ctrl+C**: 생성 중엔 1회로 중단(대화 유지), 대기 중엔 2초 내 2회로 종료
 - 여러 줄 입력: `"""` 한 줄 → 본문 → `"""` 한 줄
 - 이미지: 메시지에 이미지 파일 경로를 그대로 포함 (예: `이 그림 설명해줘 ./shot.png`)
 - `↑` 로 지난 입력 재호출(히스토리는 `~/.pleum/history`에 영속)
+- 색상 끄기: `NO_COLOR=1` (비TTY·파이프에선 자동 무색)
 
 ## 자동 실행 지원 도구
 

package/bin/pleum.mjs

@@ -5,6 +5,9 @@ import { launch, launchHelp } from "../src/launch.mjs";
 import { run } from "../src/run.mjs";
 import { listModels } from "../src/models.mjs";
 import { balance } from "../src/balance.mjs";
+import { usage } from "../src/usage.mjs";
+import { top } from "../src/top.mjs";
+import { health } from "../src/health.mjs";
 import { completion } from "../src/completion.mjs";
 import { upgrade } from "../src/upgrade.mjs";
 import { clearConfig } from "../src/config.mjs";
@@ -18,9 +21,13 @@ const HELP = `pleum — PleumRouter 터미널 CLI
                                      (claude · aider · codex · goose · openhands)
                                      도구 생략 시 지원 목록·설치 여부 표시
   pleum run [model] ["프롬프트"]      터미널 채팅(REPL) / 1회 실행 / 파이프
-                                     모델 생략 시 인터랙티브 선택, /help 로 명령
+                                     모델 생략 시 화살표로 선택, /help 로 명령
   pleum models [query] [--json]      모델 목록(가격·컨텍스트 포함)
+  pleum models <id> --info           모델 상세(가격·성능·provider별 uptime)
+  pleum top [--period weekly]        모델 리더보드·제공자 점유율(daily|weekly|monthly)
   pleum balance                      크레딧 잔액 조회
+  pleum usage [--by model] [--days 30]  내 지출 리포트(model|provider|api_key|day)
+  pleum health                       게이트웨이 연결·로그인 상태 점검
   pleum completion <zsh|bash>        셸 자동완성 스크립트 출력
   pleum upgrade                      최신 버전으로 재설치
   pleum version                      버전 출력
@@ -31,6 +38,8 @@ const HELP = `pleum — PleumRouter 터미널 CLI
   pleum run gpt-4.1                          # 대화형
   pleum run gpt-4.1 "한 줄로 요약: ..."       # 1회 실행
   cat error.log | pleum run gpt-4.1 "원인은?"  # 파이프
+  pleum models deepseek/deepseek-chat --info # 모델 상세
+  pleum usage --by day --days 7              # 최근 1주 일별 지출
   pleum login --device                       # SSH/CI 환경
 
 base_url 덮어쓰기: PLEUM_BASE_URL 환경변수`;
@@ -84,6 +93,15 @@ try {
     case "balance":
       await balance();
       break;
+    case "usage":
+      await usage(rest);
+      break;
+    case "top":
+      await top(rest);
+      break;
+    case "health":
+      await health();
+      break;
     case "completion":
       completion(rest[0]);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pleumrouter",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Official PleumRouter terminal CLI — launch any coding agent against PleumRouter.",
   "type": "module",
   "bin": {

package/src/ansi.mjs

@@ -0,0 +1,95 @@
+// 색상/스타일 프리미티브 — zero-dep. NO_COLOR·비TTY·dumb 터미널이면 자동 무색.
+// 브랜드 컬러는 frontend globals.css의 --plum-bright(#936c89) 계열.
+
+// 색상 지원 레벨: 0=무색, 1=16색, 2=256색, 3=truecolor. env/stream 주입 가능(테스트용).
+export function detectColorLevel(env = process.env, stream = process.stdout) {
+  if (env.NO_COLOR != null) return 0;
+  if (env.FORCE_COLOR != null) {
+    const n = Number(env.FORCE_COLOR);
+    return Number.isFinite(n) ? Math.max(0, Math.min(3, n)) : 3;
+  }
+  if (!stream.isTTY || env.TERM === "dumb") return 0;
+  if (env.COLORTERM === "truecolor" || env.COLORTERM === "24bit") return 3;
+  if (/-256(color)?$/.test(env.TERM || "")) return 2;
+  return 1;
+}
+
+const PLUM = [147, 108, 137]; // #936c89 — 다크 터미널에서 가독성 있는 브랜드 보라
+
+// RGB → xterm 256색 큐브 근사(16 + 36r + 6g + b, 각 축 0–5 양자화).
+function rgbTo256([r, g, b]) {
+  const q = (v) => Math.round((v / 255) * 5);
+  return 16 + 36 * q(r) + 6 * q(g) + q(b);
+}
+
+// 각 wrap은 \x1b[0m 완전 리셋 — 중첩 보존보다 색 누수 방지 우선(zero-dep 트레이드오프).
+export function createStyler(level = detectColorLevel()) {
+  const wrap = (open) => (s) => (level ? `${open}${s}\x1b[0m` : String(s));
+  const rgb = (c, fallback16) =>
+    level >= 3
+      ? wrap(`\x1b[38;2;${c.join(";")}m`)
+      : level === 2
+        ? wrap(`\x1b[38;5;${rgbTo256(c)}m`)
+        : wrap(`\x1b[${fallback16}m`);
+  return {
+    level,
+    bold: wrap("\x1b[1m"),
+    dim: wrap("\x1b[2m"),
+    italic: wrap("\x1b[3m"),
+    plum: rgb(PLUM, 35), // 16색 폴백=마젠타
+    green: wrap("\x1b[32m"),
+    red: wrap("\x1b[31m"),
+    yellow: wrap("\x1b[33m"),
+    cyan: wrap("\x1b[36m"),
+    gray: wrap("\x1b[90m"),
+  };
+}
+
+// CLI 런타임 싱글턴 — 파이프/NO_COLOR면 모든 함수가 항등이라 호출부 분기 불필요.
+export const style = createStyler();
+
+export function stripAnsi(s) {
+  // eslint 불필요 — CSI 시퀀스만 제거하면 충분(우리가 쓰는 코드 전부 CSI).
+  return String(s).replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+}
+
+// 터미널 표시 폭 — CJK(한글 등) 전각 문자는 2칸. 정렬·줄수 계산용.
+export function displayWidth(s) {
+  let w = 0;
+  for (const ch of stripAnsi(s)) {
+    const c = ch.codePointAt(0);
+    const wide =
+      c >= 0x1100 &&
+      (c <= 0x115f || // 한글 자모
+        (c >= 0x2e80 && c <= 0xa4cf) || // CJK 부수·한자·가나
+        (c >= 0xac00 && c <= 0xd7a3) || // 한글 음절
+        (c >= 0xf900 && c <= 0xfaff) ||
+        (c >= 0xfe30 && c <= 0xfe4f) ||
+        (c >= 0xff00 && c <= 0xff60) || // 전각 영숫자
+        (c >= 0xffe0 && c <= 0xffe6) ||
+        (c >= 0x20000 && c <= 0x3fffd));
+    w += wide ? 2 : 1;
+  }
+  return w;
+}
+
+// 표시 폭 기준 오른쪽 패딩 — ANSI·전각 섞여도 컬럼이 맞는다(String.padEnd 대체).
+export function padDisplay(s, width) {
+  const pad = width - displayWidth(s);
+  return pad > 0 ? s + " ".repeat(pad) : s;
+}
+
+export function terminalWidth(fallback = 80) {
+  return process.stdout.columns || fallback;
+}
+
+export function divider(width = Math.min(terminalWidth(), 60), styler = style) {
+  return styler.gray("─".repeat(Math.max(1, width)));
+}
+
+// "█████░░░░░" 수평 막대(순수 함수) — usage/top 공용.
+export function barChart(value, max, width = 20) {
+  if (!Number.isFinite(value) || !max || max <= 0) return "░".repeat(width);
+  const filled = Math.round(Math.min(Math.max(value / max, 0), 1) * width);
+  return "█".repeat(filled) + "░".repeat(Math.max(0, width - filled));
+}

package/src/balance.mjs

@@ -1,5 +1,5 @@
-import { V1 } from "./config.mjs";
-import { requireKey } from "./config.mjs";
+import { V1, requireKey } from "./config.mjs";
+import { style } from "./ansi.mjs";
 
 export async function balance() {
   const key = requireKey();
@@ -8,11 +8,18 @@ export async function balance() {
   });
   if (!res.ok) {
     const body = await res.text().catch(() => "");
-    console.error(`잔액 조회 실패 (HTTP ${res.status})${body ? `: ${body}` : ""}`);
+    console.error(`잔액 조회 실패 (HTTP ${res.status})${body ? `: ${body.slice(0, 200)}` : ""}`);
+    if (res.status === 401) {
+      console.error(style.dim("서버가 아직 API 키 잔액 조회를 지원하지 않거나 키가 만료됐을 수 있습니다 — pleum login 재시도."));
+    }
     process.exit(1);
   }
   const data = await res.json();
   const plm = data.balance_krw;
-  const usd = data.balance_usd != null ? ` / $${data.balance_usd.toFixed(4)}` : "";
-  console.log(`잔액: ${plm.toLocaleString("ko-KR")} PLM${usd}`);
+  const usd = data.balance_usd != null ? style.dim(` / $${data.balance_usd.toFixed(4)}`) : "";
+  console.log(`잔액: ${style.bold(style.plum(`${plm.toLocaleString("ko-KR")} PLM`))}${usd}`);
+  const threshold = data.auto_charge_threshold_krw;
+  if (threshold != null && plm < threshold) {
+    console.log(style.yellow(`⚠ 잔액이 자동충전 임계값(${threshold.toLocaleString("ko-KR")} PLM) 아래입니다.`));
+  }
 }

package/src/completion.mjs

@@ -1,6 +1,6 @@
 // Shell 자동완성 스크립트 출력. 명령·도구는 정적, 모델명은 `pleum models`에서 동적으로 채운다.
 // 설치: pleum completion zsh >> ~/.zshrc  ·  pleum completion bash >> ~/.bashrc
-const COMMANDS = "login logout launch run models balance version upgrade completion help";
+const COMMANDS = "login logout launch run models top balance usage health version upgrade completion help";
 const TOOLS = "claude aider codex goose openhands opencode crush";
 
 function bash() {

package/src/config.mjs

@@ -3,7 +3,9 @@ import { join } from "node:path";
 import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
 
 // 공개 게이트웨이 루트. 셀프호스트/스테이징은 PLEUM_BASE_URL로 덮어쓴다.
-export const ROOT = (process.env.PLEUM_BASE_URL ?? "https://router.pleum.ai").replace(/\/+$/, "");
+export const ROOT = (process.env.PLEUM_BASE_URL ?? "https://router.pleum.ai")
+  .replace(/\/+$/, "")
+  .replace(/\/v1$/, ""); // 사용자가 실수로 /v1까지 붙여도 V1이 /v1/v1 이중 경로가 되지 않게 정리(L12)
 // OpenAI 호환 엔드포인트는 /v1. (Claude Code만 루트를 쓴다 — recipes 참고)
 export const V1 = `${ROOT}/v1`;
 

package/src/health.mjs

@@ -0,0 +1,55 @@
+// `pleum health` — 게이트웨이 연결성 + 로그인 상태 한눈에.
+// 셀프호스트/스테이징(PLEUM_BASE_URL) 점검·고객지원 트리아지용. 공개 /v1/health 재사용.
+
+import { ROOT, V1, readConfig } from "./config.mjs";
+import { style, divider } from "./ansi.mjs";
+
+const ok = (s) => `${style.green("●")} ${s}`;
+const bad = (s) => `${style.red("●")} ${s}`;
+const warn = (s) => `${style.yellow("●")} ${s}`;
+
+// health 응답 + 로컬 상태 → 표시 문자열(순수 함수 — fixture 테스트 대상).
+export function renderHealth({ root, health, error, ms, keyPrefix }, styler = style) {
+  const lines = [];
+  lines.push(`${styler.bold(styler.plum("pleum health"))} ${styler.dim(`· ${root}`)}`);
+  lines.push(divider(undefined, styler));
+  if (error) {
+    lines.push(bad(`게이트웨이 연결 실패: ${error}`));
+  } else {
+    const isOk = (v) => v === "ok" || v === true; // 백엔드는 "ok" 문자열
+    lines.push((isOk(health.status) ? ok : warn)(`게이트웨이 ${health.status}${ms != null ? styler.dim(` (${ms}ms)`) : ""}`));
+    if (health.db != null) lines.push((isOk(health.db) ? ok : bad)(`DB ${isOk(health.db) ? "정상" : health.db}`));
+    if (health.redis != null) lines.push((isOk(health.redis) ? ok : bad)(`Redis ${isOk(health.redis) ? "정상" : health.redis}`));
+    if (health.providers_configured != null) lines.push(ok(`providers ${health.providers_configured}개 구성됨`));
+    const fx = health.fx_rate;
+    if (fx != null) {
+      const rate = typeof fx === "object" ? fx.rate : fx; // {rate, applied_rate, source}
+      const src = typeof fx === "object" && fx.source ? styler.dim(` (${fx.source})`) : "";
+      if (rate != null) lines.push(ok(`환율 USD/KRW ${rate}${src}`));
+    }
+  }
+  lines.push(
+    keyPrefix
+      ? ok(`로그인됨 ${styler.dim(`(키 ${keyPrefix}…)`)}`)
+      : warn(`로그인 안 됨 ${styler.dim("— pleum login")}`),
+  );
+  return lines.join("\n");
+}
+
+export async function health() {
+  const cfg = readConfig();
+  const keyPrefix = cfg?.key ? cfg.key.slice(0, 8) : null;
+  const t0 = Date.now();
+  let data = null;
+  let error = null;
+  try {
+    const res = await fetch(`${V1}/health`);
+    if (!res.ok) error = `HTTP ${res.status}`;
+    else data = await res.json();
+  } catch (e) {
+    error = e.message;
+  }
+  const ms = Date.now() - t0;
+  console.log(renderHealth({ root: ROOT, health: data, error, ms, keyPrefix }));
+  if (error) process.exit(1);
+}

package/src/interactive.mjs

@@ -0,0 +1,145 @@
+// 스피너 + raw-mode 화살표 셀렉터 — zero-dep 라인 플로우 인터랙션.
+
+import { style, displayWidth, terminalWidth } from "./ansi.mjs";
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+// 브레일 스피너. 기본 stderr — stdout 파이프를 더럽히지 않는다. 비TTY면 no-op.
+export function spinner(text, { stream = process.stderr, intervalMs = 80 } = {}) {
+  if (!stream.isTTY) return { update() {}, stop() {} };
+  let i = 0;
+  let msg = text;
+  let stopped = false;
+  stream.write("\x1b[?25l"); // 커서 숨김
+  const draw = () => stream.write(`\r\x1b[2K${style.plum(FRAMES[i++ % FRAMES.length])} ${style.dim(msg)}`);
+  draw();
+  const t = setInterval(draw, intervalMs);
+  return {
+    update(m) {
+      msg = m;
+    },
+    stop() {
+      if (stopped) return; // 멱등 — 중복 stop이 이후 출력 줄을 지우지 않게
+      stopped = true;
+      clearInterval(t);
+      stream.write("\r\x1b[2K\x1b[?25h");
+    },
+  };
+}
+
+// raw-mode 입력 청크 → 키 이벤트 배열(순수 함수 — 테스트 대상).
+// 화살표(\x1b[A/B)와 일반 문자가 한 청크에 섞여 와도 순서대로 분해한다.
+// 청크 끝의 외톨이 ESC는 escape(취소)로 처리 — 실터미널은 화살표 3바이트를
+// 한 이벤트로 보내므로 실사용에서 오인될 일은 거의 없다.
+export function parseKeys(chunk) {
+  const out = [];
+  for (let i = 0; i < chunk.length; ) {
+    const ch = chunk[i];
+    if (ch === "\x1b") {
+      if (chunk[i + 1] === "[") {
+        const rest = chunk.slice(i + 2);
+        const m = /^([0-9;]*)([A-Za-z~])/.exec(rest);
+        if (m) {
+          const code = m[2];
+          if (code === "A") out.push({ type: "up" });
+          else if (code === "B") out.push({ type: "down" });
+          else out.push({ type: "unknown" }); // 좌우 화살표 등은 무시
+          i += 2 + m[1].length + 1;
+          continue;
+        }
+      }
+      out.push({ type: "escape" });
+      i += 1;
+      continue;
+    }
+    if (ch === "\r" || ch === "\n") out.push({ type: "enter" });
+    else if (ch === "\x03") out.push({ type: "ctrlc" });
+    else if (ch === "\x7f" || ch === "\b") out.push({ type: "backspace" });
+    else if (ch >= " ") out.push({ type: "char", value: ch });
+    else out.push({ type: "unknown" });
+    i += 1;
+  }
+  return out;
+}
+
+// 화살표 이동 · 타이핑 필터 · Enter 선택 · Esc/Ctrl+C 취소(null).
+// 비TTY면 즉시 null — 호출자가 기존 번호 피커 등으로 폴백한다.
+// process.exit는 절대 호출하지 않는다(취소 처리는 호출자 몫).
+export async function select(items, {
+  message = "선택",
+  formatItem = String,
+  matches = (all, q) => (q ? all.filter((it) => String(formatItem(it)).toLowerCase().includes(q.toLowerCase())) : all),
+  limit = 10,
+  input = process.stdin,
+  output = process.stdout,
+} = {}) {
+  if (!input.isTTY || !output.isTTY || typeof input.setRawMode !== "function") return null;
+
+  return new Promise((resolve) => {
+    let query = "";
+    let cursor = 0;
+    let lastRows = 0;
+
+    const rowsFor = (s) => Math.max(1, Math.ceil(displayWidth(s) / Math.max(terminalWidth(), 1)));
+    const erase = () => {
+      if (!lastRows) return;
+      output.write("\r" + (lastRows > 1 ? `\x1b[${lastRows - 1}A` : "") + "\x1b[0J");
+      lastRows = 0;
+    };
+
+    const render = () => {
+      const pool = matches(items, query);
+      if (cursor >= pool.length) cursor = Math.max(0, pool.length - 1);
+      const shown = pool.slice(0, limit);
+      const lines = [
+        `${style.plum("?")} ${style.bold(message)} ${style.dim("타이핑=필터 · ↑↓=이동 · Enter=선택 · Esc=취소")}`,
+        `${style.gray("›")} ${query}`,
+        ...shown.map((it, i) =>
+          i === cursor ? `${style.plum("❯")} ${style.bold(formatItem(it))}` : `  ${style.dim(formatItem(it))}`,
+        ),
+      ];
+      if (pool.length > shown.length) lines.push(style.dim(`  … ${pool.length - shown.length}개 더 — 타이핑으로 좁히기`));
+      if (!pool.length) lines.push(style.dim("  일치 없음"));
+      erase();
+      const frame = lines.join("\n");
+      output.write(frame);
+      lastRows = lines.reduce((n, l) => n + rowsFor(l), 0);
+      return pool;
+    };
+
+    const finish = (value) => {
+      input.off("data", onData);
+      input.setRawMode(false);
+      input.pause();
+      output.write("\x1b[?25h");
+      erase();
+      if (value != null) output.write(`${style.green("✓")} ${formatItem(value)}\n`);
+      resolve(value);
+    };
+
+    const onData = (chunk) => {
+      for (const key of parseKeys(chunk)) {
+        if (key.type === "ctrlc" || key.type === "escape") return finish(null);
+        if (key.type === "enter") {
+          const pool = matches(items, query);
+          return finish(pool[cursor] ?? null);
+        }
+        if (key.type === "up") cursor = Math.max(0, cursor - 1);
+        else if (key.type === "down") cursor = Math.min(limit - 1, cursor + 1);
+        else if (key.type === "backspace") query = query.slice(0, -1);
+        else if (key.type === "char") {
+          query += key.value;
+          cursor = 0;
+        }
+      }
+      render();
+    };
+
+    input.setEncoding("utf8"); // 멀티바이트(한글) 조각 자동 재조립
+    input.setRawMode(true);
+    input.resume();
+    output.write("\x1b[?25l");
+    input.on("data", onData);
+    render();
+  });
+}

package/src/launch.mjs

@@ -50,7 +50,7 @@ export async function launch(tool, model, passthrough) {
   // Codex는 격리 CODEX_HOME에 config.toml을 써서 사용자 ~/.codex를 보존한다.
   if (r.type === "codex-home") {
     const home = join(homedir(), ".pleum", "codex-home");
-    mkdirSync(home, { recursive: true });
+    mkdirSync(home, { recursive: true, mode: 0o700 });  // 사용자 데이터 디렉토리 권한 제한(L11)
     writeFileSync(join(home, "config.toml"), codexToml(model), { mode: 0o600 });
     env.CODEX_HOME = home;
   }

package/src/markdown.mjs

@@ -0,0 +1,91 @@
+// 스트리밍 마크다운 렌더러 — 라인 플로우(풀스크린 아님).
+// 전략: \n이 도착해 완결된 줄은 스타일 입혀 확정 출력(재렌더 없음), 아직 안 끝난
+// 마지막 줄만 매 push마다 지우고 다시 그린다. 비TTY(파이프)는 완전 패스스루.
+
+import { style, displayWidth, terminalWidth } from "./ansi.mjs";
+
+// ```lang 펜스 감지(순수 함수). 열기/닫기 구분은 호출자의 inFence 상태가 한다.
+export function detectFence(line) {
+  const m = /^\s*```(\S*)\s*$/.exec(line);
+  return m ? { lang: m[1] } : null;
+}
+
+// 인라인 마크다운: `code` → cyan, **bold**, *italic*. 코드 조각 먼저 치환해
+// 코드 안의 별표가 bold로 오인되는 흔한 케이스를 줄인다.
+export function renderInline(text, styler = style) {
+  return text
+    .replace(/`([^`]+)`/g, (_, c) => styler.cyan(c))
+    .replace(/\*\*([^*]+)\*\*/g, (_, c) => styler.bold(c))
+    .replace(/(^|[^*])\*([^*\s][^*]*)\*(?!\*)/g, (_, pre, c) => pre + styler.italic(c));
+}
+
+// 완결된 한 줄 렌더(순수 함수). state.inFence는 이 줄 "이전"의 펜스 상태.
+export function renderLine(line, state = { inFence: false }, styler = style) {
+  const fence = detectFence(line);
+  if (fence) {
+    return state.inFence ? styler.gray("└─") : styler.gray("┌─ ") + styler.dim(fence.lang || "code");
+  }
+  if (state.inFence) return styler.gray("│ ") + line; // 펜스 안은 마크다운 해석 안 함
+  const h = /^(#{1,6})\s+(.*)$/.exec(line);
+  if (h) return styler.bold(styler.plum(h[2]));
+  const q = /^\s*>\s?(.*)$/.exec(line);
+  if (q) return styler.gray("┃ ") + styler.dim(renderInline(q[1], styler));
+  const li = /^(\s*)([-*+]|\d+\.)\s+(.*)$/.exec(line);
+  if (li) {
+    const marker = /^[-*+]$/.test(li[2]) ? "•" : li[2];
+    return `${li[1]}${styler.plum(marker)} ${renderInline(li[3], styler)}`;
+  }
+  return renderInline(line, styler);
+}
+
+// 스트리밍 렌더러 팩토리. write/styler/interactive 주입 가능(테스트용).
+export function createMarkdownStream({
+  write = (s) => process.stdout.write(s),
+  styler = style,
+  interactive = process.stdout.isTTY,
+  prefix = "",
+} = {}) {
+  let buf = "";
+  let inFence = false;
+  let firstLine = true; // prefix는 첫 줄에만
+  let previewRows = 0; // 직전 미완성 줄 렌더가 점유한 시각적 행 수(soft-wrap 포함)
+
+  const rowsFor = (s) => Math.max(1, Math.ceil(displayWidth(s) / Math.max(terminalWidth(), 1)));
+
+  const erasePreview = () => {
+    if (!previewRows) return;
+    write("\r" + (previewRows > 1 ? `\x1b[${previewRows - 1}A` : "") + "\x1b[0J");
+    previewRows = 0;
+  };
+
+  const commit = (line) => {
+    const rendered = (firstLine ? prefix : "") + renderLine(line, { inFence }, styler);
+    if (detectFence(line)) inFence = !inFence;
+    write(rendered + "\n");
+    firstLine = false;
+  };
+
+  return {
+    push(delta) {
+      if (!interactive) return void write(delta);
+      buf += delta;
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+      if (lines.length || buf) erasePreview();
+      for (const line of lines) commit(line);
+      if (buf) {
+        const rendered = (firstLine ? prefix : "") + renderLine(buf, { inFence }, styler);
+        write(rendered);
+        previewRows = rowsFor(rendered);
+      }
+    },
+    finish() {
+      if (!interactive) return void write("\n"); // 기존 파이프 동작 유지(항상 개행 종결)
+      erasePreview();
+      if (buf) {
+        commit(buf);
+        buf = "";
+      }
+    },
+  };
+}

package/src/models.mjs

@@ -1,4 +1,5 @@
 import { V1 } from "./config.mjs";
+import { style, padDisplay, divider } from "./ansi.mjs";
 
 // GET /v1/models 는 공개(인증 불필요). 슬러그는 provider/model 형식.
 export async function fetchModels() {
@@ -8,6 +9,15 @@ export async function fetchModels() {
   return data.data ?? [];
 }
 
+// id/표시명 부분일치 필터 — run 피커·REPL /models·목록이 공유하는 단일 구현.
+export function matchModels(models, query) {
+  const q = (query || "").toLowerCase();
+  if (!q) return models;
+  return models.filter(
+    (m) => m.id.toLowerCase().includes(q) || (m.display_name || "").toLowerCase().includes(q),
+  );
+}
+
 // 컨텍스트 길이를 사람이 읽기 좋게: 128000→128K, 1000000→1M.
 export function fmtCtx(n) {
   if (!n) return "—";
@@ -32,7 +42,8 @@ export function fmtPrice(model) {
 }
 
 // 정렬된 컬럼 테이블 — 라우터의 강점(수백 모델·가격·컨텍스트)을 한눈에.
-export function formatTable(models) {
+// 패딩은 표시 폭 기준(padDisplay) — 색·전각 문자가 섞여도 컬럼이 맞는다.
+export function formatTable(models, styler = style) {
   const headers = ["MODEL", "PROVIDER", "MODAL", "CTX", "IN/1M", "OUT/1M"];
   const rows = models.map((m) => {
     const [pin, pout] = fmtPrice(m);
@@ -46,29 +57,40 @@ export function formatTable(models) {
     ];
   });
   const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
-  const fmt = (r) => r.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
-  return [fmt(headers), ...rows.map(fmt)].join("\n");
+  const fmtRow = (r, paint) =>
+    r.map((c, i) => paint(padDisplay(c, widths[i]), i)).join("  ").trimEnd();
+  const head = fmtRow(headers, (c) => styler.dim(c));
+  const body = rows.map((r) => fmtRow(r, (c, i) => (i === 0 ? styler.plum(c) : c)));
+  return [head, ...body].join("\n");
 }
 
-// `pleum models [query] [--json]` 인자 파싱.
+// `pleum models [query] [--json] [--info]` 인자 파싱.
 export function parseModelsArgs(rest = []) {
   let json = false;
+  let info = false;
   const pos = [];
   for (const a of rest) {
     if (a === "--json") json = true;
+    else if (a === "--info" || a === "-i") info = true;
     else pos.push(a);
   }
-  return { json, query: pos[0] };
+  return { json, info, query: pos[0] };
 }
 
 export async function listModels(rest) {
   // 하위호환: 문자열 하나가 와도 query로 처리.
-  const { json, query } = Array.isArray(rest) ? parseModelsArgs(rest) : { json: false, query: rest };
+  const { json, info, query } = Array.isArray(rest)
+    ? parseModelsArgs(rest)
+    : { json: false, info: false, query: rest };
+  if (info) {
+    if (!query) {
+      console.error("사용법: pleum models <model-id> --info");
+      process.exit(1);
+    }
+    return showModelInfo(query, { json });
+  }
   const models = await fetchModels();
-  const q = (query || "").toLowerCase();
-  const rows = models.filter(
-    (m) => !q || m.id.toLowerCase().includes(q) || (m.display_name || "").toLowerCase().includes(q),
-  );
+  const rows = matchModels(models, query);
   if (json) {
     console.log(JSON.stringify(rows, null, 2));
     return;
@@ -78,5 +100,74 @@ export async function listModels(rest) {
     return;
   }
   console.log(formatTable(rows));
-  console.log(`\n${rows.length} models · 가격=토큰 1M당(표시환율 기준, 실청구는 장중 환율로 소폭 상이)`);
+  console.log(style.dim(`\n${rows.length} models · 가격=토큰 1M당(표시환율 기준, 실청구는 장중 환율로 소폭 상이)`));
+}
+
+// ── 모델 상세(ollama show 대응) — GET /v1/models/{id} ────────────────────
+// id는 provider/model 형식이라 슬래시를 그대로 둔다(백엔드 :path 컨버터).
+export async function fetchModelDetail(id) {
+  const res = await fetch(`${V1}/models/${id}`);
+  if (res.status === 404) throw new Error(`모델을 찾을 수 없음: ${id}  (목록: pleum models)`);
+  if (!res.ok) throw new Error(`모델 상세 조회 실패 (${res.status})`);
+  return res.json();
+}
+
+const fmtNum = (n) => (n == null ? "—" : Number(n).toLocaleString("en-US"));
+
+// 상세 응답 → 표시 문자열(순수 함수 — fixture 테스트 대상).
+export function renderModelInfo(m, styler = style) {
+  const [pin, pout] = fmtPrice(m);
+  const lines = [];
+  lines.push(`${styler.bold(styler.plum(m.id))}${m.display_name ? `  ${styler.dim(m.display_name)}` : ""}`);
+  lines.push(divider(undefined, styler));
+  const facts = [
+    ["maker", m.maker || "—"],
+    ["modality", m.modality || "text"],
+    ["context", fmtCtx(m.context_length || m.context_window)],
+    ["max output", fmtCtx(m.max_output_tokens || m.max_output)],
+    ["가격/1M", `입력 ${pin} · 출력 ${pout} ${styler.dim(`(마크업 ${m.effective_markup_percent ?? 0}% 포함)`)}`],
+  ];
+  if (m.supports_thinking) facts.push(["thinking", m.thinking_forced ? "강제(끌 수 없음)" : "지원"]);
+  for (const [k, v] of facts) lines.push(`${styler.dim(padDisplay(k, 10))} ${v}`);
+
+  const u = m.usage;
+  if (u) {
+    lines.push(
+      `${styler.dim(padDisplay("사용량", 10))} 주간 ${fmtNum(u.weekly_calls)} calls · ${fmtNum(u.weekly_tokens)} tok` +
+        styler.dim(`  (누적 ${fmtNum(u.total_calls)} calls)`),
+    );
+  }
+
+  const provs = m.providers || [];
+  if (provs.length) {
+    lines.push("");
+    lines.push(styler.dim("PROVIDER      IN/1M       OUT/1M      CTX    LATENCY   TPS     UPTIME"));
+    for (const p of provs) {
+      const [i1m, o1m] = fmtPrice(p);
+      lines.push(
+        [
+          styler.plum(padDisplay(p.provider, 12)),
+          padDisplay(i1m, 10),
+          padDisplay(o1m, 10),
+          padDisplay(fmtCtx(p.context_window), 5),
+          padDisplay(p.latency_ms != null ? `${Math.round(p.latency_ms)}ms` : "—", 8),
+          padDisplay(p.throughput_tps != null ? `${Math.round(p.throughput_tps)}/s` : "—", 6),
+          p.uptime_percent != null ? `${p.uptime_percent}%` : "—",
+        ].join("  "),
+      );
+    }
+  }
+
+  const sibs = (m.siblings || []).map((s) => s.id);
+  if (sibs.length) {
+    lines.push("");
+    lines.push(`${styler.dim("같은 제공자:")} ${sibs.join(styler.dim(" · "))}`);
+  }
+  return lines.join("\n");
+}
+
+export async function showModelInfo(id, { json = false } = {}) {
+  const detail = await fetchModelDetail(id);
+  if (json) return void console.log(JSON.stringify(detail, null, 2));
+  console.log(renderModelInfo(detail));
 }

package/src/run.mjs

@@ -2,7 +2,10 @@ import { createInterface } from "node:readline";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { V1, requireKey, HISTORY_FILE, SESSIONS_DIR } from "./config.mjs";
-import { fetchModels, formatTable } from "./models.mjs";
+import { fetchModels, formatTable, matchModels } from "./models.mjs";
+import { style, divider } from "./ansi.mjs";
+import { createMarkdownStream } from "./markdown.mjs";
+import { spinner, select } from "./interactive.mjs";
 
 const IMG_EXT = /\.(png|jpe?g|gif|webp|bmp)$/i;
 
@@ -34,7 +37,7 @@ export function buildContent(text, exists = existsSync, read = readFileSync) {
 // 응답 후 한 줄 통계(순수 함수 — 테스트 대상). verbose일 때만 토큰/속도 표시.
 export function formatStats({ cost, usage, ms, tokPerSec, verbose }) {
   const bits = [];
-  if (cost) bits.push(`₩${cost}`);
+  if (cost != null && cost !== "") bits.push(`₩${fmtCost(cost)}`);
   if (verbose && usage) {
     bits.push(`↑${usage.prompt_tokens ?? "?"} ↓${usage.completion_tokens ?? "?"} tok`);
     if (tokPerSec) bits.push(`${tokPerSec.toFixed(1)} tok/s`);
@@ -43,6 +46,16 @@ export function formatStats({ cost, usage, ms, tokPerSec, verbose }) {
   return bits.length ? `  (${bits.join(" · ")})` : "";
 }
 
+// 비용 표시: 숫자면 소수 2자리까지(후행 0 제거), 문자열은 그대로.
+function fmtCost(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? String(+n.toFixed(2)) : String(v);
+}
+
+function isAbort(e) {
+  return e?.name === "AbortError" || e?.code === "ABORT_ERR";
+}
+
 export async function run(rest) {
   const args = Array.isArray(rest) ? rest : rest == null ? [] : [rest];
   const { verbose, prompt: inlinePrompt, model: argModel } = parseRunArgs(args);
@@ -52,6 +65,11 @@ export async function run(rest) {
   const key = requireKey();
 
   if (!model && !oneShot) {
+    if (!process.stdin.isTTY) {
+      // 비대화형(non-TTY) stdin이면 인터랙티브 모델 선택이 멈춰버리므로 명확히 안내하고 종료(L10).
+      console.error('모델을 지정하세요: pleum run <model> ["프롬프트"]  (비대화형 stdin에선 모델 선택 불가)');
+      process.exit(1);
+    }
     model = await pickModel(); // 인터랙티브 모델 선택
     if (!model) process.exit(1);
   }
@@ -62,11 +80,17 @@ export async function run(rest) {
 
   if (oneShot) {
     const prompt = [inlinePrompt, piped].filter(Boolean).join("\n\n");
-    const messages = [{ role: "user", content: buildContent(prompt) }];
+    const content = buildContent(prompt);
+    if (Array.isArray(content)) {
+      const n = content.filter((p) => p.type === "image_url").length;
+      // 프롬프트 내 로컬 이미지 경로를 자동 첨부·업로드하므로 조용히 올리지 않고 명시 고지한다(M8).
+      console.error(`ℹ 프롬프트의 로컬 이미지 ${n}개를 첨부해 업로드합니다.`);
+    }
+    const messages = [{ role: "user", content }];
     try {
       await streamChat(key, model, messages, { verbose, quiet: true });
     } catch (e) {
-      console.error(`✗ ${e.message}`);
+      console.error(`${style.red("✗")} ${e.message}`);
       process.exit(1);
     }
     process.exit(0);
@@ -75,34 +99,35 @@ export async function run(rest) {
   await repl(key, model, verbose);
 }
 
-async function repl(key, model, verbose) {
+async function repl(key, initialModel, initialVerbose) {
+  let model = initialModel;
   let system = "";
+  let verbose = initialVerbose;
   let messages = [];
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-    prompt: "you> ",
-    history: loadHistory(),
-    historySize: 1000,
-  });
   let multiline = null; // """ 펜스 진행 중이면 누적 배열
-
-  console.log(`PleumRouter · ${model}\n/help 으로 명령, /exit 로 종료. 여러 줄은 """ 로 감싸기.\n`);
-  rl.prompt();
+  let currentAbort = null; // 생성 중이면 AbortController
+  let lastSigint = 0;
+  let pickerActive = false; // /model 셀렉터가 rl을 잠시 닫는 동안 close 핸들러 무시
+  let rl;
 
   const send = async (text) => {
     messages.push({ role: "user", content: buildContent(text) });
     const req = system ? [{ role: "system", content: system }, ...messages] : messages;
+    const ac = new AbortController();
+    currentAbort = ac;
     try {
-      const reply = await streamChat(key, model, req, { verbose });
-      messages.push({ role: "assistant", content: reply });
+      const reply = await streamChat(key, model, req, { verbose, signal: ac.signal });
+      if (reply) messages.push({ role: "assistant", content: reply });
+      else messages.pop(); // 응답 없음(즉시 중단 등) — user 턴 되돌림
     } catch (e) {
-      console.error(`\n✗ ${e.message}`);
+      console.error(`\n${style.red("✗")} ${e.message}`);
       messages.pop(); // 실패한 user 턴 제거
+    } finally {
+      currentAbort = null;
     }
   };
 
-  rl.on("line", async (line) => {
+  const onLine = async (line) => {
     if (multiline !== null) {
       if (line.trim() === '"""') {
         const text = multiline.join("\n");
@@ -153,6 +178,17 @@ async function repl(key, model, verbose) {
           system = s.system ?? "";
           messages = s.messages ?? [];
         },
+        // 화살표 셀렉터는 stdin raw-mode가 필요해 readline과 공존 불가 —
+        // 히스토리를 보존한 채 rl을 닫았다가 선택 후 재생성한다.
+        pickModel: async () => {
+          pickerActive = true;
+          const history = rl.history;
+          rl.close();
+          const picked = await pickModel();
+          makeRl(history);
+          pickerActive = false;
+          return picked;
+        },
       });
       rl.prompt();
       return;
@@ -163,20 +199,57 @@ async function repl(key, model, verbose) {
     }
     await send(text);
     rl.prompt();
-  });
+  };
 
-  rl.on("close", () => {
+  const onClose = () => {
+    if (pickerActive) return;
     saveHistory(rl.history);
-    console.log("\n안녕히 가세요.");
+    console.log(`\n${style.dim("안녕히 가세요.")}`);
     process.exit(0);
-  });
+  };
+
+  // Ctrl+C 인체공학: 생성 중 1회=중단(REPL 유지), idle에선 2초 내 2회=종료.
+  const onSigint = () => {
+    if (currentAbort) {
+      currentAbort.abort();
+      return;
+    }
+    const now = Date.now();
+    if (now - lastSigint < 2000) {
+      rl.close();
+      return;
+    }
+    lastSigint = now;
+    console.log(`\n${style.dim("한 번 더 Ctrl+C 하면 종료 (/exit 도 가능)")}`);
+    rl.prompt();
+  };
+
+  const makeRl = (history) => {
+    rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: `${style.plum("you")}${style.dim(">")} `,
+      history,
+      historySize: 1000,
+    });
+    rl.on("line", onLine);
+    rl.on("close", onClose);
+    rl.on("SIGINT", onSigint);
+    return rl;
+  };
+
+  makeRl(loadHistory());
+  console.log(`${style.bold(style.plum("PleumRouter"))} ${style.dim("·")} ${model}`);
+  console.log(style.dim('/help 명령 · /exit 종료 · 여러 줄은 """ 감싸기 · 생성 중 Ctrl+C=중단'));
+  console.log(divider());
+  rl.prompt();
 }
 
 const SLASH_HELP = `명령:
   /help, /?           이 도움말
   /clear              대화 컨텍스트 초기화(시스템 프롬프트는 유지)
   /system [텍스트]    시스템 프롬프트 설정(인자 없으면 현재값 표시)
-  /model [id]         세션 유지한 채 모델 전환(인자 없으면 현재 모델)
+  /model [id]         세션 유지한 채 모델 전환(인자 없으면 화살표 선택)
   /models [검색어]    모델 목록 보기
   /save [이름]        현재 세션 저장(기본 last)
   /load [이름]        세션 불러오기
@@ -186,7 +259,7 @@ const SLASH_HELP = `명령:
   이미지: 메시지에 이미지 파일 경로를 그대로 포함(예: 이 그림 설명해줘 ./shot.png)`;
 
 async function handleSlash(text, ctx) {
-  const [cmd, ...rest] = text.slice(1).split(/\s+/);
+  const [cmd] = text.slice(1).split(/\s+/);
   const arg = text.slice(1 + cmd.length).trim();
   switch (cmd) {
     case "help":
@@ -195,12 +268,12 @@ async function handleSlash(text, ctx) {
       break;
     case "clear":
       ctx.clear();
-      console.log("✓ 컨텍스트 초기화");
+      console.log(`${style.green("✓")} 컨텍스트 초기화`);
       break;
     case "system":
       if (arg) {
         ctx.system = arg;
-        console.log("✓ 시스템 프롬프트 설정");
+        console.log(`${style.green("✓")} 시스템 프롬프트 설정`);
       } else {
         console.log(ctx.system ? `현재 시스템 프롬프트:\n${ctx.system}` : "시스템 프롬프트 없음");
       }
@@ -208,7 +281,15 @@ async function handleSlash(text, ctx) {
     case "model":
       if (arg) {
         ctx.model = arg;
-        console.log(`✓ 모델 전환 → ${arg}`);
+        console.log(`${style.green("✓")} 모델 전환 → ${style.plum(arg)}`);
+      } else if (ctx.pickModel) {
+        const picked = await ctx.pickModel();
+        if (picked) {
+          ctx.model = picked;
+          console.log(`${style.green("✓")} 모델 전환 → ${style.plum(picked)}`);
+        } else {
+          console.log(`현재 모델: ${style.plum(ctx.model)}`);
+        }
       } else {
         console.log(`현재 모델: ${ctx.model}\n전환: /model <id>  ·  목록: /models`);
       }
@@ -216,105 +297,147 @@ async function handleSlash(text, ctx) {
     case "models":
       try {
         const models = await fetchModels();
-        const q = arg.toLowerCase();
-        const rows = models.filter(
-          (m) => !q || m.id.toLowerCase().includes(q) || (m.display_name || "").toLowerCase().includes(q),
-        );
+        const rows = matchModels(models, arg);
         console.log(rows.length ? formatTable(rows) : "일치하는 모델 없음");
       } catch (e) {
-        console.error(`✗ ${e.message}`);
+        console.error(`${style.red("✗")} ${e.message}`);
       }
       break;
     case "save":
       try {
         const name = saveSession(arg || "last", ctx.snapshot());
-        console.log(`✓ 세션 저장: ${name}`);
+        console.log(`${style.green("✓")} 세션 저장: ${name}`);
       } catch (e) {
-        console.error(`✗ 저장 실패: ${e.message}`);
+        console.error(`${style.red("✗")} 저장 실패: ${e.message}`);
       }
       break;
     case "load":
       try {
         ctx.restore(loadSession(arg || "last"));
-        console.log(`✓ 세션 불러옴 (모델: ${ctx.model})`);
+        console.log(`${style.green("✓")} 세션 불러옴 (모델: ${ctx.model})`);
       } catch {
-        console.error(`✗ 세션 없음: ${arg || "last"}`);
+        console.error(`${style.red("✗")} 세션 없음: ${arg || "last"}`);
       }
       break;
     case "verbose":
       ctx.verbose = !ctx.verbose;
-      console.log(`✓ 통계 ${ctx.verbose ? "켜짐" : "꺼짐"}`);
+      console.log(`${style.green("✓")} 통계 ${ctx.verbose ? "켜짐" : "꺼짐"}`);
       break;
     default:
       console.log(`알 수 없는 명령: /${cmd}  (/help)`);
   }
 }
 
-async function streamChat(key, model, messages, { verbose = false, quiet = false } = {}) {
+// SSE 스트리밍 채팅. fetchImpl 주입 가능(테스트용 — 네트워크 없이 SSE 파싱 검증).
+// 비용은 마지막 SSE 청크의 cost.krw — 스트리밍 응답엔 X-Cost-Krw 헤더가 없다(백엔드 계약).
+export async function streamChat(key, model, messages, { verbose = false, quiet = false, signal, fetchImpl = fetch } = {}) {
   const t0 = Date.now();
-  const res = await fetch(`${V1}/chat/completions`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
-    body: JSON.stringify({ model, messages, stream: true, stream_options: { include_usage: true } }),
-  });
+  const sp = spinner(`${model} 생각 중…`);
+  let res;
+  try {
+    res = await fetchImpl(`${V1}/chat/completions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
+      body: JSON.stringify({ model, messages, stream: true, stream_options: { include_usage: true } }),
+      signal,
+    });
+  } catch (e) {
+    sp.stop();
+    if (isAbort(e)) {
+      console.error(style.dim("⏹ 중단됨"));
+      return "";
+    }
+    throw e;
+  }
   if (!res.ok) {
+    sp.stop();
     const body = await res.text().catch(() => "");
     throw new Error(`${res.status} ${body.slice(0, 300)}`);
   }
 
-  if (!quiet) process.stdout.write("bot> ");
+  const md = createMarkdownStream({ prefix: quiet ? "" : `${style.plum("bot")}${style.dim(">")} ` });
   let full = "";
   let buf = "";
   let usage = null;
+  let cost = null;
   let firstAt = 0;
+  let aborted = false;
   const decoder = new TextDecoder();
-  for await (const chunk of res.body) {
-    buf += decoder.decode(chunk, { stream: true });
-    const lines = buf.split("\n");
-    buf = lines.pop() ?? "";
-    for (const l of lines) {
-      const s = l.trim();
-      if (!s.startsWith("data:")) continue;
-      const data = s.slice(5).trim();
-      if (data === "[DONE]") continue;
-      try {
-        const j = JSON.parse(data);
-        if (j.usage) usage = j.usage;
-        const delta = j.choices?.[0]?.delta?.content;
-        if (delta) {
-          if (!firstAt) firstAt = Date.now();
-          process.stdout.write(delta);
-          full += delta;
+  try {
+    for await (const chunk of res.body) {
+      buf += decoder.decode(chunk, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+      for (const l of lines) {
+        const s = l.trim();
+        if (!s.startsWith("data:")) continue;
+        const data = s.slice(5).trim();
+        if (data === "[DONE]") continue;
+        try {
+          const j = JSON.parse(data);
+          if (j.usage) usage = j.usage;
+          if (j.cost) cost = j.cost; // 마지막 청크 — {usd, krw, fx_rate, markup_rate}
+          const delta = j.choices?.[0]?.delta?.content;
+          if (delta) {
+            if (!firstAt) {
+              firstAt = Date.now();
+              sp.stop();
+            }
+            md.push(delta);
+            full += delta;
+          }
+        } catch {
+          // 부분 청크 — 무시
         }
-      } catch {
-        // 부분 청크 — 무시
       }
     }
+  } catch (e) {
+    if (!isAbort(e)) {
+      sp.stop();
+      throw e;
+    }
+    aborted = true;
   }
-  process.stdout.write("\n");
+  sp.stop();
+  md.finish();
+  if (aborted) console.error(style.dim("⏹ 생성 중단됨 — 부분 응답은 컨텍스트에 유지"));
 
   const ms = Date.now() - t0;
   const genSec = (Date.now() - (firstAt || t0)) / 1000;
   const tokPerSec = usage?.completion_tokens && genSec > 0 ? usage.completion_tokens / genSec : null;
-  const cost = res.headers.get("x-cost-krw");
-  // 파이프 출력(quiet)은 stdout을 깨끗이 — 통계는 verbose일 때만 stderr로.
-  const line = formatStats({ cost: quiet ? null : cost, usage, ms, tokPerSec, verbose });
-  if (line) (quiet ? console.error : console.log)(line);
-  else if (quiet && verbose && cost) console.error(`  (₩${cost})`);
+  const krw = cost?.krw ?? null;
+  // 파이프(quiet)는 stdout을 깨끗이 유지 — 통계는 stderr로. 비용은 터미널(stderr TTY)
+  // 또는 verbose일 때 표시하고, 완전 리다이렉트된 스크립트 실행에선 침묵한다.
+  const showCost = !quiet || verbose || process.stderr.isTTY;
+  const line = formatStats({ cost: showCost ? krw : null, usage, ms, tokPerSec, verbose });
+  if (line) (quiet ? console.error : console.log)(style.dim(line));
   return full;
 }
 
 // ── 인터랙티브 모델 피커 ──────────────────────────────────────────────
-// 번호 선택 + 검색어 좁히기. ponytail: 화살표 raw-mode는 후속(SSH/파이프 엣지케이스 회피).
+// 화살표 셀렉터(raw-mode) 우선, 비TTY 등으로 불가하면 번호 선택 폴백.
 async function pickModel() {
   let models;
   try {
     models = await fetchModels();
   } catch (e) {
-    console.error(`✗ 모델 목록 조회 실패: ${e.message}`);
+    console.error(`${style.red("✗")} 모델 목록 조회 실패: ${e.message}`);
     return null;
   }
   if (!models.length) return null;
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    return select(models, {
+      message: "모델 선택",
+      formatItem: (m) => `${m.id}${m.display_name ? `  ${style.dim(m.display_name)}` : ""}`,
+      matches: matchModels,
+      limit: 12,
+    }).then((m) => m?.id ?? null);
+  }
+  return pickModelNumbered(models);
+}
+
+// 번호 선택 + 검색어 좁히기 — raw-mode가 안 되는 환경 폴백.
+async function pickModelNumbered(models) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const ask = (q) => new Promise((r) => rl.question(q, r));
   let pool = models;
@@ -329,10 +452,7 @@ async function pickModel() {
       if (!ans) return null;
       const n = Number(ans);
       if (Number.isInteger(n) && n >= 1 && n <= shown.length) return shown[n - 1].id;
-      const q = ans.toLowerCase();
-      const next = models.filter(
-        (m) => m.id.toLowerCase().includes(q) || (m.display_name || "").toLowerCase().includes(q),
-      );
+      const next = matchModels(models, ans);
       pool = next.length ? next : models;
       if (!next.length) console.log("일치 없음 — 전체 목록으로.");
     }

package/src/top.mjs

@@ -0,0 +1,72 @@
+// `pleum top [--period daily|weekly|monthly]` — 공개 리더보드(/v1/stats/rankings).
+// ollama ps의 "지금 뜨는 것" 포지션 — 로컬 프로세스가 아니라 라우터 전체의 핫한 모델.
+
+import { V1 } from "./config.mjs";
+import { style, padDisplay, barChart, divider } from "./ansi.mjs";
+
+export function parseTopArgs(rest = []) {
+  let period = "weekly";
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--period" || rest[i] === "-p") period = rest[++i];
+    else if (["daily", "weekly", "monthly"].includes(rest[i])) period = rest[i];
+  }
+  if (!["daily", "weekly", "monthly"].includes(period)) {
+    throw new Error(`period는 daily|weekly|monthly 중 하나: ${period}`);
+  }
+  return { period };
+}
+
+const fmtTok = (n) => {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return String(n);
+};
+
+// rankings 응답 → 표시 문자열(순수 함수 — fixture 테스트 대상).
+export function renderTop(data, styler = style) {
+  const periodKo = { daily: "일간", weekly: "주간", monthly: "월간" }[data.period] || data.period;
+  const lines = [];
+  lines.push(`${styler.bold(styler.plum("모델 리더보드"))} ${styler.dim(`· ${periodKo} · 토큰 ${fmtTok(data.total_tokens ?? 0)}`)}`);
+  lines.push(divider(undefined, styler));
+
+  const board = data.leaderboard || [];
+  if (!board.length) {
+    lines.push(styler.dim("데이터 없음"));
+  } else {
+    const idW = Math.max(...board.map((r) => r.model.length), 5);
+    for (const r of board) {
+      const trend =
+        r.trend_pct == null
+          ? styler.dim("  new")
+          : r.trend_pct >= 0
+            ? styler.green(`▲${r.trend_pct}%`)
+            : styler.red(`▼${Math.abs(r.trend_pct)}%`);
+      lines.push(
+        `${styler.dim(String(r.rank).padStart(2))}. ${styler.plum(padDisplay(r.model, idW))}  ` +
+          `${padDisplay(fmtTok(r.tokens), 7)} tok  ${padDisplay(String(r.calls), 6)} calls  ${trend}` +
+          styler.dim(`  by ${r.maker}`),
+      );
+    }
+  }
+
+  const share = data.market_share || [];
+  if (share.length) {
+    lines.push("");
+    lines.push(styler.bold("제공자 점유율"));
+    const nameW = Math.max(...share.map((s) => s.provider.length), 8);
+    for (const s of share) {
+      lines.push(
+        `${padDisplay(s.provider, nameW)}  ${styler.plum(barChart(s.share_pct, 100, 24))} ${String(s.share_pct).padStart(5)}%`,
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+export async function top(rest) {
+  const { period } = parseTopArgs(rest);
+  const res = await fetch(`${V1}/stats/rankings?period=${period}`);
+  if (!res.ok) throw new Error(`리더보드 조회 실패 (${res.status})`);
+  console.log(renderTop(await res.json()));
+}

package/src/usage.mjs

@@ -0,0 +1,69 @@
+// `pleum usage [--by model|provider|api_key|day] [--days N]` — 내 지출 리포트.
+// GET /v1/usage/report (API 키 + usage:read 스코프 — CLI 로그인 키에 기본 동봉).
+
+import { V1, requireKey } from "./config.mjs";
+import { style, padDisplay, barChart, divider } from "./ansi.mjs";
+
+const GROUPS = ["model", "provider", "api_key", "day"];
+
+export function parseUsageArgs(rest = []) {
+  let by = "model";
+  let days = 30;
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--by") by = rest[++i];
+    else if (rest[i] === "--days") days = Number(rest[++i]);
+  }
+  if (!GROUPS.includes(by)) throw new Error(`--by 는 ${GROUPS.join("|")} 중 하나: ${by}`);
+  if (!Number.isInteger(days) || days < 1 || days > 365) throw new Error(`--days 는 1~365 정수: ${days}`);
+  return { by, days };
+}
+
+const fmtKrw = (n) => `₩${Math.round(n).toLocaleString("en-US")}`;
+
+// report 응답 → 표시 문자열(순수 함수 — fixture 테스트 대상).
+export function renderUsage(data, styler = style) {
+  const lines = [];
+  const byKo = { model: "모델별", provider: "제공자별", api_key: "키별", day: "일별" }[data.group_by] || data.group_by;
+  lines.push(`${styler.bold(styler.plum("사용량"))} ${styler.dim(`· ${byKo} · 최근 ${data.days}일`)}`);
+  lines.push(divider(undefined, styler));
+  const items = data.items || [];
+  if (!items.length) {
+    lines.push(styler.dim("사용 내역 없음"));
+    return lines.join("\n");
+  }
+  const max = Math.max(...items.map((i) => i.cost_krw), 1);
+  const keyW = Math.max(...items.map((i) => i.key.length), 4);
+  const total = { cost: 0, calls: 0 };
+  for (const it of items) {
+    total.cost += it.cost_krw;
+    total.calls += it.calls;
+    lines.push(
+      `${padDisplay(it.key, keyW)}  ${styler.plum(barChart(it.cost_krw, max, 20))} ${padDisplay(fmtKrw(it.cost_krw), 10)}` +
+        styler.dim(`  ↑${it.input_tokens.toLocaleString("en-US")} ↓${it.output_tokens.toLocaleString("en-US")} tok · ${it.calls} calls`),
+    );
+  }
+  lines.push(divider(undefined, styler));
+  lines.push(`${padDisplay("합계", keyW)}  ${" ".repeat(20)} ${styler.bold(fmtKrw(total.cost))}${styler.dim(`  ${total.calls} calls`)}`);
+  return lines.join("\n");
+}
+
+export async function usage(rest) {
+  const { by, days } = parseUsageArgs(rest);
+  const key = requireKey();
+  const res = await fetch(`${V1}/usage/report?group_by=${by}&days=${days}`, {
+    headers: { Authorization: `Bearer ${key}` },
+  });
+  if (res.status === 403) {
+    // 구버전 로그인 키(usage:read 스코프 없음) — 재로그인으로 새 키를 받으면 해결.
+    console.error(
+      `${style.red("✗")} 이 API 키에는 usage:read 권한이 없습니다.\n` +
+        `  ${style.dim("pleum login 을 다시 실행해 새 키를 발급받으세요 (최신 키에는 기본 포함).")}`,
+    );
+    process.exit(1);
+  }
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`사용량 조회 실패 (${res.status})${body ? `: ${body.slice(0, 200)}` : ""}`);
+  }
+  console.log(renderUsage(await res.json()));
+}