@wooojin/forgen 0.3.0 → 0.3.2

package/dist/core/paths.d.ts

@@ -1,23 +1,7 @@
 /** ~/.claude/ — Claude Code 설정 디렉토리 */
 export declare const CLAUDE_DIR: string;
-export declare const CODEX_DIR: string;
 /** ~/.claude/settings.json — Claude Code 설정 파일 */
 export declare const SETTINGS_PATH: string;
-/**
- * ~/.compound/ — LEGACY harness home (pre-v5).
- *
- * @deprecated A5 (2026-04-09): this path must NEVER be used for WRITES.
- * It exists solely as the source path for `migrateToForgen()`.
- * All new writes must target `FORGEN_HOME`-based paths. Consumers that
- * read from this path should prefer the FORGEN_HOME equivalent first
- * and fall back here only during migration.
- *
- * Pre-A5, `harness.ts:ensureDirectories` and several hooks actively
- * created directories under this path, causing a dual-reality where
- * state could diverge between `~/.compound/` and `~/.forgen/` when the
- * migration symlink was broken (sudo install, SIP, CI, manual delete).
- */
-export declare const COMPOUND_HOME: string;
 /** ~/.forgen/ — v1 하네스 홈 디렉토리 */
 export declare const FORGEN_HOME: string;
 /** ~/.forgen/me/ — 개인 공간 (v5.1: ~/.compound/ → ~/.forgen/ 통합) */
@@ -44,40 +28,47 @@ export declare const STATE_DIR: string;
  * `src/engine/match-eval-log.ts`; never on the hook critical path.
  */
 export declare const MATCH_EVAL_LOG_PATH: string;
+/**
+ * ~/.forgen/state/solution-quarantine.jsonl — JSONL log of solution files
+ * dropped during index build due to malformed frontmatter. Append-only,
+ * dedupe-by-path. Used by `forgen doctor` to surface dead solutions that
+ * would otherwise vanish silently (see `diagnoseFrontmatter`).
+ */
+export declare const SOLUTION_QUARANTINE_PATH: string;
+/**
+ * ~/.forgen/state/outcomes/ — per-session JSONL logs of solution inject →
+ * outcome events (accept / correct / error / unknown). Written by the
+ * solution-outcome-tracker hook. One file per session for write-safety
+ * under concurrent sessions. Consumers aggregate across files to compute
+ * fitness (see `solution-fitness.ts`).
+ */
+export declare const OUTCOMES_DIR: string;
+/**
+ * ~/.forgen/lab/candidates/ — Phase 4 quarantine zone for evolver-agent
+ * proposals before they enter the live solution index. The evolver writes
+ * here; promotion and rollback commands move files out (to ME_SOLUTIONS
+ * or to `lab/archived-{ts}/`). Keeping candidates isolated means a
+ * runaway agent cannot silently poison the match pool.
+ */
+export declare const CANDIDATES_DIR: string;
+/** ~/.forgen/lab/archived/ — rollback destination for evolved solutions. */
+export declare const ARCHIVED_DIR: string;
 /** ~/.forgen/sessions/ — 세션 로그 */
 export declare const SESSIONS_DIR: string;
 /** ~/.forgen/config.json — 글로벌 설정 */
 export declare const GLOBAL_CONFIG: string;
-/** ~/.forgen/state/session-quality/ — 세션 품질 점수 */
-export declare const SESSION_QUALITY_DIR: string;
 /** ~/.forgen/state/meta-learning/ — 메타학습 상태 파일 */
 export declare const META_LEARNING_DIR: string;
 /** ~/.forgen/lab/ — Lab 적응형 최적화 엔진 데이터 */
 export declare const LAB_DIR: string;
-/** ~/.forgen/lab/events.jsonl — Lab 이벤트 로그 (JSONL) */
-export declare const LAB_EVENTS: string;
 /** ~/.forgen/me/forge-profile.json — 글로벌 Forge 프로필 */
 export declare const FORGE_PROFILE: string;
