triflux 10.3.4 → 10.7.0

package/hooks/hook-orchestrator.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+
 // hooks/hook-orchestrator.mjs — 범용 훅 체이닝 엔진
 //
 // settings.json에 이벤트당 하나만 등록. stdin JSON에서 이벤트명+툴명을 읽고
@@ -19,10 +20,11 @@
 //   CLAUDE_PLUGIN_ROOT    — ${PLUGIN_ROOT} 치환용
 //   HOME / USERPROFILE    — ${HOME} 치환용
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { execFileSync, execFile } from "node:child_process";
 import { PLUGIN_ROOT } from "./lib/resolve-root.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -84,7 +86,8 @@ function executeHook(hook, stdinData) {
   // "bash script.sh" → ["bash", ["script.sh"]]
   // 따옴표 처리 포함
   const parts = parseCommand(cmd);
-  if (parts.length === 0) return { code: 1, stdout: "", stderr: "empty command" };
+  if (parts.length === 0)
+    return { code: 1, stdout: "", stderr: "empty command" };
 
   const [executable, ...args] = parts;
 
@@ -114,20 +117,35 @@ function executeHookAsync(hook, stdinData) {
     const cmd = resolveCommand(hook.command);
     const timeout = (hook.timeout || 10) * 1000;
     const parts = parseCommand(cmd);
-    if (parts.length === 0) { resolve({ code: 1, stdout: "", stderr: "empty command" }); return; }
+    if (parts.length === 0) {
+      resolve({ code: 1, stdout: "", stderr: "empty command" });
+      return;
+    }
     const [executable, ...args] = parts;
-    const child = execFile(executable, args, {
-      timeout,
-      encoding: "utf8",
-      windowsHide: true,
-      cwd: process.cwd(),
-      env: { ...process.env },
-    }, (err, stdout, stderr) => {
-      if (err) resolve({ code: err.status ?? 1, stdout: stdout || "", stderr: stderr || "" });
-      else resolve({ code: 0, stdout: stdout || "", stderr: "" });
-    });
-    if (stdinData) { child.stdin.write(stdinData); child.stdin.end(); }
-    else child.stdin.end();
+    const child = execFile(
+      executable,
+      args,
+      {
+        timeout,
+        encoding: "utf8",
+        windowsHide: true,
+        cwd: process.cwd(),
+        env: { ...process.env },
+      },
+      (err, stdout, stderr) => {
+        if (err)
+          resolve({
+            code: err.status ?? 1,
+            stdout: stdout || "",
+            stderr: stderr || "",
+          });
+        else resolve({ code: 0, stdout: stdout || "", stderr: "" });
+      },
+    );
+    if (stdinData) {
+      child.stdin.write(stdinData);
+      child.stdin.end();
+    } else child.stdin.end();
   });
 }
 
