@wooojin/forgen 0.1.0

package/dist/hooks/rate-limiter.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Forgen — PreToolUse: Rate Limiter Hook
+ *
+ * MCP 도구 호출 빈도를 제한하여 남용을 방지합니다.
+ * 기본 제한: 30회/분
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { readStdinJSON } from './shared/read-stdin.js';
+import { atomicWriteJSON } from './shared/atomic-write.js';
+import { isHookEnabled } from './hook-config.js';
+import { approve, deny, failOpen } from './shared/hook-response.js';
+import { STATE_DIR } from '../core/paths.js';
+const RATE_LIMIT_PATH = path.join(STATE_DIR, 'rate-limit.json');
+const DEFAULT_LIMIT = 30; // calls per minute
+const WINDOW_MS = 60_000; // 1 minute
+/** 상태 파일 로드 (스키마 검증 포함) */
+export function loadRateLimitState() {
+    try {
+        if (fs.existsSync(RATE_LIMIT_PATH)) {
+            const raw = JSON.parse(fs.readFileSync(RATE_LIMIT_PATH, 'utf-8'));
+            // 스키마 검증: calls가 number 배열이어야 함
+            if (raw && Array.isArray(raw.calls) && raw.calls.every((c) => typeof c === 'number')) {
+                return raw;
+            }
+            // 손상된 상태 → 초기화
+        }
+    }
+    catch { /* rate limit state parse failure — starting fresh, window resets (fail-open is safe here) */ }
+    return { calls: [] };
+}
+/** 상태 파일 저장 (atomic write로 동시 세션 안전) */
+export function saveRateLimitState(state) {
+    atomicWriteJSON(RATE_LIMIT_PATH, state);
+}
+/** 오래된 호출 기록 정리 + 제한 초과 여부 판정 (순수 함수) */
+export function checkRateLimit(state, now = Date.now(), limit = DEFAULT_LIMIT) {
+    // 1분 이전 호출 제거
+    const cutoff = now - WINDOW_MS;
+    const recentCalls = state.calls.filter(t => t > cutoff);
+    // 초과 여부 먼저 판정 (현재 호출 추가 전 기준)
+    const exceeded = recentCalls.length >= limit;
+    // 거부된 호출은 윈도우에 추가하지 않음 — 승인된 호출만 기록
+    if (!exceeded) {
+        recentCalls.push(now);
+    }
+    return {
+        exceeded,
+        count: recentCalls.length + (exceeded ? 1 : 0),
+        updatedState: { calls: recentCalls },
+    };
+}
+async function main() {
+    const data = await readStdinJSON(1500); // Must finish within plugin.json timeout (2000ms)
+    if (!data) {
+        // stdin 파싱 실패 — 통과 (rate limiter는 fail-open)
+        console.log(failOpen());
+        return;
+    }
+    if (!isHookEnabled('rate-limiter')) {
+        console.log(approve());
+        return;
+    }
+    const toolName = data.tool_name ?? data.toolName ?? '';
+    // MCP 도구만 추적 (mcp__ 접두사)
+    if (!toolName.startsWith('mcp__')) {
+        console.log(approve());
+        return;
+    }
+    const state = loadRateLimitState();
+    const { exceeded, count, updatedState } = checkRateLimit(state);
+    // 거부된 호출은 상태를 저장하지 않음 (윈도우 누적 방지)
+    if (!exceeded) {
+        saveRateLimitState(updatedState);
+    }
+    if (exceeded) {
+        console.log(deny(`[Forgen] Rate limit exceeded (${count}/${DEFAULT_LIMIT}/min). Wait before retrying.`));
+        return;
+    }
+    console.log(approve());
+}
+main().catch((e) => {
+    process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
+    console.log(failOpen());
+});

package/dist/hooks/secret-filter.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Forgen — PostToolUse: Secret Filter Hook
+ *
+ * 도구 실행 결과에서 API 키, 토큰, 비밀번호 등 민감 정보 노출을 감지합니다.
+ * 차단하지 않고 경고 메시지만 출력합니다.
+ */
+export interface SecretPattern {
+    name: string;
+    pattern: RegExp;
+}
+export declare const SECRET_PATTERNS: SecretPattern[];
+/** 텍스트에서 민감 정보 패턴 감지 (순수 함수) */
+export declare function detectSecrets(text: string): SecretPattern[];