-/** @deprecated use ME_DIR */
-export declare const V1_ME_DIR: string;
-/** @deprecated use FORGE_PROFILE */
-export declare const V1_PROFILE: string;
-/** @deprecated use ME_RULES */
-export declare const V1_RULES_DIR: string;
-/** @deprecated use ME_BEHAVIOR */
-export declare const V1_EVIDENCE_DIR: string;
 /** ~/.forgen/me/recommendations/ — Pack Recommendation */
 export declare const V1_RECOMMENDATIONS_DIR: string;
-/** @deprecated use ME_SOLUTIONS */
-export declare const V1_SOLUTIONS_DIR: string;
-/** @deprecated use STATE_DIR */
-export declare const V1_STATE_DIR: string;
 /** ~/.forgen/state/sessions/ — Session Effective State */
 export declare const V1_SESSIONS_DIR: string;
 /** ~/.forgen/state/raw-logs/ — Raw Log */
 export declare const V1_RAW_LOGS_DIR: string;
-/** @deprecated use GLOBAL_CONFIG */
-export declare const V1_GLOBAL_CONFIG: string;
 /** 모든 실행 모드 이름 (cancel/recovery 시 사용) */
 export declare const ALL_MODES: readonly ["ralph", "autopilot", "ultrawork", "team", "pipeline", "ccg", "ralplan", "deep-interview", "forge-loop", "ship", "retro", "learn", "calibrate"];
 /** {repo}/.compound/ — 프로젝트 로컬 디렉토리 */

package/dist/core/paths.js

@@ -3,24 +3,8 @@ import * as path from 'node:path';
 const HOME = os.homedir();
 /** ~/.claude/ — Claude Code 설정 디렉토리 */
 export const CLAUDE_DIR = path.join(HOME, '.claude');
-export const CODEX_DIR = path.join(HOME, '.codex');
 /** ~/.claude/settings.json — Claude Code 설정 파일 */
 export const SETTINGS_PATH = path.join(CLAUDE_DIR, 'settings.json');
-/**
- * ~/.compound/ — LEGACY harness home (pre-v5).
- *
- * @deprecated A5 (2026-04-09): this path must NEVER be used for WRITES.
- * It exists solely as the source path for `migrateToForgen()`.
- * All new writes must target `FORGEN_HOME`-based paths. Consumers that
- * read from this path should prefer the FORGEN_HOME equivalent first
- * and fall back here only during migration.
- *
- * Pre-A5, `harness.ts:ensureDirectories` and several hooks actively
- * created directories under this path, causing a dual-reality where
- * state could diverge between `~/.compound/` and `~/.forgen/` when the
- * migration symlink was broken (sudo install, SIP, CI, manual delete).
- */
-export const COMPOUND_HOME = path.join(HOME, '.compound');
 /** ~/.forgen/ — v1 하네스 홈 디렉토리 */
 export const FORGEN_HOME = path.join(HOME, '.forgen');
 /** ~/.forgen/me/ — 개인 공간 (v5.1: ~/.compound/ → ~/.forgen/ 통합) */
@@ -47,41 +31,47 @@ export const STATE_DIR = path.join(FORGEN_HOME, 'state');
  * `src/engine/match-eval-log.ts`; never on the hook critical path.
  */
 export const MATCH_EVAL_LOG_PATH = path.join(STATE_DIR, 'match-eval-log.jsonl');
