@wooojin/forgen 0.4.5 → 0.4.7

package/dist/core/notify.js

@@ -0,0 +1,93 @@
+/**
+ * Forgen — Desktop / webhook notification helper (ADR-008 §"테마 A 알림").
+ *
+ * 0.4.6 신설 — rate-limit auto-resume 이 sleep 끝나고 재기동될 때 사용자에게
+ * 알림을 보냄 (노트북 닫고 잘 때 끝났는지 알 수 있어야 함).
+ *
+ * 정책:
+ *  - macOS: osascript 'display notification'
+ *  - Linux: notify-send (있으면)
+ *  - Windows: 생략 (PowerShell BurntToast 의존성 회피)
+ *  - webhook: ~/.forgen/config.json 의 notifyWebhookUrl 설정 시 POST
+ *  - fail-open: 모든 실패는 silent log
+ */
+import { spawn } from 'node:child_process';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { FORGEN_HOME } from './paths.js';
+import { createLogger } from './logger.js';
+const log = createLogger('notify');
+function loadConfig() {
+    try {
+        const cfgPath = path.join(FORGEN_HOME, 'config.json');
+        if (!fs.existsSync(cfgPath))
+            return {};
+        return JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function escapeForOsascript(s) {
+    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/** macOS native notification via osascript. silent fail. */
+function notifyDarwin(title, body) {
+    try {
+        const script = `display notification "${escapeForOsascript(body)}" with title "${escapeForOsascript(title)}"`;
+        const child = spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' });
+        child.unref();
+    }
+    catch (e) {
+        log.debug('osascript notification 실패', e);
+    }
+}
+/** Linux notify-send. silent fail (notify-send 미설치 OK). */
+function notifyLinux(title, body) {
+    try {
+        const child = spawn('notify-send', [title, body], { detached: true, stdio: 'ignore' });
+        child.unref();
+    }
+    catch (e) {
+        log.debug('notify-send 실패', e);
+    }
+}
+/** webhook POST (slack/discord 호환). silent fail. */
+async function notifyWebhook(url, title, body) {
+    try {
+        // Slack / Discord 호환 — text 필드 우선, fallback 으로 content
+        const payload = JSON.stringify({
+            text: `*${title}*\n${body}`,
+            content: `**${title}**\n${body}`, // Discord
+        });
+        await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: payload,
+        });
+    }
+    catch (e) {
+        log.debug('webhook notify 실패', e);
+    }
+}
+/**
+ * 통합 알림 진입점. desktop + webhook 둘 다 시도.
+ * 모든 실패는 silent — 호출 측 차단 안 함.
+ */
+export function sendNotification(title, body) {
+    const cfg = loadConfig();
+    const desktopEnabled = cfg.notifyDesktop !== false; // default true
+    if (desktopEnabled) {
+        const platform = os.platform();
+        if (platform === 'darwin')
+            notifyDarwin(title, body);
+        else if (platform === 'linux')
+            notifyLinux(title, body);
+        // win32: 생략
+    }
+    if (cfg.notifyWebhookUrl) {
+        // fire-and-forget — await 하지 않음 (caller 차단 방지)
+        void notifyWebhook(cfg.notifyWebhookUrl, title, body);
+    }
+}

package/dist/core/spawn.d.ts

@@ -2,8 +2,19 @@ import type { V1HarnessContext } from './harness.js';
 import type { RuntimeHost } from './types.js';
 /** Claude Code를 하네스 환경으로 실행. exit code를 반환. */
 export declare function spawnClaude(args: string[], context: V1HarnessContext, runtime?: RuntimeHost): Promise<number>;
+declare const MAX_RESUMES = 3;
 /**
- * 토큰 한도 도달 시 자동 재시작을 지원하는 claude 실행 래퍼.
- * context-guard가 pending-resume.json 마커를 생성하면 쿨다운 후 재시작.
+ * Exponential backoff for rate-limit when resetAt 파싱 실패.
+ * 1m → 5m → 15m → 30m → 1h → 2h cap. 합 ≤ 6h.
+ */
+export declare function rateLimitBackoffMs(attempt: number): number;
+/**
+ * 토큰 한도 / API rate-limit 도달 시 자동 재시작을 지원하는 claude 실행 래퍼.
+ * context-guard가 pending-resume.json 마커를 생성하면 reason 별 정책으로 처리.
+ *
+ * - reason='token-limit': 30s 쿨다운, MAX_RESUMES_TOKEN=3
+ * - reason='rate-limit': resetAt 정밀 sleep (+60s 버퍼) 또는 exponential backoff,
+ *                        MAX_RESUMES_RATE=10, hard cap 6h
  */
 export declare function spawnClaudeWithResume(args: string[], context: V1HarnessContext, contextFactory: () => Promise<V1HarnessContext>, runtime?: RuntimeHost): Promise<void>;
+export { MAX_RESUMES };

package/dist/core/spawn.js

@@ -8,19 +8,39 @@ import { loadGlobalConfig } from './global-config.js';
 import { createLogger } from './logger.js';
 import { STATE_DIR } from './paths.js';
 import { getHostRuntime } from '../host/host-runtime.js';
+import { sendNotification } from './notify.js';
 const log = createLogger('spawn');
 /** Phase 2: host-runtime 어댑터 위임. */
 function findRuntimeLauncher(runtime) {
     return getHostRuntime(runtime).launcher;
 }
-function transcriptProjectDir(cwd) {
+/**
+ * 0.4.6 — runtime 별 transcript 디렉토리.
+ *
+ * - claude: ~/.claude/projects/<sanitized-cwd>/<session>.jsonl
+ * - codex: ~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<sid>.jsonl
+ *
+ * Codex 는 cwd 별 격리 없이 날짜별 격리 — 같은 사용자의 모든 codex 세션이
+ * 동일 날짜 dir 에 들어감. session attribution 은 파일 basename 의 session-id 로.
+ *
+ * Note: codex 는 일별 dir 라 자정 가로지르는 세션은 두 dir 에 걸칠 수 있음 —
+ * 본 함수는 시작 시점 dir 만 반환. 호출 측이 needed 시 보강.
+ */
+function transcriptProjectDir(cwd, runtime = 'claude') {
+    if (runtime === 'codex') {
+        const d = new Date();
+        const y = d.getUTCFullYear();
+        const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+        const day = String(d.getUTCDate()).padStart(2, '0');
+        return path.join(os.homedir(), '.codex', 'sessions', String(y), m, day);
+    }
     // Claude Code는 cwd의 /를 -로 치환하고 선행 -를 유지
     const sanitized = cwd.replace(/\//g, '-');
     return path.join(os.homedir(), '.claude', 'projects', sanitized);
 }
 /** 스냅샷용 — 세션 시작 전 존재하는 transcript basename 집합. */
-function snapshotExistingTranscripts(cwd) {
-    const dir = transcriptProjectDir(cwd);
+function snapshotExistingTranscripts(cwd, runtime = 'claude') {
+    const dir = transcriptProjectDir(cwd, runtime);
     if (!fs.existsSync(dir))
         return new Set();
     try {
@@ -43,8 +63,8 @@ function snapshotExistingTranscripts(cwd) {
  * 여전히 후보가 여러 개이면 (rare: 훅이 추가 파일을 쓴 경우) 가장 최근 수정본
  * 을 고르되 debug 로그를 남긴다.
  */
-function findSessionTranscript(cwd, sessionStartMs, preSnapshot) {
-    const dir = transcriptProjectDir(cwd);
+function findSessionTranscript(cwd, sessionStartMs, preSnapshot, runtime = 'claude') {
+    const dir = transcriptProjectDir(cwd, runtime);
     if (!fs.existsSync(dir))
         return null;
     let candidates;
@@ -81,6 +101,14 @@ function findSessionTranscript(cwd, sessionStartMs, preSnapshot) {
  * 파일 전체를 메모리에 올렸다. 수백 MB 규모 transcript에서는 heap spike가
  * 발생했고, 카운트 외엔 내용이 필요 없으니 streaming line-by-line로 충분하다.
  */
+/**
+ * 0.4.6 — claude/codex 양 schema 호환.
+ *
+ * Claude JSONL: {type: 'user' | 'queue-operation', ...}
+ * Codex JSONL: {type: 'response_item', payload: {role: 'user' | 'developer' | 'assistant', ...}}
+ *
+ * 단일 함수에서 둘 다 처리 — schema 자동 감지.
+ */
 async function countUserMessages(transcriptPath) {
     const { createInterface } = await import('node:readline');
     const stream = fs.createReadStream(transcriptPath, { encoding: 'utf-8' });
@@ -91,8 +119,15 @@ async function countUserMessages(transcriptPath) {
             if (!line)
                 continue;
             try {
-                const t = JSON.parse(line).type;
-                if (t === 'user' || t === 'queue-operation')
+                const obj = JSON.parse(line);
+                const t = obj.type;
+                // Claude schema
+                if (t === 'user' || t === 'queue-operation') {
+                    count++;
+                    continue;
+                }
+                // Codex schema (response_item with role=user)
+                if (t === 'response_item' && obj.payload?.role === 'user')
                     count++;
             }
             catch { /* skip malformed */ }
@@ -150,7 +185,7 @@ export async function spawnClaude(args, context, runtime = 'claude') {
     // 세션 시작 전 timestamp + 기존 transcript 스냅샷 기록 (종료 후 finder 용).
     // Audit fix #8 (2026-04-21): 스냅샷으로 동시 세션 transcript 오선택을 차단.
     const sessionStartTime = Date.now();
-    const preSnapshot = snapshotExistingTranscripts(context.cwd);
+    const preSnapshot = snapshotExistingTranscripts(context.cwd, runtime);
     return new Promise((resolve, reject) => {
         const child = spawn(launcher, cleanArgs, {
             stdio: 'inherit',
@@ -166,21 +201,35 @@ export async function spawnClaude(args, context, runtime = 'claude') {
             }
         });
         child.on('exit', async (code) => {
-            if (runtime !== 'claude') {
+            if (runtime !== 'claude' && runtime !== 'codex') {
                 resolve(code ?? 0);
                 return;
             }
-            // 세션 종료 후 하네스 작업
+            // 세션 종료 후 하네스 작업.
+            // 0.4.6 — codex 도 transcript 인식 (~/.codex/sessions/YYYY/MM/DD/rollout-<sid>.jsonl).
+            // Codex transcript 의 schema 는 claude 와 다르므로 auto-compound 의 input parsing 은
+            // 별개 작업 (0.4.7). 현재 단계는 *transcript 위치 인식 + count* 만 codex 호환.
             try {
-                const transcript = findSessionTranscript(context.cwd, sessionStartTime, preSnapshot);
+                const transcript = findSessionTranscript(context.cwd, sessionStartTime, preSnapshot, runtime);
                 if (!transcript) {
                     log.debug('이 세션에서 생성된 transcript를 찾을 수 없음 (snapshot diff)');
                 }
                 else {
-                    const sessionId = path.basename(transcript, '.jsonl');
-                    // 1. FTS5 인덱싱
-                    await indexTranscriptToFTS(context.cwd, transcript, sessionId);
-                    // 2. 자동 compound (10+ user 메시지인 경우만) — streaming line count
+                    // 0.4.6 — claude/codex 양 schema 호환 (countUserMessages + extractSummary).
+                    // codex transcript 의 sessionId 는 파일명 패턴 'rollout-<ts>-<sid>.jsonl' 의 끝부분.
+                    let sessionId;
+                    if (runtime === 'codex') {
+                        const m = path.basename(transcript, '.jsonl').match(/rollout-[\dT-]+-(.+)$/);
+                        sessionId = m ? m[1] : path.basename(transcript, '.jsonl');
+                    }
+                    else {
+                        sessionId = path.basename(transcript, '.jsonl');
+                    }
+                    // 1. FTS5 인덱싱 (claude only — codex schema FTS 호환은 미검증, 별도 작업)
+                    if (runtime === 'claude') {
+                        await indexTranscriptToFTS(context.cwd, transcript, sessionId);
+                    }
+                    // 2. 자동 compound (10+ user 메시지인 경우만) — 양 runtime 호환
                     const userMsgCount = await countUserMessages(transcript);
                     if (userMsgCount >= 10) {
                         await runAutoCompound(context.cwd, transcript, sessionId);
@@ -198,17 +247,52 @@ export async function spawnClaude(args, context, runtime = 'claude') {
     });
 }
 const RESUME_COOLDOWN_MS = 30_000;
-const MAX_RESUMES = 3;
+const MAX_RESUMES_TOKEN = 3;
+const MAX_RESUMES_RATE = 10; // ADR-008: rate-limit wait 은 5h 단위라 더 관대
+const MAX_RESUMES = MAX_RESUMES_TOKEN; // backward compat — 기존 token-limit 호출자
+const RATE_LIMIT_HARD_CAP_MS = 6 * 60 * 60 * 1000; // 6h max single wait
+const COUNTDOWN_INTERVAL_MS = 30_000;
+/**
+ * Exponential backoff for rate-limit when resetAt 파싱 실패.
+ * 1m → 5m → 15m → 30m → 1h → 2h cap. 합 ≤ 6h.
+ */
+export function rateLimitBackoffMs(attempt) {
+    const schedule = [60_000, 5 * 60_000, 15 * 60_000, 30 * 60_000, 60 * 60_000, 2 * 60 * 60_000];
+    return schedule[Math.min(attempt, schedule.length - 1)];
+}
 /**
- * 토큰 한도 도달 시 자동 재시작을 지원하는 claude 실행 래퍼.
- * context-guard가 pending-resume.json 마커를 생성하면 쿨다운 후 재시작.
+ * Foreground countdown — 30s 마다 남은 시간 단일 라인 갱신, Ctrl+C 시 abort.
+ */
+async function countdownSleep(totalMs, label) {
+    const deadline = Date.now() + totalMs;
+    while (Date.now() < deadline) {
+        const remainMs = deadline - Date.now();
+        const remainMin = Math.floor(remainMs / 60_000);
+        const remainSec = Math.floor((remainMs % 60_000) / 1000);
+        const eta = remainMin >= 60
+            ? `${Math.floor(remainMin / 60)}h ${remainMin % 60}m`
+            : `${remainMin}m ${remainSec}s`;
+        process.stdout.write(`\r[forgen] ${label} — ${eta} remaining (Ctrl+C to abort)    `);
+        const tick = Math.min(COUNTDOWN_INTERVAL_MS, remainMs);
+        await new Promise(resolve => setTimeout(resolve, tick));
+    }
+    process.stdout.write('\n');
+}
+/**
+ * 토큰 한도 / API rate-limit 도달 시 자동 재시작을 지원하는 claude 실행 래퍼.
+ * context-guard가 pending-resume.json 마커를 생성하면 reason 별 정책으로 처리.
+ *
+ * - reason='token-limit': 30s 쿨다운, MAX_RESUMES_TOKEN=3
+ * - reason='rate-limit': resetAt 정밀 sleep (+60s 버퍼) 또는 exponential backoff,
+ *                        MAX_RESUMES_RATE=10, hard cap 6h
  */
 export async function spawnClaudeWithResume(args, context, contextFactory, runtime = 'claude') {
-    let resumeCount = 0;
+    let tokenResumeCount = 0;
+    let rateResumeCount = 0;
     let currentContext = context;
     while (true) {
         const exitCode = await spawnClaude(args, currentContext, runtime);
-        if (runtime !== 'claude') {
+        if (runtime !== 'claude' && runtime !== 'codex') {
             if (exitCode !== 0)
                 process.exit(exitCode);
             break;
@@ -222,20 +306,56 @@ export async function spawnClaudeWithResume(args, context, contextFactory, runti
         try {
             const marker = JSON.parse(fs.readFileSync(resumePath, 'utf-8'));
             fs.unlinkSync(resumePath);
-            if (marker.reason !== 'token-limit') {
-                if (exitCode !== 0)
-                    process.exit(exitCode);
-                break;
+            if (marker.reason === 'token-limit') {
+                if (tokenResumeCount >= MAX_RESUMES_TOKEN) {
+                    console.log(`[forgen] 최대 자동 재시작 횟수(${MAX_RESUMES_TOKEN}) 도달. 수동으로 다시 시작하세요.`);
+                    break;
+                }
+                tokenResumeCount++;
+                console.log(`[forgen] 토큰 한도 도달. ${RESUME_COOLDOWN_MS / 1000}초 후 자동 재시작합니다... (${tokenResumeCount}/${MAX_RESUMES_TOKEN})`);
+                await new Promise(resolve => setTimeout(resolve, RESUME_COOLDOWN_MS));
+                console.log('[forgen] 세션 재시작 중...');
+                currentContext = await contextFactory();
+                continue;
             }
-            if (resumeCount >= MAX_RESUMES) {
-                console.log(`[forgen] 최대 자동 재시작 횟수(${MAX_RESUMES}) 도달. 수동으로 다시 시작하세요.`);
-                break;
+            if (marker.reason === 'rate-limit') {
+                if (rateResumeCount >= MAX_RESUMES_RATE) {
+                    console.log(`[forgen] rate-limit 자동 재시작 한도(${MAX_RESUMES_RATE}) 도달. 수동 재시작 필요.`);
+                    break;
+                }
+                rateResumeCount++;
+                let sleepMs;
+                let label;
+                if (marker.resetAt) {
+                    const resetMs = Date.parse(marker.resetAt);
+                    if (Number.isFinite(resetMs)) {
+                        const target = resetMs - Date.now() + 60_000; // 60s 버퍼
+                        sleepMs = Math.min(Math.max(target, 0), RATE_LIMIT_HARD_CAP_MS);
+                        label = `Rate limit. Resuming after reset (${marker.resetAt})`;
+                    }
+                    else {
+                        sleepMs = rateLimitBackoffMs(rateResumeCount - 1);
+                        label = `Rate limit. Backoff #${rateResumeCount}`;
+                    }
+                }
+                else {
+                    sleepMs = rateLimitBackoffMs(rateResumeCount - 1);
+                    label = `Rate limit. Backoff #${rateResumeCount}`;
+                }
+                if (sleepMs >= RATE_LIMIT_HARD_CAP_MS) {
+                    console.log(`[forgen] rate-limit reset 시각이 hard cap(6h) 초과 — 수동 재시작 필요. handoff 저장됨.`);
+                    break;
+                }
+                await countdownSleep(sleepMs, label);
+                console.log('[forgen] 세션 재시작 중...');
+                sendNotification('forgen — Rate limit 회복', `${runtime} 세션 재기동 중 (${rateResumeCount}/${MAX_RESUMES_RATE} resume)`);
+                currentContext = await contextFactory();
+                continue;
             }
-            resumeCount++;
-            console.log(`[forgen] 토큰 한도 도달. ${RESUME_COOLDOWN_MS / 1000}초 후 자동 재시작합니다... (${resumeCount}/${MAX_RESUMES})`);
-            await new Promise(resolve => setTimeout(resolve, RESUME_COOLDOWN_MS));
-            console.log('[forgen] 세션 재시작 중...');
-            currentContext = await contextFactory();
+            // 알 수 없는 reason → exit (fail-open, 수동 처리)
+            if (exitCode !== 0)
+                process.exit(exitCode);
+            break;
         }
         catch {
             if (exitCode !== 0)
@@ -244,3 +364,5 @@ export async function spawnClaudeWithResume(args, context, contextFactory, runti
         }
     }
 }
+// MAX_RESUMES re-export for backward-compat tests
+export { MAX_RESUMES };

package/dist/core/state-gc.d.ts

@@ -17,6 +17,16 @@ export interface PruneOptions {
     /** Current time for deterministic tests. Defaults to Date.now(). */
     now?: number;
 }
+export interface RotateReport {
+    scanned: number;
+    rotated: number;
+    bytesFreed: number;
+    sample: string[];
+}
+export declare function rotateAppendOnlyLogs(opts?: {
+    stateDir?: string;
+    maxBytes?: number;
+}): RotateReport;
 /**
  * Prune session-scoped files older than `retentionMs` from the state and
  * outcomes directories. Defaults to a dry-run so callers must opt-in to

package/dist/core/state-gc.js

@@ -78,6 +78,77 @@ function pruneDir(dir, cutoff, dryRun, filter) {
     }
     return out;
 }
+/**
+ * 0.4.6 #14 — append-only jsonl 로그 회전.
+ *
+ * state-gc 의 SESSION_SCOPED_PREFIXES 는 session 별 파일을 prefix-base 로 잡지만,
+ * 단일 aggregate jsonl (hook-timing, prompt-history, usage-telemetry 등) 은 매번
+ * append 되어 무한 grow. 본 함수가 size cap (default 10MB) 초과 시 `<name>.1` 로
+ * rotate 하고 `<name>.2` 는 삭제 (한 단계만 보존).
+ *
+ * 회전 정책:
+ *  - cap 미만: no-op
+ *  - cap 초과: <name>.2 삭제 → <name>.1 → <name>.2, <name> → <name>.1, 새 빈 <name>
+ *  - 0.4.6 신설 jsonl 들 (prompt-history, usage-telemetry, rate-limit-misses) 포함
+ *
+ * fail-open: 모든 I/O 실패는 silent — 호출 측 차단 안 함.
+ */
+const ROTATABLE_LOGS = [
+    'hook-errors.jsonl',
+    'hook-timing.jsonl',
+    'implicit-feedback.jsonl',
+    'match-eval-log.jsonl',
+    'solution-quarantine.jsonl',
+    'prompt-history.jsonl',
+    'usage-telemetry.jsonl',
+    'rate-limit-misses.jsonl',
+];
+const DEFAULT_MAX_LOG_BYTES = 10 * 1024 * 1024; // 10MB
+export function rotateAppendOnlyLogs(opts = {}) {
+    const stateDir = opts.stateDir ?? STATE_DIR;
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_LOG_BYTES;
+    const out = { scanned: 0, rotated: 0, bytesFreed: 0, sample: [] };
+    if (!fs.existsSync(stateDir))
+        return out;
+    for (const name of ROTATABLE_LOGS) {
+        const full = path.join(stateDir, name);
+        let stat;
+        try {
+            stat = fs.statSync(full);
+        }
+        catch {
+            continue;
+        }
+        out.scanned++;
+        if (stat.size <= maxBytes)
+            continue;
+        try {
+            const r1 = `${full}.1`;
+            const r2 = `${full}.2`;
+            // .2 삭제
+            try {
+                fs.unlinkSync(r2);
+                out.bytesFreed += fs.existsSync(r2) ? 0 : (fs.statSync(r2).size ?? 0);
+            }
+            catch { /* no .2 */ }
+            // .1 → .2
+            try {
+                if (fs.existsSync(r1))
+                    fs.renameSync(r1, r2);
+            }
+            catch { /* skip */ }
+            // active → .1
+            fs.renameSync(full, r1);
+            // 새 빈 파일
+            fs.writeFileSync(full, '');
+            out.rotated++;
+            if (out.sample.length < 20)
+                out.sample.push(name);
+        }
+        catch { /* fail-open per file */ }
+    }
+    return out;
+}
 /**
  * Prune session-scoped files older than `retentionMs` from the state and
  * outcomes directories. Defaults to a dry-run so callers must opt-in to

package/dist/core/statusline-cli.js

@@ -15,6 +15,13 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import { execSync } from 'node:child_process';
 import { loadActiveRules } from '../store/rule-store.js';
+import { getUsageStats } from './usage-telemetry.js';
+import { STATE_DIR } from './paths.js';
+// 0.4.6 perf #13 — statusline 출력을 5초 캐싱.
+// claude statusLine 은 짧은 간격으로 재호출되는데 매번 git/find/rule-store 를
+// 실행하면 ~100ms 누적. CACHE_TTL_MS 동안 동일 출력 재사용.
+const STATUSLINE_CACHE_PATH = path.join(STATE_DIR, 'statusline-cache.txt');
+const CACHE_TTL_MS = 5_000;
 // ANSI codes
 const DIM = '\x1b[2m';
 const CYAN = '\x1b[36m';
@@ -116,6 +123,23 @@ function buildLine1(payload, cwd) {
         parts.push(`${GREEN}${gitBranch}${RESET}`);
     return parts.join(`  ${DIM}|${RESET}  `);
 }
+/** Build usage line: "📊 87/5h · 412/wk (claude)" — 0.4.6 신설 */
+function buildUsageLine() {
+    try {
+        const stats = getUsageStats();
+        if (stats.week.total === 0)
+            return null;
+        const dominant = stats.week.codex > stats.week.claude ? 'codex' : 'claude';
+        return [
+            `${YELLOW}📊 ${stats.hour5.total}/5h${RESET}`,
+            `${YELLOW}${stats.week.total}/wk${RESET}`,
+            `${DIM}(${dominant})${RESET}`,
+        ].join(`  ${DIM}·${RESET}  `);
+    }
+    catch {
+        return null;
+    }
+}
 function buildLine3(claudeDir, cwd) {
     const settings = getSettingsJson(claudeDir);
     const claudeMdCount = countClaudeMd(cwd);
@@ -136,15 +160,46 @@ function buildLine3(claudeDir, cwd) {
         `${YELLOW}${hookCount} hooks${RESET}`,
     ].join(`  ${DIM}|${RESET}  `);
 }
+/** 0.4.6 perf #13: cached output if fresh. */
+function readCacheIfFresh() {
+    try {
+        const stat = fs.statSync(STATUSLINE_CACHE_PATH);
+        if (Date.now() - stat.mtimeMs < CACHE_TTL_MS) {
+            return fs.readFileSync(STATUSLINE_CACHE_PATH, 'utf-8');
+        }
+    }
+    catch { /* no cache or stale */ }
+    return null;
+}
+function writeCache(content) {
+    try {
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+        fs.writeFileSync(STATUSLINE_CACHE_PATH, content);
+    }
+    catch { /* fail-open */ }
+}
 export async function handleStatusline() {
+    // 캐시 hit 시 stdin payload 무시하고 바로 출력 (5초 윈도우 내 동일 출력 가정).
+    // 라인 단위 cache → console.log 라인별 (테스트 호환).
+    const cached = readCacheIfFresh();
+    if (cached !== null) {
+        for (const line of cached.split('\n').filter(Boolean))
+            console.log(line);
+        return;
+    }
     const payload = readStdinJson();
     const cwd = payload.workspace?.current_dir ?? process.cwd();
     const claudeDir = path.join(os.homedir(), '.claude');
     const line1 = buildLine1(payload, cwd);
     const line3 = buildLine3(claudeDir, cwd);
+    const usageLine = buildUsageLine();
     // Line 2 (context/usage): stdin JSON spec 미확인으로 생략 — TODO
     // Line 4 (tool counts): 추적 인프라 없음 — TODO
     // Line 5 (active task): 추적 인프라 없음 — TODO
     console.log(line1);
     console.log(line3);
+    if (usageLine)
+        console.log(usageLine);
+    const cacheBody = usageLine ? `${line1}\n${line3}\n${usageLine}\n` : `${line1}\n${line3}\n`;
+    writeCache(cacheBody);
 }

package/dist/core/usage-telemetry.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Forgen Usage Telemetry — ADR-008 §"테마 A unattended resilience"
+ *
+ * 5h / weekly window 의 tool call 수를 sliding window 로 추적하여 statusline
+ * (`forgen me`) 에 노출. rate-limit hit 전에 사용자가 사용량을 가시화할 수 있도록.
+ *
+ * 정책:
+ *  - 각 PostToolUse 마다 append-only JSONL 에 timestamp 한 줄 기록
+ *  - read 시 sliding window 로 필터 + 카운트 (스트리밍 — 메모리 절약)
+ *  - 10K 엔트리 누적 시 weekly cap 밖 엔트리 prune (rewrite once)
+ *  - fail-open: 모든 I/O 실패는 로그 후 무시, 호출 측 차단 안 함
+ *
+ * 0.4.6 신설. limit prediction 은 의도적으로 제외 — Anthropic 의 실제 limit 가
+ * 계정/플랜별 가변이라 hard-code 부정확. raw count 만 노출하고 사용자가 판단.
+ */
+export interface UsageStats {
+    hour5: {
+        claude: number;
+        codex: number;
+        total: number;
+    };
+    week: {
+        claude: number;
+        codex: number;
+        total: number;
+    };
+}
+export declare function recordToolCall(runtime?: 'claude' | 'codex'): void;
+/**
+ * sliding window count. fail-open: 파일 미존재/parse 실패는 0 반환.
+ *
+ * @param now epoch ms (테스트 결정성)
+ */
+export declare function getUsageStats(now?: number): UsageStats;