@wooojin/forgen 0.4.10 → 0.4.12

package/dist/fgx.js

@@ -19,7 +19,7 @@ const FORGEN_SUBCOMMANDS = new Set([
     'notepad', 'inspect', 'onboarding', 'doctor', 'uninstall', 'rule',
     'classify-enforce', 'rule-meta-scan', 'lifecycle-scan',
     'stats', 'last-block', 'recall', 'migrate', 'suppress-rule', 'activate-rule',
-    'regress-map',
+    'regress-map', 'watch', 'health', 'probe-workflow', 'workflows', 'explain', 'changelog',
     // 메타 명령도 cli.ts 가 처리 (fgx claude spawn 으로는 의미 없음)
     'help', '--help', '-h', '--version', '-V',
 ]);

package/dist/hooks/notepad-injector.js

@@ -22,6 +22,7 @@ import { truncateContent } from './shared/injection-caps.js';
 import { calculateBudget } from './shared/context-budget.js';
 import { approve, approveWithContext, failOpenWithTracking } from './shared/hook-response.js';
 import { escapeAllXmlTags } from './prompt-injection-filter.js';
+import { checkForgenInitialized, hasPreflightWarned, markPreflightWarned } from './shared/preflight-check.js';
 // ── 메인 ──
 async function main() {
     const input = await readStdinJSON();
@@ -33,6 +34,12 @@ async function main() {
         console.log(approve());
         return;
     }
+    const sessionId = input.session_id ?? 'unknown';
+    const preflight = checkForgenInitialized();
+    if (!preflight.initialized && !hasPreflightWarned(sessionId)) {
+        markPreflightWarned(sessionId);
+        process.stderr.write(`${preflight.message}\n`);
+    }
     const effectiveCwd = input.cwd ?? process.env.FORGEN_CWD ?? process.env.COMPOUND_CWD ?? process.cwd();
     const notepadContent = readNotepad(effectiveCwd);
     if (!notepadContent.trim()) {

package/dist/hooks/post-tool-use.js

@@ -131,7 +131,14 @@ async function main() {
         const rawResponse = data.tool_response ?? data.toolOutput ?? '';
         const toolResponse = typeof rawResponse === 'string' ? rawResponse : JSON.stringify(rawResponse);
         const sessionId = data.session_id ?? 'default';
-        const modState = loadModifiedFiles(sessionId);
+        // ADR-009 §2d: subagent context (agent_id 존재) 의 tool 추적은 per-agent 파일로
+        // 분리한다 → (a) 메인 세션 recentTools 가 subagent tool 노이즈에 오염되지 않고,
+        // (b) 각 subagent 가 자기 TEST-2 윈도우를 가지며, (c) 워크플로우 동시 subagent 가
+        // 서로의 recentTools 를 덮어쓰는 레이스를 제거. agent_id 가 없으면(메인 세션)
+        // sessionId 그대로 → 기존 동작 불변. violation/bypass 기록은 실 sessionId 유지.
+        const agentId = data.agent_id ?? data.agentId;
+        const trackingKey = agentId ? `${sessionId}.agent-${agentId}` : sessionId;
+        const modState = loadModifiedFiles(trackingKey);
         modState.toolCallCount = (modState.toolCallCount ?? 0) + 1;
         // TEST-2: recent tool name window — stop-guard 의 self-score inflation 가드가
         // "최근 세션에서 측정 도구 몇 번 불렸나?" 를 이 배열로 계산한다.

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/dist/hooks/shared/preflight-check.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Preflight check for forgen initialization state.
+ *
+ * Detects "hooks wired but no profile" — a user who ran `forgen install`
+ * but never completed onboarding via `forgen`. Emits a one-time warning
+ * per session so the user knows personalization is disabled.
+ */
+export declare function checkForgenInitialized(): {
+    initialized: boolean;
+    message?: string;
+};
+/** Returns true if a preflight warning has already been emitted this session */
+export declare function hasPreflightWarned(sessionId: string): boolean;
+/** Mark that a preflight warning has been emitted for this session */
+export declare function markPreflightWarned(sessionId: string): void;

package/dist/hooks/shared/preflight-check.js

@@ -0,0 +1,51 @@
+/**
+ * Preflight check for forgen initialization state.
+ *
+ * Detects "hooks wired but no profile" — a user who ran `forgen install`
+ * but never completed onboarding via `forgen`. Emits a one-time warning
+ * per session so the user knows personalization is disabled.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { FORGEN_HOME, STATE_DIR } from '../../core/paths.js';
+const ME_DIR = path.join(FORGEN_HOME, 'me');
+const PROFILE_PATH = path.join(ME_DIR, 'forge-profile.json');
+export function checkForgenInitialized() {
+    try {
+        if (!fs.existsSync(FORGEN_HOME)) {
+            return {
+                initialized: false,
+                message: '[forgen] ~/.forgen not found — run `forgen` to complete setup.',
+            };
+        }
+        if (!fs.existsSync(PROFILE_PATH)) {
+            return {
+                initialized: false,
+                message: '[forgen] Profile not found — run `forgen` to complete onboarding. Hooks are active but personalization is disabled.',
+            };
+        }
+        return { initialized: true };
+    }
+    catch {
+        return { initialized: true };
+    }
+}
+/** Returns true if a preflight warning has already been emitted this session */
+export function hasPreflightWarned(sessionId) {
+    try {
+        return fs.existsSync(path.join(STATE_DIR, `preflight-warned-${sessionId}`));
+    }
+    catch {
+        return true;
+    }
+}
+/** Mark that a preflight warning has been emitted for this session */
+export function markPreflightWarned(sessionId) {
+    try {
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+        fs.writeFileSync(path.join(STATE_DIR, `preflight-warned-${sessionId}`), '1');
+    }
+    catch {
+        // fail-open
+    }
+}

package/dist/hooks/stop-guard.js

@@ -24,10 +24,7 @@ import * as os from 'node:os';
 import { readStdinJSON } from './shared/read-stdin.js';
 import { approve, approveWithWarning, blockStop, failOpenWithTracking } from './shared/hook-response.js';
 import { takeLastExtractionNotice } from '../core/extraction-notice.js';
-import { checkConclusionVerificationRatio } from '../checks/conclusion-verification-ratio.js';
-import { checkSelfScoreInflation } from '../checks/self-score-deflation.js';
-import { checkFactVsAgreement } from '../checks/fact-vs-agreement.js';
-import { checkDangerousResponsePattern } from '../checks/dangerous-response-pattern.js';
+import { runMetaGuards } from '../checks/_shared/meta-guard-dispatch.js';
 import { sanitizeForGuard } from '../checks/_shared/text-sanitizer.js';
 import { STATE_DIR } from '../core/paths.js';
 import { sanitizeId } from './shared/sanitize-id.js';
@@ -179,14 +176,19 @@ function messageTriggersRule(message, rule) {
     const t = rule.trigger;
     if (!t.response_keywords_regex)
         return false;
+    // ADR-009 §7 후속: 룰-스토어 트리거도 built-in 메타가드와 동일하게 sanitize 된
+    // 텍스트로 매칭한다. 트리거 어휘를 코드펜스/백틱/인용으로 *언급만* 한 referential
+    // 케이스(메타 대화)에서 룰이 self-match 하던 거짓양성을 줄인다. 자연 산문 속 실제
+    // 주장은 sanitize 후에도 남으므로 진짜 탐지(TP)는 보존된다.
+    const m = sanitizeForGuard(message);
     const includeRes = compileSafeRegex(t.response_keywords_regex, 'i');
     if (!includeRes.regex)
         return false;
-    if (!safeRegexTest(includeRes.regex, message))
+    if (!safeRegexTest(includeRes.regex, m))
         return false;
     if (t.context_exclude_regex) {
         const excludeRes = compileSafeRegex(t.context_exclude_regex, 'i');
-        if (excludeRes.regex && safeRegexTest(excludeRes.regex, message))
+        if (excludeRes.regex && safeRegexTest(excludeRes.regex, m))
             return false;
     }
     return true;
@@ -498,71 +500,28 @@ export async function main() {
         // block/approve 어느 경로이든 동일하게 기록 (참조는 응답 내용이 결정).
         const sessionIdForRef = input?.session_id ?? 'unknown';
         emitRecallReferencesFailOpen(sessionIdForRef, lastMessage);
-        // TEST-1/2/3: rule-free meta guards — FORGEN_USER_CONFIRMED=1 우회 공통.
-        // Pathfinder D7: 3중 보일러플레이트를 CHECKS 배열 + for-loop 디스패처로 통합.
-        // Pathfinder D4/D5: sanitizeForGuard 가 모든 체크 입력 단계에 일괄 적용.
+        // TEST-1/2/3 + DANGEROUS: rule-free meta guards — FORGEN_USER_CONFIRMED=1 우회 공통.
+        // ADR-009 §2a: 디스패처 본체를 checks/_shared/meta-guard-dispatch 로 추출 (Stop 과
+        // SubagentStop 이 공유). 여기서는 순수 평가 결과를 받아 recordViolation·blockStop
+        // 부수효과만 수행한다. 평가 순서/sanitize/laziness 는 추출 모듈이 보존.
         if (process.env.FORGEN_USER_CONFIRMED !== '1') {
             const sessionId = input?.session_id ?? 'unknown';
             const recentTools = loadRecentToolNames(sessionId);
-            const sanitized = sanitizeForGuard(lastMessage);
-            // 평가 순서: DANGEROUS-RESPONSE (즉시 차단 — 안전 우선) → TEST-2 (강한 신호) → TEST-3 (텍스트 비율) → TEST-1 (alert-only).
-            const checks = [
-                {
-                    shortId: 'dangerous-response-pattern',
-                    ruleSlug: 'rule:DANGEROUS-RESPONSE — destructive command suggestion',
-                    kind: 'block',
-                    // 주의: sanitizer 가 백틱/코드블록을 제거하므로 raw lastMessage 를 전달.
-                    // 위험 명령은 코드 fence 안에 있어도 동등하게 위험함.
-                    run: () => {
-                        const r = checkDangerousResponsePattern({ text: lastMessage });
-                        return { triggered: r.block, reason: r.reason };
-                    },
-                },
-                {
-                    shortId: 'self-score-inflation',
-                    ruleSlug: 'rule:TEST-2 — self-score inflation',
-                    kind: 'block',
-                    run: () => {
-                        const r = checkSelfScoreInflation({ text: sanitized, recentTools });
-                        return { triggered: r.block, reason: r.reason };
-                    },
-                },
-                {
-                    shortId: 'conclusion-ratio',
-                    ruleSlug: 'rule:TEST-3 — conclusion/verification ratio',
-                    kind: 'block',
-                    run: () => {
-                        const r = checkConclusionVerificationRatio({ text: sanitized });
-                        return { triggered: r.block, reason: r.reason };
-                    },
-                },
-                {
-                    shortId: 'fact-vs-agreement',
-                    ruleSlug: 'rule:TEST-1 — fact vs agreement',
-                    kind: 'correction', // alert-level only per fact-vs-agreement.ts design
-                    run: () => {
-                        const r = checkFactVsAgreement({ text: sanitized, recentTools, minMeasurements: 1 });
-                        return { triggered: r.alert, reason: r.reason };
-                    },
-                },
-            ];
-            for (const c of checks) {
-                const out = c.run();
-                if (!out.triggered)
-                    continue;
+            const results = runMetaGuards({ lastMessage, recentTools, minMeasurements: 1 });
+            for (const r of results) {
                 recordViolation({
-                    rule_id: `builtin:${c.shortId}`,
+                    rule_id: `builtin:${r.shortId}`,
                     session_id: sessionId,
                     source: 'stop-guard',
-                    kind: c.kind,
+                    kind: r.kind,
                     message_preview: lastMessage.slice(0, 120),
                 });
-                if (c.kind !== 'block')
+                if (r.kind !== 'block')
                     continue;
-                const reasonText = `[forgen:stop-guard/${c.shortId}] ${out.reason}
+                const reasonText = `[forgen:stop-guard/${r.shortId}] ${r.reason}
 
 (Override this turn: set FORGEN_USER_CONFIRMED=1 (audited).)`;
-                console.log(blockStop(reasonText, c.ruleSlug));
+                console.log(blockStop(reasonText, r.ruleSlug));
                 return;
             }
         }

package/dist/hooks/subagent-stop-guard.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * Forgen — SubagentStop Guard (ADR-009 §2)
+ *
+ * 워크플로우/Task subagent 의 마지막 응답에 메타 가드(TEST-1/2/3 + DANGEROUS)를
+ * 적용한다. probe 실측(2026-05-29)으로 워크플로우 내부 에이전트도 forgen 훅을
+ * 발화함이 확인되어, 대화 밖에서 수행되는 subagent 산출물도 검증 사각지대에서
+ * 끌어낸다. SubagentStop 은 `decision:"block"` + `reason` 을 지원하므로(공식 문서
+ * 확인) 메인 Stop 과 동일한 Mech-B 재개 메커니즘이 작동한다.
+ *
+ * 설계 (ADR-009 §2a/2c/2d):
+ *   - 평가 본체는 checks/_shared/meta-guard-dispatch.runMetaGuards 를 Stop 과 공유.
+ *   - block-count 는 (sessionId, agentId) 합성 키로 분리 → 동시 subagent 간 stuck-
+ *     loop 카운터 충돌 방지 (2c).
+ *   - recentTools 는 per-agent modified-files (post-tool-use 2d 키) 에서 로드 →
+ *     subagent 자기 tool 윈도우로 TEST-1/2 를 정확히 판정 (2d).
+ *
+ * fail-open: 어떤 단계든 throw/누락이면 approve. subagent 추적/검증은 best-effort —
+ * 에이전트 실행을 막지 않는다.
+ */
+/** SubagentStop 에는 last_assistant_message 가 없으므로 transcript JSONL 을 역순 스캔. */
+export declare function readLastAssistantFromTranscript(transcriptPath?: string): string | null;
+export declare function main(): Promise<void>;

package/dist/hooks/subagent-stop-guard.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Forgen — SubagentStop Guard (ADR-009 §2)
+ *
+ * 워크플로우/Task subagent 의 마지막 응답에 메타 가드(TEST-1/2/3 + DANGEROUS)를
+ * 적용한다. probe 실측(2026-05-29)으로 워크플로우 내부 에이전트도 forgen 훅을
+ * 발화함이 확인되어, 대화 밖에서 수행되는 subagent 산출물도 검증 사각지대에서
+ * 끌어낸다. SubagentStop 은 `decision:"block"` + `reason` 을 지원하므로(공식 문서
+ * 확인) 메인 Stop 과 동일한 Mech-B 재개 메커니즘이 작동한다.
+ *
+ * 설계 (ADR-009 §2a/2c/2d):
+ *   - 평가 본체는 checks/_shared/meta-guard-dispatch.runMetaGuards 를 Stop 과 공유.
+ *   - block-count 는 (sessionId, agentId) 합성 키로 분리 → 동시 subagent 간 stuck-
+ *     loop 카운터 충돌 방지 (2c).
+ *   - recentTools 는 per-agent modified-files (post-tool-use 2d 키) 에서 로드 →
+ *     subagent 자기 tool 윈도우로 TEST-1/2 를 정확히 판정 (2d).
+ *
+ * fail-open: 어떤 단계든 throw/누락이면 approve. subagent 추적/검증은 best-effort —
+ * 에이전트 실행을 막지 않는다.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { readStdinJSON } from './shared/read-stdin.js';
+import { approve, blockStop, failOpenWithTracking } from './shared/hook-response.js';
+import { isHookEnabled } from './hook-config.js';
+import { sanitizeId } from './shared/sanitize-id.js';
+import { recordHookTiming } from './shared/hook-timing.js';
+import { STATE_DIR } from '../core/paths.js';
+import { runMetaGuards } from '../checks/_shared/meta-guard-dispatch.js';
+import { recordViolation } from '../engine/lifecycle/signals.js';
+import { incrementBlockCount, resetBlockCount, getStuckLoopThreshold, logDriftEvent, } from './stop-guard.js';
+const HOOK_NAME = 'subagent-stop-guard';
+/** SubagentStop 에는 last_assistant_message 가 없으므로 transcript JSONL 을 역순 스캔. */
+export function readLastAssistantFromTranscript(transcriptPath) {
+    if (!transcriptPath)
+        return null;
+    try {
+        const lines = fs.readFileSync(transcriptPath, 'utf-8').trim().split('\n');
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i].trim();
+            if (!line)
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                if (entry.role !== 'assistant')
+                    continue;
+                if (typeof entry.content === 'string')
+                    return entry.content;
+                if (Array.isArray(entry.content)) {
+                    const parts = entry.content
+                        .map((p) => {
+                        if (typeof p === 'string')
+                            return p;
+                        if (p && typeof p === 'object' && 'text' in p)
+                            return String(p.text);
+                        return '';
+                    })
+                        .filter(Boolean);
+                    if (parts.length)
+                        return parts.join('\n');
+                }
+            }
+            catch {
+                // skip malformed line
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** ADR-009 §2d: per-agent modified-files 에서 recentToolNames 로드. 없으면 []. */
+function loadAgentRecentTools(sessionId, agentId) {
+    try {
+        const key = `${sessionId}.agent-${agentId}`;
+        const p = path.join(STATE_DIR, `modified-files-${sanitizeId(key)}.json`);
+        if (!fs.existsSync(p))
+            return [];
+        const data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (Array.isArray(data.recentToolNames)) {
+            return data.recentToolNames.filter((n) => typeof n === 'string');
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function main() {
+    const started = Date.now();
+    try {
+        if (!isHookEnabled(HOOK_NAME)) {
+            console.log(approve());
+            return;
+        }
+        const input = await readStdinJSON();
+        const lastMessage = readLastAssistantFromTranscript(input?.transcript_path);
+        if (!lastMessage) {
+            console.log(approve());
+            return;
+        }
+        // 사용자 명시 우회 — 메인 Stop 과 일관.
+        if (process.env.FORGEN_USER_CONFIRMED === '1') {
+            console.log(approve());
+            return;
+        }
+        const sessionId = input?.session_id ?? 'unknown';
+        const agentId = input?.agent_id ?? input?.agentId ?? 'unknown';
+        const recentTools = loadAgentRecentTools(sessionId, agentId);
+        const results = runMetaGuards({ lastMessage, recentTools, minMeasurements: 1 });
+        // 2c: stuck-loop 카운터를 (sessionId, agentId) 로 분리해 동시 subagent 간 충돌 방지.
+        const counterKey = `${sessionId}:${agentId}`;
+        for (const r of results) {
+            recordViolation({
+                rule_id: `builtin:${r.shortId}`,
+                session_id: sessionId,
+                source: HOOK_NAME,
+                kind: r.kind,
+                message_preview: lastMessage.slice(0, 120),
+            });
+            if (r.kind !== 'block')
+                continue;
+            const count = incrementBlockCount(counterKey, r.shortId);
+            if (count > getStuckLoopThreshold()) {
+                // 같은 subagent 가 같은 가드에 반복 차단 → block reason 에 말려든 루프.
+                // force approve + drift 기록 후 카운터 리셋 (메인 Stop 과 동일 정책).
+                logDriftEvent({
+                    kind: 'subagent_stuck_loop_force_approve',
+                    session_id: counterKey,
+                    rule_id: r.shortId,
+                    count,
+                    reason_preview: r.reason.slice(0, 120),
+                    message_preview: lastMessage.slice(0, 120),
+                });
+                resetBlockCount(counterKey, r.shortId);
+                console.log(approve());
+                return;
+            }
+            const reasonText = `[forgen:subagent-stop-guard/${r.shortId}] (agent ${agentId.slice(0, 8)}) ${r.reason}
+
+(Override this turn: set FORGEN_USER_CONFIRMED=1 (audited).)`;
+            console.log(blockStop(reasonText, r.ruleSlug));
+            return;
+        }
+        console.log(approve());
+    }
+    catch (e) {
+        console.log(failOpenWithTracking(HOOK_NAME, e));
+    }
+    finally {
+        recordHookTiming(HOOK_NAME, Date.now() - started, 'SubagentStop');
+    }
+}
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+    void main();
+}

package/dist/hooks/subagent-tracker.d.ts

@@ -3,8 +3,41 @@
  * Forgen — SubagentStart/Stop Hook
  *
  * 에이전트 생성/종료 추적.
- * - 활성 에이전트 수 모니터링
- * - 에이전트 동시 실행 제한 (10개 초과 시 경고)
+ * - 활성 에이전트 수 모니터링 + 동시 실행 경고 (ADR-009 §4: 기본 16, workflow 면제)
  * - 에이전트 실행 이력 기록
+ * - ADR-009 §A: 상태 갱신을 file-lock 으로 보호 (동시 fanout lost-update 방지)
  */
-export {};
+/**
+ * 동시 에이전트 경고 임계값.
+ * ADR-009 §4: dynamic workflows 는 동시 16 까지 정상 사용하므로 기본값을 16 으로
+ * 올리고 env 로 조정 가능하게 한다. 과거 10 고정값은 workflow/team/swarm 실행마다
+ * 거짓 경고를 뱉었다.
+ */
+export declare function maxConcurrentAgents(): number;
+/**
+ * 동시성 경고를 띄울지 결정 (순수 — 테스트 대상).
+ * ADR-009 §4/§B: workflow-subagent 는 동시 16 이 정상이므로 면제. 그 외 에이전트가
+ * 임계값을 초과할 때만 경고.
+ */
+export declare function shouldWarnConcurrency(agentType: string, activeCount: number, max: number): boolean;
+export interface AgentEvent {
+    sessionId: string;
+    action: 'start' | 'stop';
+    agentId: string;
+    agentType?: string;
+    model?: string;
+}
+/**
+ * 에이전트 이벤트를 file-lock 아래에서 적용한다 (ADR-009 §A).
+ *
+ * 락이 없던 시절에는 동시 SubagentStart (워크플로우 fanout) 가 같은 active-agents
+ * 파일을 read-modify-write 하면서 lost-update 로 일부 에이전트가 누락됐다 (probe 에서
+ * 3개 중 1개 손실 관찰). 락 안에서 **fresh re-read** 후 mutate 해야 변경이 보존된다.
+ * staleMs 는 hook fn 이 짧으므로 5s 로 단축.
+ *
+ * statePath 는 테스트 주입용 (기본은 sessionId 파생 경로). 반환값은 start 후 활성
+ * 에이전트 수 (경고 판정에 사용; stop 은 0).
+ */
+export declare function recordAgentEvent(ev: AgentEvent, statePath?: string): Promise<{
+    activeCount: number;
+}>;