+/**
+ * ~/.forgen/state/solution-quarantine.jsonl — JSONL log of solution files
+ * dropped during index build due to malformed frontmatter. Append-only,
+ * dedupe-by-path. Used by `forgen doctor` to surface dead solutions that
+ * would otherwise vanish silently (see `diagnoseFrontmatter`).
+ */
+export const SOLUTION_QUARANTINE_PATH = path.join(STATE_DIR, 'solution-quarantine.jsonl');
+/**
+ * ~/.forgen/state/outcomes/ — per-session JSONL logs of solution inject →
+ * outcome events (accept / correct / error / unknown). Written by the
+ * solution-outcome-tracker hook. One file per session for write-safety
+ * under concurrent sessions. Consumers aggregate across files to compute
+ * fitness (see `solution-fitness.ts`).
+ */
+export const OUTCOMES_DIR = path.join(STATE_DIR, 'outcomes');
+/**
+ * ~/.forgen/lab/candidates/ — Phase 4 quarantine zone for evolver-agent
+ * proposals before they enter the live solution index. The evolver writes
+ * here; promotion and rollback commands move files out (to ME_SOLUTIONS
+ * or to `lab/archived-{ts}/`). Keeping candidates isolated means a
+ * runaway agent cannot silently poison the match pool.
+ */
+export const CANDIDATES_DIR = path.join(FORGEN_HOME, 'lab', 'candidates');
+/** ~/.forgen/lab/archived/ — rollback destination for evolved solutions. */
+export const ARCHIVED_DIR = path.join(FORGEN_HOME, 'lab', 'archived');
 /** ~/.forgen/sessions/ — 세션 로그 */
 export const SESSIONS_DIR = path.join(FORGEN_HOME, 'sessions');
 /** ~/.forgen/config.json — 글로벌 설정 */
 export const GLOBAL_CONFIG = path.join(FORGEN_HOME, 'config.json');
-/** ~/.forgen/state/session-quality/ — 세션 품질 점수 */
-export const SESSION_QUALITY_DIR = path.join(STATE_DIR, 'session-quality');
 /** ~/.forgen/state/meta-learning/ — 메타학습 상태 파일 */
 export const META_LEARNING_DIR = path.join(STATE_DIR, 'meta-learning');
 /** ~/.forgen/lab/ — Lab 적응형 최적화 엔진 데이터 */
 export const LAB_DIR = path.join(FORGEN_HOME, 'lab');
-/** ~/.forgen/lab/events.jsonl — Lab 이벤트 로그 (JSONL) */
-export const LAB_EVENTS = path.join(LAB_DIR, 'events.jsonl');
 /** ~/.forgen/me/forge-profile.json — 글로벌 Forge 프로필 */
 export const FORGE_PROFILE = path.join(ME_DIR, 'forge-profile.json');
-// ── v1 호환 경로 (ME_*와 동일 — 점진 제거 예정) ──
-/** @deprecated use ME_DIR */
-export const V1_ME_DIR = ME_DIR;
-/** @deprecated use FORGE_PROFILE */
-export const V1_PROFILE = FORGE_PROFILE;
-/** @deprecated use ME_RULES */
-export const V1_RULES_DIR = ME_RULES;
-/** @deprecated use ME_BEHAVIOR */
-export const V1_EVIDENCE_DIR = ME_BEHAVIOR;
 /** ~/.forgen/me/recommendations/ — Pack Recommendation */
 export const V1_RECOMMENDATIONS_DIR = path.join(ME_DIR, 'recommendations');
-/** @deprecated use ME_SOLUTIONS */
-export const V1_SOLUTIONS_DIR = ME_SOLUTIONS;
-/** @deprecated use STATE_DIR */
-export const V1_STATE_DIR = STATE_DIR;
 /** ~/.forgen/state/sessions/ — Session Effective State */
 export const V1_SESSIONS_DIR = path.join(STATE_DIR, 'sessions');
 /** ~/.forgen/state/raw-logs/ — Raw Log */
 export const V1_RAW_LOGS_DIR = path.join(STATE_DIR, 'raw-logs');