package/dist/hooks/secret-filter.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Forgen — PostToolUse: Secret Filter Hook
+ *
+ * 도구 실행 결과에서 API 키, 토큰, 비밀번호 등 민감 정보 노출을 감지합니다.
+ * 차단하지 않고 경고 메시지만 출력합니다.
+ */
+import { HookError } from '../core/errors.js';
+import { readStdinJSON } from './shared/read-stdin.js';
+import { isHookEnabled } from './hook-config.js';
+import { approve, approveWithWarning, failOpen } from './shared/hook-response.js';
+export const SECRET_PATTERNS = [
+    { name: 'API Key', pattern: /(sk|pk|api[_-]?key)[_-][\w\-.]{20,}/i },
+    { name: 'AWS Access Key', pattern: /AKIA[\w]{16}/ },
+    { name: 'Token/Bearer/JWT', pattern: /(token|bearer|jwt)[=:\s]["']?[\w\-.]{20,}/i },
+    { name: 'Password', pattern: /(password|passwd|pwd)\s*[=:]\s*["']?[^\s"']{8,}/i },
+    { name: 'Private Key', pattern: /-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----/ },
+    { name: 'Connection String', pattern: /(mongodb|postgres|mysql|redis):\/\/\w+:[^@]+@/ },
+];
+/** 텍스트에서 민감 정보 패턴 감지 (순수 함수) */
+export function detectSecrets(text) {
+    const found = [];
+    for (const sp of SECRET_PATTERNS) {
+        if (sp.pattern.test(text)) {
+            found.push(sp);
+        }
+    }
+    return found;
+}
+async function main() {
+    const data = await readStdinJSON();
+    if (!isHookEnabled('secret-filter')) {
+        console.log(approve());
+        return;
+    }
+    if (!data) {
+        console.log(approve());
+        return;
+    }
+    const toolName = data.tool_name ?? data.toolName ?? '';
+    const toolResponse = data.tool_response ?? data.toolOutput ?? '';
+    const toolInput = data.tool_input ?? data.toolInput ?? {};
+    // Write/Edit/Bash 도구만 검사
+    if (!['Write', 'Edit', 'Bash'].includes(toolName)) {
+        console.log(approve());
+        return;
+    }
+    // 도구 입력 + 출력 모두 검사
+    const inputStr = typeof toolInput === 'string' ? toolInput : JSON.stringify(toolInput);
+    const textToScan = `${inputStr}\n${toolResponse}`;
+    const secrets = detectSecrets(textToScan);
+    if (secrets.length > 0) {
+        const names = secrets.map(s => s.name).join(', ');
+        console.log(approveWithWarning(`<compound-security-warning>\n[Forgen] ⚠ Sensitive information exposure detected: ${names}\nThe output may contain secrets. Please review.\n</compound-security-warning>`));
+        return;
+    }
+    console.log(approve());
+}
+main().catch((e) => {
+    const hookErr = new HookError(e instanceof Error ? e.message : String(e), {
+        hookName: 'secret-filter', eventType: 'PostToolUse', cause: e,
+    });
+    process.stderr.write(`[ch-hook] ${hookErr.name}: ${hookErr.message}\n`);
+    console.log(failOpen());
+});

package/dist/hooks/session-recovery.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Forgen — Session Recovery Hook
+ *
+ * Claude Code SessionStart 훅으로 등록.
+ * 이전 세션에서 활성화된 지속 모드(ralph, autopilot, ultrawork)의
+ * 상태를 복구하여 작업을 자동 재개합니다.
+ */
+export interface Checkpoint {
+    sessionId: string;
+    mode: string;
+    modifiedFiles: string[];
+    lastToolCall: string;
+    toolCallCount: number;
+    timestamp: string;
+    cwd: string;
+}
+/** 체크포인트 저장 */
+export declare function saveCheckpoint(data: Checkpoint): void;
+/** 체크포인트 로드 */
+export declare function loadCheckpoint(sessionId: string): Checkpoint | null;
+/** 오래된 체크포인트 삭제 */
+export declare function cleanStaleCheckpoints(maxAgeMs?: number): number;
+export declare function resolveSessionStartContext(rawInput: string): {
+    sessionId: string;
+    cwd: string;
+};

package/dist/hooks/session-recovery.js

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+/**
+ * Forgen — Session Recovery Hook
+ *
+ * Claude Code SessionStart 훅으로 등록.
+ * 이전 세션에서 활성화된 지속 모드(ralph, autopilot, ultrawork)의
+ * 상태를 복구하여 작업을 자동 재개합니다.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLogger } from '../core/logger.js';
+const log = createLogger('session-recovery');
+import { atomicWriteJSON } from './shared/atomic-write.js';
+import { sanitizeId } from './shared/sanitize-id.js';
+import { isHookEnabled } from './hook-config.js';
+import { approve, approveWithContext, failOpen } from './shared/hook-response.js';
+import { HANDOFFS_DIR, STATE_DIR } from '../core/paths.js';
+/** 체크포인트 저장 */
+export function saveCheckpoint(data) {
+    try {
+        const filePath = path.join(STATE_DIR, `checkpoint-${sanitizeId(data.sessionId)}.json`);
+        atomicWriteJSON(filePath, data);
+    }
+    catch (e) {
+        log.debug('체크포인트 저장 실패', e);
+    }
+}
+/** Checkpoint 구조 검증 */
+function isValidCheckpoint(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const d = data;
+    return (typeof d.sessionId === 'string' &&
+        typeof d.timestamp === 'string' &&
+        typeof d.mode === 'string' &&
+        typeof d.cwd === 'string' &&
+        Array.isArray(d.modifiedFiles) &&
+        typeof d.lastToolCall === 'string' &&
+        typeof d.toolCallCount === 'number');
+}
+/** ModeState 구조 검증 */
+function isValidModeState(data) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const d = data;
+    return typeof d.active === 'boolean' && typeof d.startedAt === 'string';
+}
+/** 체크포인트 로드 */
+export function loadCheckpoint(sessionId) {
+    try {
+        const filePath = path.join(STATE_DIR, `checkpoint-${sanitizeId(sessionId)}.json`);
+        if (fs.existsSync(filePath)) {
+            const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            if (!isValidCheckpoint(data)) {
+                log.debug('체크포인트 구조 검증 실패', { sessionId });
+                return null;
+            }
+            return data;
+        }
+    }
+    catch (e) {
+        log.debug('체크포인트 로드 실패', e);
+    }
+    return null;
+}
+/** 오래된 체크포인트 삭제 */
+export function cleanStaleCheckpoints(maxAgeMs = 24 * 60 * 60 * 1000) {
+    let cleaned = 0;
+    try {
+        if (!fs.existsSync(STATE_DIR))
+            return 0;
+        const files = fs.readdirSync(STATE_DIR).filter(f => f.startsWith('checkpoint-') && f.endsWith('.json'));
+        const now = Date.now();
+        for (const file of files) {
+            const filePath = path.join(STATE_DIR, file);
+            try {
+                const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+                if (!isValidCheckpoint(parsed)) {
+                    // 구조 검증 실패한 파일도 정리
+                    try {
+                        fs.unlinkSync(filePath);
+                        cleaned++;
+                    }
+                    catch (e) {
+                        log.debug(`invalid checkpoint unlink failed: ${filePath}`, e);
+                    }
+                    continue;
+                }
+                const age = now - new Date(parsed.timestamp).getTime();
+                if (age > maxAgeMs) {
+                    fs.unlinkSync(filePath);
+                    cleaned++;
+                }
+            }
+            catch {
+                // 파싱 실패한 파일도 정리
+                try {
+                    fs.unlinkSync(filePath);
+                    cleaned++;
+                }
+                catch (e) {
+                    log.debug(`corrupt checkpoint unlink failed: ${filePath}`, e);
+                }
+            }
+        }
+    }
+    catch (e) {
+        log.debug('스테일 체크포인트 정리 실패', e);
+    }
+    return cleaned;
+}
+const PERSISTENT_MODES = ['ralph', 'autopilot', 'ultrawork', 'team', 'pipeline'];
+export function resolveSessionStartContext(rawInput) {
+    const fallbackCwd = process.env.FORGEN_CWD ?? process.env.COMPOUND_CWD ?? process.cwd();
+    try {
+        const parsed = JSON.parse(rawInput);
+        return {
+            sessionId: parsed.session_id?.trim() || `session-${Date.now()}`,
+            cwd: parsed.cwd?.trim() || fallbackCwd,
+        };
+    }
+    catch {
+        return {
+            sessionId: `session-${Date.now()}`,
+            cwd: fallbackCwd,
+        };
+    }
+}
+async function main() {
+    // SessionStart 훅은 stdin으로 세션 정보를 받음 (타임아웃 포함)
+    const chunks = [];
+    process.stdin.setEncoding('utf-8');
+    await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            process.stdin.removeAllListeners('data');
+            process.stdin.removeAllListeners('end');
+            resolve();
+        }, 2000);
+        process.stdin.on('data', (chunk) => chunks.push(String(chunk)));
+        process.stdin.on('end', () => { clearTimeout(timeout); resolve(); });
+    });
+    const sessionContext = resolveSessionStartContext(chunks.join(''));
+    if (!isHookEnabled('session-recovery')) {
+        console.log(approve());
+        return;
+    }
+    if (!fs.existsSync(STATE_DIR)) {
+        console.log(approve());
+        return;
+    }
+    // 활성 모드 찾기
+    const recoveryMessages = [];
+    for (const mode of PERSISTENT_MODES) {
+        const statePath = path.join(STATE_DIR, `${mode}-state.json`);
+        if (!fs.existsSync(statePath))
+            continue;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+            if (!isValidModeState(parsed)) {
+                log.debug(`상태 파일 구조 검증 실패: ${mode}`);
+                continue;
+            }
+            const state = parsed;
+            if (!state.active)
+                continue;
+            // 24시간 이상 경과한 상태는 만료
+            const startedAt = new Date(state.startedAt).getTime();
+            const elapsed = Date.now() - startedAt;
+            if (elapsed > 24 * 60 * 60 * 1000) {
+                fs.unlinkSync(statePath);
+                continue;
+            }
+            const elapsedMinutes = Math.round(elapsed / 60000);
+            // Security: 상태 파일의 사용자 입력을 XML에 삽입하기 전 이스케이프
+            const escXml = (s) => s.replace(/[<>&"]/g, c => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;' })[c] ?? c);
+            recoveryMessages.push(`<compound-recovery mode="${mode}">` +
+                `\n${mode} mode from previous session has been recovered.` +
+                `\nStarted: ${state.startedAt} (${elapsedMinutes} minutes ago)` +
+                (state.prompt ? `\nOriginal request: ${escXml(state.prompt)}` : '') +
+                (state.stage ? `\nCurrent stage: ${escXml(state.stage)}` : '') +
+                (state.completedSteps?.length ? `\nCompleted steps: ${state.completedSteps.map((s) => escXml(s)).join(', ')}` : '') +
+                `\n\nContinue the previous work. To stop, type "cancelforgen".` +
+                `\n</compound-recovery>`);
+        }
+        catch (e) {
+            log.debug(`상태 파일 파싱 실패`, e);
+        }
+    }
+    // Phase 0: endTime이 없는 이전 세션 backfill (file mtime 기반)
+    // 최근 7일 파일만 대상 — 오래된 파일은 무시하여 성능 보장
+    try {
+        const { SESSIONS_DIR: sessDir } = await import('../core/paths.js');
+        if (fs.existsSync(sessDir)) {
+            const cutoff = Date.now() - 7 * 24 * 60 * 60 * 1000;
+            const sessionFiles = fs.readdirSync(sessDir)
+                .filter(f => f.endsWith('.json'))
+                .filter(f => {
+                try {
+                    return fs.statSync(path.join(sessDir, f)).mtimeMs > cutoff;
+                }
+                catch {
+                    return false;
+                }
+            });
+            for (const file of sessionFiles) {
+                const fp = path.join(sessDir, file);
+                try {
+                    const raw = JSON.parse(fs.readFileSync(fp, 'utf-8'));
+                    if (raw.startTime && !raw.endTime) {
+                        const mtime = fs.statSync(fp).mtime;
+                        raw.endTime = mtime.toISOString();
+                        raw.durationMs = mtime.getTime() - new Date(raw.startTime).getTime();
+                        raw.recoveredEndTime = true;
+                        atomicWriteJSON(fp, raw);
+                    }
+                }
+                catch { /* individual file recovery failure — skip and continue */ }
+            }
+        }
+    }
+    catch (e) {
+        log.debug('세션 endTime backfill 실패', e);
+    }
+    // 미완료 체크포인트 감지
+    try {
+        const checkpointFiles = fs.readdirSync(STATE_DIR)
+            .filter(f => f.startsWith('checkpoint-') && f.endsWith('.json'));
+        for (const file of checkpointFiles) {
+            try {
+                const parsedCp = JSON.parse(fs.readFileSync(path.join(STATE_DIR, file), 'utf-8'));
+                if (!isValidCheckpoint(parsedCp)) {
+                    log.debug(`체크포인트 파일 구조 검증 실패: ${file}`);
+                    continue;
+                }
+                const cp = parsedCp;
+                const age = Date.now() - new Date(cp.timestamp).getTime();
+                if (age > 24 * 60 * 60 * 1000) {
+                    fs.unlinkSync(path.join(STATE_DIR, file));
+                    continue;
+                }
+                const elapsedMin = Math.round(age / 60000);
+                const safeSessionId = String(cp.sessionId).replace(/[&"<>]/g, '_');
+                const safeLastTool = String(cp.lastToolCall ?? '').replace(/[<>]/g, '_');
+                const safeCwd = String(cp.cwd ?? '').replace(/[<>]/g, '_');
+                recoveryMessages.push(`<compound-checkpoint session="${safeSessionId}">` +
+                    `\nIncomplete checkpoint found (${elapsedMin} minutes ago)` +
+                    `\n- Modified files: ${cp.modifiedFiles.length}` +
+                    `\n- Tool calls: ${cp.toolCallCount}` +
+                    `\n- Last tool: ${safeLastTool}` +
+                    `\n- Working directory: ${safeCwd}` +
+                    `\n</compound-checkpoint>`);
+            }
+            catch { /* 개별 파일 파싱 실패 무시 */ }
+        }
+    }
+    catch (e) {
+        log.debug('체크포인트 스캔 실패', e);
+    }
+    // pending-compound 마커 확인 (이전 세션에서 compound loop 필요 표시)
+    const pendingPath = path.join(STATE_DIR, 'pending-compound.json');
+    if (fs.existsSync(pendingPath)) {
+        try {
+            const pending = JSON.parse(fs.readFileSync(pendingPath, 'utf-8'));
+            recoveryMessages.push(`<compound-pending>` +
+                `\nCompound loop was scheduled in the previous session (${pending.promptCount ?? '?'} prompts).` +
+                `\nRun \`forgen compound\` to preview, then \`forgen compound --save\` to persist patterns/solutions.` +
+                `\n</compound-pending>`);
+            // 마커 삭제 (한 번만 안내)
+            fs.unlinkSync(pendingPath);
+        }
+        catch (e) {
+            log.debug('pending-compound 마커 읽기 실패', e);
+        }
+    }
+    // 핸드오프 파일 확인
+    const handoffDir = HANDOFFS_DIR;
+    if (fs.existsSync(handoffDir)) {
+        try {
+            const handoffs = fs.readdirSync(handoffDir)
+                .filter(f => f.endsWith('.md'))
+                .sort();
+            if (handoffs.length > 0) {
+                const latest = handoffs[handoffs.length - 1];
+                const latestPath = path.join(handoffDir, latest);
+                // Security: symlink 방지 + XML 이스케이프
+                if (fs.lstatSync(latestPath).isSymbolicLink())
+                    throw new Error('symlink rejected');
+                const raw = fs.readFileSync(latestPath, 'utf-8');
+                const safeName = latest.replace(/[&"<>]/g, '_');
+                const escaped = raw.replace(/<\/?[a-zA-Z][\w-]*(?:\s[^>]*)?\/?>/g, m => m.replace(/</g, '&lt;').replace(/>/g, '&gt;'));
+                recoveryMessages.push(`<compound-handoff file="${safeName}">\n${escaped}\n</compound-handoff>`);
+                // 마커 삭제 (한 번만 안내 — pending-compound.json과 동일 패턴)
+                try {
+                    fs.unlinkSync(latestPath);
+                }
+                catch (e) {
+                    log.debug('handoff 파일 삭제 실패', e);
+                }
+            }
+        }
+        catch (e) {
+            log.debug('handoff 파일 읽기 실패', e);
+        }
+    }
+    const sessionId = sessionContext.sessionId;
+    // 이전 세션 자동 compound (fire-and-forget)
+    // /new로 세션 리셋 시 SessionStart가 다시 호출됨 — 이때 이전 transcript를 compound
+    try {
+        const cwd = sessionContext.cwd;
+        const sanitized = cwd.replace(/\//g, '-');
+        const projectDir = path.join(os.homedir(), '.claude', 'projects', sanitized);
+        if (fs.existsSync(projectDir)) {
+            const transcripts = fs.readdirSync(projectDir)
+                .filter(f => f.endsWith('.jsonl') && f !== `${sessionId}.jsonl`) // 현재 세션 제외
+                .map(f => ({ name: f, mtime: fs.statSync(path.join(projectDir, f)).mtimeMs }))
+                .sort((a, b) => b.mtime - a.mtime);
+            if (transcripts.length > 0) {
+                const prevTranscript = path.join(projectDir, transcripts[0].name);
+                const lastCompoundPath = path.join(STATE_DIR, 'last-auto-compound.json');
+                let lastCompoundedSession = '';
+                try {
+                    lastCompoundedSession = JSON.parse(fs.readFileSync(lastCompoundPath, 'utf-8')).sessionId ?? '';
+                }
+                catch { /* first time */ }
+                const prevSessionId = transcripts[0].name.replace('.jsonl', '');
+                if (prevSessionId !== lastCompoundedSession) {
+                    // 이전 세션이 compound 안 된 상태 — 메시지 수 확인
+                    // W-D2: 대용량 transcript 보호 — 앞 200KB만 읽어 메시지 수 추정
+                    const fd = fs.openSync(prevTranscript, 'r');
+                    const buf = Buffer.alloc(200 * 1024);
+                    const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
+                    fs.closeSync(fd);
+                    const content = buf.toString('utf-8', 0, bytesRead);
+                    const userMsgCount = content.split('\n')
+                        .filter(l => { try {
+                        const t = JSON.parse(l).type;
+                        return t === 'user' || t === 'queue-operation';
+                    }
+                    catch {
+                        return false;
+                    } })
+                        .length;
+                    if (userMsgCount >= 10) {
+                        // background로 auto-compound 실행 (hook timeout과 무관)
+                        const { spawn: spawnProcess } = await import('node:child_process');
+                        const autoCompound = spawnProcess('node', [
+                            path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'core', 'auto-compound-runner.js'),
+                            cwd, prevTranscript, prevSessionId,
+                        ], { detached: true, stdio: 'ignore' });
+                        autoCompound.unref();
+                        log.debug(`이전 세션 auto-compound 시작: ${prevSessionId} (${userMsgCount} messages)`);
+                    }
+                }
+            }
+        }
+    }
+    catch (e) {
+        log.debug('이전 세션 auto-compound 체크 실패', e);
+    }
+    // v1: regex 기반 패턴 학습(prompt-learner) 제거. Evidence 기반으로 전환됨.
+    // Compound v3: Run lifecycle check once per day
+    try {
+        const lifecycleModulePath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'engine', 'compound-lifecycle.js');
+        const lastLifecyclePath = path.join(STATE_DIR, 'last-lifecycle.json');
+        let shouldRun = true;
+        try {
+            if (fs.existsSync(lastLifecyclePath)) {
+                const data = JSON.parse(fs.readFileSync(lastLifecyclePath, 'utf-8'));
+                const last = new Date(data.lastRun).getTime();
+                shouldRun = Date.now() - last > 24 * 60 * 60 * 1000;
+            }
+        }
+        catch { /* last-lifecycle.json parse failure — run lifecycle check anyway */ }
+        if (shouldRun) {
+            // B-4: detached background spawn으로 분리 — hook timeout 초과 방지
+            const { spawn: spawnLifecycle } = await import('node:child_process');
+            const lifecycleRunner = spawnLifecycle('node', [
+                '--input-type=module',
+                '-e',
+                `import('${lifecycleModulePath.replace(/\\/g, '/')}').then(m => m.runLifecycleCheck('${sessionId}'))`,
+            ], { detached: true, stdio: 'ignore' });
+            lifecycleRunner.unref();
+            const { atomicWriteJSON: writeJSON } = await import('./shared/atomic-write.js');
+            writeJSON(lastLifecyclePath, { lastRun: new Date().toISOString() });
+        }
+    }
+    catch (e) {
+        log.debug('lifecycle check 실패', e);
+    }
+    if (recoveryMessages.length > 0) {
+        console.log(approveWithContext(recoveryMessages.join('\n\n'), 'SessionStart'));
+    }
+    else {
+        console.log(approve());
+    }
+}
+// ESM main guard: 다른 모듈에서 import 시 main() 실행 방지
+// realpathSync로 symlink 해석 (플러그인 캐시가 symlink일 때 경로 불일치 방지)
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
+    main().catch((e) => {
+        process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
+        console.log(failOpen());
+    });
+}

package/dist/hooks/shared/atomic-write.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 훅 공유 유틸: 원자적 파일 쓰기
+ *
+ * write → rename 패턴으로 동시 세션에서의 상태 파일 손상을 방지합니다.
+ *
+ * 보안 모델:
+ *   - mode 옵션이 0o600인 파일은 같은 호스트의 다른 user로부터 보호.
+ *   - tmp 파일은 PID + randomBytes(6) suffix → 같은 process가 동시 atomic write를
+ *     하더라도 tmp 충돌 없음. symlink TOCTOU도 방지.
+ *
+ * Windows 한계:
+ *   - fchmodSync/chmodSync는 Windows에서 read-only 비트만 영향. 0o600 같은
+ *     POSIX 권한은 의미가 없으며, 보안은 OS-level ACL과 사용자 home 격리에 의존.
+ *   - 민감 데이터는 Windows에서 추가 보호가 필요할 수 있다.
+ */
+/**
+ * JSON 데이터를 원자적으로 파일에 기록 (tmp → rename)
+ *
+ * @param options.pretty 들여쓴 포맷으로 직렬화
+ * @param options.mode   생성될 파일의 권한 (예: 0o600). 기본값은 umask 의존(보통 0o644).
+ *                       민감한 캐시(컨텍스트 식별자/태그 포함)에 대해서는 0o600 권장.
+ * @param options.dirMode 부모 디렉터리 mode. cache는 0o700 권장.
+ *
+ * 권한 보장 (M6+M16+M17 fix):
+ *   1. tmp 파일이 random suffix → 다른 fd 충돌 없음 (Promise.all 안전).
+ *   2. fd 단위 fchmodSync로 새 inode 권한 강제.
+ *   3. post-rename chmodSync 실패는 throw — 느슨한 권한 침묵 방지.
+ *   4. Windows에서는 위 mode가 무효일 수 있으나, OS-level ACL이 일반적으로 user 격리.
+ */
+export declare function atomicWriteJSON(filePath: string, data: unknown, options?: {
+    pretty?: boolean;
+    mode?: number;
+    dirMode?: number;
+}): void;
+/** 텍스트를 원자적으로 파일에 기록 (tmp → rename) */
+export declare function atomicWriteText(filePath: string, content: string, options?: {
+    mode?: number;
+    dirMode?: number;
+}): void;
+/** JSON 파일을 안전하게 읽기 (파싱 실패 시 fallback 반환) */
+export declare function safeReadJSON<T>(filePath: string, fallback: T): T;