@@ -170,11 +188,19 @@ function mergeOutputs(accumulated, newOutput) {
 
     // hookSpecificOutput 머지 — additionalContext는 누적, 나머지는 덮어쓰기
     if (parsed.hookSpecificOutput) {
-      if (accumulated.hookSpecificOutput?.additionalContext && parsed.hookSpecificOutput.additionalContext) {
+      if (
+        accumulated.hookSpecificOutput?.additionalContext &&
+        parsed.hookSpecificOutput.additionalContext
+      ) {
         parsed.hookSpecificOutput.additionalContext =
-          accumulated.hookSpecificOutput.additionalContext + "\n" + parsed.hookSpecificOutput.additionalContext;
+          accumulated.hookSpecificOutput.additionalContext +
+          "\n" +
+          parsed.hookSpecificOutput.additionalContext;
       }
-      accumulated.hookSpecificOutput = { ...accumulated.hookSpecificOutput, ...parsed.hookSpecificOutput };
+      accumulated.hookSpecificOutput = {
+        ...accumulated.hookSpecificOutput,
+        ...parsed.hookSpecificOutput,
+      };
     }
     // systemMessage는 누적
     if (parsed.systemMessage) {
@@ -220,7 +246,12 @@ function recordRouteOutcome(slug, mode, outcome) {
 
   const weights = existsSync(weightsPath)
     ? JSON.parse(readFileSync(weightsPath, "utf8"))
-    : { updated_at: null, total_routes: 0, overrides: 0, weights: { mode_bias: {}, profile_bias: {}, depth_bias: {} } };
+    : {
+        updated_at: null,
+        total_routes: 0,
+        overrides: 0,
+        weights: { mode_bias: {}, profile_bias: {}, depth_bias: {} },
+      };
 
   weights.total_routes++;
   weights.updated_at = new Date().toISOString();
@@ -284,6 +315,32 @@ async function main() {
 
   if (!eventName) process.exit(0);
 
+  // ── SessionStart fast-path ──
+  // TRIFLUX_HOOK_FAST_PATH=false로 비활성화 가능 (rollback)
+  if (eventName === "SessionStart" && process.env.TRIFLUX_HOOK_FAST_PATH !== "false") {
+    try {
+      const { execute } = await import("./session-start-fast.mjs");
+      const result = await execute(stdinRaw);
+      if (result.stdout?.trim()) {
+        const output = { additionalContext: result.stdout.trim() };
+        process.stdout.write(JSON.stringify(output));
+      }
+
+      // external source 훅 (session-vault 등)은 기존 방식으로 실행
+      const allHooks = registry.events.SessionStart || [];
+      const externalHooks = allHooks.filter((h) => h.enabled !== false && h.source !== "triflux");
+      for (const hook of externalHooks) {
+        const hookResult = executeHookAsync(hook, stdinRaw);
+        hookResult.catch(() => {}); // fire-and-forget for external hooks
+      }
+
+      process.exit(0);
+    } catch (err) {
+      // fast-path 실패 시 기존 방식으로 폴백
+      process.stderr.write(`[orchestrator] fast-path failed, falling back: ${err.message}\n`);
+    }
+  }
+
   // 이벤트에 해당하는 훅 목록
   const hooks = registry.events[eventName];
   if (!hooks || hooks.length === 0) process.exit(0);
@@ -326,7 +383,9 @@ async function main() {
       }
     } else {
       // 같은 priority 다중 훅 — 비동기 병렬 실행
-      const results = await Promise.all(group.hooks.map((h) => executeHookAsync(h, stdinRaw)));
+      const results = await Promise.all(
+        group.hooks.map((h) => executeHookAsync(h, stdinRaw)),
+      );
       for (const result of results) {
         if (result.code === 2) {
           if (result.stderr) process.stderr.write(result.stderr);
@@ -340,18 +399,43 @@ async function main() {
     }
   }
 
+  // ── PostToolUse: 컨텍스트 압축 nudge (인라인, 프로세스 추가 없음) ──
+  if (eventName === "PostToolUse" && !blocked) {
+    try {
+      const home = process.env.HOME || process.env.USERPROFILE || "";
+      const snapshotPath = join(home, ".claude", "cache", "tfx-hub", "context-monitor.json");
+      const nudgeMarker = join(tmpdir(), "tfx-compact-nudge-sent");
+      if (existsSync(snapshotPath) && !existsSync(nudgeMarker)) {
+        const snap = JSON.parse(readFileSync(snapshotPath, "utf8"));
+        const percent = Number(snap.percent || 0);
+        if (percent >= 80) {
+          const level = percent >= 90 ? "critical" : "warn";
+          const msg = level === "critical"
+            ? `[context ${percent}%] 컨텍스트 ${percent}% 사용. /compact 또는 에이전트 분할을 강력 권장합니다.`
+            : `[context ${percent}%] 컨텍스트 ${percent}% 사용. 마일스톤이면 /compact를 권장합니다.`;
+          mergedOutput = mergeOutputs(mergedOutput, JSON.stringify({ systemMessage: msg }));
+          if (level === "warn") {
+            writeFileSync(nudgeMarker, new Date().toISOString());
+          }
+        }
+      }
+    } catch { /* 컨텍스트 모니터 읽기 실패 무시 */ }
+  }
+
   // ── PostToolUse:Skill 완료 시 라우팅 가중치 기록 ──
   if (eventName === "PostToolUse" && toolName === "Skill" && !blocked) {
     try {
       const input = JSON.parse(stdinRaw);
       const skillName = input.tool_input?.skill || "";
-      if (skillName && skillName.startsWith("tfx-")) {
+      if (skillName?.startsWith("tfx-")) {
         const mode = skillName.replace(/^tfx-/, "");
         const gitRoot = process.env.GIT_WORK_TREE || process.cwd();
         const slug = gitRoot.split(/[\\/]/).pop() || "unknown";
         recordRouteOutcome(slug, mode, "completion");
       }
-    } catch { /* 가중치 기록 실패 무시 */ }
+    } catch {
+      /* 가중치 기록 실패 무시 */
+    }
   }
 
   // 결과 출력

package/hooks/hook-registry.json

@@ -192,6 +192,17 @@
         "blocking": false,
         "description": "supergateway MCP 서비스 헬스체크 및 자동 기동"
       },
+      {
+        "id": "tfx-session-stale-cleanup",
+        "source": "triflux",
+        "matcher": "*",
+        "command": "node \"${PLUGIN_ROOT}/scripts/session-stale-cleanup.mjs\"",
+        "priority": 5,
+        "enabled": true,
+        "timeout": 3,
+        "blocking": false,
+        "description": "이전 세션의 stale tfx-multi 상태 파일 정리 (#62)"
+      },
       {
         "id": "ext-session-vault-start",
         "source": "session-vault",

package/hooks/keyword-rules.json

@@ -11,12 +11,7 @@
       "skill": null,
       "action": "suppress_all",
       "priority": 0,
-      "supersedes": [
-        "tfx-multi",
-        "tfx-unified",
-        "tfx-codex",
-        "tfx-gemini"
-      ],
+      "supersedes": ["tfx-multi", "tfx-unified", "tfx-codex", "tfx-gemini"],
       "exclusive": true,
       "state": null,
       "mcp_route": null
@@ -62,9 +57,7 @@
       ],
       "skill": "tfx-swarm",
       "priority": 1,
-      "supersedes": [
-        "tfx-codex"
-      ],
+      "supersedes": ["tfx-codex"],
       "exclusive": false,
       "state": null,
       "mcp_route": null
@@ -80,7 +73,10 @@
         { "source": "(?:분석해|계획|설계해)", "flags": "i" },
         { "source": "(?:찾아봐|조사해|검색해)", "flags": "i" },
         { "source": "(?:정리해|슬롭|클린업)", "flags": "i" },
-        { "source": "\\b(?:implement|build|fix|review|test|plan|analyze)\\b", "flags": "i" }
+        {
+          "source": "\\b(?:implement|build|fix|review|test|plan|analyze)\\b",
+          "flags": "i"
+        }
       ],
       "skill": "tfx-auto",
       "priority": 2,

package/hooks/lib/resolve-root.mjs

@@ -51,7 +51,7 @@ export function resolvePluginRoot(callerUrl) {
 
   const moduleFallback = toPluginRootFromUrl(import.meta.url) || process.cwd();
   process.stderr.write(
-    `[resolve-root] warning: failed to resolve plugin root from breadcrumb/env/caller; fallback=${moduleFallback}\n`
+    `[resolve-root] warning: failed to resolve plugin root from breadcrumb/env/caller; fallback=${moduleFallback}\n`,
   );
   return moduleFallback;
 }

package/hooks/mcp-config-watcher.mjs

@@ -25,10 +25,14 @@ function buildSystemMessage(filePath, stdioServers, result) {
 
   if (result.modified) {
     const actionLabel = result.replacement ? "자동 치환" : "자동 제거";
-    lines.push(`[mcp-guard] stdio MCP ${actionLabel}: ${stdioServers.map((server) => server.name).join(", ")}`);
+    lines.push(
+      `[mcp-guard] stdio MCP ${actionLabel}: ${stdioServers.map((server) => server.name).join(", ")}`,
+    );
 
     if (result.replacement?.name && result.replacement?.url) {
-      lines.push(`[mcp-guard] 대체 서버: ${result.replacement.name} -> ${result.replacement.url}`);
+      lines.push(
+        `[mcp-guard] 대체 서버: ${result.replacement.name} -> ${result.replacement.url}`,
+      );
     }
 
     if (result.backupPath) {

package/hooks/pipeline-stop.mjs

@@ -11,11 +11,8 @@ let getPipelineStateDbPath;
 let ensurePipelineTable;
 let listPipelineStates;
 try {
-  ({
-    getPipelineStateDbPath,
-    ensurePipelineTable,
-    listPipelineStates,
-  } = await import("../hub/pipeline/state.mjs"));
+  ({ getPipelineStateDbPath, ensurePipelineTable, listPipelineStates } =
+    await import("../hub/pipeline/state.mjs"));
 } catch {
   // hub/pipeline 모듈 없으면 훅 무동작
   process.exit(0);
@@ -53,7 +50,7 @@ try {
   // 활성 파이프라인 발견 → 구조화 decision으로 block
   const lines = active.map(
     (s) =>
-      `  - 팀 ${s.team_name}: ${s.phase} 단계 (fix: ${s.fix_attempt}/${s.fix_max}, ralph: ${s.ralph_iteration}/${s.ralph_max})`
+      `  - 팀 ${s.team_name}: ${s.phase} 단계 (fix: ${s.fix_attempt}/${s.fix_max}, ralph: ${s.ralph_iteration}/${s.ralph_max})`,
   );
 
   const reason =

package/hooks/safety-guard.mjs

@@ -8,23 +8,51 @@
 //   BLOCK (exit 2)  — 복구 불가능한 파괴적 명령
 //   WARN  (allow + context) — 주의가 필요한 명령
 
-import { readFileSync, existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 // ── 차단 규칙 ──────────────────────────────────────────────
 const BLOCK_RULES = [
-  { pattern: /\brm\s+(-[^\s]*)?-rf?\s+[/~](?!tmp\b)(?!\S*node_modules)/i, reason: "루트/홈 디렉토리 rm -rf 차단" },
-  { pattern: /\brm\s+(-[^\s]*)?-rf?\s+\.\s*$/i, reason: "현재 디렉토리 rm -rf . 차단" },
-  { pattern: /\bgit\s+push\s+.*--force\s+.*\b(main|master)\b/i, reason: "main/master force push 차단" },
-  { pattern: /\bgit\s+push\s+--force\s*$/i, reason: "대상 미지정 force push 차단" },
-  { pattern: /\bgit\s+reset\s+--hard\s+origin\//i, reason: "remote reset --hard 차단 — 로컬 작업 소실 위험" },
+  {
+    pattern: /\brm\s+(-[^\s]*)?-rf?\s+[/~](?!tmp\b)(?!\S*node_modules)/i,
+    reason: "루트/홈 디렉토리 rm -rf 차단",
+  },
+  {
+    pattern: /\brm\s+(-[^\s]*)?-rf?\s+\.\s*$/i,
+    reason: "현재 디렉토리 rm -rf . 차단",
+  },
+  {
+    pattern: /\bgit\s+push\s+.*--force\s+.*\b(main|master)\b/i,
+    reason: "main/master force push 차단",
+  },
+  {
+    pattern: /\bgit\s+push\s+--force\s*$/i,
+    reason: "대상 미지정 force push 차단",
+  },
+  {
+    pattern: /\bgit\s+reset\s+--hard\s+origin\//i,
+    reason: "remote reset --hard 차단 — 로컬 작업 소실 위험",
+  },
   { pattern: /\bdrop\s+(table|database|schema)\b/i, reason: "SQL DROP 차단" },
   { pattern: /\btruncate\s+table\b/i, reason: "SQL TRUNCATE 차단" },
   { pattern: /\bformat\s+[a-z]:/i, reason: "디스크 포맷 차단" },
   { pattern: /\b(del|rmdir)\s+\/[sq]\b/i, reason: "Windows 재귀 삭제 차단" },
-  { pattern: /\bgit\s+clean\s+.*-fd/i, reason: "git clean -fd 차단 — 추적되지 않은 파일 소실 위험" },
-  { pattern: /\bpsmux\s+kill-session\b/i, reason: "raw psmux kill-session 차단 — WT ConPTY 프리징 위험. 안전 경로: node hub/team/psmux.mjs kill --session <name>", skipIfGit: true },
-  { pattern: /\bpsmux\s+kill-server\b/i, reason: "psmux kill-server 차단 — 모든 세션이 즉시 종료됩니다. node hub/team/psmux.mjs kill-swarm 사용", skipIfGit: true },
+  {
+    pattern: /\bgit\s+clean\s+.*-fd/i,
+    reason: "git clean -fd 차단 — 추적되지 않은 파일 소실 위험",
+  },
+  {
+    pattern: /\bpsmux\s+kill-session\b/i,
+    reason:
+      "raw psmux kill-session 차단 — WT ConPTY 프리징 위험. 안전 경로: node hub/team/psmux.mjs kill --session <name>",
+    skipIfGit: true,
+  },
+  {
+    pattern: /\bpsmux\s+kill-server\b/i,
+    reason:
+      "psmux kill-server 차단 — 모든 세션이 즉시 종료됩니다. node hub/team/psmux.mjs kill-swarm 사용",
+    skipIfGit: true,
+  },
 ];
 
 const WT_DIRECT_PATTERNS = [
@@ -42,12 +70,12 @@ const WT_DIRECT_BLOCK_MESSAGE =
 // ── SSH+PowerShell bash 문법 차단 ────────────────────────────
 // 원격 기본 셸이 PowerShell인 호스트에 bash redirect/glob을 보내면 오동작
 const BASH_SYNTAX_IN_SSH = [
-  /2>\/dev\/null/,          // 2>/dev/null → PowerShell에서 Out-File C:\dev\null
-  />\s*\/dev\/null/,        // >/dev/null
-  /&>\s*\/dev\/null/,       // &>/dev/null
-  /\$\(/,                   // $(cmd) → PowerShell에서 다른 의미
-  /\bsource\s+/,            // source → PowerShell에 없음
-  /\bexport\s+\w+=/,        // export VAR= → PowerShell에 없음
+  /2>\/dev\/null/, // 2>/dev/null → PowerShell에서 Out-File C:\dev\null
+  />\s*\/dev\/null/, // >/dev/null
+  /&>\s*\/dev\/null/, // &>/dev/null
+  /\$\(/, // $(cmd) → PowerShell에서 다른 의미
+  /\bsource\s+/, // source → PowerShell에 없음
+  /\bexport\s+\w+=/, // export VAR= → PowerShell에 없음
 ];
 
 const SSH_POWERSHELL_HINT =
@@ -56,28 +84,59 @@ const SSH_POWERSHELL_HINT =
 
 // ── 경고 규칙 ──────────────────────────────────────────────
 const WARN_RULES = [
-  { pattern: /\bgit\s+push\b(?!.*--force)/i, warn: "git push 감지. 원격 저장소에 반영됩니다." },
-  { pattern: /\bgit\s+rebase\b/i, warn: "git rebase 감지. 커밋 히스토리가 변경됩니다." },
+  {
+    pattern: /\bgit\s+push\b(?!.*--force)/i,
+    warn: "git push 감지. 원격 저장소에 반영됩니다.",
+  },
+  {
+    pattern: /\bgit\s+rebase\b/i,
+    warn: "git rebase 감지. 커밋 히스토리가 변경됩니다.",
+  },
   { pattern: /\bgit\s+branch\s+-[dD]\b/i, warn: "브랜치 삭제 감지." },
-  { pattern: /\bnpm\s+publish\b/i, warn: "npm publish 감지. 공개 레지스트리에 배포됩니다." },
-  { pattern: /\brm\s+(-[^\s]*)?-rf?\s/i, warn: "재귀 삭제 감지. 대상을 확인하세요." },
-  { pattern: /--no-verify\b/i, warn: "--no-verify 감지. 훅 건너뛰기는 권장하지 않습니다." },
+  {
+    pattern: /\bnpm\s+publish\b/i,
+    warn: "npm publish 감지. 공개 레지스트리에 배포됩니다.",
+  },
+  {
+    pattern: /\brm\s+(-[^\s]*)?-rf?\s/i,
+    warn: "재귀 삭제 감지. 대상을 확인하세요.",
+  },
+  {
+    pattern: /--no-verify\b/i,
+    warn: "--no-verify 감지. 훅 건너뛰기는 권장하지 않습니다.",
+  },
   { pattern: /\bchmod\s+777\b/i, warn: "chmod 777 감지. 보안 위험." },
-  { pattern: /\bcurl\s.*\|\s*(bash|sh)\b/i, warn: "curl | sh 감지. 원격 스크립트 실행 주의." },
+  {
+    pattern: /\bcurl\s.*\|\s*(bash|sh)\b/i,
+    warn: "curl | sh 감지. 원격 스크립트 실행 주의.",
+  },
 ];
 
 // ── reflexion 적응형 패널티 로드 ──────────────────────────────
 function loadReflexionPenalties() {
   try {
     const home = process.env.HOME || process.env.USERPROFILE || "";
-    const penaltyFile = join(home, ".triflux", "reflexion", "pending-penalties.jsonl");
+    const penaltyFile = join(
+      home,
+      ".triflux",
+      "reflexion",
+      "pending-penalties.jsonl",
+    );
     if (!existsSync(penaltyFile)) return [];
     return readFileSync(penaltyFile, "utf8")
       .split("\n")
       .filter(Boolean)
-      .map(line => { try { return JSON.parse(line); } catch { return null; } })
+      .map((line) => {
+        try {
+          return JSON.parse(line);
+        } catch {
+          return null;
+        }
+      })
       .filter(Boolean);
-  } catch { return []; }
+  } catch {
+    return [];
+  }
 }
 
 function readStdin() {
@@ -89,7 +148,11 @@ function readStdin() {
 }
 
 function shouldSkipSegment(segment) {
-  return !segment || segment.startsWith("#") || /^\s*(echo|printf|grep|git\s+commit)\b/i.test(segment);
+  return (
+    !segment ||
+    segment.startsWith("#") ||
+    /^\s*(echo|printf|grep|git\s+commit)\b/i.test(segment)
+  );
 }
 
 function hasSegmentInvocation(cmd, patterns) {
@@ -122,7 +185,7 @@ function blockCommand(message, command) {
   process.stderr.write(
     `${message}\n` +
       `명령어: ${command.slice(0, 120)}${command.length > 120 ? "..." : ""}\n` +
-      "이 명령은 실행할 수 없습니다. 안전한 대안을 사용하세요."
+      "이 명령은 실행할 수 없습니다. 안전한 대안을 사용하세요.",
   );
   process.exit(2);
 }
@@ -161,7 +224,15 @@ function main() {
   const penalties = loadReflexionPenalties();
   if (penalties.length > 0) {
     for (const penalty of penalties) {
-      if (penalty.error_pattern && new RegExp(penalty.error_pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").slice(0, 80), "i").test(command)) {
+      if (
+        penalty.error_pattern &&
+        new RegExp(
+          penalty.error_pattern
+            .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+            .slice(0, 80),
+          "i",
+        ).test(command)
+      ) {
         const output = {
           hookSpecificOutput: {
             hookEventName: "PreToolUse",
@@ -186,7 +257,7 @@ function main() {
       const sshMatch = seg.trim().match(/^ssh\s+\S+\s+(.*)/s);
       if (!sshMatch) continue;
       const sshPayload = sshMatch[1];
-      const bashSyntax = BASH_SYNTAX_IN_SSH.find(p => p.test(sshPayload));
+      const bashSyntax = BASH_SYNTAX_IN_SSH.find((p) => p.test(sshPayload));
       if (bashSyntax) {
         blockCommand(
           `[safety-guard] SSH 명령에 bash 전용 문법 감지: ${bashSyntax}. ${SSH_POWERSHELL_HINT}`,

package/hooks/session-start-fast.mjs

@@ -0,0 +1,143 @@
+// hooks/session-start-fast.mjs — SessionStart in-process fast-path
+//
+// hook-orchestrator.mjs가 SessionStart 이벤트일 때 이 모듈을 dynamic import.
+// 6개 훅을 1개 node 프로세스 안에서 실행하여 콜드스타트 7회 → 1회로 줄인다.
+//
+// 분류:
+//   BLOCKING  (직렬, stdout 반환 전 완료): setup.runCritical, mcp-safety-guard.run
+//   DEFERRED  (병렬, 실패해도 안 죽음):   hub-ensure.run, mcp-gateway-ensure.run, setup.runDeferred
+//   BACKGROUND (fire-and-forget):          preflight-cache.run
+//
+// external source 훅 (session-vault 등)은 여전히 execFile로 실행된다.
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createModuleLogger } from "../scripts/lib/logger.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCRIPTS = join(__dirname, "..", "scripts");
+
+const log = createModuleLogger("session-start-fast");
+
+/**
+ * BLOCKING 훅을 순차 실행. 하나라도 throw하면 로그만 남기고 계속.
+ * @param {string} stdinData
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ */
+async function runBlocking(stdinData) {
+  const output = { stdout: "", stderr: "" };
+  const timings = [];
+
+  // 1. setup.runCritical — 환경 초기화 필수
+  try {
+    const t0 = performance.now();
+    const setup = await import(join(SCRIPTS, "setup.mjs"));
+    const result = await setup.runCritical(stdinData);
+    const dur = performance.now() - t0;
+    timings.push({ hook: "setup.critical", dur_ms: Math.round(dur) });
+    if (result?.stdout) output.stdout += result.stdout + "\n";
+    if (result?.stderr) output.stderr += result.stderr + "\n";
+    log.info({ hook: "setup.critical", dur_ms: Math.round(dur) }, "hook.completed");
+  } catch (err) {
+    log.error({ hook: "setup.critical", err: String(err.message || err) }, "hook.failed");
+  }
+
+  // 2. mcp-safety-guard.run — EPERM 방지
+  try {
+    const t0 = performance.now();
+    const guard = await import(join(SCRIPTS, "mcp-safety-guard.mjs"));
+    guard.run();
+    const dur = performance.now() - t0;
+    timings.push({ hook: "mcp-safety-guard", dur_ms: Math.round(dur) });
+    log.info({ hook: "mcp-safety-guard", dur_ms: Math.round(dur) }, "hook.completed");
+  } catch (err) {
+    log.error({ hook: "mcp-safety-guard", err: String(err.message || err) }, "hook.failed");
+  }
+
+  return { ...output, timings };
+}
+
+/**
+ * DEFERRED 훅을 병렬 실행. 실패해도 crash 안 함, 로그만 남김.
+ * Promise는 의도적으로 관리하지 않음 (fire-and-forget with logging).
+ * @param {string} stdinData
+ */
+function runDeferred(stdinData) {
+  const tasks = [
+    {
+      name: "hub-ensure",
+      fn: async () => {
+        const mod = await import(join(SCRIPTS, "hub-ensure.mjs"));
+        return mod.run(stdinData);
+      },
+    },
+    {
+      name: "mcp-gateway-ensure",
+      fn: async () => {
+        const mod = await import(join(SCRIPTS, "mcp-gateway-ensure.mjs"));
+        return mod.run(stdinData);
+      },
+    },
+    {
+      name: "setup.deferred",
+      fn: async () => {
+        const mod = await import(join(SCRIPTS, "setup.mjs"));
+        return mod.runDeferred(stdinData);
+      },
+    },
+  ];
+
+  for (const task of tasks) {
+    const t0 = performance.now();
+    task.fn()
+      .then((result) => {
+        const dur = performance.now() - t0;
+        log.info({ hook: task.name, dur_ms: Math.round(dur), code: result?.code }, "deferred.completed");
+      })
+      .catch((err) => {
+        const dur = performance.now() - t0;
+        log.error({ hook: task.name, dur_ms: Math.round(dur), err: String(err.message || err) }, "deferred.failed");
+      });
+  }
+}
+
+/**
+ * BACKGROUND 훅. fire-and-forget.
+ * @param {string} stdinData
+ */
+function runBackground(stdinData) {
+  // preflight-cache
+  import(join(SCRIPTS, "preflight-cache.mjs"))
+    .then((mod) => mod.run(stdinData))
+    .catch(() => {}); // 완전 무시
+
+  // session-vault은 external source — hook-orchestrator가 execFile로 실행
+}
+
+/**
+ * SessionStart fast-path 진입점.
+ * hook-orchestrator.mjs에서 호출된다.
+ *
+ * @param {string} stdinData — orchestrator가 전달하는 stdin JSON
+ * @param {Array} externalHooks — source !== 'triflux'인 훅 목록 (orchestrator가 execFile로 실행)
+ * @returns {Promise<{stdout: string, stderr: string, timings: Array}>}
+ */
+export async function execute(stdinData, externalHooks = []) {
+  const totalStart = performance.now();
+
+  // BLOCKING: 프롬프트 전 완료 필수
+  const blocking = await runBlocking(stdinData);
+
+  // DEFERRED + BACKGROUND: fire-and-forget
+  runDeferred(stdinData);
+  runBackground(stdinData);
+
+  const totalDur = performance.now() - totalStart;
+  log.info({ total_ms: Math.round(totalDur), blocking_count: 2, deferred_count: 3, bg_count: 1 }, "session-start.done");
+
+  return {
+    stdout: blocking.stdout,
+    stderr: blocking.stderr,
+    timings: blocking.timings,
+  };
+}