-/** @deprecated use GLOBAL_CONFIG */
-export const V1_GLOBAL_CONFIG = GLOBAL_CONFIG;
 // ── 레거시 ──
 /** 모든 실행 모드 이름 (cancel/recovery 시 사용) */
 export const ALL_MODES = [

package/dist/core/settings-injector.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Settings Injection — Claude Code settings.json manipulation
+ *
+ * Extracted from harness.ts (B9 decomposition).
+ * Handles reading, merging hooks, trust policy, and atomic write.
+ */
+import type { RuntimeHost } from './types.js';
+import type { V1BootstrapResult } from './v1-bootstrap.js';
+/**
+ * Inject forgen settings into Claude Code settings.json.
+ * Coordinates: read/backup → env merge → statusLine → hooks → trust policy → atomic write.
+ */
+export declare function injectSettings(env: Record<string, string>, v1Result: V1BootstrapResult, runtime: RuntimeHost, cwd: string, pkgRoot: string): void;

package/dist/core/settings-injector.js

@@ -0,0 +1,167 @@
+/**
+ * Settings Injection — Claude Code settings.json manipulation
+ *
+ * Extracted from harness.ts (B9 decomposition).
+ * Handles reading, merging hooks, trust policy, and atomic write.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { generateHooksJson } from '../hooks/hooks-generator.js';
+import { ConfigError } from './errors.js';
+import { createLogger } from './logger.js';
+import { acquireLock, atomicWriteFileSync, CLAUDE_DIR, readSettingsSafely, releaseLock, rollbackSettings, SETTINGS_BACKUP_PATH, SETTINGS_PATH, } from './settings-lock.js';
+const log = createLogger('settings-injector');
+const FORGEN_PERMISSION_RULES = new Set([
+    '# forgen-managed',
+    'Bash(rm -rf *)',
+    'Bash(git push --force*)',
+    'Bash(git reset --hard*)',
+]);
+function stripForgenManagedRules(rules) {
+    return rules.filter((r) => !FORGEN_PERMISSION_RULES.has(r));
+}
+/**
+ * Read settings.json + create forgen-backup of the valid content.
+ *
+ * Parse-failure handling moved to `readSettingsSafely` in settings-lock.ts
+ * (2026-04-21 audit fix #2): prior silent `{}` fallback would let the
+ * caller write merged forgen settings over the user's malformed-but-
+ * original file, losing their data. We now preserve the corrupt file to
+ * `.corrupt-<ts>` and propagate the error — `injectSettings` releases
+ * the lock and the harness bails out of writing.
+ */
+function readSettingsWithBackup() {
+    const settings = readSettingsSafely();
+    if (Object.keys(settings).length > 0 && fs.existsSync(SETTINGS_PATH)) {
+        try {
+            fs.copyFileSync(SETTINGS_PATH, SETTINGS_BACKUP_PATH);
+        }
+        catch (e) {
+            log.debug('settings.json backup 복사 실패 (쓰기는 계속 진행)', new ConfigError('settings.json backup failed', { configPath: SETTINGS_PATH, cause: e }));
+        }
+    }
+    return settings;
+}
+/** Apply forgen statusLine only if user hasn't set a custom one. */
+function applyStatusLine(settings) {
+    const existing = settings.statusLine;
+    const isForgenOwned = !existing || !existing.command || existing.command.startsWith('forgen');
+    if (isForgenOwned) {
+        settings.statusLine = { type: 'command', command: 'forgen me' };
+    }
+}
+/** Check if a settings.json hook entry was installed by forgen. */
+function isForgenHookEntry(entry, pkgRoot) {
+    const distHooksPath = path.join(pkgRoot, 'dist', 'hooks');
+    const matchesPath = (cmd) => cmd.includes(distHooksPath) || /[\\/]dist[\\/]hooks[\\/].*\.js/.test(cmd);
+    if (typeof entry.command === 'string' && matchesPath(entry.command))
+        return true;
+    const hooks = entry.hooks;
+    return (Array.isArray(hooks) &&
+        hooks.some((h) => typeof h.command === 'string' && matchesPath(h.command)));
+}
+/** Strip existing forgen hooks from settings, merge fresh hooks.json. */
+function mergeHooksIntoSettings(settings, runtime, cwd, pkgRoot) {
+    const hooksConfig = settings.hooks ?? {};
+    // Remove existing forgen hooks (clean slate before re-inject)
+    for (const [event, entries] of Object.entries(hooksConfig)) {
+        if (!Array.isArray(entries))
+            continue;
+        const filtered = entries.filter((h) => !isForgenHookEntry(h, pkgRoot));
+        if (filtered.length === 0)
+            delete hooksConfig[event];
+        else
+            hooksConfig[event] = filtered;
+    }
+    try {
+        if (runtime === 'codex') {
+            const generated = generateHooksJson({ cwd, runtime, pluginRoot: path.join(pkgRoot, 'dist') });
+            for (const [event, handlers] of Object.entries(generated.hooks)) {
+                if (!hooksConfig[event])
+                    hooksConfig[event] = [];
+                hooksConfig[event].push(...handlers);
+            }
+        }
+        else {
+            // Read hooks.json and inject, replacing ${CLAUDE_PLUGIN_ROOT}
+            const hooksJsonPath = path.join(pkgRoot, 'hooks', 'hooks.json');
+            if (fs.existsSync(hooksJsonPath)) {
+                const hooksJson = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf-8'));
+                const hooksData = hooksJson.hooks;
+                if (hooksData) {
+                    const resolved = JSON.parse(JSON.stringify(hooksData).replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pkgRoot));
+                    for (const [event, handlers] of Object.entries(resolved)) {
+                        if (!hooksConfig[event])
+                            hooksConfig[event] = [];
+                        hooksConfig[event].push(...handlers);
+                    }
+                }
+            }
+        }
+    }
+    catch (e) {
+        log.debug('hooks.json 로드 실패', e);
+    }
+    settings.hooks = Object.keys(hooksConfig).length > 0 ? hooksConfig : undefined;
+    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+    }
+}
+/** Apply v1 trust policy → permissions (deny/ask lists). */
+function applyTrustPolicyPermissions(settings, v1Result) {
+    if (!v1Result.session)
+        return;
+    const trust = v1Result.session.effective_trust_policy;
+    const permissions = settings.permissions ?? {};
+    const existingDeny = stripForgenManagedRules(permissions.deny ?? []);
+    if (trust === '가드레일 우선') {
+        permissions.deny = [
+            ...existingDeny,
+            '# forgen-managed',
+            'Bash(rm -rf *)',
+            'Bash(git push --force*)',
+            'Bash(git reset --hard*)',
+        ];
+    }
+    else if (trust === '승인 완화') {
+        const existingAsk = stripForgenManagedRules(permissions.ask ?? []);
+        permissions.ask = [
+            ...existingAsk,
+            '# forgen-managed',
+            'Bash(rm -rf *)',
+            'Bash(git push --force*)',
+        ];
+        permissions.deny = existingDeny.length > 0 ? existingDeny : undefined;
+    }
+    // '완전 신뢰 실행': 추가 제한 없음
+    if (!permissions.deny?.length)
+        delete permissions.deny;
+    if (!permissions.ask?.length)
+        delete permissions.ask;
+    if (Object.keys(permissions).length > 0)
+        settings.permissions = permissions;
+}
+/**
+ * Inject forgen settings into Claude Code settings.json.
+ * Coordinates: read/backup → env merge → statusLine → hooks → trust policy → atomic write.
+ */
+export function injectSettings(env, v1Result, runtime, cwd, pkgRoot) {
+    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+    acquireLock();
+    const settings = readSettingsWithBackup();
+    // Merge env vars
+    settings.env = { ...(settings.env ?? {}), ...env };
+    applyStatusLine(settings);
+    mergeHooksIntoSettings(settings, runtime, cwd, pkgRoot);
+    applyTrustPolicyPermissions(settings, v1Result);
+    try {
+        atomicWriteFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+    }
+    catch (err) {
+        rollbackSettings();
+        throw err;
+    }
+    finally {
+        releaseLock();
+    }
+}

