@wooojin/forgen 0.4.11 → 0.4.13

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://claude.ai/schemas/claude-plugin.json",
   "name": "forgen",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Claude Code harness — the more you use Claude, the better it gets",
   "author": {
     "name": "jang-ujin",

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.13] — 2026-06-02 — Hotfix: fgx 세션 종료 시 터미널 물림 방지
+
+핫픽스 한 건.
+
+- **fix(fgx)**: `fgx` 가 대화형 세션 성공 경로에서 `process.exit` 를 호출하지 않고 Node
+  이벤트 루프 자연 배수에 의존해 종료해 왔다. `spawnClaude` 는 세션 종료 시
+  `auto-compound-runner` 를 detached + unref 로 띄우고 즉시 resolve 하므로(0.4.12 에서
+  비차단 전환) 현재는 미해제 핸들이 없어 정상 종료한다. 그러나 향후 post-session 경로
+  (`indexTranscriptToFTS`·rate-limit scan 등)에 닫히지 않은 핸들(SQLite 커넥션·타이머·소켓)이
+  하나라도 생기면 fgx 가 종료하지 못하고 셸 프롬프트가 돌아오지 않는다(= 터미널 물림).
+  `runClaudeLauncher()` 직후 명시적 `process.exit(0)` 추가로 이 종류의 회귀를 원천 차단.
+  cli.js 위임 경로(`watch`/`dashboard`/`workflows` 등 long-running)는 자체 exit 를 책임지므로
+  손대지 않았다. detached 자식은 unref 되어 독립 세션에서 실행되므로 `process.exit(0)` 후에도
+  생존(PID 1 로 reparent 확인) — 백그라운드 compound 는 영향받지 않는다.
+
+## [0.4.12] — 2026-06-01 — Hotfix: 훅 stdout 누출 + 세션 종료 블로킹
+
+핫픽스 두 건.
+
+- **fix(hooks)**: `secret-filter` 에 ESM main-guard 누락 → `context-guard` 가 `redactSecrets`
+  를 import 할 때 `secret-filter.main()` 이 import 부작용으로 실행되어 유령 `{"continue":true}`
+  를 1줄 추가 emit. 그 결과 context-guard 의 stdout 이 JSON 2줄이 되어 Claude Code 파싱
+  실패 → raw `{"continue":true}` 가 매 프롬프트/세션 종료마다 사용자 터미널에 노출되었다.
+  표준 main-guard 추가로 수정. (등록 훅 11개 중 context-guard 만 영향)
+- **perf(compound)**: 세션 종료 시 `runAutoCompound` 가 execFileSync 로 동기 실행되어 최대
+  ~210초(haiku LLM 3회 순차) 블록되었다. 같은 작업을 Stop 훅·session-recovery 가 이미
+  detached 로 spawn 하므로(dedup 마커 공유), 동기 경로를 detached + unref 로 전환해 세션
+  종료를 막지 않게 했다. 결과는 다음 세션 시작 시 surface.
+- **test**: `hook-single-line-output` (훅당 stdout 1줄 + secret-filter import 무부작용),
+  `auto-compound-detached` (detached/unref/dedup 분기) 회귀 테스트 추가.
+
 ## [0.4.11] — 2026-05-29 — Opus 4.8 + Dynamic Workflows 대응
 
 테마: Claude Opus 4.8(2026-05-28 GA)의 **dynamic workflows**(최대 1,000 서브에이전트,

package/dist/core/spawn.d.ts

@@ -1,5 +1,18 @@
 import type { V1HarnessContext } from './harness.js';
 import type { RuntimeHost } from './types.js';
+/**
+ * 세션 종료 후 자동 compound 추출을 백그라운드(detached)로 시작.
+ *
+ * 과거에는 execFileSync 로 동기 실행하여 세션 종료가 최대 ~210초(haiku LLM 3회
+ * 순차: 솔루션 추출 90s + behavior 60s + 세션 학습 60s) 동안 블록되었다. 같은
+ * 작업을 context-guard Stop 훅(maybeSpawnAutoCompound)과 session-recovery 가 이미
+ * detached 로 spawn 하므로, 여기서도 detached + unref 로 전환해 세션 종료를 막지
+ * 않는다. 결과(추출 솔루션/패턴)는 다음 세션 시작 시 session-recovery 가 surface 한다.
+ *
+ * dedup: last-auto-compound.json 을 Stop 훅과 공유 — 같은 세션의 최근 run 이 있으면
+ * skip 하여 detached spawn 의 double-run 을 방지한다.
+ */
+export declare function runAutoCompound(cwd: string, transcriptPath: string, sessionId: string): void;
 /**
  * Plan B-1: 세션 transcript 사후 스캔으로 rate-limit 감지.
  *

package/dist/core/spawn.js

@@ -223,19 +223,47 @@ async function scanCommitDiffForActedOn(sessionId, cwd, sessionStartTime) {
  * 세션 종료 후 자동 compound 추출 + USER.md 업데이트.
  * auto-compound-runner.ts를 동기 실행하여 솔루션 추출 + 사용자 패턴 관찰.
  */
-async function runAutoCompound(cwd, transcriptPath, sessionId) {
-    console.log('\n[forgen] 세션 분석 중... (자동 compound)');
+// Stop 훅(maybeSpawnAutoCompound)/session-recovery 와 공유하는 dedup cooldown.
+const AUTO_COMPOUND_DEDUP_COOLDOWN_MS = 5 * 60 * 1000; // 5min
+/**
+ * 세션 종료 후 자동 compound 추출을 백그라운드(detached)로 시작.
+ *
+ * 과거에는 execFileSync 로 동기 실행하여 세션 종료가 최대 ~210초(haiku LLM 3회
+ * 순차: 솔루션 추출 90s + behavior 60s + 세션 학습 60s) 동안 블록되었다. 같은
+ * 작업을 context-guard Stop 훅(maybeSpawnAutoCompound)과 session-recovery 가 이미
+ * detached 로 spawn 하므로, 여기서도 detached + unref 로 전환해 세션 종료를 막지
+ * 않는다. 결과(추출 솔루션/패턴)는 다음 세션 시작 시 session-recovery 가 surface 한다.
+ *
+ * dedup: last-auto-compound.json 을 Stop 훅과 공유 — 같은 세션의 최근 run 이 있으면
+ * skip 하여 detached spawn 의 double-run 을 방지한다.
+ */
+export function runAutoCompound(cwd, transcriptPath, sessionId) {
+    const markerPath = path.join(STATE_DIR, 'last-auto-compound.json');
+    try {
+        const parsed = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
+        if (parsed.sessionId === sessionId) {
+            const last = parsed.completedAt ? Date.parse(parsed.completedAt) : 0;
+            if (Number.isFinite(last) && Date.now() - last < AUTO_COMPOUND_DEDUP_COOLDOWN_MS) {
+                log.debug('auto-compound skip: 최근 동일 세션 run 존재 (dedup)');
+                return;
+            }
+        }
+    }
+    catch {
+        // 마커 없음(최초)/손상 — 진행 (fail-open).
+    }
     const runnerPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'auto-compound-runner.js');
     try {
-        execFileSync('node', [runnerPath, cwd, transcriptPath, sessionId], {
+        const child = spawn('node', [runnerPath, cwd, transcriptPath, sessionId], {
             cwd,
-            timeout: 120_000,
-            stdio: ['pipe', 'inherit', 'inherit'],
+            detached: true,
+            stdio: 'ignore',
         });
-        console.log('[forgen] 자동 compound 완료\n');
+        child.unref();
+        console.log('\n[forgen] 세션 분석을 백그라운드로 시작했습니다 (자동 compound) — 결과는 다음 세션 시작 시 반영됩니다.\n');
     }
     catch (e) {
-        log.debug('auto-compound 실패', e);
+        log.debug('auto-compound 시작 실패', e);
     }
 }
 /**
@@ -415,7 +443,7 @@ export async function spawnClaude(args, context, runtime = 'claude') {
                     // 4. 자동 compound (10+ user 메시지인 경우만) — 양 runtime 호환
                     const userMsgCount = await countUserMessages(transcript);
                     if (userMsgCount >= 10) {
-                        await runAutoCompound(context.cwd, transcript, sessionId);
+                        runAutoCompound(context.cwd, transcript, sessionId);
                     }
                     else {
                         console.log(`[forgen] 세션이 짧아 auto-compound 생략 (${userMsgCount} messages)`);

package/dist/fgx.js

@@ -80,10 +80,22 @@ async function runClaudeLauncher() {
 async function main() {
     const sub = findFirstSubcommand(args);
     if (sub !== null) {
+        // cli.js 위임 경로는 건드리지 않는다. watch/dashboard/workflows 등 long-running
+        // 서브커맨드가 여기서 강제 종료되면 잘린다. cli.js 가 자체 process.exit 를 책임진다.
         await routeToCli();
         return;
     }
     await runClaudeLauncher();
+    // 대화형 세션 종료 후 fgx 프로세스 종료를 명시적으로 보장한다.
+    //
+    // WHY: spawnClaude 는 세션 종료 시 auto-compound-runner 를 detached + unref 로 띄우고
+    // 즉시 resolve 한다(설계상 비차단). 그런데 fgx 는 성공 경로에서 process.exit 를 호출하지
+    // 않고 Node 이벤트 루프 자연 배수에 의존해 왔다. 지금은 미해제 핸들이 없어 정상 종료하지만,
+    // 향후 post-session 경로에 닫히지 않은 핸들(SQLite 커넥션, 타이머, 소켓 등)이 하나라도
+    // 생기면 fgx 가 종료하지 못하고 셸 프롬프트가 돌아오지 않는다(= 터미널 물림). 명시 종료로
+    // 이 종류의 회귀를 원천 차단한다. detached 자식은 unref 되어 독립 실행되므로 백그라운드
+    // compound 는 영향받지 않고 계속된다.
+    process.exit(0);
 }
 main().catch((err) => {
     console.error('[forgen] Error:', err instanceof Error ? err.message : err);

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

@@ -22,3 +22,4 @@ export declare function redactSecrets(text: string): {
 };
 /** 텍스트에서 민감 정보 패턴 감지 (순수 함수) */
 export declare function detectSecrets(text: string): SecretPattern[];
+export declare function main(): Promise<void>;

package/dist/hooks/secret-filter.js

@@ -5,6 +5,9 @@
  * 도구 실행 결과에서 API 키, 토큰, 비밀번호 등 민감 정보 노출을 감지합니다.
  * 차단하지 않고 경고 메시지만 출력합니다.
  */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { HookError } from '../core/errors.js';
 import { readStdinJSON } from './shared/read-stdin.js';
 import { isHookEnabled } from './hook-config.js';
@@ -53,7 +56,7 @@ export function detectSecrets(text) {
     }
     return found;
 }
-async function main() {
+export async function main() {
     const data = await readStdinJSON();
     if (!isHookEnabled('secret-filter')) {
         console.log(approve());
@@ -82,10 +85,17 @@ async function main() {
     }
     console.log(approve());
 }
-main().catch((e) => {
-    const hookErr = new HookError(e instanceof Error ? e.message : String(e), {
-        hookName: 'secret-filter', eventType: 'PostToolUse', cause: e,
+// ESM main guard: import 시 main() 실행 방지 (context-guard 와 동일 패턴).
+// secret-filter 는 redactSecrets 등을 다른 hook (context-guard) 이 import 하므로,
+// guard 없이 top-level main() 을 호출하면 import 부작용으로 main() 이 실행되어
+// stdout 에 유령 {"continue":true} 가 1줄 추가된다. 그 결과 import 한 hook 의
+// stdout 이 JSON 2줄이 되어 Claude Code 파싱 실패 → raw JSON 이 터미널에 노출됨.
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
+    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(failOpenWithTracking('secret-filter', e));
     });
-    process.stderr.write(`[ch-hook] ${hookErr.name}: ${hookErr.message}\n`);
-    console.log(failOpenWithTracking('secret-filter', e));
-});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooojin/forgen",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "preferGlobal": true,
   "main": "dist/lib.js",
   "types": "./dist/lib.d.ts",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://claude.ai/schemas/claude-plugin.json",
   "name": "forgen",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Claude Code harness — the more you use Claude, the better it gets",
   "author": {
     "name": "jang-ujin",