triflux 10.54.0 → 10.55.0

package/README.ko.md

@@ -141,7 +141,7 @@ Codex는 이름 붙은 프로필로 실행한다. 모델 ID는 `~/.codex/<프로
 
 **라이브 세션.** `tfx-live`는 Claude Code와 Codex TUI 세션을 조종한다. Claude 데몬 대상
 (`--short`/`--session-id`)은 UDS를 먼저 시도하고, `--session`도 주면 실패 시 tmux로 넘어간다.
-Codex `ask`는 `codex queue`로 메시지를 쌓고(TUI에 `[from <보낸 세션>]` 첫 줄로 보인다) 못 쓰면 이유를
+Codex `ask`는 Codex 큐(app-server `thread/queue/add`)에 메시지를 쌓고(TUI에 `[from <보낸 세션>]` 첫 줄로 보인다) 못 쓰면 이유를
 남기고 tmux로 보낸다. `--transport uds --thread <id|auto>`로 UDS도 쓸 수 있다. `peer`는 두 세션 사이를
 `--rounds`만큼 중계한다. triflux의 Codex
 훅이 실행 중인 Codex 세션을 `~/.local/state/triflux/codex-sessions/`에 기록하므로

package/README.md

@@ -143,7 +143,7 @@ escalation chain: [`.claude/rules/tfx-escalation-chain.md`](.claude/rules/tfx-es
 
 **Live sessions.** `tfx-live` drives Claude Code and Codex TUI sessions. Claude daemon targets
 (`--short`/`--session-id`) try UDS first and fall back to tmux when `--session` is also given;
-Codex `ask` queues the message with `codex queue` (shown in the TUI with a
+Codex `ask` queues the message through the app-server `thread/queue/add` API (shown in the TUI with a
 `[from <sender>]` first line) and falls back to tmux with a reported reason; UDS stays available with
 `--transport uds --thread <id|auto>`. `peer` relays between two sessions for `--rounds`. triflux's Codex hook records running Codex
 sessions under `~/.local/state/triflux/codex-sessions/`, so `tfx-live list-sessions --cli codex|claude`

package/adapters/codex/skills/tfx-live/SKILL.md

@@ -18,7 +18,7 @@ Codex에서는 `$tfx-live`로 호출한다. CLI의 `--cli`는 현재 호스트
 ## 전송 경로
 
 - Claude `--short` 또는 `--session-id`는 기본 `auto`로 UDS를 먼저 시도한다. `--session`이 있고 입력 미전송이 확인된 UDS 실패라면 tmux로 전환하고 `~/.claude/cache/triflux/tfx-live/bug-reports/uds-fallback-*.json`을 남긴다. 컨텍스트 가드 거부 시에는 전환하지 않는다.
-- Codex `ask`는 `codex queue`가 기본이다. 아래 "Codex 메시지 전송" 순서를 따른다. 기존 Codex thread의 UDS 연결은 `--transport uds --thread <id|auto>`를 명시한다.
+- Codex `ask`는 Codex 큐(app-server `thread/queue/add`)가 기본이다. 아래 "Codex 메시지 전송" 순서를 따른다. 기존 Codex thread의 UDS 연결은 `--transport uds --thread <id|auto>`를 명시한다.
 - daemon 참조가 없는 Claude는 tmux가 기본이다.
 - UDS 결과는 `matchedCompletion === true`일 때만 `done: true`다. timeout이나 연결 종료는 완료가 아니다.
 - bridge 선택 순서는 `--bridge`, `$TFX_BRIDGE`, `$TFX_REPO_ROOT/hub/bridge.mjs`, 번들된 `hub/bridge.mjs`다.
@@ -48,7 +48,7 @@ tfx-live stop --cli codex --session cx1
 
 ### Codex 메시지 전송
 
-1. 기본은 `codex queue --thread <UUID>`다. 입력창을 건드리지 않고, 바쁘면 쌓였다가 앞 턴이 끝난 직후 순서대로 들어간다. 유휴 TUI는 약 20초 주기로 큐를 가져간다.
+1. 기본은 app-server 실험 API `thread/queue/add`로 쌓는 것이다. 프롬프트가 프로세스 인자에 보이지 않는다. 입력창을 건드리지 않고, 바쁘면 쌓였다가 앞 턴이 끝난 직후 순서대로 들어간다. 유휴 TUI는 약 20초 주기로 큐를 가져간다. add가 없는 Codex에서만 `codex queue --thread <UUID> --message`로 보내며, 이때 프롬프트가 argv에 보이고 결과에 `queueVia: "codex-queue-argv"`와 `queueFallbackReason`이 남는다. 평소 값은 `queueVia: "app-server"`다.
 2. 첫 줄 머리말은 `[from <보낸 세션 이름>] [tfx-live req=<id>]`다. 이름은 `--from`, `$TFX_LIVE_FROM`, Claude 세션 기록, Codex `session_index` 순으로 찾고 없으면 머리말 없이 표식만 붙인다. Codex TUI는 Claude처럼 접어 보여 주지 않고 사용자 입력으로 그대로 표시한다.
 3. thread는 `--thread UUID`, `start`가 남긴 `@tfx_codex_thread`, Codex 세션 레지스트리, pane 프로세스의 `resume <UUID>` 인자, pane cwd와 같은 rollout 하나 순으로 찾는다. cwd 대응은 그 cwd의 Codex TUI가 하나일 때만 쓰고 exec 워커와 서브에이전트 thread는 뺀다. 이름으로는 보내지 않는다(`codex queue`의 이름 조회가 실패한다).
 4. tmux 직접 입력은 queue를 못 쓸 때만 쓴다: 원격 호스트, thread를 못 찾음(`start` 밖에서 `resume --last`로 띄운 세션, `start --resume-last`의 `threadId: null`, 같은 cwd의 TUI 여럿 포함), `codex queue` 오류(0.160 미만 포함). 결과에 `transport: "tmux"`, `transportRequested: "queue"`, `fallbackReason`이 남는다. 시간 초과처럼 queue가 이미 쌓았을 수도 있는 오류는 `status: "unknown"`으로 끝내고 재전송하지 않는다.

package/bin/tfx-live.mjs

@@ -95,7 +95,7 @@ function usage(command) {
     "  tfx-live start --session NAME [--name NAME] [--cli codex|claude] [--model ID] [--effort TIER] [--cwd DIR] [--remote HOST] [--resume ID] [--resume-last 1] [--ready-timeout 30] [--poll-interval 1500]",
     "  tfx-live ask --session NAME[:WINDOW.PANE] --prompt TEXT [--cli codex|claude] [--if-busy wait|fail|interrupt] [--busy-timeout 60] [--timeout 60] [--remote HOST] [--settle 1500] [--poll-interval 1500]",
     "  tfx-live ask --cli codex [--transport queue|tmux] (--session NAME[:WINDOW.PANE] | --thread UUID) --prompt TEXT [--from NAME] [--timeout 60] [--no-wait]",
-    "    Codex ask defaults to `codex queue` (queued, delivered when the TUI picks it up); tmux paste is the reported fallback and the path for slash commands.",
+    "    Codex ask defaults to the app-server queue (thread/queue/add, `codex queue --message` only when add is unavailable; delivered when the TUI picks it up); tmux paste is the reported fallback and the path for slash commands.",
     "  tfx-live ask --cli codex --transport uds --thread ID|auto --prompt TEXT [--codex-socket PATH|default] [--cwd DIR] [--if-busy wait|fail|steer] [--busy-timeout 60] [--timeout 60] [--max-turn SECONDS]",
     "  tfx-live ask --transport uds|auto (--short SHORT | --session-id ID) --prompt TEXT [--config-dir DIR] [--bridge ABS] [--session NAME (auto fallback)] [--timeout 60]",
     "    ask options: --no-wait --no-relay-tag --warn-context-pct N --max-context-pct N (0 disables; Claude 60/90, Codex 15/22).",
@@ -2725,6 +2725,10 @@ async function doAskViaQueue(adapter, opts, deps = {}) {
     ok: true,
     inputSent: true,
     queuedMessageId: queued.queuedMessageId,
+    queueVia: queued.via,
+    ...(queued.fallbackReason
+      ? { queueFallbackReason: queued.fallbackReason }
+      : {}),
     submittedAt: new Date().toISOString(),
   };
   // 표식이 없으면 rollout 에서 이 요청의 턴을 가려낼 수 없다.

package/bin/triflux.mjs

@@ -44,6 +44,7 @@ import {
   cleanupLegacyMcp,
   cleanupTfxHub,
   findProjectHubEntries,
+  pinRegistryMcpPackages,
 } from "../scripts/lib/legacy-mcp-cleanup.mjs";
 import {
   addRegistryServer,
@@ -66,11 +67,12 @@ import {
   applyStatusLine,
   cleanupStaleSkills,
   ensureCodexProfiles,
-  ensureTrifluxMods,
   getVersion,
+  inspectTrifluxMods,
   isSkillSupportedOnPlatform,
   LEGACY_CODEX_MODELS,
   listInlineProfileNames,
+  MODS_UPDATE_COMMAND,
   persistSettings,
   REQUIRED_CODEX_PROFILES,
   retireOldInstallFiles,
@@ -1260,6 +1262,9 @@ async function cmdSetup(options = {}) {
   });
   for (const warning of hubCleanup.warnings) warn(warning);
   if (hubCleanup.changed) ok("제거된 허브의 설정과 실행 흔적 정리");
+  const mcpPins = pinRegistryMcpPackages({ backups: mcpBackups });
+  for (const warning of mcpPins.warnings) warn(warning);
+  if (mcpPins.pinned) ok(`MCP 패키지 고정 버전 반영: ${mcpPins.pinned}개 항목`);
   if (fromUpdate) refreshSetupCaches();
 
   console.log(`\n${BOLD}triflux setup${RESET}\n`);
@@ -1269,7 +1274,6 @@ async function cmdSetup(options = {}) {
   }
   retireOldInstallFiles(info);
   reportSkillSync();
-  ensureTrifluxMods({ install: mods, log: console.log, warn });
 
   // ── 결과 추적 ──
   const summary = [];
@@ -1367,7 +1371,7 @@ async function cmdSetup(options = {}) {
   }
 
   // Codex 프로필 정리가 끝난 뒤에 훅을 다룬다.
-  await runConsentSteps({ log: info, warn });
+  await runConsentSteps({ modsInstall: mods, log: info, warn });
 
   // ── psmux 기본 셸 자동 수정 (cmd.exe → PowerShell) ──
   if (process.platform === "win32" && which("psmux")) {
@@ -1860,6 +1864,9 @@ async function cmdDoctor(options = {}) {
             status: invalidCount > 0 ? "issues" : "ok",
             actions: mcpSync.actions,
           });
+          for (const action of mcpSync.actions)
+            if (action.status === "warning" && action.message)
+              warn(`${action.label}: ${action.message}`);
           if (updatedCount > 0)
             ok(`MCP registry 동기화: ${updatedCount}개 설정 반영됨`);
           else info("MCP registry: 이미 최신 상태");
@@ -1964,6 +1971,21 @@ async function cmdDoctor(options = {}) {
       warn(`미설치 ${GRAY}(선택사항)${RESET}`);
     }
 
+    // mods 가 없으면 effort 없이 부른 서브에이전트가 리드 effort 를 물려받는다.
+    section("Claude mods");
+    const mods = inspectTrifluxMods({ pkgVersion: PKG.version });
+    addDoctorCheck(report, { name: "triflux-mods", ...mods });
+    if (mods.status === "current")
+      ok(`설치됨 ${DIM}v${mods.installedVersion}${RESET}`);
+    else if (mods.status === "missing") {
+      warn("미설치");
+      info("수정: tfx setup --mods");
+    } else if (mods.status === "outdated") {
+      warn(`버전 차이: 설치 ${mods.installedVersion}, 패키지 ${PKG.version}`);
+      info(`수정: ${MODS_UPDATE_COMMAND}`);
+    } else if (mods.status === "failed") warn(`확인 실패: ${mods.error}`);
+    else info(`건너뜀 (${mods.reason})`);
+
     // Codex CLI
     section(`Codex CLI ${WHITE_BRIGHT}●${RESET}`);
     const codexCli = checkCliCrossShell(
@@ -3607,7 +3629,10 @@ function cmdMcp(args = [], options = {}) {
         }
         const label = `${action.label} ${DIM}(${formatPathForDisplay(action.filePath)})${RESET}`;
         if (action.status === "updated") ok(`${label} → updated`);
-        else if (action.status === "warning") warn(`${label} → warning`);
+        else if (action.status === "warning")
+          warn(
+            `${label} → warning${action.message ? `: ${action.message}` : ""}`,
+          );
         else if (action.status === "invalid-config")
           fail(`${label} → invalid-config`);
         else info(`${stripAnsi(label)} → ${action.status}`);

package/hub/team/codex-queue.mjs

@@ -1,4 +1,5 @@
 import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { open, readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -175,16 +176,57 @@ export async function countCodexTuiInCwd(cwd, { execFn = execFileAsync } = {}) {
   }
 }
 
+// app-server 의 thread/queue/add 로 쌓아 프롬프트가 ps 에 보이지 않게 한다.
 export async function queueCodexMessage({
   threadId,
   message,
   env = process.env,
   execFn = execFileAsync,
+  spawnFn = spawn,
 }) {
+  let addSent = false;
+  try {
+    const result = await withCodexAppServer(
+      (request) => {
+        addSent = true;
+        return request("thread/queue/add", {
+          threadId,
+          input: [{ type: "text", text: message, text_elements: [] }],
+          clientUserMessageId: randomUUID(),
+        });
+      },
+      { env, spawnFn },
+    );
+    const id = result?.queuedSubmission?.id;
+    if (id) return { queuedMessageId: id, via: "app-server" };
+    throw new Error(
+      `unexpected thread/queue/add result: ${JSON.stringify(result)}`,
+    );
+  } catch (error) {
+    // 오류 응답이 아니면 add 가 이미 쌓였을 수 있어 재전송하지 않는다.
+    if (addSent && !error.rpcError) {
+      error.maybeQueued = true;
+      throw error;
+    }
+    const queued = await queueCodexMessageByArgv({
+      threadId,
+      message,
+      env,
+      execFn,
+    });
+    return {
+      ...queued,
+      via: "codex-queue-argv",
+      fallbackReason: error.message,
+    };
+  }
+}
+
+// add 를 못 쓰는 Codex(app-server 없음, 메서드 없음)만 이 경로로 와서 프롬프트가 argv 에 보인다.
+async function queueCodexMessageByArgv({ threadId, message, env, execFn }) {
   let stdout;
   try {
     // cwd 의 프로젝트 .codex/config.toml 이 깨져 있으면 queue 가 실패하므로 HOME 에서 실행한다.
-    // codex queue 는 메시지를 --message 인자로만 받아(stdin, 파일 옵션 없음) ps 노출을 피할 수 없다.
     ({ stdout } = await execFn(
       "codex",
       ["queue", `--thread=${threadId}`, `--message=${message}`],
@@ -216,7 +258,7 @@ export async function queueCodexMessage({
   return { queuedMessageId: match[1] };
 }
 
-// 공식 app-server 를 stdio 로 잠깐 띄워 요청을 보낸다. 큐 조회와 삭제가 실험 API 라 experimentalApi 를 켠다.
+// 공식 app-server 를 stdio 로 잠깐 띄워 요청을 보낸다. 큐 API 가 실험 API 라 experimentalApi 를 켠다.
 export async function withCodexAppServer(
   run,
   { env = process.env, timeoutMs = 30_000, spawnFn = spawn } = {},
@@ -251,7 +293,11 @@ export async function withCodexAppServer(
     if (!waiter) return;
     pending.delete(message.id);
     if (message.error)
-      waiter.reject(new Error(`${waiter.method}: ${message.error.message}`));
+      waiter.reject(
+        Object.assign(new Error(`${waiter.method}: ${message.error.message}`), {
+          rpcError: message.error,
+        }),
+      );
     else waiter.resolve(message.result);
   });
   const send = (message) =>

package/package.json

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

package/scripts/lib/legacy-mcp-cleanup.mjs

@@ -15,9 +15,10 @@ import {
   writeFileSync,
 } from "node:fs";
 import { createRequire } from "node:module";
-import { homedir, platform as osPlatform } from "node:os";
+import { homedir, platform as osPlatform, userInfo } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+import { loadRegistryOrDefault, pinnedArgs } from "./mcp-guard-engine.mjs";
 
 const require = createRequire(import.meta.url);
 const toml = require("@iarna/toml");
@@ -1236,3 +1237,131 @@ export function cleanupTfxHub({
   }
   return result;
 }
+
+// doctor 가 레지스트리와 비교하는 사용자 설정 파일. [HOME 기준 경로, 형식, 클라이언트]
+// 프로젝트의 .mcp.json 은 저장소에 커밋될 수 있어 setup 이 바꾸지 않는다(doctor --fix, mcp sync 몫).
+const REGISTRY_PIN_FILES = [
+  [".claude.json", "json", "claude"],
+  [".mcp.json", "json", "claude"],
+  [".claude/mcp.json", "json", "claude"],
+  [".codex/config.toml", "toml", "codex"],
+  [".gemini/config/mcp_config.json", "json", "antigravity"],
+];
+
+function pinJson(original, servers) {
+  const data = JSON.parse(original);
+  let count = 0;
+  for (const [name, server] of servers) {
+    const entry = data?.mcpServers?.[name];
+    const args = pinnedArgs(entry, server);
+    if (!args) continue;
+    entry.args = args;
+    count++;
+  }
+  return {
+    output: count ? `${JSON.stringify(data, null, 2)}\n` : original,
+    count,
+  };
+}
+
+// [mcp_servers.<name>] 머리글 다음 줄부터 다음 표 머리글 전까지의 범위.
+function tomlSectionBody(text, name) {
+  let offset = 0;
+  let start = -1;
+  for (const line of text.split(/(?<=\n)/)) {
+    if (start >= 0 && /^\s*\[/.test(line)) return { start, end: offset };
+    const match = line.match(
+      /^\s*\[mcp_servers\.(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))\]\s*(?:#.*)?\r?\n?$/,
+    );
+    offset += line.length;
+    if ((match?.[1] ?? match?.[2] ?? match?.[3]) === name) start = offset;
+  }
+  return start >= 0 ? { start, end: offset } : null;
+}
+
+function pinToml(original, servers) {
+  const data = toml.parse(original);
+  let output = original;
+  let count = 0;
+  for (const [name, server] of servers) {
+    const args = pinnedArgs(data.mcp_servers?.[name], server);
+    const section = args && tomlSectionBody(output, name);
+    if (!section) continue;
+    const body = output.slice(section.start, section.end);
+    const next = body.replace(
+      /^([ \t]*(?:args|"args"|'args')[ \t]*=[ \t]*)\[[^\]]*\]/m,
+      `$1${JSON.stringify(args)}`,
+    );
+    if (next === body) continue;
+    output = output.slice(0, section.start) + next + output.slice(section.end);
+    data.mcp_servers[name].args = args;
+    count++;
+  }
+  if (count && !isDeepStrictEqual(toml.parse(output), data))
+    throw new Error("TOML 구조 불일치");
+  return { output, count };
+}
+
+/** 레지스트리 stdio 항목 중 패키지 버전만 다른 것을 레지스트리 고정 버전으로 바꾼다. */
+export function pinRegistryMcpPackages({
+  home = homedir(),
+  registry = loadRegistryOrDefault(),
+  backups,
+} = {}) {
+  const result = {
+    ok: true,
+    changed: false,
+    pinned: 0,
+    backups: [],
+    warnings: [],
+  };
+  // 테스트가 실제 홈의 설정을 바꾸지 않게 한다.
+  if (
+    process.env.NODE_TEST_CONTEXT &&
+    resolve(home) === resolve(userInfo().homedir)
+  ) {
+    result.skipped = true;
+    return result;
+  }
+  const stdio = Object.entries(registry?.servers ?? {}).filter(
+    ([, server]) =>
+      typeof server?.command === "string" && Array.isArray(server.args),
+  );
+  const seen = new Set();
+  for (const [relative, kind, client] of REGISTRY_PIN_FILES) {
+    const servers = stdio.filter(([, server]) =>
+      // mcp-guard-engine 의 serverTargets 처럼 빈 targets 는 기본 세 클라이언트다.
+      (server.targets?.length
+        ? server.targets
+        : ["claude", "codex", "antigravity"]
+      ).includes(client),
+    );
+    if (!servers.length) continue;
+    const file = join(home, relative);
+    try {
+      const target = fileTarget(file);
+      if (!target || !markFirst(seen, target)) continue;
+      const original = readFileSync(target, "utf8");
+      if (!original.trim()) continue;
+      const plan =
+        kind === "toml"
+          ? pinToml(original, servers)
+          : pinJson(original, servers);
+      if (!plan.count) continue;
+      if (
+        fileTarget(file) !== target ||
+        readFileSync(target, "utf8") !== original
+      ) {
+        result.warnings.push(`${file}: 검사 후 변경되어 건너뜀`);
+        continue;
+      }
+      result.backups.push(writeAtomic(file, target, plan.output, backups));
+      result.pinned += plan.count;
+      result.changed = true;
+    } catch {
+      result.warnings.push(`${file}: MCP 버전 고정 반영 실패, 파일 보존`);
+      result.ok = false;
+    }
+  }
+  return result;
+}

package/scripts/lib/mcp-guard-engine.mjs

@@ -6,6 +6,7 @@ import {
   readFileSync,
   writeFileSync,
 } from "node:fs";
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import {
   basename,
@@ -16,6 +17,7 @@ import {
   resolve,
 } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
 
 const PROJECT_ROOT = fileURLToPath(new URL("../../", import.meta.url));
 const DEFAULT_REGISTRY_PATH = join(PROJECT_ROOT, "config", "mcp-registry.json");
@@ -632,20 +634,31 @@ function formatTomlArray(values = []) {
   return `[${values.map((value) => formatTomlString(value)).join(", ")}]`;
 }
 
+// 한 줄에서 열린 [ 와 닫힌 ] 의 차. 문자열과 주석 안의 괄호는 세지 않는다.
+function arrayDepth(text) {
+  const code = text
+    .replace(/"""[\s\S]*?"""|'''[\s\S]*?'''/g, "")
+    .replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, "")
+    .replace(/#.*$/, "");
+  return (code.match(/\[/g) || []).length - (code.match(/\]/g) || []).length;
+}
+
+const TOML_MANAGED_KEYS = new Set([
+  "url",
+  "transport",
+  "command",
+  "args",
+  "bearer_token_env_var",
+  "http_headers",
+  "env_http_headers",
+  "env",
+  "env_vars",
+]);
+
 function upsertTomlServer(raw, name, config, codex = {}) {
   const lines = String(raw || "").split(/\r?\n/);
   const header = `[mcp_servers.${name}]`;
-  const managedKeys = new Set([
-    "url",
-    "transport",
-    "command",
-    "args",
-    "bearer_token_env_var",
-    "http_headers",
-    "env_http_headers",
-    "env",
-    "env_vars",
-  ]);
+  const managedKeys = TOML_MANAGED_KEYS;
   const nextManagedLines = [];
   if (typeof config.url === "string") {
     nextManagedLines.push(`url = ${formatTomlString(config.url)}`);
@@ -696,6 +709,21 @@ function upsertTomlServer(raw, name, config, codex = {}) {
       const keyMatch = lines[index].match(/^\s*([A-Za-z0-9_]+)\s*=/);
       if (!keyMatch || !managedKeys.has(keyMatch[1])) {
         preserved.push(lines[index]);
+      } else {
+        // 여러 줄 배열 값은 닫는 ] 까지 함께 걷어낸다. 남기면 다음 줄들이 고아가 되어 파일이 깨진다.
+        // 배열 값일 때만, 다음 키나 표 머리글 앞에서는 멈춘다.
+        const value = lines[index].slice(keyMatch[0].length);
+        let depth = value.trimStart().startsWith("[") ? arrayDepth(value) : 0;
+        while (
+          depth > 0 &&
+          index + 1 < lines.length &&
+          !/^\s*(?:[A-Za-z0-9_-]+\s*=|\[\[?\s*[A-Za-z0-9_"'-])/.test(
+            lines[index + 1],
+          )
+        ) {
+          index += 1;
+          depth += arrayDepth(lines[index]);
+        }
       }
       index += 1;
     }
@@ -751,6 +779,29 @@ function syncDenylistKey(client, serverName) {
     .toLowerCase()}`;
 }
 