package/dist/core/settings-lock.d.ts

@@ -1,9 +1,30 @@
 import { CLAUDE_DIR, SETTINGS_PATH } from './paths.js';
 export { CLAUDE_DIR, SETTINGS_PATH };
 export declare const SETTINGS_BACKUP_PATH: string;
-/** lockfile 획득 (최대 3초 대기, 100ms 간격 재시도) */
+/** settings.json 쓰기 경로가 락으로 보호받지 못할 때 던지는 오류. */
+export declare class SettingsLockError extends Error {
+    constructor(message: string);
+}
+/**
+ * lockfile 획득 (최대 3초 대기, 100ms 간격 재시도).
+ *
+ * Audit fix #1 (2026-04-21): 이전 구현은 타임아웃 후 기존 holder가
+ * **살아있어도** 무조건 `writeFileSync`로 PID를 덮어써 동시 쓰기를 유발했다.
+ * 주석은 "보류"라고 되어있었지만 코드는 그렇지 않았다. 이제:
+ *   - holder가 살아있으면 `SettingsLockError`를 throw (쓰기 중단)
+ *   - holder가 죽었을 때만 stale recovery로 강제 획득
+ * 호출자는 락 실패 시 사용자 작업을 망치지 않도록 merge 결과를 버릴 책임을 진다.
+ */
 export declare function acquireLock(): void;
