@wooojin/forgen 0.3.0 → 0.3.2

package/dist/core/spawn.js

@@ -15,21 +15,96 @@ function findClaude() {
 function findRuntimeLauncher(runtime) {
     return runtime === 'codex' ? 'codex' : findClaude();
 }
-/**
- * 가장 최근 transcript 파일을 찾는다.
- * Claude Code는 세션 대화를 ~/.claude/projects/{sanitized-cwd}/{uuid}.jsonl에 저장.
- */
-function findLatestTranscript(cwd) {
+function transcriptProjectDir(cwd) {
     // Claude Code는 cwd의 /를 -로 치환하고 선행 -를 유지
     const sanitized = cwd.replace(/\//g, '-');
-    const projectDir = path.join(os.homedir(), '.claude', 'projects', sanitized);
-    if (!fs.existsSync(projectDir))
+    return path.join(os.homedir(), '.claude', 'projects', sanitized);
+}
+/** 스냅샷용 — 세션 시작 전 존재하는 transcript basename 집합. */
+function snapshotExistingTranscripts(cwd) {
+    const dir = transcriptProjectDir(cwd);
+    if (!fs.existsSync(dir))
+        return new Set();
+    try {
+        return new Set(fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * 세션 시작 후 새로 생성된 transcript 파일을 고른다.
+ *
+ * Audit fix #8 (2026-04-21): 이전 findLatestTranscript는 mtime 최신 파일을
+ * 선택했기에, 같은 cwd에서 동시에 두 세션이 돌면 더 늦게 시작된 세션의
+ * transcript가 두 세션의 exit 핸들러 모두에서 선택되어 transcript
+ * attribution이 섞였다. 이제는
+ *   1) 세션 시작 시점의 "이미 존재하던" 파일 스냅샷을 preSnapshot으로 전달받고
+ *   2) exit 시점에 스냅샷에 없던 새 파일만 후보로 보고
+ *   3) mtime이 세션 시작 시각 이후인 것 중 최신을 선택한다.
+ * 여전히 후보가 여러 개이면 (rare: 훅이 추가 파일을 쓴 경우) 가장 최근 수정본
+ * 을 고르되 debug 로그를 남긴다.
+ */
+function findSessionTranscript(cwd, sessionStartMs, preSnapshot) {
+    const dir = transcriptProjectDir(cwd);
+    if (!fs.existsSync(dir))
         return null;
-    const jsonlFiles = fs.readdirSync(projectDir)
-        .filter(f => f.endsWith('.jsonl'))
-        .map(f => ({ name: f, mtime: fs.statSync(path.join(projectDir, f)).mtimeMs }))
-        .sort((a, b) => b.mtime - a.mtime);
-    return jsonlFiles.length > 0 ? path.join(projectDir, jsonlFiles[0].name) : null;
+    let candidates;
+    try {
+        candidates = fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.jsonl') && !preSnapshot.has(f))
+            .map((f) => {
+            try {
+                return { name: f, mtime: fs.statSync(path.join(dir, f)).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((x) => x !== null && x.mtime >= sessionStartMs);
+    }
+    catch {
+        return null;
+    }
+    if (candidates.length === 0)
+        return null;
+    candidates.sort((a, b) => b.mtime - a.mtime);
+    if (candidates.length > 1) {
+        log.debug(`multiple new transcripts after session start — picking ${candidates[0].name} ` +
+            `(others: ${candidates.slice(1).map((c) => c.name).join(', ')})`);
+    }
+    return path.join(dir, candidates[0].name);
+}
+/**
+ * 사용자 메시지 수 카운트 (streaming).
+ *
+ * Audit fix #8 (2026-04-21): 이전에는 `fs.readFileSync(transcript, 'utf-8')`로
+ * 파일 전체를 메모리에 올렸다. 수백 MB 규모 transcript에서는 heap spike가
+ * 발생했고, 카운트 외엔 내용이 필요 없으니 streaming line-by-line로 충분하다.
+ */
+async function countUserMessages(transcriptPath) {
+    const { createInterface } = await import('node:readline');
+    const stream = fs.createReadStream(transcriptPath, { encoding: 'utf-8' });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    let count = 0;
+    try {
+        for await (const line of rl) {
+            if (!line)
+                continue;
+            try {
+                const t = JSON.parse(line).type;
+                if (t === 'user' || t === 'queue-operation')
+                    count++;
+            }
+            catch { /* skip malformed */ }
+        }
+    }
+    finally {
+        rl.close();
+        stream.close();
+    }
+    return count;
 }
 /**
  * 세션 종료 후 자동 compound 추출 + USER.md 업데이트.
@@ -74,8 +149,10 @@ export async function spawnClaude(args, context, runtime = 'claude') {
         !cleanArgs.includes('--dangerously-skip-permissions')) {
         cleanArgs.unshift('--dangerously-skip-permissions');
     }
-    // 세션 시작 전 timestamp 기록 (종료 후 transcript 찾기 위해)
+    // 세션 시작 전 timestamp + 기존 transcript 스냅샷 기록 (종료 후 finder 용).
+    // Audit fix #8 (2026-04-21): 스냅샷으로 동시 세션 transcript 오선택을 차단.
     const sessionStartTime = Date.now();
+    const preSnapshot = snapshotExistingTranscripts(context.cwd);
     return new Promise((resolve, reject) => {
         const child = spawn(launcher, cleanArgs, {
             stdio: 'inherit',
@@ -102,37 +179,21 @@ export async function spawnClaude(args, context, runtime = 'claude') {
             }
             // 세션 종료 후 하네스 작업
             try {
-                const transcript = findLatestTranscript(context.cwd);
+                const transcript = findSessionTranscript(context.cwd, sessionStartTime, preSnapshot);
                 if (!transcript) {
-                    log.debug('transcript 파일을 찾을 수 없음');
+                    log.debug('이 세션에서 생성된 transcript를 찾을 수 없음 (snapshot diff)');
                 }
                 else {
-                    const stat = fs.statSync(transcript);
-                    // 이 세션에서 생성/수정된 transcript만
-                    if (stat.mtimeMs <= sessionStartTime) {
-                        log.debug(`transcript mtime(${stat.mtimeMs}) <= sessionStart(${sessionStartTime}), 건너뜀`);
+                    const sessionId = path.basename(transcript, '.jsonl');
+                    // 1. FTS5 인덱싱
+                    await indexTranscriptToFTS(context.cwd, transcript, sessionId);
+                    // 2. 자동 compound (10+ user 메시지인 경우만) — streaming line count
+                    const userMsgCount = await countUserMessages(transcript);
+                    if (userMsgCount >= 10) {
+                        await runAutoCompound(context.cwd, transcript, sessionId);
                     }
                     else {
-                        const sessionId = path.basename(transcript, '.jsonl');
-                        // 1. FTS5 인덱싱
-                        await indexTranscriptToFTS(context.cwd, transcript, sessionId);
-                        // 2. 자동 compound (10+ user 메시지인 경우만)
-                        const content = fs.readFileSync(transcript, 'utf-8');
-                        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) {
-                            await runAutoCompound(context.cwd, transcript, sessionId);
-                        }
-                        else {
-                            console.log(`[forgen] 세션이 짧아 auto-compound 생략 (${userMsgCount} messages)`);
-                        }
+                        console.log(`[forgen] 세션이 짧아 auto-compound 생략 (${userMsgCount} messages)`);
                     }
                 }
             }

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

@@ -0,0 +1,30 @@
+export interface PruneReport {
+    scanned: number;
+    pruned: number;
+    bytesFreed: number;
+    retentionDays: number;
+    dryRun: boolean;
+    /** First 20 pruned file basenames for user confirmation */
+    sample: string[];
+}
+export interface PruneOptions {
+    retentionMs?: number;
+    dryRun?: boolean;
+    /** Override the state directory. Used by tests. */
+    stateDir?: string;
+    /** Override the outcomes directory. Used by tests. */
+    outcomesDir?: string;
+    /** Current time for deterministic tests. Defaults to Date.now(). */
+    now?: number;
+}
+/**
+ * Prune session-scoped files older than `retentionMs` from the state and
+ * outcomes directories. Defaults to a dry-run so callers must opt-in to
+ * deletion via `dryRun: false`.
+ */
+export declare function pruneState(opts?: PruneOptions): PruneReport;
+/**
+ * Count session-scoped files in STATE_DIR without deleting. Used by doctor
+ * to surface a warning when the directory is bloated.
+ */
+export declare function countSessionScopedFiles(stateDir?: string): number;

package/dist/core/state-gc.js

@@ -0,0 +1,119 @@
+/**
+ * State directory garbage collector.
+ *
+ * `~/.forgen/state/` accumulates per-session files that are never cleaned
+ * up (injection-cache, active-agents, checkpoint, modified-files,
+ * outcome-pending, permissions, skill-trigger, tool-state, etc.). A field
+ * audit on 2026-04-21 found one installation with 10,802 files in a single
+ * flat directory — SessionStart hook scans linearly on each session, and
+ * `ls` / `rsync` / backup tools all pay the cost.
+ *
+ * This module scans session-scoped files by filename prefix and prunes
+ * those older than a configurable retention window (default 7 days). The
+ * jsonl aggregate logs (hook-errors.jsonl, hook-timing.jsonl,
+ * implicit-feedback.jsonl, match-eval-log.jsonl, solution-quarantine.jsonl)
+ * are left alone — they are tracked append-only and handled by #5
+ * (log rotation).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { STATE_DIR, OUTCOMES_DIR } from './paths.js';
+/** Filename prefixes that identify session-scoped ephemeral files. */
+const SESSION_SCOPED_PREFIXES = [
+    'active-agents-',
+    'checkpoint-',
+    'injection-cache-',
+    'modified-files-',
+    'outcome-pending-',
+    'permissions-',
+    'skill-trigger-',
+    'tool-state-',
+    'reminder-',
+    'context-',
+    'last-',
+];
+const DEFAULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+function hasSessionPrefix(name) {
+    return SESSION_SCOPED_PREFIXES.some((pfx) => name.startsWith(pfx));
+}
+function pruneDir(dir, cutoff, dryRun, filter) {
+    const out = { scanned: 0, pruned: 0, bytes: 0, sample: [] };
+    if (!fs.existsSync(dir))
+        return out;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        if (!filter(name))
+            continue;
+        const full = path.join(dir, name);
+        let stat;
+        try {
+            stat = fs.statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        out.scanned++;
+        if (stat.mtimeMs >= cutoff)
+            continue;
+        if (!dryRun) {
+            try {
+                fs.unlinkSync(full);
+            }
+            catch {
+                continue;
+            }
+        }
+        out.pruned++;
+        out.bytes += stat.size;
+        if (out.sample.length < 20)
+            out.sample.push(name);
+    }
+    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
+ * deletion via `dryRun: false`.
+ */
+export function pruneState(opts = {}) {
+    const retentionMs = opts.retentionMs ?? DEFAULT_RETENTION_MS;
+    const dryRun = opts.dryRun ?? true;
+    const stateDir = opts.stateDir ?? STATE_DIR;
+    const outcomesDir = opts.outcomesDir ?? OUTCOMES_DIR;
+    const now = opts.now ?? Date.now();
+    const cutoff = now - retentionMs;
+    const state = pruneDir(stateDir, cutoff, dryRun, hasSessionPrefix);
+    // outcomes/*.jsonl: one file per session, session-scoped by design.
+    // These compound over time exactly like state session files.
+    const outcomes = pruneDir(outcomesDir, cutoff, dryRun, (n) => n.endsWith('.jsonl'));
+    return {
+        scanned: state.scanned + outcomes.scanned,
+        pruned: state.pruned + outcomes.pruned,
+        bytesFreed: state.bytes + outcomes.bytes,
+        retentionDays: Math.round(retentionMs / (24 * 60 * 60 * 1000)),
+        dryRun,
+        sample: [...state.sample, ...outcomes.sample].slice(0, 20),
+    };
+}
+/**
+ * Count session-scoped files in STATE_DIR without deleting. Used by doctor
+ * to surface a warning when the directory is bloated.
+ */
+export function countSessionScopedFiles(stateDir = STATE_DIR) {
+    if (!fs.existsSync(stateDir))
+        return 0;
+    try {
+        return fs.readdirSync(stateDir).filter(hasSessionPrefix).length;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/core/uninstall.js

@@ -118,11 +118,13 @@ function cleanSettings() {
         console.error('[forgen] Failed to parse settings.json — skipping.');
         return;
     }
-    // env에서 COMPOUND_ 접두어 키 제거
+    // Audit fix #7 (2026-04-21): env 정리가 `COMPOUND_` 접두어만 검사해서
+    // install이 주입한 `FORGEN_*` 키(예: FORGEN_HARNESS, FORGEN_CWD)가
+    // uninstall 후에도 settings.json에 영구 잔존했다. 이제 둘 다 정리.
     const env = settings.env;
     if (env) {
         for (const key of Object.keys(env)) {
-            if (key.startsWith('COMPOUND_'))
+            if (key.startsWith('COMPOUND_') || key.startsWith('FORGEN_'))
                 delete env[key];
         }
         if (Object.keys(env).length === 0) {
@@ -162,9 +164,15 @@ function cleanSettings() {
             delete settings.hooks;
         }
     }
-    // statusLine이 forgen status면 제거
+    // statusLine이 forgen이 설치한 command 중 하나면 제거.
+    //
+    // Audit fix #7 (2026-04-21): 이전 체크는 `'forgen status'`만 인식했지만
+    // 실제 install은 `settings-injector.ts:59`에서 `'forgen me'`를 주입한다.
+    // command 문자열이 `forgen`으로 시작하는 경우를 모두 forgen 소유로 보고
+    // 제거 — 사용자 커스텀 statusLine(예: `custom-cli ...`)은 건드리지 않음.
     const statusLine = settings.statusLine;
-    if (statusLine?.command === 'forgen status') {
+    if (typeof statusLine?.command === 'string' &&
+        /^forgen(\s|$)/.test(statusLine.command.trim())) {
         delete settings.statusLine;
     }
     // enabledPlugins에서 forgen@forgen-local 제거

package/dist/core/v1-bootstrap.js

@@ -15,7 +15,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { FORGEN_HOME, V1_ME_DIR, V1_RULES_DIR, V1_EVIDENCE_DIR, V1_RECOMMENDATIONS_DIR, V1_SESSIONS_DIR, V1_STATE_DIR, V1_RAW_LOGS_DIR, V1_SOLUTIONS_DIR } from './paths.js';
+import { FORGEN_HOME, ME_DIR, ME_RULES, ME_BEHAVIOR, V1_RECOMMENDATIONS_DIR, V1_SESSIONS_DIR, STATE_DIR, V1_RAW_LOGS_DIR, ME_SOLUTIONS } from './paths.js';
 import { checkLegacyProfile, runLegacyCutover } from './legacy-detector.js';
 import { detectRuntimeCapability } from './runtime-detector.js';
 import { loadProfile, profileExists } from '../store/profile-store.js';
@@ -27,7 +27,7 @@ import { loadEvidenceBySession } from '../store/evidence-store.js';
 import { computeSessionSignals, detectMismatch } from '../forge/mismatch-detector.js';
 import { createRecommendation, saveRecommendation } from '../store/recommendation-store.js';
 // ── Directory Initialization ──
-const V1_DIRS = [FORGEN_HOME, V1_ME_DIR, V1_RULES_DIR, V1_EVIDENCE_DIR, V1_RECOMMENDATIONS_DIR, V1_STATE_DIR, V1_SESSIONS_DIR, V1_RAW_LOGS_DIR, V1_SOLUTIONS_DIR];
+const V1_DIRS = [FORGEN_HOME, ME_DIR, ME_RULES, ME_BEHAVIOR, V1_RECOMMENDATIONS_DIR, STATE_DIR, V1_SESSIONS_DIR, V1_RAW_LOGS_DIR, ME_SOLUTIONS];
 export function ensureV1Directories() {
     for (const dir of V1_DIRS) {
         fs.mkdirSync(dir, { recursive: true });

package/dist/engine/compound-cli.d.ts

@@ -20,5 +20,30 @@ export declare function removeSolution(name: string): void;
 export declare function cleanStaleSolutions(): void;
 /** Retag all solutions using improved extractTags */
 export declare function retagSolutions(): void;
-/** Rollback auto-extracted solutions since a given date */
-export declare function rollbackSolutions(sinceDate: string): void;
+/** Result of a rollback operation — used by tests and callers that need counts. */
+export interface RollbackCliResult {
+    archived: string[];
+    archiveDir: string | null;
+    skipped: string[];
+    errors: string[];
+    dryRun: boolean;
+}
+/**
+ * Rollback auto-extracted solutions created since a given date.
+ *
+ * Invariant (2026-04-20, feedback_core_loop_invariant):
+ *   rollback은 **archive 이동**만 수행한다. `fs.unlinkSync`로 솔루션 파일을
+ *   영구 삭제하지 않는다. 실수로 rollback을 실행해도 `~/.forgen/lab/archived/
+ *   rollback-{ts}/`에서 복구할 수 있어야 한다. (과거 `unlinkSync` 경로는
+ *   time-bounded rollback이 "되돌리기 불가 영구 삭제"로 동작하던 버그였다.)
+ *
+ * 필터 기준:
+ *   - category === 'solution'만 대상 (rule은 제외)
+ *   - reflected > 0 OR sessions > 0인 것은 유지 (사용된 솔루션 보호)
+ *   - created >= since 인 것만 대상
+ *
+ * dryRun=true면 아무 파일도 건드리지 않고 대상 목록만 반환.
+ */
+export declare function rollbackSolutions(sinceDate: string, opts?: {
+    dryRun?: boolean;
+}): RollbackCliResult;

package/dist/engine/compound-cli.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { extractTags, parseFrontmatterOnly, parseSolutionV3 } from './solution-format.js';
 import { mutateSolutionFile } from './solution-writer.js';
-import { ME_SOLUTIONS, ME_RULES } from '../core/paths.js';
+import { ARCHIVED_DIR, ME_SOLUTIONS, ME_RULES } from '../core/paths.js';
 /** Scan saved compound entries and return summaries */
 function scanEntries() {
     const summaries = [];
@@ -78,7 +78,17 @@ export function listSolutions() {
             console.log(`      ${entry.name} [${entry.category}]  (${entry.confidence.toFixed(2)})  ${evStr}  [${entry.tags.slice(0, 3).join(', ')}]`);
         }
     }
-    console.log(`\n  Total: ${total} entries\n`);
+    // retired 카운트: scanEntries는 모든 상태를 포함하므로 직접 계산
+    const retiredCount = entries.filter(e => e.status === 'retired').length;
+    const activeCount = total - retiredCount;
+    const highConfidence = entries.filter(e => e.status === 'verified' || e.status === 'mature').length;
+    const denominator = total;
+    const precision = denominator > 0 ? Math.round((highConfidence / denominator) * 100) : null;
+    console.log(`\n  Total: ${activeCount} active + ${retiredCount} retired`);
+    if (precision !== null) {
+        console.log(`  Extraction precision: ${precision}%`);
+    }
+    console.log();
 }
 /** Inspect a single saved entry in detail */
 export function inspectSolution(name) {
@@ -218,33 +228,76 @@ export function retagSolutions() {
     }
     console.log(`\n  Retagged ${retagged}/${entries.length} solutions.\n`);
 }
-/** Rollback auto-extracted solutions since a given date */
-export function rollbackSolutions(sinceDate) {
+/**
+ * Rollback auto-extracted solutions created since a given date.
+ *
+ * Invariant (2026-04-20, feedback_core_loop_invariant):
+ *   rollback은 **archive 이동**만 수행한다. `fs.unlinkSync`로 솔루션 파일을
+ *   영구 삭제하지 않는다. 실수로 rollback을 실행해도 `~/.forgen/lab/archived/
+ *   rollback-{ts}/`에서 복구할 수 있어야 한다. (과거 `unlinkSync` 경로는
+ *   time-bounded rollback이 "되돌리기 불가 영구 삭제"로 동작하던 버그였다.)
+ *
+ * 필터 기준:
+ *   - category === 'solution'만 대상 (rule은 제외)
+ *   - reflected > 0 OR sessions > 0인 것은 유지 (사용된 솔루션 보호)
+ *   - created >= since 인 것만 대상
+ *
+ * dryRun=true면 아무 파일도 건드리지 않고 대상 목록만 반환.
+ */
+export function rollbackSolutions(sinceDate, opts = {}) {
+    const result = {
+        archived: [],
+        archiveDir: null,
+        skipped: [],
+        errors: [],
+        dryRun: !!opts.dryRun,
+    };
     const since = new Date(sinceDate);
     if (Number.isNaN(since.getTime())) {
         console.log(`\n  Invalid date: ${sinceDate}\n`);
-        return;
+        result.errors.push(`invalid-date:${sinceDate}`);
+        return result;
     }
     const solutions = scanEntries().filter((entry) => entry.category === 'solution');
-    const toRemove = solutions.filter((solution) => {
+    const toRollback = solutions.filter((solution) => {
         if (solution.evidence.reflected > 0 || solution.evidence.sessions > 0)
-            return false; // keep used ones
+            return false;
         const created = new Date(solution.created);
         return created >= since;
     });
-    if (toRemove.length === 0) {
+    if (toRollback.length === 0) {
         console.log(`\n  No solutions to rollback since ${sinceDate}.\n`);
-        return;
+        return result;
     }
-    console.log(`\n  Rolling back ${toRemove.length} solutions since ${sinceDate}:\n`);
-    for (const sol of toRemove) {
+    if (opts.dryRun) {
+        console.log(`\n  [dry-run] ${toRollback.length} solutions would be archived since ${sinceDate}:\n`);
+        for (const sol of toRollback) {
+            console.log(`    Would archive: ${sol.name}`);
+            result.skipped.push(sol.filePath);
+        }
+        console.log(`\n  Re-run without --dry-run to archive them.\n`);
+        return result;
+    }
+    const archiveDir = path.join(ARCHIVED_DIR, `rollback-${Date.now()}`);
+    result.archiveDir = archiveDir;
+    console.log(`\n  Rolling back ${toRollback.length} solutions since ${sinceDate} → ${archiveDir}:\n`);
+    for (const sol of toRollback) {
         try {
-            fs.unlinkSync(sol.filePath);
-            console.log(`    Removed: ${sol.name}`);
+            fs.mkdirSync(archiveDir, { recursive: true });
+            // 원본 경로 정보를 destName에 보존 — 복원 시 원위치 판별용.
+            // 예: "solutions__my-pattern.md"
+            const originDir = path.basename(path.dirname(sol.filePath));
+            const destName = `${originDir}__${path.basename(sol.filePath)}`;
+            fs.renameSync(sol.filePath, path.join(archiveDir, destName));
+            console.log(`    Archived: ${sol.name}`);
+            result.archived.push(sol.filePath);
         }
-        catch {
-            console.log(`    Failed: ${sol.name}`);
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            console.log(`    Failed: ${sol.name} — ${msg}`);
+            result.errors.push(`${sol.filePath}: ${msg}`);
         }
     }
-    console.log();
+    console.log(`\n  ${result.archived.length}/${toRollback.length} archived. Restore from ${archiveDir} if needed.\n`);
+    return result;
 }

package/dist/engine/compound-export.d.ts

@@ -7,6 +7,21 @@
  * Export creates a tar.gz archive; Import extracts it while skipping existing
  * files to prevent accidental overwrites.
  */
+/**
+ * Test-friendly containment check (exported for unit tests).
+ *
+ * Audit fix (2026-04-21, follow-up #A): prior guard
+ * `realDest.startsWith(ME_DIR)` was a naive prefix match. A path like
+ * `/home/u/.forgen/me-evil/x.md` starts with `/home/u/.forgen/me` and
+ * bypassed the check — even though it's a sibling, not a child, of
+ * ME_DIR. Fix: compare with `parent + path.sep` so `/home/u/.forgen/me/`
+ * cannot prefix-match `/home/u/.forgen/me-evil/...`.
+ *
+ * @param parentWithSep absolute canonical parent path that INCLUDES a
+ *   trailing `path.sep` (precomputed by caller once per archive).
+ * @param candidate any path string (will be resolved lexically).
+ */
+export declare function isPathInside(parentWithSep: string, candidate: string): boolean;
 export interface ExportResult {
     outputPath: string;
     counts: Record<string, number>;

package/dist/engine/compound-export.js

@@ -14,6 +14,24 @@ import { execFileSync } from 'node:child_process';
 import { ME_DIR } from '../core/paths.js';
 /** Directories within ME_DIR to include in the archive. */
 const KNOWLEDGE_DIRS = ['solutions', 'rules', 'behavior'];
+/**
+ * Test-friendly containment check (exported for unit tests).
+ *
+ * Audit fix (2026-04-21, follow-up #A): prior guard
+ * `realDest.startsWith(ME_DIR)` was a naive prefix match. A path like
+ * `/home/u/.forgen/me-evil/x.md` starts with `/home/u/.forgen/me` and
+ * bypassed the check — even though it's a sibling, not a child, of
+ * ME_DIR. Fix: compare with `parent + path.sep` so `/home/u/.forgen/me/`
+ * cannot prefix-match `/home/u/.forgen/me-evil/...`.
+ *
+ * @param parentWithSep absolute canonical parent path that INCLUDES a
+ *   trailing `path.sep` (precomputed by caller once per archive).
+ * @param candidate any path string (will be resolved lexically).
+ */
+export function isPathInside(parentWithSep, candidate) {
+    const resolved = path.resolve(candidate) + path.sep;
+    return resolved.startsWith(parentWithSep) && resolved !== parentWithSep;
+}
 /**
  * Count .md files in a directory (non-recursive).
  * Returns 0 if the directory does not exist.
@@ -92,12 +110,21 @@ export function importKnowledge(archivePath) {
             stdio: ['pipe', 'pipe', 'pipe'],
         });
         const result = { imported: 0, skipped: 0, details: [] };
+        // Audit fix (2026-04-21, follow-up #A): prior check
+        // `realDest.startsWith(ME_DIR)` was a broken prefix guard. An archive
+        // entry `../me-evil/payload.md` resolves to a sibling directory path
+        // that still startsWith ME_DIR (prefix collision) and bypasses the
+        // check. Fix: compare lexically resolved paths with an explicit
+        // `path.sep` suffix so `.../me-evil` can never masquerade as
+        // `.../me/...`. Both source and destination are validated — a
+        // malformed archive must neither read from outside tmpDir nor write
+        // outside ME_DIR.
+        const meDirCanon = path.resolve(ME_DIR) + path.sep;
+        const tmpDirCanon = path.resolve(tmpDir) + path.sep;
         for (const relFile of archiveFiles) {
-            const srcPath = path.join(tmpDir, relFile);
-            const destPath = path.join(ME_DIR, relFile);
-            // Security: ensure the dest path stays within ME_DIR
-            const realDest = path.resolve(destPath);
-            if (!realDest.startsWith(ME_DIR)) {
+            const srcPath = path.resolve(path.join(tmpDir, relFile));
+            const destPath = path.resolve(path.join(ME_DIR, relFile));
+            if (!isPathInside(meDirCanon, destPath) || !isPathInside(tmpDirCanon, srcPath)) {
                 result.skipped++;
                 result.details.push({ file: relFile, action: 'skipped' });
                 continue;

package/dist/engine/compound-loop.js

@@ -324,11 +324,12 @@ export async function handleCompound(args) {
         const sinceIdx = args.indexOf('--since');
         const since = sinceIdx !== -1 ? args[sinceIdx + 1] : undefined;
         if (!since) {
-            console.log('  Usage: forgen compound rollback --since 2026-03-20\n');
+            console.log('  Usage: forgen compound rollback --since YYYY-MM-DD [--dry-run]\n');
             return;
         }
+        const dryRun = args.includes('--dry-run');
         const { rollbackSolutions } = await import('./compound-cli.js');
-        rollbackSolutions(since);
+        rollbackSolutions(since, { dryRun });
         return;
     }
     // --- explicit interactive command ---

package/dist/engine/learn-cli.d.ts

@@ -0,0 +1 @@
+export declare function handleLearn(args: string[]): Promise<void>;