@wooojin/forgen 0.4.5 → 0.4.6

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;

package/dist/core/usage-telemetry.js

@@ -0,0 +1,101 @@
+/**
+ * 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 만 노출하고 사용자가 판단.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { STATE_DIR } from './paths.js';
+import { createLogger } from './logger.js';
+const log = createLogger('usage-telemetry');
+const TELEMETRY_PATH = path.join(STATE_DIR, 'usage-telemetry.jsonl');
+const HOUR5_MS = 5 * 60 * 60 * 1000;
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const PRUNE_THRESHOLD = 10_000; // 10K lines 누적 시 prune
+export function recordToolCall(runtime = 'claude') {
+    try {
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+        const entry = { ts: Date.now(), rt: runtime };
+        fs.appendFileSync(TELEMETRY_PATH, `${JSON.stringify(entry)}\n`);
+    }
+    catch (e) {
+        log.debug('telemetry append 실패', e);
+    }
+}
+/**
+ * sliding window count. fail-open: 파일 미존재/parse 실패는 0 반환.
+ *
+ * @param now epoch ms (테스트 결정성)
+ */
+export function getUsageStats(now = Date.now()) {
+    const stats = {
+        hour5: { claude: 0, codex: 0, total: 0 },
+        week: { claude: 0, codex: 0, total: 0 },
+    };
+    try {
+        if (!fs.existsSync(TELEMETRY_PATH))
+            return stats;
+        const cutoff5h = now - HOUR5_MS;
+        const cutoffWeek = now - WEEK_MS;
+        const raw = fs.readFileSync(TELEMETRY_PATH, 'utf-8');
+        const lines = raw.split('\n');
+        let total = 0;
+        for (const line of lines) {
+            if (!line)
+                continue;
+            total++;
+            try {
+                const e = JSON.parse(line);
+                if (typeof e.ts !== 'number' || e.ts < cutoffWeek)
+                    continue;
+                const rt = e.rt === 'codex' ? 'codex' : 'claude';
+                stats.week[rt]++;
+                stats.week.total++;
+                if (e.ts >= cutoff5h) {
+                    stats.hour5[rt]++;
+                    stats.hour5.total++;
+                }
+            }
+            catch { /* skip malformed line */ }
+        }
+        if (total > PRUNE_THRESHOLD)
+            pruneOldEntries(now);
+    }
+    catch (e) {
+        log.debug('telemetry read 실패', e);
+    }
+    return stats;
+}
+/** 누적 엔트리가 PRUNE_THRESHOLD 초과 시 weekly cap 밖 entry 제거 (rewrite). */
+function pruneOldEntries(now) {
+    try {
+        const cutoff = now - WEEK_MS;
+        const raw = fs.readFileSync(TELEMETRY_PATH, 'utf-8');
+        const kept = [];
+        for (const line of raw.split('\n')) {
+            if (!line)
+                continue;
+            try {
+                const e = JSON.parse(line);
+                if (typeof e.ts === 'number' && e.ts >= cutoff)
+                    kept.push(line);
+            }
+            catch { /* drop malformed */ }
+        }
+        fs.writeFileSync(TELEMETRY_PATH, kept.join('\n') + (kept.length ? '\n' : ''));
+        log.debug(`telemetry pruned to ${kept.length} entries`);
+    }
+    catch (e) {
+        log.debug('telemetry prune 실패', e);
+    }
+}

package/dist/hooks/context-guard.d.ts

@@ -9,6 +9,19 @@
  * 또한 UserPromptSubmit에서 현재 대화 길이를 추적하여
  * context 한계에 접근 시 preemptive 경고를 제공합니다.
  */
+export declare const TOKEN_LIMIT_REGEX: RegExp;
+export declare const RATE_LIMIT_REGEX: RegExp;
+/**
+ * Best-effort reset 시각 파서 (ADR-008 §2).
+ *
+ * 5 패턴 시도, 모두 실패 시 null. 실제 메시지 포맷은 Claude/Codex CLI 의
+ * 공식 contract 가 아니므로 hotfix 가능한 best-effort.
+ *
+ * @param msg stderr/error message text
+ * @param now epoch ms (테스트 결정성 위해 주입 가능)
+ * @returns ISO timestamp 또는 null
+ */
+export declare function parseRateLimitResetAt(msg: string, now?: number): string | null;
 /** 경고 표시 여부 판정 (순수 함수) */
 export declare function shouldWarn(contextPercent: {
     promptCount: number;