-/** lockfile 해제 */
+/**
+ * lockfile 해제.
+ *
+ * Audit fix #1 (2026-04-21): 이전에는 ownership 확인 없이 `rmSync`로
+ * 다른 프로세스의 lock도 지울 수 있었다 (cascade lock loss). 이제 lock
+ * 파일의 PID가 내 PID와 일치할 때만 삭제한다. 불일치 시 조용히 no-op —
+ * 정상 케이스에서는 내 PID만 존재하므로 영향 없음, 비정상 경합 시에는
+ * 다른 프로세스의 lock을 존중한다.
+ */
 export declare function releaseLock(): void;
 /** 임시파일에 쓴 후 rename으로 원자적 교체 */
 export declare function atomicWriteFileSync(targetPath: string, data: string): void;
@@ -12,6 +33,18 @@ export declare function atomicWriteFileSync(targetPath: string, data: string): v
  * 파일이 없으면 빈 객체 반환. 파싱 실패 시 Error throw (빈 설정 덮어쓰기 방지).
  */
 export declare function readSettings(): Record<string, unknown>;
+/**
+ * settings.json 안전 읽기 + 손상본 보존.
+ *
+ * 2026-04-21 audit (finding #2, #10): `readSettingsWithBackup`가 parse
+ * 실패 시 silent `{}` 반환했고, 이후 merged write가 사용자 원본을 덮어써서
+ * 데이터 손실 경로가 됐다. 이제 파싱 실패 시 원본을 `.corrupt-<ts>` 로
+ * 별도 보존 후 예외를 던진다 — 호출자가 덮어쓰기를 중단할 수 있도록.
+ *
+ * Fallthrough: 파일 없음 → `{}`. IO 실패 → throw. Parse 실패 → 손상본
+ * 보존 후 throw.
+ */
+export declare function readSettingsSafely(): Record<string, unknown>;
 /** settings.json 안전 쓰기. backup 생성 + lock + atomic write */
 export declare function writeSettings(settings: Record<string, unknown>): void;
 /** settings.json.forgen-backup 파일에서 원본 복원 */

package/dist/core/settings-lock.js

@@ -33,7 +33,23 @@ function isProcessAlive(pid) {
         return false;
     }
 }