+// 범위 이름(@scope/name)의 첫 @ 는 이름에 속한다.
+function splitPackageSpec(spec) {
+  const match = /^((?:@[^/@\s]+\/)?[^@\s]+)(?:@(\S+))?$/.exec(spec);
+  return match ? { name: match[1], version: match[2] ?? null } : null;
+}
+
+// 명령과 인자 수가 같고, 다른 자리는 레지스트리의 고정 패키지와 이름만 같을 때 고정 인자를 돌려준다.
+export function pinnedArgs(entry, server) {
+  if (entry?.command !== server.command || !Array.isArray(entry.args))
+    return null;
+  if (entry.args.length !== server.args.length) return null;
+  let changed = false;
+  for (const [index, want] of server.args.entries()) {
+    const have = entry.args[index];
+    if (have === want) continue;
+    const pin = splitPackageSpec(want);
+    if (!pin?.version || typeof have !== "string") return null;
+    if (splitPackageSpec(have)?.name !== pin.name) return null;
+    changed = true;
+  }
+  return changed ? [...server.args] : null;
+}
+
 export function buildDesiredServerRecord(name, serverConfig, filePath) {
   const policy = serverPolicy(serverConfig);
   if (policy === "stdio") {
@@ -1107,6 +1158,27 @@ function updateCodexConfig(filePath, updates = [], removals = []) {
   if (finalRaw === previousRaw) {
     return { modified: false, filePath: resolvedPath };
   }
+  // 줄 단위 치환이 파일을 깨뜨리거나 관리 키 밖의 값을 지우면 쓰지 않는다.
+  // 파서가 원본부터 못 읽는 표기(파서가 모르는 TOML 1.0 문법)는 판정할 수 없어 예전처럼 쓴다.
+  const toml = tomlParser();
+  try {
+    if (
+      toml &&
+      parsesAsToml(toml, previousRaw) &&
+      !isDeepStrictEqual(
+        withoutManagedServers(toml.parse(previousRaw), updates, removals),
+        withoutManagedServers(toml.parse(finalRaw), updates, removals),
+      )
+    )
+      throw new Error("unmanaged TOML changed");
+  } catch {
+    return {
+      modified: false,
+      filePath: resolvedPath,
+      skipped: true,
+      reason: "toml-rewrite-unsafe",
+    };
+  }
 
   mkdirSync(dirname(resolvedPath), { recursive: true });
   // 헤더 비밀이 들어갈 수 있다. 새 파일은 0600, 기존 파일은 권한이 그대로 유지된다.
@@ -1830,6 +1902,52 @@ export function removeServerFromTargets(name, options = {}) {
   return { actions };
 }
 
+// packages/remote 는 @iarna/toml 을 의존으로 두지 않아 늦게 불러오고, 없으면 null.
+function tomlParser() {
+  try {
+    return createRequire(import.meta.url)("@iarna/toml");
+  } catch {
+    return null;
+  }
+}
+
+// 갱신한 서버의 관리 키만 뺀다. 남은 값이 원본과 같아야 치환이 사용자 값을 건드리지 않은 것이다.
+function withoutManagedServers(data, updates, removals) {
+  for (const name of removals) delete data.mcp_servers?.[name];
+  for (const { name } of updates) {
+    const server = data.mcp_servers?.[name];
+    if (!server) continue;
+    for (const key of TOML_MANAGED_KEYS) delete server[key];
+    if (!Object.keys(server).length) delete data.mcp_servers[name];
+  }
+  if (data.mcp_servers && !Object.keys(data.mcp_servers).length)
+    delete data.mcp_servers;
+  return data;
+}
+
+function parsesAsToml(toml, raw) {
+  try {
+    toml.parse(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// 간이 TOML 스캐너는 작은따옴표와 줄 끝 주석을 잘못 읽으므로 보호 판정에 쓸 Codex 항목은 실제 파서로 읽는다.
+function existingServerEntry(filePath, snapshot, name) {
+  const scanned = snapshot.servers.find((server) => server.name === name);
+  const toml = isCodexConfig(filePath) && tomlParser();
+  if (!toml) return scanned;
+  try {
+    const entry = toml.parse(readFileSync(resolveFilePath(filePath), "utf8"))
+      .mcp_servers?.[name];
+    return entry && { ...entry, args: entry.args ?? [] };
+  } catch {
+    return scanned;
+  }
+}
+
 export function syncRegistryTargets(options = {}) {
   const registry = options.registry || loadRegistryOrDefault();
   const syncTargets = Array.isArray(options.targets)
@@ -1934,6 +2052,29 @@ export function syncRegistryTargets(options = {}) {
         continue;
       }
 
+      // 사용자가 바꾼 stdio 항목은 덮어쓰지 않는다. 같은 패키지의 버전 차이만 고정 버전으로 맞춘다.
+      const existing = existingServerEntry(target.filePath, snapshot, name);
+      if (
+        serverPolicy(serverConfig) === "stdio" &&
+        typeof existing?.command === "string" &&
+        existing.command &&
+        !(
+          existing.command === serverConfig.command &&
+          JSON.stringify(existing.args) === JSON.stringify(serverConfig.args)
+        ) &&
+        !pinnedArgs(existing, serverConfig)
+      ) {
+        actions.push({
+          type: "sync",
+          filePath: target.filePath,
+          label: target.label,
+          status: "warning",
+          server: name,
+          message: `${name}: 레지스트리와 다른 사용자 항목이라 덮어쓰지 않음 (${[existing.command, ...(existing.args ?? [])].join(" ")})`,
+        });
+        continue;
+      }
+
       updates.push(
         buildDesiredServerRecord(name, serverConfig, target.filePath),
       );
@@ -1950,6 +2091,18 @@ export function syncRegistryTargets(options = {}) {
       continue;
     }
 
+    if (result.reason === "toml-rewrite-unsafe") {
+      actions.push({
+        type: "sync",
+        filePath: target.filePath,
+        label: target.label,
+        status: "warning",
+        message:
+          "줄 단위로 고칠 수 없는 TOML 표기(여러 줄 값 등)라 파일을 바꾸지 않음",
+      });
+      continue;
+    }
+
     actions.push({
       type: "sync",
       filePath: target.filePath,

package/scripts/setup.mjs

@@ -35,7 +35,11 @@ import {
   cleanupAgyHooks,
   cleanupLegacyHooks,
 } from "./lib/legacy-hook-cleanup.mjs";
-import { cleanupLegacyMcp, cleanupTfxHub } from "./lib/legacy-mcp-cleanup.mjs";
+import {
+  cleanupLegacyMcp,
+  cleanupTfxHub,
+  pinRegistryMcpPackages,
+} from "./lib/legacy-mcp-cleanup.mjs";
 import {
   MACHINE_PROFILE_KEYS,
   parseMachineProfileContent,
@@ -447,7 +451,7 @@ const PSMUX_WINGET_ARGS = [
 ];
 const PSMUX_MANUAL_INSTALL = "winget install --exact --id marlocarlo.psmux";
 
-// psmux 설치와 Codex 훅 승인은 사용자 동의 뒤에만 한다. 물을 수 없으면 하지 않고 안내만 남긴다.
+// psmux, tmr, mods 설치와 Codex 훅 승인은 사용자 동의 뒤에만 한다. 물을 수 없으면 하지 않고 안내만 남긴다.
 export async function runConsentSteps({
   platform = process.platform,
   env = process.env,
@@ -459,6 +463,8 @@ export async function runConsentSteps({
   run = execFileSync,
   ensureHooks = ensureCodexHooks,
   offerTmr = offerTmrInstall,
+  modsInstall = false,
+  offerMods = ensureTrifluxMods,
   home = _TFX_HOME,
   log = console.log,
   warn = console.warn,
@@ -466,6 +472,7 @@ export async function runConsentSteps({
   const result = {
     psmux: "not-needed",
     tmr: "not-needed",
+    mods: "not-needed",
     codexHooks: "skipped",
   };
 
@@ -504,6 +511,16 @@ export async function runConsentSteps({
     warn,
   });
 
+  result.mods = await offerMods({
+    install: modsInstall,
+    interactive,
+    ask,
+    env,
+    execFileSyncFn: run,
+    log,
+    warn,
+  });
+
   try {
     const hooks = ensureHooks({ trust: false });
     if (hooks?.skipped) return result;
@@ -1292,17 +1309,12 @@ function isProtectedSetupEnv(env = process.env) {
   return env.CI === "true" || Boolean(env.TRIFLUX_TEST_HOME) || isTestRun(env);
 }
 
-export function ensureTrifluxMods({
-  install = false,
-  env = process.env,
-  execFileSyncFn = execFileSync,
-  log = console.log,
-  warn = console.warn,
-} = {}) {
-  if (isProtectedSetupEnv(env) || env.npm_lifecycle_event === "postinstall") {
-    return { ok: true, skipped: true, reason: "protected-env" };
-  }
-  const run = (args) =>
+const MODS_PLUGIN_ID = "triflux-mods@triflux";
+export const MODS_UPDATE_COMMAND =
+  "claude plugin marketplace update triflux && claude plugin update triflux-mods@triflux --scope user";
+
+function claudeCli(env, execFileSyncFn) {
+  return (args) =>
     execFileSyncFn("claude", args, {
       env,
       encoding: "utf8",
@@ -1311,13 +1323,23 @@ export function ensureTrifluxMods({
       windowsHide: true,
       shell: process.platform === "win32",
     });
+}
+
+/** mods 설치 상태를 읽기만 한다. setup 과 doctor 가 같은 판정을 쓴다. */
+export function inspectTrifluxMods({
+  env = process.env,
+  pkgVersion = getPackageVersion(),
+  run = claudeCli(env, execFileSync),
+} = {}) {
+  if (isProtectedSetupEnv(env) || env.npm_lifecycle_event === "postinstall")
+    return { status: "skipped", reason: "protected-env" };
   let version;
   try {
     version = String(run(["--version"]))
       .trim()
       .match(/^(\d+)\.(\d+)\.(\d+)(?:\s|$)/u);
   } catch {
-    return { ok: true, skipped: true, reason: "claude-unavailable" };
+    return { status: "skipped", reason: "claude-unavailable" };
   }
   const [major, minor, patch] = (version?.slice(1) || []).map(Number);
   if (
@@ -1325,32 +1347,91 @@ export function ensureTrifluxMods({
       major > 2 ||
       (major === 2 && (minor > 1 || (minor === 1 && patch >= 287)))
     )
-  ) {
-    return { ok: true, skipped: true, reason: "unsupported-version" };
-  }
+  )
+    return { status: "skipped", reason: "unsupported-version" };
   try {
     const marketplaces = JSON.parse(
       run(["plugin", "marketplace", "list", "--json"]),
     );
-    const plugins = JSON.parse(run(["plugin", "list", "--json"]));
-    const installed = plugins.some(
-      (plugin) => plugin.id === "triflux-mods@triflux",
+    // setup 은 user scope 에만 설치한다. project/local 설치는 다른 프로젝트 것일 수 있어 보지 않는다.
+    const plugin = JSON.parse(run(["plugin", "list", "--json"])).find(
+      (entry) =>
+        entry.id === MODS_PLUGIN_ID && (entry.scope ?? "user") === "user",
+    );
+    const hasMarketplace = marketplaces.some(
+      (marketplace) => marketplace.name === "triflux",
     );
-    if (!marketplaces.some((marketplace) => marketplace.name === "triflux")) {
+    // 버전을 모르면 차이로 보지 않는다.
+    const outdated =
+      Boolean(plugin?.version && pkgVersion) && plugin.version !== pkgVersion;
+    return {
+      status: !plugin ? "missing" : outdated ? "outdated" : "current",
+      installedVersion: plugin?.version,
+      pkgVersion,
+      hasMarketplace,
+    };
+  } catch (error) {
+    return { status: "failed", error: _normalizeErrorMessage(error) };
+  }
+}
+
+// 설치와 업데이트는 --mods 나 대화형 동의가 있을 때만 한다. 물을 수 없으면 안내만 남긴다.
+export async function ensureTrifluxMods({
+  install = false,
+  interactive = false,
+  ask = async () => false,
+  env = process.env,
+  pkgVersion = getPackageVersion(),
+  execFileSyncFn = execFileSync,
+  log = console.log,
+  warn = console.warn,
+} = {}) {
+  const run = claudeCli(env, execFileSyncFn);
+  const mods = inspectTrifluxMods({ env, pkgVersion, run });
+  if (mods.status === "skipped") return "not-needed";
+  if (mods.status === "current") return "present";
+  try {
+    if (mods.status === "failed") throw new Error(mods.error);
+    if (!mods.hasMarketplace)
       run(["plugin", "marketplace", "add", "tellang/triflux"]);
-    }
-    if (!installed) {
-      if (install) {
-        run(["plugin", "install", "triflux-mods@triflux"]);
-        log("mods 설치 완료: triflux-mods@triflux");
-      } else {
+    if (mods.status === "missing") {
+      if (!install && !interactive) {
         log("mods 설치: tfx setup --mods");
+        return "deferred";
+      }
+      if (
+        !install &&
+        !(await ask(
+          "triflux mods 플러그인(HUD band, 서브에이전트 effort 정책)을 설치할까요?",
+        ))
+      ) {
+        log("mods 설치를 건너뜀. 나중에 설치: tfx setup --mods");
+        return "declined";
       }
+      run(["plugin", "install", MODS_PLUGIN_ID]);
+      log(`mods 설치 완료: ${MODS_PLUGIN_ID}`);
+      return "installed";
     }
-    return { ok: true, installed: installed || install };
+    const gap = `${mods.installedVersion}, 패키지 ${mods.pkgVersion}`;
+    if (!install && !interactive) {
+      log(`mods 버전이 다르다(설치 ${gap}). 업데이트: ${MODS_UPDATE_COMMAND}`);
+      return "outdated";
+    }
+    if (
+      !install &&
+      !(await ask(`triflux mods 를 업데이트할까요? (설치 ${gap})`))
+    ) {
+      log(`mods 업데이트를 건너뜀. 나중에: ${MODS_UPDATE_COMMAND}`);
+      return "update-declined";
+    }
+    run(["plugin", "marketplace", "update", "triflux"]);
+    // scope 를 빼면 CLI 가 다른 scope 설치를 고를 수 있다.
+    run(["plugin", "update", MODS_PLUGIN_ID, "--scope", "user"]);
+    log("mods 업데이트 완료. Claude Code 를 다시 시작하면 적용된다.");
+    return "updated";
   } catch (error) {
     warn(`[setup] mods 설정 실패: ${_normalizeErrorMessage(error)}`);
-    return { ok: false, reason: "setup-failed" };
+    return "failed";
   }
 }
 
@@ -2015,17 +2096,27 @@ export async function runDeferred(stdinData) {
   for (const warning of hubCleanup.warnings) io.log(`  ⚠ ${warning}`);
   if (hubCleanup.changed) io.log("  허브 설정과 실행 흔적 정리");
 
+  const mcpPins = pinRegistryMcpPackages({
+    home: _TFX_HOME,
+    backups: mcpBackups,
+  });
+  for (const warning of mcpPins.warnings) io.log(`  ⚠ ${warning}`);
+  if (mcpPins.pinned)
+    io.log(`  MCP 패키지 고정 버전 반영: ${mcpPins.pinned}개 항목`);
+
   const pkgVersion = getPackageVersion();
   const marker = readMarker();
   const skillSync = syncSkills();
   for (const warning of skillSync.warnings) io.log(`  ⚠ ${warning}`);
   if (!skillSync.ok) return io.result(1);
-  ensureTrifluxMods({
-    install: argv.includes("--mods"),
-    log: (message) => io.log(message),
-    warn: (message) => io.log(`  ⚠ ${message}`),
-  });
-  if (pkgVersion && marker?.version === pkgVersion && !isForce) {
+  // --mods 는 동의 단계에서 처리하므로 이미 동기화된 버전이어도 건너뛰지 않는다.
+  const modsInstall = argv.includes("--mods");
+  if (
+    pkgVersion &&
+    marker?.version === pkgVersion &&
+    !isForce &&
+    !modsInstall
+  ) {
     io.log(`setup: skip (v${pkgVersion} already synced)`);
     return io.result(0);
   }
@@ -2213,6 +2304,7 @@ export async function runDeferred(stdinData) {
   }
 
   await runConsentSteps({
+    modsInstall,
     log: (message) => io.log(`  ${message}`),
     warn: (message) => io.log(`  \x1b[33m⚠\x1b[0m ${message}`),
   });

package/skills/tfx-live/SKILL.md

@@ -14,7 +14,7 @@ argument-hint: "<start|ask|wait|queue|compact|stop|rename|interrupt|probe|list-s
 ## 전송 경로
 
 - Claude `--short` 또는 `--session-id`는 기본 `auto`로 UDS를 먼저 시도한다. `--session`이 있고 입력 미전송이 확인된 UDS 실패라면 tmux로 전환하고 `~/.claude/cache/triflux/tfx-live/bug-reports/uds-fallback-*.json`을 남긴다. 컨텍스트 가드 거부 시에는 전환하지 않는다.
-- Codex `ask`는 `codex queue`가 기본이다. 아래 "Codex 메시지 전송" 순서를 따른다. 기존 Codex thread의 UDS 연결은 `--transport uds --thread <id|auto>`를 명시한다.
+- Codex `ask`는 Codex 큐(app-server `thread/queue/add`)가 기본이다. 아래 "Codex 메시지 전송" 순서를 따른다. 기존 Codex thread의 UDS 연결은 `--transport uds --thread <id|auto>`를 명시한다.
 - daemon 참조가 없는 Claude는 tmux가 기본이다.
 - UDS 결과는 `matchedCompletion === true`일 때만 `done: true`다. timeout이나 연결 종료는 완료가 아니다.
 - bridge 선택 순서는 `--bridge`, `$TFX_BRIDGE`, `$TFX_REPO_ROOT/hub/bridge.mjs`, 번들된 `hub/bridge.mjs`다.
@@ -44,7 +44,7 @@ tfx-live stop --cli codex --session cx1
 
 ### Codex 메시지 전송
 
-1. 기본은 `codex queue --thread <UUID>`다. 입력창을 건드리지 않고, 바쁘면 쌓였다가 앞 턴이 끝난 직후 순서대로 들어간다. 유휴 TUI는 약 20초 주기로 큐를 가져간다.
+1. 기본은 app-server 실험 API `thread/queue/add`로 쌓는 것이다. 프롬프트가 프로세스 인자에 보이지 않는다. 입력창을 건드리지 않고, 바쁘면 쌓였다가 앞 턴이 끝난 직후 순서대로 들어간다. 유휴 TUI는 약 20초 주기로 큐를 가져간다. add가 없는 Codex에서만 `codex queue --thread <UUID> --message`로 보내며, 이때 프롬프트가 argv에 보이고 결과에 `queueVia: "codex-queue-argv"`와 `queueFallbackReason`이 남는다. 평소 값은 `queueVia: "app-server"`다.
 2. 첫 줄 머리말은 `[from <보낸 세션 이름>] [tfx-live req=<id>]`다. 이름은 `--from`, `$TFX_LIVE_FROM`, Claude 세션 기록, Codex `session_index` 순으로 찾고 없으면 머리말 없이 표식만 붙인다. Codex TUI는 Claude처럼 접어 보여 주지 않고 사용자 입력으로 그대로 표시한다.
 3. thread는 `--thread UUID`, `start`가 남긴 `@tfx_codex_thread`, Codex 세션 레지스트리, pane 프로세스의 `resume <UUID>` 인자, pane cwd와 같은 rollout 하나 순으로 찾는다. cwd 대응은 그 cwd의 Codex TUI가 하나일 때만 쓰고 exec 워커와 서브에이전트 thread는 뺀다. 이름으로는 보내지 않는다(`codex queue`의 이름 조회가 실패한다).
 4. tmux 직접 입력은 queue를 못 쓸 때만 쓴다: 원격 호스트, thread를 못 찾음(`start` 밖에서 `resume --last`로 띄운 세션, `start --resume-last`의 `threadId: null`, 같은 cwd의 TUI 여럿 포함), `codex queue` 오류(0.160 미만 포함). 결과에 `transport: "tmux"`, `transportRequested: "queue"`, `fallbackReason`이 남는다. 시간 초과처럼 queue가 이미 쌓았을 수도 있는 오류는 `status: "unknown"`으로 끝내고 재전송하지 않는다.