@triflux/core 10.53.0 → 10.55.0

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

@@ -15,63 +15,82 @@ 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");
+// 이주가 써 넣는 직접 연결 패키지. 버전은 이 표 한 곳에서만 올린다(2026-10-08 npm 최신, serena 는 v1.7.0 커밋).
+export const MCP_PACKAGE_PINS = Object.freeze({
+  context7: "@upstash/context7-mcp@4.2.0",
+  "brave-search": "@brave/brave-search-mcp-server@2.1.4",
+  exa: "exa-mcp-server@3.4.2",
+  tavily: "tavily-mcp@0.2.22",
+  jira: "mcp-jira-cloud@4.4.0",
+  serena:
+    "git+https://github.com/oraios/serena@949a27ef1e5fda1a6e7b561e777bcece345c6ffd",
+  notion: "@notionhq/notion-mcp-server@2.5.2",
+});
+// gatewayCmd 는 옛 게이트웨이가 띄운 명령 그대로다. 남은 프로세스를 알아보는 데만 쓴다.
 const SERVERS = [
-  ["context7", 8100, "npx", ["-y", "@upstash/context7-mcp@latest"], []],
+  ["context7", 8100, "npx -y @upstash/context7-mcp@latest", []],
   [
     "brave-search",
     8101,
-    "npx",
-    ["-y", "@brave/brave-search-mcp-server"],
+    "npx -y @brave/brave-search-mcp-server",
     ["BRAVE_API_KEY"],
   ],
-  ["exa", 8102, "npx", ["-y", "exa-mcp-server"], ["EXA_API_KEY"]],
-  ["tavily", 8103, "npx", ["-y", "tavily-mcp@latest"], ["TAVILY_API_KEY"]],
+  ["exa", 8102, "npx -y exa-mcp-server", ["EXA_API_KEY"]],
+  ["tavily", 8103, "npx -y tavily-mcp@latest", ["TAVILY_API_KEY"]],
   [
     "jira",
     8104,
-    "npx",
-    ["-y", "mcp-jira-cloud@latest"],
+    "npx -y mcp-jira-cloud@latest",
     ["JIRA_API_TOKEN", "JIRA_EMAIL", "JIRA_INSTANCE_URL"],
   ],
   [
     "serena",
     8105,
-    "uvx",
-    [
-      "--from",
-      "git+https://github.com/oraios/serena",
-      "serena",
-      "start-mcp-server",
-    ],
+    "uvx --from git+https://github.com/oraios/serena serena start-mcp-server",
     [],
   ],
-  [
-    "notion",
-    8106,
-    "npx",
-    ["-y", "@notionhq/notion-mcp-server"],
-    ["NOTION_TOKEN"],
-  ],
+  ["notion", 8106, "npx -y @notionhq/notion-mcp-server", ["NOTION_TOKEN"]],
   [
     "notion-guest",
     8107,
-    "npx",
-    ["-y", "@notionhq/notion-mcp-server"],
+    "npx -y @notionhq/notion-mcp-server",
     ["NOTION_TOKEN"],
   ],
-].map(([name, port, command, args, envVars]) => ({
-  name,
-  port,
-  command,
-  args,
-  envVars,
-}));
+].map(([name, port, gatewayCmd, envVars]) => {
+  const pin = MCP_PACKAGE_PINS[name === "notion-guest" ? "notion" : name];
+  return {
+    name,
+    port,
+    gatewayCmd,
+    command: name === "serena" ? "uvx" : "npx",
+    args:
+      name === "serena"
+        ? ["--from", pin, "serena", "start-mcp-server"]
+        : ["-y", pin],
+    envVars,
+  };
+});
+// 게이트웨이 이주와 허브 정리가 함께 쓰는 사용자 MCP 설정 파일. HOME 기준 경로와 형식.
+// ~/.mcp.json 은 HOME 에서 Claude 를 열 때 읽는 파일이라 프로젝트 파일이 아니라 사용자 파일로 본다.
+const USER_MCP_FILES = [
+  [".claude.json", "json"],
+  [".mcp.json", "json"],
+  [".claude/mcp.json", "json"],
+  [".claude/.mcp.json", "json"],
+  [".claude/settings.json", "json"],
+  [".codex/config.json", "json"],
+  [".codex/config.toml", "toml"],
+  [".gemini/settings.json", "json"],
+  // agy 는 \${VAR} 참조를 풀지 않으므로 env 없이 바꾸고 셸 환경을 물려받게 한다.
+  [".gemini/config/mcp_config.json", "agy"],
+];
 const BY_PORT = new Map(SERVERS.map((server) => [server.port, server]));
 const LABEL = "com.tellang.mcp-gateway";
 const TASK = "MCP Gateway";