-/** lockfile 획득 (최대 3초 대기, 100ms 간격 재시도) */
+/** settings.json 쓰기 경로가 락으로 보호받지 못할 때 던지는 오류. */
+export class SettingsLockError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SettingsLockError';
+    }
+}
+/**
+ * lockfile 획득 (최대 3초 대기, 100ms 간격 재시도).
+ *
+ * Audit fix #1 (2026-04-21): 이전 구현은 타임아웃 후 기존 holder가
+ * **살아있어도** 무조건 `writeFileSync`로 PID를 덮어써 동시 쓰기를 유발했다.
+ * 주석은 "보류"라고 되어있었지만 코드는 그렇지 않았다. 이제:
+ *   - holder가 살아있으면 `SettingsLockError`를 throw (쓰기 중단)
+ *   - holder가 죽었을 때만 stale recovery로 강제 획득
+ * 호출자는 락 실패 시 사용자 작업을 망치지 않도록 merge 결과를 버릴 책임을 진다.
+ */
 export function acquireLock() {
     const maxWaitMs = 3000;
     const intervalMs = 100;
@@ -54,17 +70,28 @@ export function acquireLock() {
     // 타임아웃: lock을 잡고 있는 프로세스가 살아있는지 확인
     const lockPid = readLockPid();
     if (lockPid !== null && isProcessAlive(lockPid)) {
-        log.debug(`lockfile 타임아웃 — pid ${lockPid} 프로세스가 아직 활성 상태, 대기 중 강제 획득 보류`);
-        // 프로세스가 살아있으면 그래도 강제 획득 (데드락 방지)
-    }
-    else {
-        log.debug(`lockfile 타임아웃 — stale lock 감지 (pid: ${lockPid ?? 'unknown'}, 프로세스 종료됨)`);
+        log.warn(`lockfile 타임아웃 — pid ${lockPid} 프로세스가 활성 상태, 쓰기 중단`);
+        throw new SettingsLockError(`Could not acquire settings.json lock: another forgen process (pid ${lockPid}) is actively writing`);
     }
+    log.debug(`lockfile stale lock 감지 — pid ${lockPid ?? 'unknown'} 종료됨, 회수`);
     fs.writeFileSync(SETTINGS_LOCK_PATH, String(process.pid));
 }
-/** lockfile 해제 */
+/**
+ * lockfile 해제.
+ *
+ * Audit fix #1 (2026-04-21): 이전에는 ownership 확인 없이 `rmSync`로
+ * 다른 프로세스의 lock도 지울 수 있었다 (cascade lock loss). 이제 lock
+ * 파일의 PID가 내 PID와 일치할 때만 삭제한다. 불일치 시 조용히 no-op —
+ * 정상 케이스에서는 내 PID만 존재하므로 영향 없음, 비정상 경합 시에는
+ * 다른 프로세스의 lock을 존중한다.
+ */
 export function releaseLock() {
     try {
+        const ownerPid = readLockPid();
+        if (ownerPid !== null && ownerPid !== process.pid) {
+            log.debug(`releaseLock: pid ${ownerPid} owns the lock, not me (${process.pid}) — no-op`);
+            return;
+        }
         fs.rmSync(SETTINGS_LOCK_PATH, { force: true });
     }
     catch { /* 이미 없으면 무시 */ }
@@ -86,6 +113,37 @@ export function readSettings() {
     const raw = fs.readFileSync(SETTINGS_PATH, 'utf-8');
     return JSON.parse(raw); // 파싱 실패 시 throw → 호출자가 처리
 }
+/**
+ * settings.json 안전 읽기 + 손상본 보존.
+ *
+ * 2026-04-21 audit (finding #2, #10): `readSettingsWithBackup`가 parse
+ * 실패 시 silent `{}` 반환했고, 이후 merged write가 사용자 원본을 덮어써서
+ * 데이터 손실 경로가 됐다. 이제 파싱 실패 시 원본을 `.corrupt-<ts>` 로
+ * 별도 보존 후 예외를 던진다 — 호출자가 덮어쓰기를 중단할 수 있도록.
+ *
+ * Fallthrough: 파일 없음 → `{}`. IO 실패 → throw. Parse 실패 → 손상본
+ * 보존 후 throw.
+ */
+export function readSettingsSafely() {
+    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+    if (!fs.existsSync(SETTINGS_PATH))
+        return {};
+    const raw = fs.readFileSync(SETTINGS_PATH, 'utf-8');
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        const corruptPath = `${SETTINGS_PATH}.corrupt-${Date.now()}`;
+        try {
+            fs.copyFileSync(SETTINGS_PATH, corruptPath);
+            log.warn(`settings.json parse 실패 — 손상본을 ${corruptPath}로 보존 후 쓰기 중단`);
+        }
+        catch (copyErr) {
+            log.warn(`settings.json parse 실패 + 손상본 보존 실패 — 쓰기 중단`, copyErr);
+        }
+        throw e instanceof Error ? e : new Error(String(e));
+    }
+}
 /** settings.json 안전 쓰기. backup 생성 + lock + atomic write */
 export function writeSettings(settings) {
     fs.mkdirSync(CLAUDE_DIR, { recursive: true });