triflux 10.30.1 → 10.32.0

package/hooks/codex-session-hook.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { argv, exit, stdin, stdout } from "node:process";
+import { pathToFileURL } from "node:url";
+import { drainPendingSynapse as defaultDrainPendingSynapse } from "../hub/team/synapse-http.mjs";
+import {
+  heartbeatInteractiveSession as defaultHeartbeatInteractiveSession,
+  registerInteractiveSession as defaultRegisterInteractiveSession,
+} from "./session-start-fast.mjs";
+
+// hub-ensure is loaded lazily so the byte-identical packages/core mirror of this
+// file loads cleanly. packages/core mirrors scripts/lib only (not scripts/*), so a
+// static `../scripts/hub-ensure.mjs` import would make the core copy throw
+// ERR_MODULE_NOT_FOUND at load time. The core copy is published-but-dormant — the
+// live codex hook always runs from the installed triflux package where the path
+// resolves. This mirrors session-start-fast.mjs's dynamic script-import pattern.
+async function defaultHubEnsureRun(stdinData) {
+  const { run } = await import(
+    new URL("../scripts/hub-ensure.mjs", import.meta.url).href
+  );
+  return run(stdinData);
+}
+
+function parsePayload(stdinData) {
+  try {
+    const raw = typeof stdinData === "string" ? stdinData : "";
+    return raw.trim()
+      ? { ok: true, payload: JSON.parse(raw) }
+      : { ok: false, payload: {} };
+  } catch {
+    return { ok: false, payload: {} };
+  }
+}
+
+function normalizeMode(mode, payload) {
+  const direct = String(mode || "")
+    .trim()
+    .toLowerCase();
+  if (direct === "register" || direct === "heartbeat") return direct;
+
+  const eventName = String(payload?.hook_event_name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/-/g, "_");
+  if (eventName === "session_start" || eventName === "sessionstart") {
+    return "register";
+  }
+  if (eventName === "user_prompt_submit" || eventName === "userpromptsubmit") {
+    return "heartbeat";
+  }
+  return "";
+}
+
+export async function runCodexSessionHook(stdinData, opts = {}) {
+  const output = "{}\n";
+  const parsed = parsePayload(stdinData);
+  const mode = parsed.ok
+    ? normalizeMode(opts.argvMode ?? argv[2], parsed.payload)
+    : "";
+  const hubEnsureRun = opts.hubEnsureRun || defaultHubEnsureRun;
+  const registerInteractiveSession =
+    opts.registerInteractiveSession || defaultRegisterInteractiveSession;
+  const heartbeatInteractiveSession =
+    opts.heartbeatInteractiveSession || defaultHeartbeatInteractiveSession;
+  const drainPendingSynapse =
+    opts.drainPendingSynapse || defaultDrainPendingSynapse;
+
+  try {
+    if (mode === "register") {
+      try {
+        await hubEnsureRun(stdinData);
+      } catch {}
+      try {
+        registerInteractiveSession(stdinData);
+      } catch {}
+      try {
+        await drainPendingSynapse(1000);
+      } catch {}
+    } else if (mode === "heartbeat") {
+      try {
+        heartbeatInteractiveSession(stdinData);
+      } catch {}
+      try {
+        await drainPendingSynapse(500);
+      } catch {}
+    }
+  } catch {
+    // Codex session hooks are observational and must never block the session.
+  }
+
+  if (opts.writeStdout !== false) {
+    stdout.write(output);
+  }
+  return output;
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    stdin.setEncoding("utf8");
+    stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    stdin.on("end", () => resolve(data));
+    stdin.on("error", () => resolve(data));
+  });
+}
+
+if (argv[1] && import.meta.url === pathToFileURL(argv[1]).href) {
+  const stdinData = await readStdin();
+  await runCodexSessionHook(stdinData);
+  exit(0);
+}

package/hub/server.mjs

@@ -22,6 +22,7 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
+import { runCollect } from "../cto/collect.mjs";
 import { createModuleLogger } from "../scripts/lib/logger.mjs";
 import { broker as brokerInstance, reloadBroker } from "./account-broker.mjs";
 import { createAdaptiveEngine } from "./adaptive.mjs";
@@ -53,6 +54,7 @@ import {
   writeState,
 } from "./state.mjs";
 import { createStoreAdapter } from "./store-adapter.mjs";
+import { createCtoAutoCollector } from "./team/cto-auto-collect.mjs";
 import { createGitPreflight } from "./team/git-preflight.mjs";
 import { nativeProxy } from "./team/nativeProxy.mjs";
 import { createSwarmLocks } from "./team/swarm-locks.mjs";
@@ -1009,10 +1011,16 @@ export async function startHub({
     registry: synapseRegistry,
     locks: swarmLocks,
   });
+  const ctoAutoCollector = createCtoAutoCollector({
+    registry: synapseRegistry,
+    runCollect,
+    logger: hubLog,
+  });
 
   // Synapse Layer 5: emitter subscribers — bridge events to hub logging