@@ -94,6 +113,13 @@ function fileTarget(file) {
   return target;
 }
 
+function markFirst(seen, target) {
+  const key = realpathSync(target);
+  if (seen.has(key)) return false;
+  seen.add(key);
+  return true;
+}
+
 function ownedUrl(value) {
   if (typeof value !== "string") return null;
   let url;
@@ -349,8 +375,11 @@ function backupStartup(home, file) {
   return backupFile(join(directory, basename(file)), readFileSync(file));
 }
 
-function writeAtomic(file, target, output) {
-  const backup = backupFile(file);
+// setup 한 번은 게이트웨이 이주와 허브 정리에 같은 backups 를 넘긴다.
+// 같은 파일은 그 setup 에서 처음 바꾸기 직전의 원본만 백업한다.
+function writeAtomic(file, target, output, backups = new Map()) {
+  const backup = backups.get(target) ?? backupFile(file);
+  backups.set(target, backup);
   const temp = join(
     dirname(target),
     `.tfx-mcp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.tmp`,
@@ -600,9 +629,9 @@ function ownedCommand(command) {
       "--healthEndpoint /healthz",
     ].every((flag) => command.includes(flag)) &&
     SERVERS.some(
-      ({ port, command: executable, args }) =>
+      ({ port, gatewayCmd }) =>
         new RegExp(`\\s--port\\s+${port}(?:\\s|$)`).test(command) &&
-        command.includes([executable, ...args].join(" ")),
+        command.includes(gatewayCmd),
     )
   );
 }
@@ -676,6 +705,7 @@ export function cleanupLegacyMcp({
   uid = process.getuid?.(),
   env = process.env,
   dryRun = false,
+  backups,
 } = {}) {
   const result = {
     ok: true,
@@ -713,21 +743,35 @@ export function cleanupLegacyMcp({
     result.warnings.push("별도 HOME과 실제 작업 디렉터리가 섞여 이주를 중단함");
     return result;
   }
-  const files = [
-    [join(home, ".claude.json"), "json"],
-    [join(repoRoot, ".mcp.json"), "json"],
-    [join(home, ".codex/config.toml"), "toml"],
-    [join(home, ".gemini/settings.json"), "json"],
-    // agy 는 \${VAR} 참조를 풀지 않으므로 env 없이 바꾸고 셸 환경을 물려받게 한다.
-    [join(home, ".gemini/config/mcp_config.json"), "agy"],
-  ];
+  const files = USER_MCP_FILES.map(([relative, kind]) => [
+    join(home, relative),
+    kind,
+  ]);
+  if (resolve(repoRoot) !== resolve(home))
+    files.push([join(repoRoot, ".mcp.json"), "json"]);
   const plans = [];
+  const kinds = new Map();
   let blocked = false;
   for (const [file, kind] of files) {
     try {
       const target = fileTarget(file);
       if (!target) continue;
+      // symlink 별칭이 같은 파일을 두 번 계획하면 두 번째 쓰기가 원문 검증에서 막힌다.
+      // 형식이 다른 별칭(agy 와 json)은 env 처리가 달라 한쪽이 깨지므로 이주를 멈춘다.
+      const key = realpathSync(target);
+      if (kinds.has(key)) {
+        if (kinds.get(key) !== kind) {
+          result.warnings.push(
+            `${file}: 형식이 다른 설정과 같은 파일이라 이주를 멈춤`,
+          );
+          blocked = true;
+        }
+        continue;
+      }
+      kinds.set(key, kind);
       const original = readFileSync(target, "utf8");
+      // 빈 파일은 항목이 없는 것이다. 형식 오류로 보면 이주 전체가 멈춘다.
+      if (!original.trim()) continue;
       const plan =
         kind === "toml"
           ? patchToml(original, file, home, env, result.warnings)
@@ -754,7 +798,9 @@ export function cleanupLegacyMcp({
         readFileSync(plan.target, "utf8") !== plan.original
       )
         throw new Error(`${plan.file}: 검사 후 변경됨`);
-      result.backups.push(writeAtomic(plan.file, plan.target, plan.output));
+      result.backups.push(
+        writeAtomic(plan.file, plan.target, plan.output, backups),
+      );
       result.changed = true;
     }
   } catch (error) {
@@ -784,15 +830,11 @@ export function cleanupLegacyMcp({
 }
 
 const HUB_SERVER = "tfx-hub";
-const HUB_TASK = "TrifluxHubEnsure";
-const HUB_CONFIG_FILES = [
-  [".claude.json", "json"],
-  [".claude/settings.json", "json"],
-  [".claude/mcp.json", "json"],
-  [".codex/config.json", "json"],
-  [".codex/config.toml", "toml"],
-  [".gemini/settings.json", "json"],
-  [".gemini/config/mcp_config.json", "json"],
+// [작업 이름, 그 작업이 허브용임을 보여 주는 실행 명령 조각]
+// \Triflux\Hub 는 만든 코드가 이력에 없지만 지워진 `tfx hub ensure` 를 실행해 로그온마다 실패한다.
+const HUB_TASKS = [
+  ["TrifluxHubEnsure", "hub-ensure.mjs"],
+  ["\\Triflux\\Hub", "tfx hub ensure"],
 ];
 
 // 허브가 등록한 항목은 loopback 의 /mcp 주소다. 다른 모양이면 사용자 항목으로 본다.
@@ -899,32 +941,130 @@ function hubCommandLine(pid, platform, run) {
   return platform !== "win32" && result.status === 1 ? null : undefined;
 }
 
-function stopHub(home, platform, run, result) {
-  const pidFile = join(home, ".claude/cache/tfx-hub/hub.pid");
-  const target = fileTarget(pidFile);
-  if (!target) return;
-  let pid;
+// 명령줄을 argv 로 나눈다. Linux 는 /proc 의 실제 argv, Windows 는 따옴표 규칙을 쓴다.
+// macOS ps 는 인자 경계를 보존하지 않아 공백으로 나누고 exact 를 false 로 둔다.
+function processArgv(pid, command, platform) {
+  if (platform === "linux") {
+    try {
+      const argv = readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0");
+      if (argv.at(-1) === "") argv.pop();
+      if (argv.length) return { argv, exact: true };
+    } catch {
+      // 프로세스가 사라졌거나 /proc 를 읽을 수 없다.
+    }
+  }
+  if (platform === "win32") return splitWindowsCommandLine(command);
+  return { argv: command.trim().split(/\s+/), exact: false };
+}
+
+// 따옴표 밖 space, tab 에서만 끊고 따옴표 구간은 앞뒤 글자와 한 인자로 잇는다(Windows CRT 규칙).
+// 백슬래시로 가린 따옴표는 규칙이 복잡해 경계를 믿지 않는다.
+function splitWindowsCommandLine(command) {
+  const argv = [];
+  let current = "";
+  let quoted = false;
+  let started = false;
+  for (const char of command) {
+    if (char === '"') {
+      quoted = !quoted;
+      started = true;
+    } else if ((char === " " || char === "\t") && !quoted) {
+      if (started) argv.push(current);
+      current = "";
+      started = false;
+    } else {
+      current += char;
+      started = true;
+    }
+  }
+  if (started) argv.push(current);
+  return { argv, exact: !command.includes('\\"') };
+}
+
+// 허용 목록. 값을 받는 옵션(다음 인자 또는 --name=value)과 값이 없는 플래그만 건너뛴다.
+// 그 밖의 옵션(--run, --eval, --test, --watch 같은 실행 모드 포함)은 entry 를 특정할 수 없어
+// 허브가 아닌 것으로 본다.
+const NODE_VALUE_OPTIONS = new Set([
+  "-r",
+  "--require",
+  "--import",
+  "--loader",
+  "--experimental-loader",
+  "--env-file",
+  "--input-type",
+  "-C",
+  "--conditions",
+]);
+const NODE_FLAG_OPTIONS = new Set([
+  "--no-warnings",
+  "--enable-source-maps",
+  "--trace-warnings",
+  "--trace-uncaught",
+  "--inspect",
+  "--expose-gc",
+]);
+
+// node 의 entry script 가 triflux 패키지의 hub/server.mjs 일 때만 패키지 루트를 돌려준다.
+// 같은 경로를 인자로 받거나 편집하는 다른 프로세스는 허브가 아니다.
+// argv 경계를 믿을 수 없으면(exact=false) 값이 붙는 옵션은 공백 든 값일 수 있어 판정하지 않는다.
+function trifluxHubRoot({ argv, exact }) {
+  if (!/(?:^|[/\\])node(?:\.exe)?$/i.test(argv[0] ?? "")) return null;
+  let index = 1;
+  while (argv[index]?.startsWith("-")) {
+    const [name, value] = argv[index].split("=");
+    if (NODE_FLAG_OPTIONS.has(name) && value === undefined) index += 1;
+    else if (exact && NODE_VALUE_OPTIONS.has(name))
+      index += value === undefined ? 2 : 1;
+    else return null;
+  }
+  // 공백이 든 경로가 잘린 조각은 상대 경로로 남으므로 절대 경로만 받는다.
+  const entry = argv[index]?.match(
+    /^((?:[A-Za-z]:)?[/\\].*)[/\\]hub[/\\]server\.mjs$/,
+  );
+  if (!entry) return null;
+  // 공백 든 entry 가 잘린 조각일 수 있으므로 뒤에 인자가 남으면 판정하지 않는다.
+  if (!exact && argv.length > index + 1) return null;
   try {
-    pid = Number(JSON.parse(readFileSync(target, "utf8")).pid);
+    const pkg = JSON.parse(
+      readFileSync(join(entry[1], "package.json"), "utf8"),
+    );
+    return pkg?.name === "triflux" ? entry[1] : null;
   } catch {
-    /* 아래에서 보존 처리 */
+    return null;
   }
-  if (!Number.isInteger(pid) || pid <= 1) {
-    result.warnings.push(`${pidFile}: pid 를 읽을 수 없어 보존`);
-    return;
+}
+
+function listHubProcesses(platform, run) {
+  if (platform === "win32") {
+    const result = runPowerShell(
+      run,
+      "$items=@(Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | ForEach-Object { @{ pid=[string]$_.ProcessId; command=$_.CommandLine } }); ConvertTo-Json -InputObject $items -Compress",
+    );
+    if (!result.ok) return null;
+    return JSON.parse(result.output || "[]");
   }
-  const command = hubCommandLine(pid, platform, run);
-  if (command === undefined) {
-    result.warnings.push(`${pidFile}: pid ${pid} 확인 실패, 종료하지 않음`);
+  const result = tryRun(run, "ps", ["-axo", "pid=,command="]);
+  if (!result.ok) return null;
+  return result.output.split(/\r?\n/).flatMap((line) => {
+    const match = line.match(/^\s*(\d+)\s+(.+)$/);
+    return match ? [{ pid: match[1], command: match[2] }] : [];
+  });
+}
+
+// 허브는 제거됐으므로 triflux 패키지의 hub/server.mjs 로 확인된 프로세스는 설치본,
+// 체크아웃, worktree 를 가리지 않고 종료한다(2026-10-08 결정).
+function stopHubs(home, platform, run, result, log) {
+  const processes = listHubProcesses(platform, run);
+  if (!processes) {
+    result.warnings.push("허브 프로세스 조회 실패, 종료하지 않음");
     return;
   }
-  if (command !== null) {
-    if (!/[/\\]hub[/\\]server\.mjs(?:["'\s]|$)/.test(command)) {
-      // 허브가 아닌 프로세스는 건드리지 않고 우리 파일만 지운다.
-      unlinkSync(target);
-      result.changed = true;
-      return;
-    }
+  let allStopped = true;
+  for (const { pid, command } of processes) {
+    if (Number(pid) === process.pid || typeof command !== "string") continue;
+    const root = trifluxHubRoot(processArgv(pid, command, platform));
+    if (!root) continue;
+    log(`허브 종료: pid ${pid} (${root})`);
     const stopped =
       platform === "win32"
         ? tryRun(run, "taskkill", ["/F", "/T", "/PID", String(pid)])
@@ -935,38 +1075,67 @@ function stopHub(home, platform, run, result) {
       if (!gone)
         Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
     }
-    if (!gone) {
-      result.warnings.push(`${pidFile}: pid ${pid} 종료 확인 실패, 파일 보존`);
-      return;
+    if (gone) result.hubStopped = true;
+    else {
+      allStopped = false;
+      result.warnings.push(`허브 pid ${pid}: 종료 확인 실패`);
     }
-    result.hubStopped = true;
   }
-  unlinkSync(target);
+  const pidFile = join(home, ".claude/cache/tfx-hub/hub.pid");
+  if (!allStopped || !fileTarget(pidFile)) return;
+  // 판정을 못 했지만 허브로 보이는 프로세스가 hub.pid 에 있으면 단서를 남긴다.
+  let pid;
+  try {
+    pid = Number(JSON.parse(readFileSync(pidFile, "utf8")).pid);
+  } catch {
+    /* 읽을 수 없는 pid 파일은 지운다 */
+  }
+  const command = Number.isInteger(pid)
+    ? hubCommandLine(pid, platform, run)
+    : null;
+  if (command && /[/\\]hub[/\\]server\.mjs/.test(command)) {
+    result.warnings.push(`${pidFile}: pid ${pid} 를 허브로 확인하지 못해 보존`);
+    return;
+  }
+  unlinkSync(pidFile);
   result.changed = true;
 }
 
-function removeHubTask(run, result) {
-  const query = tryRun(run, "schtasks.exe", [
-    "/Query",
-    "/TN",
-    HUB_TASK,
-    "/FO",
-    "LIST",
-    "/V",
-  ]);
-  if (!query.ok) return;
-  if (!query.output.includes("hub-ensure.mjs")) {
-    result.warnings.push(`${HUB_TASK}: hub-ensure 작업이 아니라 보존`);
-    return;
+// 작업 XML 에서 실행 동작만 꺼낸다. 설명 같은 다른 필드의 문구로 판정하지 않는다.
+function taskExecCommand(xml) {
+  const decode = (text = "") =>
+    text
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'")
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&amp;/g, "&");
+  const actions = xml.match(/<Actions\b[^>]*>([\s\S]*?)<\/Actions>/)?.[1] ?? "";
+  const execs = [...actions.matchAll(/<Exec\b[^>]*>([\s\S]*?)<\/Exec>/g)];
+  if (
+    execs.length !== 1 ||
+    /<(?:ComHandler|SendEmail|ShowMessage)\b/.test(actions)
+  )
+    return null;
+  const field = (name) =>
+    decode(
+      execs[0][1].match(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`))?.[1],
+    );
+  return `${field("Command")} ${field("Arguments")}`;
+}
+
+function removeHubTasks(run, result) {
+  for (const [task, marker] of HUB_TASKS) {
+    const query = tryRun(run, "schtasks.exe", ["/Query", "/TN", task, "/XML"]);
+    if (!query.ok) continue;
+    if (!taskExecCommand(query.output)?.includes(marker)) {
+      result.warnings.push(`${task}: 허브 작업이 아니라 보존`);
+      continue;
+    }
+    const removed = tryRun(run, "schtasks.exe", ["/Delete", "/TN", task, "/F"]);
+    if (removed.ok) result.changed = true;
+    else result.warnings.push(`${task}: 예약 작업 삭제 실패`);
   }
-  const removed = tryRun(run, "schtasks.exe", [
-    "/Delete",
-    "/TN",
-    HUB_TASK,
-    "/F",
-  ]);
-  if (removed.ok) result.changed = true;
-  else result.warnings.push(`${HUB_TASK}: 예약 작업 삭제 실패`);
 }
 
 /** cwd 의 프로젝트 MCP 파일 중 제거된 허브가 만든 tfx-hub 항목이 있는 파일을 돌려준다. */
@@ -988,6 +1157,8 @@ export function cleanupTfxHub({
   platform = osPlatform(),
   run = defaultRun,
   pluginRoot,
+  log = () => {},
+  backups,
 } = {}) {
   const result = {
     ok: true,
@@ -1006,12 +1177,14 @@ export function cleanupTfxHub({
     result.skipped = true;
     return result;
   }
-  for (const [relative, kind] of HUB_CONFIG_FILES) {
+  const seen = new Set();
+  for (const [relative, kind] of USER_MCP_FILES) {
     const file = join(home, relative);
     try {
       const target = fileTarget(file);
-      if (!target) continue;
+      if (!target || !markFirst(seen, target)) continue;
       const original = readFileSync(target, "utf8");
+      if (!original.trim()) continue;
       const plan =
         kind === "toml"
           ? removeHubFromToml(original, file, result.warnings)
@@ -1024,7 +1197,7 @@ export function cleanupTfxHub({
         result.warnings.push(`${file}: 검사 후 변경되어 건너뜀`);
         continue;
       }
-      result.backups.push(writeAtomic(file, target, plan.output));
+      result.backups.push(writeAtomic(file, target, plan.output, backups));
       result.removed += plan.count;
       result.changed = true;
     } catch {
@@ -1037,8 +1210,8 @@ export function cleanupTfxHub({
     (resolve(home) === resolve(homedir()) && platform === osPlatform());
   if (realSystem) {
     try {
-      stopHub(home, platform, run, result);
-      if (platform === "win32") removeHubTask(run, result);
+      stopHubs(home, platform, run, result, log);
+      if (platform === "win32") removeHubTasks(run, result);
     } catch (error) {
       result.ok = false;
       result.warnings.push(`허브 프로세스 정리 실패: ${error.message}`);
@@ -1064,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/machine-profile.mjs

@@ -7,8 +7,8 @@
 // 신뢰 경계: 파일을 source 하거나 eval 하지 않는다. allowlist key 와 안전한
 // literal 값만 읽으므로 셸 표현식은 실행되지 않는다.
 //
-// 부수효과: 모듈 로드 시 파일을 읽지 않고 환경도 바꾸지 않는다. hub/lib/cto-env.mjs
-// 처럼 순수 함수만 노출하므로 HUD, hook, hub 어느 소비자에서도 안전하게 import 한다.
+// 부수효과: 모듈 로드 시 파일을 읽지 않고 환경도 바꾸지 않는다. 순수 함수만
+// 노출하므로 HUD, hook, hub 어느 소비자에서도 안전하게 import 한다.
 
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";