-  synapseEmitter.on("synapse.session.started", ({ sessionId }) => {
+  synapseEmitter.on("synapse.session.started", ({ sessionId, session }) => {
     hubLog.info({ sessionId }, "synapse.session.started");
+    ctoAutoCollector.handleSessionStarted({ sessionId, session });
   });
   synapseEmitter.on("synapse.session.heartbeat", ({ sessionId }) => {
     hubLog.debug({ sessionId }, "synapse.session.heartbeat");
@@ -2054,6 +2062,16 @@ export async function startHub({
   }, 60000);
   sessionTimer.unref();
 
+  const synapsePruneTimer = setInterval(() => {
+    try {
+      const { count } = synapseRegistry.pruneExpired();
+      if (count > 0) hubLog.info({ count }, "synapse.prune");
+    } catch (err) {
+      hubLog.warn({ err }, "synapse.prune_failed");
+    }
+  }, 60000);
+  synapsePruneTimer.unref();
+
   // 고아 node.exe 프로세스 + stale spawn 세션 주기적 정리 (5분마다)
   // TFX_DISABLE_ORPHAN_CLEANUP=1 로 비활성 (active SSH/swarm 세션 보호 회피용 hotfix gate)
   const orphanCleanupTimer = setInterval(
@@ -2288,6 +2306,7 @@ export async function startHub({
               router.stopSweeper();
               clearInterval(hitlTimer);
               clearInterval(sessionTimer);
+              clearInterval(synapsePruneTimer);
               clearInterval(rateLimitTimer);
               clearInterval(orphanCleanupTimer);
               if (idleTimer) {

package/hub/team/cto-auto-collect.mjs

@@ -0,0 +1,109 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const DEFAULT_DEBOUNCE_MS = 120_000;
+const OFF_VALUES = new Set(["0", "false", "off", "no"]);
+
+export function isCtoAutoCollectDisabled(env = process.env) {
+  return OFF_VALUES.has(
+    String(env?.TFX_CTO_AUTO_COLLECT ?? "")
+      .trim()
+      .toLowerCase(),
+  );
+}
+
+function freshCurrentMd(projectRoot, now, debounceMs) {
+  try {
+    const currentMd = join(projectRoot, ".triflux", "lake", "current.md");
+    if (!existsSync(currentMd)) return false;
+    return now - statSync(currentMd).mtimeMs < debounceMs;
+  } catch {
+    return false;
+  }
+}
+
+export function createCtoAutoCollector(opts = {}) {
+  const registry = opts.registry;
+  const runCollect = opts.runCollect;
+  const logger = opts.logger || null;
+  const debounceMs = Number(opts.debounceMs || DEFAULT_DEBOUNCE_MS);
+  const now = opts.now || (() => Date.now());
+  const env = opts.env || process.env;
+  const lastCollectMs = opts.lastCollectMs || new Map();
+  const inFlight = new Set();
+
+  function handleSessionStarted({ sessionId, session } = {}) {
+    if (isCtoAutoCollectDisabled(env))
+      return { triggered: false, reason: "disabled" };
+    if (!registry || typeof registry.querySessions !== "function") {
+      return { triggered: false, reason: "missing-registry" };
+    }
+    if (typeof runCollect !== "function") {
+      return { triggered: false, reason: "missing-runCollect" };
+    }
+
+    const cwd = typeof session?.cwd === "string" ? session.cwd : "";
+    const worktree =
+      typeof session?.worktreePath === "string" ? session.worktreePath : "";
+    const projectRoot = worktree || cwd;
+    if (!projectRoot)
+      return { triggered: false, reason: "missing-project-root" };
+
+    let peers = [];
+    try {
+      peers = registry.querySessions({
+        cwd,
+        worktree,
+        excludeSessionId: sessionId,
+      });
+    } catch (error) {
+      logger?.warn?.(
+        { sessionId, err: String(error?.message || error) },
+        "cto.auto_collect.query_failed",
+      );
+      return { triggered: false, reason: "query-failed" };
+    }
+    if (!Array.isArray(peers) || peers.length < 1) {
+      return { triggered: false, reason: "no-peers" };
+    }
+
+    const currentTime = now();
+    const last = lastCollectMs.get(projectRoot) || 0;
+    if (currentTime - last < debounceMs) {
+      return { triggered: false, reason: "debounced" };
+    }
+    if (freshCurrentMd(projectRoot, currentTime, debounceMs)) {
+      lastCollectMs.set(projectRoot, currentTime);
+      return { triggered: false, reason: "fresh-lake" };
+    }
+
+    lastCollectMs.set(projectRoot, currentTime);
+    const promise = Promise.resolve()
+      .then(() => runCollect([], { rootDir: projectRoot }))
+      .catch((error) => {
+        logger?.warn?.(
+          { projectRoot, err: String(error?.message || error) },
+          "cto.auto_collect.failed",
+        );
+      })
+      .finally(() => {
+        inFlight.delete(promise);
+      });
+    inFlight.add(promise);
+    return {
+      triggered: true,
+      reason: "triggered",
+      projectRoot,
+      peerCount: peers.length,
+    };
+  }
+
+  async function drain() {
+    await Promise.allSettled([...inFlight]);
+  }
+
+  return Object.freeze({
+    handleSessionStarted,
+    drain,
+  });
+}

package/hub/team/synapse-registry.mjs

@@ -5,6 +5,7 @@ const DEFAULT_LOCAL_HEARTBEAT_INTERVAL_MS = 5_000;
 const DEFAULT_LOCAL_TIMEOUT_MS = 30_000;
 const DEFAULT_REMOTE_HEARTBEAT_INTERVAL_MS = 15_000;
 const DEFAULT_REMOTE_TIMEOUT_MS = 90_000;
+const DEFAULT_EXPIRE_TIMEOUT_MS = 24 * 60 * 60 * 1000;
 // Interactive (Claude/Codex) sessions idle for long stretches; a 30s local
 // timeout produces stale false-positives. 5-minute TTL + an `idle` state
 // distinguishes "alive but inactive" from "presumed dead".
@@ -133,6 +134,7 @@ export function createSynapseRegistry(opts = {}) {
     remoteTimeoutMs = DEFAULT_REMOTE_TIMEOUT_MS,
     interactiveHeartbeatIntervalMs = DEFAULT_INTERACTIVE_HEARTBEAT_INTERVAL_MS,
     interactiveTimeoutMs = DEFAULT_INTERACTIVE_TIMEOUT_MS,
+    expireTimeoutMs = DEFAULT_EXPIRE_TIMEOUT_MS,
   } = opts;
 
   const sessions = new Map();
@@ -355,10 +357,89 @@ export function createSynapseRegistry(opts = {}) {
     return true;
   }
 
+  // stale/expired 세션이 expireTimeoutMs 넘게 누적되면 Map에서 제거.
+  // live(active/idle)는 lastHeartbeat가 오래돼도 보존 — git-preflight dirty-file 가드가 의존.
+  function pruneExpired(opts2 = {}) {
+    if (destroyed) return { removed: [], count: 0 };
+
+    const cutoff =
+      typeof opts2.olderThanMs === "number"
+        ? opts2.olderThanMs
+        : expireTimeoutMs;
+    const removed = [];
+    const currentTime = now();
+
+    for (const [sessionId, session] of sessions) {
+      if (
+        isLiveStatus(session.status) ||
+        currentTime - session.lastHeartbeat <= cutoff
+      ) {
+        continue;
+      }
+
+      stopMonitor(sessionId);
+      sessions.delete(sessionId);
+      removed.push(sessionId);
+      notifyRemoved(session);
+    }
+
+    if (removed.length > 0) persist();
+    return { removed, count: removed.length };
+  }
+
   function heartbeat(sessionId, partialMeta = null) {
     const normalized = normalizeSessionId(sessionId);
     const session = sessions.get(normalized);
-    if (!session) return false;
+    if (!session) {
+      // self-heal은 위치 정보(worktreePath 또는 cwd)가 있는 heartbeat에서만
+      // 발동한다. UserPromptSubmit heartbeat는 항상 worktreePath를 보내므로
+      // SessionStart register POST drop 복구 경로는 커버되고, taskSummary만 담은
+      // 빈약한 heartbeat로 위치 없는 가비지 세션이 register 되는 것은 막는다
+      // (그 경우는 기존대로 false → 400/heartbeat failed).
+      const hasLocator =
+        partialMeta &&
+        typeof partialMeta === "object" &&
+        !Array.isArray(partialMeta) &&
+        ((typeof partialMeta.worktreePath === "string" &&
+          partialMeta.worktreePath.length > 0) ||
+          (typeof partialMeta.cwd === "string" && partialMeta.cwd.length > 0));
+      const canSelfHeal = Boolean(normalized) && hasLocator;
+      if (!canSelfHeal) return false;
+
+      // 미등록 세션 heartbeat = SessionStart register POST가 drop된 경우.
+      // self-heal로 register 복구(영구 미등록 방지).
+      //
+      // sessionKind는 명시값이 없으면 "interactive"로 본다. 실제 복구 경로인
+      // heartbeatInteractiveSession은 worktreePath/host/taskSummary만 보내고
+      // sessionKind는 생략하는데, sanitizeSession 기본값("headless")으로 떨어지면
+      // 복구된 Claude 세션이 30초 local timeout을 받아 idle/5분 TTL을 잃고 곧장
+      // stale로 전이돼 getActive()/peer discovery에서 사라진다(이 PRD가 고치려던
+      // 원래 증상의 재현). heartbeat 기반 liveness로 살아나는 세션은 interactive다.
+      const sanitizedKind =
+        typeof partialMeta.sessionKind === "string"
+          ? partialMeta.sessionKind
+          : "interactive";
+      const healed = sanitizeSession(
+        {
+          ...partialMeta,
+          sessionId: normalized,
+          sessionKind: sanitizedKind,
+          status: "active",
+          lastHeartbeat: now(),
+        },
+        normalized,
+      );
+      if (!healed) return false;
+
+      sessions.set(normalized, healed);
+      startMonitor(normalized);
+      persist();
+      emitter?.emit("synapse.session.started", {
+        sessionId: normalized,
+        session: cloneSession(healed),
+      });
+      return true;
+    }
 
     const wasRemote = session.isRemote;
     const updated = { ...session, lastHeartbeat: now(), status: "active" };
@@ -492,6 +573,7 @@ export function createSynapseRegistry(opts = {}) {
   return Object.freeze({
     register,
     unregister,
+    pruneExpired,
     heartbeat,
     getActive,
     getAll,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.30.1",
+  "version": "10.32.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Antigravity, and Claude",
   "type": "module",
   "bin": {

package/scripts/ensure-codex-hooks.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = dirname(__dirname);
+const SESSION_START_MATCHER = "startup|resume|clear";
+const TRIFLUX_HOOK_BASENAME = "codex-session-hook.mjs";
+
+function atomicWriteFile(path, content) {
+  const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmpPath, content, "utf8");
+  renameSync(tmpPath, path);
+}
+
+function quoteCommandPath(value) {
+  return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function buildCommand(nodeBin, hookScriptPath, mode) {
+  return `${nodeBin} ${quoteCommandPath(hookScriptPath)} ${mode}`;
+}
+
+export function canonicalJson(value) {
+  if (Array.isArray(value)) return value.map((item) => canonicalJson(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, canonicalJson(value[key])]),
+    );
+  }
+  return value;
+}
+
+export function computeTrustedHookHash({
+  eventName,
+  matcher,
+  command,
+  timeout,
+  statusMessage,
+}) {
+  const hook = {
+    type: "command",
+    command,
+    timeout: Math.max(1, Number(timeout ?? 600)),
+    async: false,
+  };
+  if (statusMessage) hook.statusMessage = statusMessage;
+  const identity = {
+    event_name: eventName,
+    ...(matcher ? { matcher } : {}),
+    hooks: [hook],
+  };
+  return `sha256:${createHash("sha256")
+    .update(JSON.stringify(canonicalJson(identity)))
+    .digest("hex")}`;
+}
+
+function normalizeHooksJson(raw) {
+  try {
+    const parsed = raw.trim() ? JSON.parse(raw) : {};
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { hooks: {} };
+    }
+    if (!parsed.hooks || typeof parsed.hooks !== "object") parsed.hooks = {};
+    return parsed;
+  } catch {
+    return { hooks: {} };
+  }
+}
+
+function isTrifluxHookGroup(group) {
+  return Array.isArray(group?.hooks)
+    ? group.hooks.some(
+        (hook) =>
+          typeof hook?.command === "string" &&
+          hook.command.includes(TRIFLUX_HOOK_BASENAME),
+      )
+    : false;
+}
+
+function upsertHookGroup(groups, desired) {
+  const list = Array.isArray(groups) ? [...groups] : [];
+  const existingIndex = list.findIndex((group) => isTrifluxHookGroup(group));
+  if (existingIndex >= 0) {
+    list[existingIndex] = desired;
+    return { groups: list, index: existingIndex };
+  }
+  list.push(desired);
+  return { groups: list, index: list.length - 1 };
+}
+
+function buildDesiredGroups({ nodeBin, hookScriptPath }) {
+  return {
+    SessionStart: {
+      matcher: SESSION_START_MATCHER,
+      hooks: [
+        {
+          type: "command",
+          command: buildCommand(nodeBin, hookScriptPath, "register"),
+          timeout: 15,
+        },
+      ],
+    },
+    UserPromptSubmit: {
+      hooks: [
+        {
+          type: "command",
+          command: buildCommand(nodeBin, hookScriptPath, "heartbeat"),
+          timeout: 10,
+        },
+      ],
+    },
+  };
+}
+
+function formatHooksJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function escapeTomlKey(key) {
+  return `"${String(key).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function stateLine(key, hash) {
+  return `${escapeTomlKey(key)} = { trusted_hash = "${hash}" }`;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stripManagedStateLines(content, managedKeys, hooksPath) {
+  if (!content) return "";
+  const escapedKeys = [...managedKeys].map((key) =>
+    escapeRegExp(escapeTomlKey(key)),
+  );
+  for (const label of ["session_start", "user_prompt_submit"]) {
+    escapedKeys.push(
+      escapeRegExp(escapeTomlKey(`${hooksPath}:${label}:`)).replace(
+        /"$/,
+        '\\d+:\\d+"',
+      ),
+    );
+  }
+  const re = new RegExp(
+    `^\\s*(?:${escapedKeys.join("|")})\\s*=\\s*\\{\\s*trusted_hash\\s*=.*\\}\\s*$`,
+    "gm",
+  );
+  return content.replace(re, "").replace(/\n{3,}/g, "\n\n");
+}
+
+function mergeHooksState(content, entries, hooksPath) {
+  const managedKeys = new Set(entries.map((entry) => entry.key));
+  let updated = stripManagedStateLines(content, managedKeys, hooksPath);
+  const lines = entries.map((entry) => stateLine(entry.key, entry.hash));
+  const sectionRe = /^\[hooks\.state\]\s*$/m;
+  const match = sectionRe.exec(updated);
+
+  if (!match) {
+    if (updated.length > 0 && !updated.endsWith("\n")) updated += "\n";
+    if (updated.length > 0 && !updated.endsWith("\n\n")) updated += "\n";
+    return `${updated}[hooks.state]\n${lines.join("\n")}\n`;
+  }
+
+  const sectionStart = match.index;
+  const afterHeader = match.index + match[0].length;
+  const nextSectionMatch = /^\[[^\]]+\]\s*$/m.exec(updated.slice(afterHeader));
+  const sectionEnd = nextSectionMatch
+    ? afterHeader + nextSectionMatch.index
+    : updated.length;
+  let sectionBody = updated.slice(sectionStart, sectionEnd).trimEnd();
+  sectionBody += `\n${lines.join("\n")}\n`;
+  return (
+    updated.slice(0, sectionStart) + sectionBody + updated.slice(sectionEnd)
+  );
+}
+
+function timestamp() {
+  return new Date()
+    .toISOString()
+    .replace(/[-:.TZ]/g, "")
+    .slice(0, 14);
+}
+
+export function ensureCodexHooks(opts = {}) {
+  const codexHome = opts.codexHome || join(homedir(), ".codex");
+  if (!existsSync(codexHome)) {
+    return { skipped: true, changedHooks: false, changedConfig: false };
+  }
+
+  const hooksPath = resolve(codexHome, "hooks.json");
+  const configPath = resolve(codexHome, "config.toml");
+  const hookScriptPath = resolve(
+    opts.hookScriptPath || join(PROJECT_ROOT, "hooks", TRIFLUX_HOOK_BASENAME),
+  );
+  const nodeBin = opts.nodeBin || process.execPath;
+  const desired = buildDesiredGroups({ nodeBin, hookScriptPath });
+
+  const hooksJson = normalizeHooksJson(
+    existsSync(hooksPath) ? readFileSync(hooksPath, "utf8") : "",
+  );
+  const sessionStart = upsertHookGroup(
+    hooksJson.hooks.SessionStart,
+    desired.SessionStart,
+  );
+  const promptSubmit = upsertHookGroup(
+    hooksJson.hooks.UserPromptSubmit,
+    desired.UserPromptSubmit,
+  );
+  hooksJson.hooks.SessionStart = sessionStart.groups;
+  hooksJson.hooks.UserPromptSubmit = promptSubmit.groups;
+
+  const originalHooks = existsSync(hooksPath)
+    ? readFileSync(hooksPath, "utf8")
+    : "";
+  const nextHooks = formatHooksJson(hooksJson);
+  const changedHooks = originalHooks !== nextHooks;
+  if (changedHooks) {
+    mkdirSync(dirname(hooksPath), { recursive: true });
+    atomicWriteFile(hooksPath, nextHooks);
+  }
+
+  const stateEntries = [
+    {
+      key: `${hooksPath}:session_start:${sessionStart.index}:0`,
+      hash: computeTrustedHookHash({
+        eventName: "session_start",
+        matcher: desired.SessionStart.matcher,
+        command: desired.SessionStart.hooks[0].command,
+        timeout: desired.SessionStart.hooks[0].timeout,
+      }),
+    },
+    {
+      key: `${hooksPath}:user_prompt_submit:${promptSubmit.index}:0`,
+      hash: computeTrustedHookHash({
+        eventName: "user_prompt_submit",
+        command: desired.UserPromptSubmit.hooks[0].command,
+        timeout: desired.UserPromptSubmit.hooks[0].timeout,
+      }),
+    },
+  ];
+
+  const originalConfig = existsSync(configPath)
+    ? readFileSync(configPath, "utf8")
+    : "";
+  const nextConfig = mergeHooksState(originalConfig, stateEntries, hooksPath);
+  const changedConfig = originalConfig !== nextConfig;
+  if (changedConfig) {
+    if (existsSync(configPath)) {
+      const backupPath = `${configPath}.bak-tfx-codex-hooks-${opts.backupTimestamp || timestamp()}`;
+      if (!existsSync(backupPath)) {
+        writeFileSync(backupPath, originalConfig, "utf8");
+      }
+    }
+    atomicWriteFile(configPath, nextConfig);
+  }
+
+  return {
+    skipped: false,
+    changedHooks,
+    changedConfig,
+    hooksPath,
+    configPath,
+  };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const result = ensureCodexHooks();
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}

package/scripts/setup.mjs

@@ -26,6 +26,7 @@ import {
   ensureTfxSection,
   getLatestRoutingTable,
 } from "./claudemd-sync.mjs";
+import { ensureCodexHooks } from "./ensure-codex-hooks.mjs";
 import { addPluginRootFallbackToCommand } from "./lib/doctor-env-checks.mjs";
 import { cleanupTmpFiles } from "./tmp-cleanup.mjs";
 
@@ -1373,6 +1374,9 @@ function ensureCriticalSetup() {
   try {
     ensureCodexProfiles();
   } catch {}
+  try {
+    ensureCodexHooks();
+  } catch {}
 }
 
 export {
@@ -1383,6 +1387,7 @@ export {
   cleanupStaleSkills,
   DEPRECATED_SKILLS,
   detectDevMode,
+  ensureCodexHooks,
   ensureCodexHubServerConfig,
   ensureCodexProfiles,
   ensureHooksInSettings,
@@ -2147,6 +2152,21 @@ export async function runDeferred(stdinData) {
     synced++;
   }
 
+  try {
+    const codexHooksResult = ensureCodexHooks();
+    if (
+      !codexHooksResult?.skipped &&
+      (codexHooksResult?.changedHooks || codexHooksResult?.changedConfig)
+    ) {
+      io.log("  \x1b[32m✓\x1b[0m Codex hooks: registered session sync hooks");
+      synced++;
+    }
+  } catch (error) {
+    io.log(
+      `  \x1b[33m⚠\x1b[0m Codex hooks 등록 실패: ${error.message || error}`,
+    );
+  }
+
   // ── Windows Codex 단독 실행 보호: 로그인 시 hub-ensure 등록 ──
   // Claude SessionStart 훅이 없는 순수 Codex 시작 경로에서도 tfx-hub가 살아있게 한다.
   if (enableHubAutostart) {

package/scripts/tfx-route.sh

@@ -464,6 +464,85 @@ prepend_codex_north_star() {
   rm -f "$tmp_file" 2>/dev/null || true
 }
 
+# prepend_skill: opt-in 으로 등록된 스킬의 SKILL.md 본문을 프롬프트 앞에 주입한다.
+# 활성 조건은 TFX_INJECT_SKILL env (tfx-auto 가 --skill <name> 으로 set). 미설정이면
+# 현행 동작 그대로 (no-op). CLI-agnostic — codex/agy 레인에서 동일하게 재사용한다.
+# 전달은 prepend_codex_north_star 와 동일하게 printf/cat → temp file 만 사용하므로
+# $ / 백슬래시(₩) 같은 특수문자를 셸 재확장 없이 리터럴로 보존한다 (parse-safe).
+# 스킬 경로: ${TFX_SKILLS_DIR:-<repo>/skills}/<name>/SKILL.md.
+prepend_skill() {
+  local prompt="${1:-}"
+  local skill_name="${TFX_INJECT_SKILL:-}"
+  if [[ -z "$skill_name" ]]; then
+    printf '%s' "$prompt"
+    return 0
+  fi
+  # 경로 탈출 방지: skill_name 은 skills/ 하위 단일 디렉토리 이름만 허용한다.
+  if [[ "$skill_name" == *"/"* || "$skill_name" == *".."* ]]; then
+    echo "[tfx-route] WARNING: TFX_INJECT_SKILL='${skill_name}' 에 경로 구분자/.. 포함 — 주입 거부" >&2
+    printf '%s' "$prompt"
+    return 0
+  fi
+
+  local skills_dir="${TFX_SKILLS_DIR:-}"
+  if [[ -z "$skills_dir" ]]; then
+    skills_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." 2>/dev/null && pwd)/skills"
+  fi
+  local skill_file="${skills_dir}/${skill_name}/SKILL.md"
+  if [[ ! -r "$skill_file" ]]; then
+    echo "[tfx-route] WARNING: TFX_INJECT_SKILL='${skill_name}' 스킬을 찾지 못함 ($skill_file) — 주입 생략" >&2
+    printf '%s' "$prompt"
+    return 0
+  fi
+
+  local tmp_file
+  tmp_file="$(mktemp "${TFX_TMP:-${TMPDIR:-/tmp}}/tfx-skill-prompt.XXXXXX" 2>/dev/null)" || {
+    printf '%s' "$prompt"
+    return 0
+  }
+
+  if ! {
+    printf '%s\n' "--- SKILL: ${skill_name} (apply this methodology to the task below) ---"
+    cat "$skill_file"
+    if [[ -s "$skill_file" ]]; then
+      local last_byte
+      last_byte="$(tail -c 1 "$skill_file" 2>/dev/null || true)"
+      [[ -n "$last_byte" ]] && printf '\n'
+    fi
+    printf '%s\n' "--- END SKILL ---"
+    printf '%s' "$prompt"
+  } > "$tmp_file"; then
+    rm -f "$tmp_file" 2>/dev/null || true
+    printf '%s' "$prompt"
+    return 0
+  fi
+
+  cat "$tmp_file" 2>/dev/null || printf '%s' "$prompt"
+  rm -f "$tmp_file" 2>/dev/null || true
+}
+
+# append_agy_anti_overclaim: agy(Gemini 3.x) 레인 전용 완료/grounding 규율 블록을
+# 프롬프트 *뒤*에 붙인다. Gemini 3.x 는 과신(overconfidence) outlier 라 거짓 완료
+# 주장·환각이 잦다 (AA-Omniscience 실증). 부정 제약은 Gemini 3 공식 가이드 권고대로
+# 프롬프트 END 에 배치하고, blanket "do not guess" 대신 "주어진 context 로 추론 +
+# 정확한 abstention 우선" 형태로 적는다 (open-ended negative 는 역효과). TFX_AGY_ANTI_OVERCLAIM=0 으로 opt-out.
+append_agy_anti_overclaim() {
+  local prompt="${1:-}"
+  case "${TFX_AGY_ANTI_OVERCLAIM:-1}" in
+    0|false|FALSE|off|OFF|no|NO)
+      printf '%s' "$prompt"
+      return 0
+      ;;
+  esac
+
+  printf '%s' "$prompt"
+  printf '\n\n%s\n' "--- COMPLETION & GROUNDING DISCIPLINE (apply strictly) ---"
+  printf '%s\n' "- Claim done/fixed/passing ONLY after running the check in this turn and seeing its output. With no fresh evidence, report what is still unverified instead of asserting success."
+  printf '%s\n' "- Ground every answer in the provided context and the actual repository. If something is not verifiable from what you can see, say 'No Info / 확인 불가' and stop rather than inventing plausible-but-unconfirmed details."
+  printf '%s\n' "- Use the provided context for deductions and prefer accurate abstention over confident guessing."
+  printf '%s' "--- END DISCIPLINE ---"
+}
+
 read_probe_state() {
   local pid="$1"
   local state_file="${TFX_PROBE_STATE_FILE:-${TFX_PROBE_DIR}/${pid}.json}"
@@ -2678,6 +2757,14 @@ FALLBACK_EOF
       _codex_full_prompt_with_sentinel="$(prepend_codex_north_star "$FULL_PROMPT"; printf '%s' "$_codex_prompt_sentinel")"
       FULL_PROMPT="${_codex_full_prompt_with_sentinel%"$_codex_prompt_sentinel"}"
     fi
+    # Opt-in 스킬 주입 (TFX_INJECT_SKILL). north-star 와 동일한 sentinel 패턴으로
+    # trailing newline 을 보존한다. 미설정이면 prepend_skill 이 no-op.
+    if [[ -n "${TFX_INJECT_SKILL:-}" ]]; then
+      local _codex_skill_sentinel="__TFX_CODEX_SKILL_END_${$}_${RANDOM}__"
+      local _codex_skill_prompt
+      _codex_skill_prompt="$(prepend_skill "$FULL_PROMPT"; printf '%s' "$_codex_skill_sentinel")"
+      FULL_PROMPT="${_codex_skill_prompt%"$_codex_skill_sentinel"}"
+    fi
     codex_transport_effective="exec"
     if [[ "$TFX_CODEX_TRANSPORT" != "exec" ]]; then
       run_codex_mcp "$FULL_PROMPT" "$use_tee" || exit_code=$?
@@ -2782,6 +2869,18 @@ EOF
       _agy_full_prompt_with_sentinel="$(prepend_codex_north_star "$FULL_PROMPT"; printf '%s' "$_agy_prompt_sentinel")"
       FULL_PROMPT="${_agy_full_prompt_with_sentinel%"$_agy_prompt_sentinel"}"
     fi
+    # Opt-in 스킬 주입 (TFX_INJECT_SKILL) — codex 레인과 동일.
+    if [[ -n "${TFX_INJECT_SKILL:-}" ]]; then
+      local _agy_skill_sentinel="__TFX_AGY_SKILL_END_${$}_${RANDOM}__"
+      local _agy_skill_prompt
+      _agy_skill_prompt="$(prepend_skill "$FULL_PROMPT"; printf '%s' "$_agy_skill_sentinel")"
+      FULL_PROMPT="${_agy_skill_prompt%"$_agy_skill_sentinel"}"
+    fi
+    # agy(Gemini 3.x) anti-overclaim 규율 블록을 프롬프트 END 에 append. opt-out: TFX_AGY_ANTI_OVERCLAIM=0.
+    local _agy_aoc_sentinel="__TFX_AGY_AOC_END_${$}_${RANDOM}__"
+    local _agy_aoc_prompt
+    _agy_aoc_prompt="$(append_agy_anti_overclaim "$FULL_PROMPT"; printf '%s' "$_agy_aoc_sentinel")"
+    FULL_PROMPT="${_agy_aoc_prompt%"$_agy_aoc_sentinel"}"
     run_antigravity_exec "$FULL_PROMPT" "$use_tee" || exit_code=$?
     if [[ "$exit_code" -ne 0 && "$exit_code" -ne 124 ]]; then
       local agy_stderr_bytes=0

package/skills/tfx-auto/SKILL.md

@@ -28,7 +28,7 @@ triggers:
   - spec-panel
   - business-panel
   - index-repo
-argument-hint: "<command|task> [args...] [--cli auto|codex|antigravity|claude] [--mode quick|deep|consensus] [--risk-tier auto|low|medium|high] [--shape consensus|debate|panel] [--cli-set triad|no-antigravity|custom] [--parallel 1|N|swarm] [--retry 0|1|ralph] [--isolation none|worktree] [--remote <host>|none]"
+argument-hint: "<command|task> [args...] [--cli auto|codex|antigravity|claude] [--mode quick|deep|consensus] [--risk-tier auto|low|medium|high] [--shape consensus|debate|panel] [--cli-set triad|no-antigravity|custom] [--parallel 1|N|swarm] [--retry 0|1|ralph] [--isolation none|worktree] [--remote <host>|none] [--skill <name>]"
 ---
 
 # tfx-auto — 통합 CLI 오케스트레이터
@@ -169,6 +169,7 @@ ARGUMENTS 에 아래 플래그가 있으면 Step 0 스마트 라우팅의 내부
 | `--no-claude-native` | false (기본) | Claude native sub-agent 경로 유지 | — |
 | `--no-claude-native` | true | Claude native 경로 disable, CLI 기반 worker 강제 | tfx-route.sh |
 | `--max-iterations` | `0` (기본, unlimited) | `--retry ralph`/`auto-escalate` 상한 | retry-state-machine.mjs |
+| `--skill` | `<name>` | `skills/<name>/SKILL.md` 본문을 codex/agy 프롬프트 앞에 주입 (`TFX_INJECT_SKILL`). 미지정 시 no-op | tfx-route.sh |
 
 ### `--risk-tier` 계약
 
@@ -204,6 +205,37 @@ ARGUMENTS 에 아래 플래그가 있으면 Step 0 스마트 라우팅의 내부
 - `--retry ralph` → true ralph state machine (Phase 3, retry-state-machine.mjs)
 - `--retry auto-escalate` → CLI 승격 체인 (Phase 3)
 - `--max-iterations N` (N>0) → ralph/auto-escalate 에 상한 부여
+- `--skill <name>` → `TFX_INJECT_SKILL=<name>` 로 tfx-route.sh 에 전달. 스킬 파일 부재 시 warning 후 주입 생략 (fail-open, 작업은 계속)
+
+### 스킬 주입 (`--skill <name>`)
+
+codex/agy 워커 프롬프트 앞에 등록된 스킬의 방법론을 주입하는 **opt-in** 프레임워크. 설계 근거는 `decision-skill-passing` (omc 레퍼런스 + codex/agy 네이티브 스킬 조사):
+
+- **메커니즘**: `--skill <name>` → tfx-route.sh `TFX_INJECT_SKILL=<name>`. `skills/<name>/SKILL.md` 본문을 `--- SKILL: <name> (apply this methodology...) ---` delimited block 으로 프롬프트 앞에 prepend. codex·agy 레인 공통 (CLI-agnostic, `prepend_skill`).
+- **기본 off**: 미지정이면 no-op → 현행 동작 그대로. 회귀 위험 없음.
+- **파싱 안전**: prepend 는 `printf`/`cat` → temp file 만 사용. codex 는 argv `--` 뒤, agy 는 stdin `printf %s` 로 전달되므로 `$`(codex)·`₩`/백슬래시(agy) 같은 특수문자를 셸 재확장 없이 **리터럴 보존**. 스킬 본문을 그대로 넘겨도 깨지지 않음.
+- **네이티브 스킬을 안 쓰는 이유**: codex `$skill-name`/`/name` 슬래시와 agy `/name` 은 둘 다 **인터랙티브 TUI 전용** → headless one-shot 에서 named-skill 강제 호출 불가 (미문서). 그래서 prose 주입을 채택 (레퍼런스 omc 도 role .md 를 raw prepend, 네이티브 회피).
+
+#### 커맨드→스킬 매핑 (tfx-auto convention, opt-in)
+
+tfx-auto 가 커맨드/agent 별로 주입할 스킬을 고를 때 쓰는 **권고 테이블**. 기본은 매핑 없음 (명시 `--skill` 만 작동) — 부적절한 스킬이 모든 프롬프트에 새는 것을 막는다. 프로젝트가 명시적으로 활성화할 때만 아래를 적용해 `--skill` 을 자동 부여한다.
+
+| 커맨드/agent | 권고 스킬 | 비고 |
+|--------------|-----------|------|
+| (기본) | 없음 | explicit `--skill` 우선 |
+| 프로젝트 정의 | 프로젝트가 지정 | 활성화 시 tfx-auto 가 해당 `--skill` set |
+
+> 매핑된 스킬 파일이 없으면 `prepend_skill` 이 warning 후 주입을 생략한다 (fail-open). 존재하지 않는 매핑을 "주입됨"으로 가정하지 않는다.
+
+#### agy anti-overclaim (자동, agy 레인 전용)
+
+agy(Gemini 3.x) 레인은 `TFX_AGY_ANTI_OVERCLAIM`(기본 on) 으로 완료/grounding 규율 블록을 프롬프트 **END** 에 자동 append (`append_agy_anti_overclaim`). Gemini 3.x 과신(AA-Omniscience 실측: 정확도 53-56% 대비 환각률 88-91%) 대응:
+
+- fresh 증거 없이 done/fixed/passing 주장 금지.
+- 검증 불가 시 `No Info / 확인 불가` 후 중단 (날조 금지).
+- 추론은 주어진 context 로, confident guessing 보다 accurate abstention 우선.
+
+부정 제약은 Gemini 3 공식 가이드대로 **END 배치**하고 blanket "do not guess" 는 역효과라 피한다. opt-out: `TFX_AGY_ANTI_OVERCLAIM=0`.
 
 ### Retry state machine 계약 (legacy autoroute / persist 이관)