@kaydash9999/banker-plugins 0.17.0 → 0.18.0

package/skills/omc-patch/scripts/omc-patch.mjs

@@ -7,8 +7,10 @@
  *   node omc-patch.mjs --revert     패치·고정 되돌리기
  *   node omc-patch.mjs --no-update  버전은 그대로 두고 패치만
  *   node omc-patch.mjs --root <플러그인 폴더> [--check | --revert]
- *                                   그 폴더의 hooks/hooks.json 과 scripts/ 만 다룬다(번들 사본용).
+ *                                   그 폴더의 hooks/hooks.json 과 scripts/ 만 다룬다(번들 사본, 활성 캐시 폴더 하나).
  *                                   installed_plugins.json, 마켓플레이스 origin, 판은 건드리지 않는다.
+ *                                   이름표(.claude-plugin/plugin.json 의 name, 없으면 package.json 의 name)가
+ *                                   OMC 가 아니면 멈춘다.
  *   node omc-patch.mjs --scan <파일>...
  *                                   헬퍼 선언의 블록 깊이와 래핑 자리를 JSON 으로 낸다(읽기 전용).
  *
@@ -16,14 +18,14 @@
  * 읽는다. 캐시에 TARGET_VERSION 이 있다고 그것을 활성으로 보지 않는다(--no-update 는 활성 버전을 패치).
  * OMC_PATCH_INSTALLED=<json 경로> 로 읽을 파일을 바꿀 수 있다(시험용, --check 와 함께).
  *
- * OS: Windows / macOS / Linux 공통. 런처는 apply.cmd(Windows), apply.sh(그 외).
- * 배경과 근거는 같은 폴더의 README.md.
+ * OS: Windows / macOS / Linux 공통. 런처(apply.cmd, apply.sh)와 배경 문서(README.md)는
+ * 킷 배포 폴더에만 있다. 이 파일만 옮겨 쓰는 곳(예: 스킬 폴더)에는 없다.
  */
 import {
   readFileSync, writeFileSync, writeSync, existsSync, copyFileSync, readdirSync,
-  unlinkSync, mkdirSync, rmSync, symlinkSync,
+  unlinkSync, mkdirSync, rmSync, symlinkSync, lstatSync, realpathSync,
 } from "node:fs";
-import { join, dirname, resolve } from "node:path";
+import { join, dirname, resolve, sep as PATH_SEP, delimiter as PATH_LIST_SEP } from "node:path";
 import { homedir, hostname } from "node:os";
 import { execFileSync } from "node:child_process";
 
@@ -47,7 +49,8 @@ const argv = new Set(args);
 const MODE = argv.has("--revert") ? "revert" : argv.has("--check") ? "check" : "apply";
 const NO_UPDATE = argv.has("--no-update");
 // --root <플러그인 폴더>: 이 PC 의 설치 상태와 상관없이 그 폴더 하나만 고친다. 번들 사본처럼
-// 판 폴더도 installed_plugins.json 도 없는 트리에 쓴다. 값이 없거나 다음 플래그면 멈춘다.
+// 판 폴더도 installed_plugins.json 도 없는 트리나, 활성 캐시 폴더 하나만 고칠 때 쓴다.
+// 값이 없거나 다음 플래그면 멈춘다.
 const ROOT_AT = args.indexOf("--root");
 const ROOT_ARG = ROOT_AT >= 0 ? args[ROOT_AT + 1] : null;
 const ROOT = ROOT_ARG && !ROOT_ARG.startsWith("--") ? resolve(ROOT_ARG) : null;
@@ -113,19 +116,44 @@ const installedVersions = () =>
 // installPath 마지막 구간 → 옛 규칙(TARGET 이 캐시에 있으면 TARGET, 아니면 최신) 순으로 본다.
 function activeVersion() {
   const versions = installedVersions();
-  try {
-    const e = JSON.parse(readFileSync(INSTALLED, "utf8")).plugins?.[PLUGIN_KEY]?.[0];
-    if (e) {
-      if (typeof e.version === "string" && /^\d+\.\d+\.\d+$/.test(e.version) && versions.includes(e.version)) return { v: e.version, src: "installed_plugins.json" };
-      const last = typeof e.installPath === "string" ? e.installPath.split(/[\\/]+/).filter(Boolean).pop() : null;
-      if (last && versions.includes(last)) return { v: last, src: "installed_plugins.json installPath" };
-    }
-  } catch { /* 읽기·파싱 실패는 옛 규칙으로 */ }
+  const found = entryVersion(installedEntry(), versions);
+  if (found) return found;
   return { v: versions.includes(TARGET_VERSION) ? TARGET_VERSION : versions[0] || TARGET_VERSION, src: "추정: installed_plugins.json 에서 확인 못 함" };
 }
 
+// installed_plugins.json 의 omc 항목. 읽기·파싱 실패는 null(옛 규칙으로).
+function installedEntry() {
+  try { return JSON.parse(readFileSync(INSTALLED, "utf8")).plugins?.[PLUGIN_KEY]?.[0] || null; }
+  catch { return null; }
+}
+
+// 항목의 version 필드, 없으면 installPath 마지막 구간. 캐시에 있는 판이어야 한다.
+function entryVersion(e, versions) {
+  if (!e) return null;
+  if (typeof e.version === "string" && /^\d+\.\d+\.\d+$/.test(e.version) && versions.includes(e.version)) return { v: e.version, src: "installed_plugins.json" };
+  const last = typeof e.installPath === "string" ? e.installPath.split(/[\\/]+/).filter(Boolean).pop() : null;
+  if (last && versions.includes(last)) return { v: last, src: "installed_plugins.json installPath" };
+  return null;
+}
+
+// git 이 일할 저장소를 cwd 와 상관없이 정하는 변수. git 훅처럼 GIT_DIR 을 내보낸 셸에서 이 도구를 부르면
+// 마켓플레이스가 아니라 그 저장소의 origin 을 고정했다(/tmp 에서 재현). git 이 다른 저장소로 옮겨 갈 때
+// 지우는 목록(`git rev-parse --local-env-vars`, git 2.43)과 같다. Windows 는 변수 이름의 대소문자를 가리지 않는다.
+const GIT_REPO_VARS = new Set(["GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS",
+  "GIT_CONFIG_COUNT", "GIT_OBJECT_DIRECTORY", "GIT_DIR", "GIT_WORK_TREE", "GIT_IMPLICIT_WORK_TREE", "GIT_GRAFT_FILE",
+  "GIT_INDEX_FILE", "GIT_NO_REPLACE_OBJECTS", "GIT_REPLACE_REF_BASE", "GIT_PREFIX", "GIT_SHALLOW_FILE", "GIT_COMMON_DIR"]);
+// 마켓플레이스의 .git 이 깨졌으면(중단된 clone) git 은 위로 올라가 다음 저장소(dotfiles 로 관리하는 ~/.claude 등)를
+// 고른다. 바로 위 폴더를 천장(GIT_CEILING_DIRECTORIES)으로 두어 마켓플레이스 밖으로 나가지 못하게 한다.
+// 마켓플레이스가 링크면 실제 경로 쪽 위 폴더도 막는다. 셸에 있던 천장 값은 대소문자와 상관없이 이 값으로 바꾼다.
+const gitEnv = () => {
+  const drop = (k) => GIT_REPO_VARS.has(k.toUpperCase()) || k.toUpperCase() === "GIT_CEILING_DIRECTORIES";
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !drop(k)));
+  env.GIT_CEILING_DIRECTORIES = [...new Set([dirname(MARKET), dirname(realOr(MARKET))])].join(PATH_LIST_SEP);
+  return env;
+};
+
 function git(args, cwd = MARKET) {
-  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  return execFileSync("git", args, { cwd, env: gitEnv(), encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
 }
 
 // ── 1. 업데이트 ──────────────────────────────────────────────────────────────
@@ -133,6 +161,19 @@ function ensureVersion() {
   const have = installedVersions();
   if (have.includes(TARGET_VERSION)) { ok(`${TARGET_VERSION} 설치되어 있음`); return true; }
   if (MODE === "check") { bad(`${TARGET_VERSION} 미설치 (설치된 버전: ${have.join(", ") || "없음"})`); return false; }
+  if (!canInstallTarget()) return false;
+
+  log(`  ${TARGET_VERSION} 설치 중...`);
+  const sha = targetSha();
+  if (sha === null) return false;
+  const dest = join(CACHE, TARGET_VERSION);
+  unpackTarget(dest);
+  linkNodeModules(dest, have);
+  return switchActive(sha, have);
+}
+
+// 마켓플레이스가 제 git 저장소이고 git 과 tar 가 있어야 TARGET_VERSION 을 꺼낼 수 있다.
+function canInstallTarget() {
   if (!existsSync(MARKET)) { bad(`마켓플레이스 없음: ${MARKET}\n      Claude Code 에서 marketplace 를 먼저 추가하십시오: ${REPO_URL}`); return false; }
   if (!existsSync(join(MARKET, ".git"))) { bad(`마켓플레이스 폴더가 git 저장소가 아님: ${MARKET}`); return false; }
 
@@ -143,23 +184,28 @@ function ensureVersion() {
     try { execFileSync(cmd, ["--version"], { stdio: "ignore" }); }
     catch { bad(`${cmd} 를 찾을 수 없습니다 (${why} 필요). 설치한 뒤 다시 실행하거나, --no-update 로 패치만 적용하십시오.`); return false; }
   }
+  return true;
+}
 
-  log(`  ${TARGET_VERSION} 설치 중...`);
+// 태그 v<TARGET_VERSION> 의 커밋. 못 찾으면 null.
+function targetSha() {
   try { git(["fetch", "--tags", "--quiet", "origin"]); } catch { /* 오프라인이어도 로컬 태그가 있으면 진행 */ }
-  let sha;
-  try { sha = git(["rev-parse", `v${TARGET_VERSION}^{}`]); }
-  catch { bad(`태그 v${TARGET_VERSION} 를 마켓플레이스에서 찾을 수 없음`); return false; }
+  try { return git(["rev-parse", `v${TARGET_VERSION}^{}`]); }
+  catch { bad(`태그 v${TARGET_VERSION} 를 마켓플레이스에서 찾을 수 없음`); return null; }
+}
 
-  const dest = join(CACHE, TARGET_VERSION);
+// git archive | tar 로 소스를 편다. 저장소에 dist/ 가 포함되어 빌드는 불필요하다.
+function unpackTarget(dest) {
   if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
   mkdirSync(dest, { recursive: true });
-  // git archive | tar 로 소스를 편다. 저장소에 dist/ 가 포함되어 빌드는 불필요하다.
-  execFileSync("git", ["-C", MARKET, "archive", `v${TARGET_VERSION}`, "-o", join(dest, "_src.tar")], { stdio: "ignore" });
+  git(["archive", `v${TARGET_VERSION}`, "-o", join(dest, "_src.tar")]);
   execFileSync("tar", ["-xf", join(dest, "_src.tar"), "-C", dest], { stdio: "ignore" });
   unlinkSync(join(dest, "_src.tar"));
+}
 
-  // node_modules 는 복사하지 않고 직전 버전 것을 링크한다. Windows 는 junction
-  // (관리자 권한 불필요), POSIX 는 type 인자가 무시되고 디렉터리 symlink 가 된다.
+// node_modules 는 복사하지 않고 직전 버전 것을 링크한다. Windows 는 junction
+// (관리자 권한 불필요), POSIX 는 type 인자가 무시되고 디렉터리 symlink 가 된다.
+function linkNodeModules(dest, have) {
   const prev = have.find((v) => v !== TARGET_VERSION);
   const nm = join(dest, "node_modules");
   if (!existsSync(nm) && prev && existsSync(join(CACHE, prev, "node_modules"))) {
@@ -168,8 +214,10 @@ function ensureVersion() {
   } else if (!existsSync(nm)) {
     bad(`node_modules 없음. ${dest} 에서 \`npm install --omit=dev\` 를 실행하십시오`);
   }
+}
 
-  // 활성 버전 전환
+// 활성 버전 전환
+function switchActive(sha, have) {
   const j = JSON.parse(readFileSync(INSTALLED, "utf8"));
   const e = j.plugins?.[PLUGIN_KEY]?.[0];
   if (!e) { bad(`installed_plugins.json 에 ${PLUGIN_KEY} 항목이 없음 — 수동 확인 필요`); return false; }
@@ -210,109 +258,160 @@ const REGEX_PREV_KW = new Set(["return", "typeof", "instanceof", "in", "of", "ne
 // probe(i, fnStack) 를 주면 코드 글자(문자열·주석·정규식·중괄호가 아닌 자리)마다 부른다.
 // --scan 이 같은 토크나이저로 헬퍼 선언의 깊이를 재는 데 쓴다. 패치 경로는 probe 없이 부른다.
 function scanTopLevelAwaitImports(src, probe) {
-  const n = src.length;
-  const fnStack = [];
-  const hits = [];
-  let i = 0, prev = "", prevIdx = -1;
-
-  const wordEndingAt = (j) => {
-    let e = j;
-    while (j >= 0 && ID_CH.test(src[j])) j--;
-    return src.slice(j + 1, e + 1);
-  };
-  const backSkip = (j) => {
-    for (;;) {
-      while (j >= 0 && /\s/.test(src[j])) j--;
-      if (j >= 1 && src[j] === "/" && src[j - 1] === "*") {           // */ 로 끝나는 주석
-        const s = src.lastIndexOf("/*", j - 1);
-        if (s < 0) return -1;
-        j = s - 1; continue;
-      }
-      return j;
-    }
-  };
-  const skipString = (q) => {
-    i++;
-    while (i < n) {
-      const c = src[i];
-      if (c === "\\") { i += 2; continue; }
-      if (c === q) { i++; return; }
-      if (q === "`" && c === "$" && src[i + 1] === "{") {
-        i += 2;
-        let d = 1;
-        while (i < n && d > 0) {
-          const k = src[i];
-          if (k === "\\") { i += 2; continue; }
-          if (k === "'" || k === '"' || k === "`") { skipString(k); continue; }
-          if (k === "{") d++;
-          else if (k === "}") d--;
-          i++;
-        }
-        continue;
-      }
-      i++;
-    }
-  };
-  // 이 중괄호가 «함수 몸통» 을 여는가
-  const isFunctionBrace = (at) => {
-    let j = backSkip(at - 1);
-    if (j < 0) return false;
-    if (src[j] === ">" && src[j - 1] === "=") return true;             // () => {
-    if (src[j] !== ")") return false;                                  // class/객체/블록
-    let d = 0;
-    for (; j >= 0; j--) {                                              // 짝 맞는 ( 찾기
-      if (src[j] === ")") d++;
-      else if (src[j] === "(") { if (--d === 0) break; }
-    }
-    if (j < 0) return false;
-    const k = backSkip(j - 1);
-    if (k < 0 || !ID_CH.test(src[k])) return false;
-    return !BLOCK_KW.has(wordEndingAt(k));                             // if/for/while/catch… 은 블록
-  };
+  const s = { src, n: src.length, i: 0, prev: "", prevIdx: -1, fnStack: [], hits: [] };
+  while (s.i < s.n) {
+    if (!skipNonCode(s)) stepCode(s, probe);
+  }
+  return s.hits;
+}
 
-  while (i < n) {
-    const c = src[i];
-    if (c === "/" && src[i + 1] === "/") { while (i < n && src[i] !== "\n") i++; continue; }
-    if (c === "/" && src[i + 1] === "*") { const e = src.indexOf("*/", i + 2); i = e < 0 ? n : e + 2; continue; }
-    if (c === "'" || c === '"' || c === "`") { skipString(c); prev = c; continue; }
-    if (/\s/.test(c)) { i++; continue; }
-    if (c === "/") {
-      const asRegex = prev === "" || REGEX_PREV_CH.has(prev)
-        || (prevIdx >= 0 && ID_CH.test(prev) && REGEX_PREV_KW.has(wordEndingAt(prevIdx)));
-      if (asRegex) {
-        i++;
-        let inClass = false;
-        while (i < n) {
-          const k = src[i];
-          if (k === "\\") { i += 2; continue; }
-          if (k === "[") inClass = true;
-          else if (k === "]") inClass = false;
-          else if (k === "/" && !inClass) { i++; break; }
-          else if (k === "\n") break;
-          i++;
-        }
-        while (i < n && ID_CH.test(src[i])) i++;                       // 플래그
-        prev = "/"; prevIdx = i - 1; continue;
-      }
-    }
-    if (c === "{") { fnStack.push(isFunctionBrace(i)); i++; prev = "{"; prevIdx = i - 1; continue; }
-    if (c === "}") { fnStack.pop(); i++; prev = "}"; prevIdx = i - 1; continue; }
-    if (c === "a" && !(i > 0 && ID_CH.test(src[i - 1])) && /^await\s+import\s*\(/.test(src.slice(i, i + 40))) {
-      if (!fnStack.some(Boolean)) hits.push(i);
-    }
-    if (probe) probe(i, fnStack);
-    prev = c; prevIdx = i; i++;
+const wordEndingAt = (src, j) => {
+  const e = j;
+  while (j >= 0 && ID_CH.test(src[j])) j--;
+  return src.slice(j + 1, e + 1);
+};
+
+// j 에서 거꾸로 공백과 /* */ 주석을 건너뛴 자리. 주석의 시작이 없으면 -1.
+function backSkip(src, j) {
+  for (;;) {
+    while (j >= 0 && /\s/.test(src[j])) j--;
+    if (!(j >= 1 && src[j] === "/" && src[j - 1] === "*")) return j;  // */ 로 끝나는 주석이 아님
+    const s = src.lastIndexOf("/*", j - 1);
+    if (s < 0) return -1;
+    j = s - 1;
   }
-  return hits;
+}
+
+// 아래 함수들은 토크나이저 상태 s 를 함께 쓴다. src 와 n(길이), i(지금 자리), prev 와
+// prevIdx(직전 코드 글자와 그 자리), fnStack(열린 중괄호마다 함수 몸통이면 true), hits.
+
+// 주석, 문자열, 공백, 정규식이면 건너뛰고 true. 코드 글자면 그대로 두고 false.
+function skipNonCode(s) {
+  const c = s.src[s.i];
+  if (skipComment(s)) return true;
+  if (c === "'" || c === '"' || c === "`") { skipString(s, c); s.prev = c; return true; }
+  if (/\s/.test(c)) { s.i++; return true; }
+  if (c === "/" && startsRegex(s)) { skipRegex(s); return true; }
+  return false;
+}
+
+function skipComment(s) {
+  const { src, n } = s;
+  if (src[s.i] !== "/") return false;
+  if (src[s.i + 1] === "/") {
+    while (s.i < n && src[s.i] !== "\n") s.i++;
+    return true;
+  }
+  if (src[s.i + 1] !== "*") return false;
+  const e = src.indexOf("*/", s.i + 2);
+  s.i = e < 0 ? n : e + 2;
+  return true;
+}
+
+// s.i 는 여는 따옴표. 닫는 따옴표 다음으로 옮긴다. 템플릿의 ${ } 는 skipTemplateExpr 가 맡는다.
+function skipString(s, q) {
+  const { src, n } = s;
+  s.i++;
+  while (s.i < n) {
+    const c = src[s.i];
+    if (c === "\\") { s.i += 2; continue; }
+    if (c === q) { s.i++; return; }
+    if (q === "`" && c === "$" && src[s.i + 1] === "{") { skipTemplateExpr(s); continue; }
+    s.i++;
+  }
+}
+
+// s.i 는 ${ 의 $. 짝 맞는 } 다음으로 옮긴다. 그 안의 문자열은 다시 skipString 으로 건너뛴다.
+function skipTemplateExpr(s) {
+  const { src, n } = s;
+  s.i += 2;
+  let d = 1;
+  while (s.i < n && d > 0) {
+    const k = src[s.i];
+    if (k === "\\") { s.i += 2; continue; }
+    if (k === "'" || k === '"' || k === "`") { skipString(s, k); continue; }
+    if (k === "{") d++;
+    else if (k === "}") d--;
+    s.i++;
+  }
+}
+
+// 여기의 / 가 나눗셈이 아니라 정규식을 여는가. 직전 코드 글자나 직전 낱말로 정한다.
+function startsRegex(s) {
+  const { src, prev, prevIdx } = s;
+  return prev === "" || REGEX_PREV_CH.has(prev)
+    || (prevIdx >= 0 && ID_CH.test(prev) && REGEX_PREV_KW.has(wordEndingAt(src, prevIdx)));
+}
+
+// s.i 는 정규식을 여는 /. 닫는 / 와 플래그 다음으로 옮긴다. 줄이 끝나면 거기서 멈춘다.
+function skipRegex(s) {
+  const { src, n } = s;
+  s.i++;
+  let inClass = false;
+  while (s.i < n) {
+    const k = src[s.i];
+    if (k === "\\") { s.i += 2; continue; }
+    if (k === "[") inClass = true;
+    else if (k === "]") inClass = false;
+    else if (k === "/" && !inClass) { s.i++; break; }
+    else if (k === "\n") break;
+    s.i++;
+  }
+  skipWord(s);                                                       // 플래그
+  s.prev = "/"; s.prevIdx = s.i - 1;
+}
+
+function skipWord(s) {
+  while (s.i < s.n && ID_CH.test(s.src[s.i])) s.i++;
+}
+
+// 코드 글자 하나. 중괄호면 함수 스택을 바꾸고, 함수 밖의 `await import(` 면 hits 에 넣는다.
+function stepCode(s, probe) {
+  const { src } = s;
+  const c = src[s.i];
+  if (c === "{" || c === "}") {
+    if (c === "{") s.fnStack.push(isFunctionBrace(src, s.i));
+    else s.fnStack.pop();
+    s.i++; s.prev = c; s.prevIdx = s.i - 1;
+    return;
+  }
+  if (c === "a" && isAwaitImportAt(src, s.i) && !s.fnStack.some(Boolean)) s.hits.push(s.i);
+  if (probe) probe(s.i, s.fnStack);
+  s.prev = c; s.prevIdx = s.i; s.i++;
+}
+
+const isAwaitImportAt = (src, i) => !(i > 0 && ID_CH.test(src[i - 1])) && /^await\s+import\s*\(/.test(src.slice(i, i + 40));
+
+// 이 중괄호가 «함수 몸통» 을 여는가
+function isFunctionBrace(src, at) {
+  let j = backSkip(src, at - 1);
+  if (j < 0) return false;
+  if (src[j] === ">" && src[j - 1] === "=") return true;             // () => {
+  if (src[j] !== ")") return false;                                  // class/객체/블록
+  j = openParenOf(src, j);                                           // 짝 맞는 ( 찾기
+  if (j < 0) return false;
+  const k = backSkip(src, j - 1);
+  if (k < 0 || !ID_CH.test(src[k])) return false;
+  return !BLOCK_KW.has(wordEndingAt(src, k));                        // if/for/while/catch… 은 블록
+}
+
+// j 의 ) 와 짝인 ( 의 자리. 없으면 -1.
+function openParenOf(src, j) {
+  let d = 0;
+  for (; j >= 0; j--) {
+    if (src[j] === ")") d++;
+    else if (src[j] === "(" && --d === 0) return j;
+  }
+  return -1;
 }
 
 // 자리별 상태. 이미 손으로 Promise.race 를 두른 자리는 건드리지 않는다(4.15.7 에 그런 것이 둘 있다).
-// 이미 감싼 파일이라도 헬퍼 선언이 블록 안이면(옛 판의 자리) «패치됨» 이 아니라 «misplaced» 다.
+// 이미 감싼 파일이라도 헬퍼가 쓰일 수 없는 자리면(옛 판의 자리) «패치됨» 이 아니라 «misplaced» 다.
 // 그 상태를 «패치됨» 으로 넘기면 --check 가 결함 트리에 «모두 적용» 을 낸다(2026-10-12 실측).
 function siteInfo(src) {
   if (src.includes("__omcRaceImport")) {
-    const decl = scanFacts(src).helperDecls.find((d) => d.depth !== 0);
-    return decl ? { state: "misplaced", sites: [], decl } : { state: "patched", sites: [] };
+    const why = helperDefect(scanFacts(src));
+    return why ? { state: "misplaced", sites: [], why } : { state: "patched", sites: [] };
   }
   const all = scanTopLevelAwaitImports(src);
   if (!all.length) return { state: "n/a", sites: [] };
@@ -321,20 +420,26 @@ function siteInfo(src) {
   return { state: "needs", sites: open };
 }
 
+// 헬퍼가 쓰일 수 없는 자리면 그 이유를, 제자리면 null 을 낸다.
+//   - 선언이 블록 안(깊이 1 이상): 다른 블록의 자리에서 ReferenceError(옛 킷이 남긴 자리)
+//   - 선언을 못 찾음: 이름만으로는 «패치됨» 이라 할 근거가 없다. 앞쪽 글을 토크나이저가 잘못
+//     읽어 선언이 문자열 안으로 보였을 수도 있다
+//   - 최상위 사용이 선언보다 앞: 그 자리가 먼저 돌아 const, let 은 TDZ 의 ReferenceError, var 는
+//     undefined 호출. function 선언은 끌어올려져 앞에서 불러도 된다. 순서는 줄이 아니라 글자 자리로 본다
+function helperDefect({ helperDecls, wrapped }) {
+  const inBlock = helperDecls.find((d) => d.depth !== 0);
+  if (inBlock) return `헬퍼 선언 :${inBlock.line} 이 블록 안, 깊이 ${inBlock.depth}`;
+  if (!helperDecls.length) return "헬퍼 선언을 찾지 못함";
+  const decl = helperDecls[0];
+  const first = wrapped.find((w) => !w.inFunction);
+  if (first && first.at < decl.at && decl.kind !== "function") return `헬퍼 선언 :${decl.line} 이 첫 사용 :${first.line} 보다 뒤`;
+  return null;
+}
+
 function transform(src) {
   const info = siteInfo(src);
   if (info.state !== "needs") return null;
-  const edits = [];
-  for (const start of info.sites) {
-    const open = src.indexOf("(", src.indexOf("import", start));
-    let depth = 0, end = -1;
-    for (let i = open; i < src.length; i++) {
-      const c = src[i];
-      if (c === "(") depth++;
-      else if (c === ")" && --depth === 0) { end = i; break; }
-    }
-    if (end !== -1) edits.push({ start, end });
-  }
+  const edits = importSpans(src, info.sites);
   if (!edits.length) return null;
   let out = src;
   for (const e of edits.reverse()) {
@@ -351,6 +456,27 @@ function transform(src) {
   return out.slice(0, ls) + HELPER + out.slice(ls);
 }
 
+// 감쌀 자리마다 `await` 에서 import( 의 짝 맞는 ) 까지.
+function importSpans(src, sites) {
+  const edits = [];
+  for (const start of sites) {
+    const end = closingParenOf(src, src.indexOf("(", src.indexOf("import", start)));
+    if (end !== -1) edits.push({ start, end });
+  }
+  return edits;
+}
+
+// open 의 ( 와 짝인 ) 의 자리. 없으면 -1.
+function closingParenOf(src, open) {
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    const c = src[i];
+    if (c === "(") depth++;
+    else if (c === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
 // ── 읽기 전용 진단 (--scan) ──────────────────────────────────────────────────
 // 패치가 «제자리» 에 앉았는지를 위 토크나이저 하나로 잰다. 시험이 토크나이저를 따로 가지면
 // 패치가 고르는 자리와 시험이 재는 자리가 서로 다른 규칙을 따르게 된다.
@@ -367,12 +493,20 @@ function scanFacts(src) {
     if (ch !== "c" && ch !== "l" && ch !== "v" && ch !== "f" && ch !== "a") return;
     if (i > 0 && ID_CH.test(src[i - 1])) return;
     const head = src.slice(i, i + 48);
-    if (/^(?:const|let|var|function)\s+__omcRaceImport\b/.test(head)) helperDecls.push({ line: lineOf(i), depth: fnStack.length });
-    else if (/^await\s+__omcRaceImport\s*\(/.test(head)) wrapped.push({ line: lineOf(i), inFunction: fnStack.some(Boolean) });
+    const decl = /^(const|let|var|function)\s+__omcRaceImport\b/.exec(head);
+    if (decl) helperDecls.push({ line: lineOf(i), depth: fnStack.length, at: i, kind: decl[1] });
+    else if (/^await\s+__omcRaceImport\s*\(/.test(head)) wrapped.push({ line: lineOf(i), inFunction: fnStack.some(Boolean), at: i });
   }).map(lineOf);
   return { helperDecls, wrapped, unwrapped };
 }
 
+// --scan 이 내는 칸. at 과 kind 는 판정용이라 내보내지 않는다(출력 형식은 그대로 둔다).
+const publicFacts = ({ helperDecls, wrapped, unwrapped }) => ({
+  helperDecls: helperDecls.map(({ line, depth }) => ({ line, depth })),
+  wrapped: wrapped.map(({ line, inFunction }) => ({ line, inFunction })),
+  unwrapped,
+});
+
 function syntaxError(file) {
   try { execFileSync(process.execPath, ["--check", file], { stdio: ["ignore", "ignore", "pipe"] }); return null; }
   catch (e) {
@@ -387,8 +521,7 @@ const looksHandPatched = (src) =>
   !src.includes("__omcRaceImport") && /Promise\.race\s*\(\s*\[?[\s\S]{0,120}?\bimport\s*\(/.test(src);
 
 function patchHooks(root) {
-  let done = 0, skip = 0, fail = 0, need = 0, misplaced = 0;
-  const foreign = [];
+  const r = { done: 0, skip: 0, fail: 0, need: 0, misplaced: 0, foreign: [], orphan: [], failed: [] };
   // revert 는 scripts/ 전체를 훑는다. hooks.json 기반 목록은 두 번 새는데, 실측으로
   // 4.15.7 이 둘 다 겪었다 — PostToolUse 를 지우면 그 스크립트가 목록에서 빠지고(그래서
   // .omcbak 이 있어도 안 돌아온다), 손으로 고친 파일은 .omcbak 조차 없어 아예 안 보인다.
@@ -397,64 +530,138 @@ function patchHooks(root) {
     : hookNames(root);
   for (const n of names) {
     const f = join(root, "scripts", `${n}.mjs`);
-    const bak = `${f}.omcbak`;
     if (!existsSync(f)) continue;
+    if (MODE === "revert") revertScript(root, n, f, r);
+    else checkOrPatchScript(root, n, f, r);
+  }
+  return r;
+}
 
-    if (MODE === "revert") {
-      if (existsSync(bak)) { copyFileSync(bak, f); unlinkSync(bak); log(`  되돌림  ${n}`); done++; continue; }
-      // 백업이 없는데 이미 감싸여 있다면 «이 도구가 아닌 손» 이 고친 것이다. 되돌릴 원본이
-      // 디스크에 없으니 조용히 넘기지 않고 이름을 댄다(실측: 4.15.7 의 두 파일이 그랬다).
-      // 주의: 손 패치는 `await import(` 를 `await Promise.race([import(` 로 «바꿔치기» 하므로
-      // await import 패턴 자체가 사라진다. siteInfo 로는 잡히지 않아 원문에서 직접 찾는다.
-      if (looksHandPatched(readFileSync(f, "utf8"))) foreign.push(n);
-      continue;
-    }
-    const info = siteInfo(readFileSync(f, "utf8"));
-    // 헬퍼 자리 결함은 check 와 apply 모두 이름을 댄다. 이미 감싼 파일이라 transform 으로는
-    // 고칠 수 없으므로 apply 도 건드리지 않고, 되돌린 뒤 다시 적용하라고 안내한다(MISPLACED_HINT).
-    if (info.state === "misplaced") {
-      bad(`헬퍼 자리 결함: ${n} (헬퍼 선언 :${info.decl.line} 이 블록 안, 깊이 ${info.decl.depth})`);
-      misplaced++; continue;
-    }
-    if (info.state !== "needs") { skip++; continue; }
-    if (MODE === "check") { bad(`패치 필요: ${n}`); need++; continue; }
-
-    const out = transform(readFileSync(f, "utf8"));
-    if (!out) { bad(`변환 실패: ${n}`); fail++; continue; }
-    if (!existsSync(bak)) copyFileSync(f, bak);
-    writeFileSync(f, out, "utf8");
-    const err = syntaxError(f);
-    if (err) { copyFileSync(bak, f); bad(`문법오류로 롤백: ${n}\n      ${err}`); fail++; continue; }
-    done++;
+function revertScript(root, n, f, r) {
+  const bak = `${f}.omcbak`;
+  if (existsSync(bak)) {
+    const why = whyNotWrite(root, f, bak);
+    if (why) { bad(`되돌리지 않음: ${shown(n)} (${why})`); r.fail++; r.failed.push(f); return; }
+    copyFileSync(bak, f); unlinkSync(bak); log(`  되돌림  ${shown(n)}`); r.done++; return;
   }
-  return { done, skip, fail, need, misplaced, foreign };
+  // 백업이 없는데 이미 감싸여 있으면 되돌릴 원본이 디스크에 없다. 조용히 넘기지 않고 이름을 댄다.
+  //   - 우리 헬퍼가 있으면: 이 도구나 옛 킷이 고쳤는데 백업이 사라진 파일(복사해 온 폴더 등)
+  //   - 손 패치: `await import(` 를 `await Promise.race([import(` 로 «바꿔치기» 해서 await import
+  //     패턴 자체가 사라진다. siteInfo 로는 잡히지 않아 원문에서 직접 찾는다(실측: 4.15.7 의 두 파일)
+  const src = readFileSync(f, "utf8");
+  if (src.includes("__omcRaceImport")) r.orphan.push(n);
+  else if (looksHandPatched(src)) r.foreign.push(n);
+}
+
+function checkOrPatchScript(root, n, f, r) {
+  const info = siteInfo(readFileSync(f, "utf8"));
+  // 헬퍼 자리 결함은 check 와 apply 모두 이름을 댄다. 이미 감싼 파일이라 transform 으로는
+  // 고칠 수 없으므로 apply 도 건드리지 않고, 되돌린 뒤 다시 적용하라고 안내한다(misplacedHint).
+  if (info.state === "misplaced") { bad(`헬퍼 자리 결함: ${n} (${info.why})`); r.misplaced++; return; }
+  if (info.state !== "needs") { r.skip++; return; }
+  if (MODE === "check") { bad(`패치 필요: ${n}`); r.need++; return; }
+
+  const bak = `${f}.omcbak`;
+  const why = whyNotWrite(root, f, bak);
+  if (why) { bad(`쓰지 않음: ${n} (${why})`); r.fail++; return; }
+  const out = transform(readFileSync(f, "utf8"));
+  if (!out) { bad(`변환 실패: ${n}`); r.fail++; return; }
+  if (!existsSync(bak)) copyFileSync(f, bak);
+  writeFileSync(f, out, "utf8");
+  const err = syntaxError(f);
+  if (err) { copyFileSync(bak, f); bad(`문법오류로 롤백: ${n}\n      ${err}`); r.fail++; return; }
+  r.done++;
+}
+
+// 쓰기 전에 본다. 쓸 파일이 (링크를 따라가서) 플러그인 폴더 밖이거나 백업 자리가 링크면 그 이유를,
+// 아니면 null. 백업 자리가 깨진 링크면 existsSync 는 false 라, copyFileSync 가 링크가 가리키는 곳에 쓴다.
+function whyNotWrite(root, file, bak) {
+  if (isLink(bak)) return "백업 자리가 링크";
+  if (!insideRoot(root, file)) return "파일이 플러그인 폴더 밖에 있음";
+  return null;
 }
 
+const isLink = (p) => {
+  try { return lstatSync(p).isSymbolicLink(); } catch { return false; }
+};
+
+// 실제 경로로 p 가 root 안인가. 버전 폴더 자체가 링크(옛 판이 새 판을 가리킴)여도 root 를 같이
+// 풀므로 맞다. Windows 는 경로의 대소문자를 구분하지 않아 소문자로 비교한다.
+function insideRoot(root, p) {
+  const fold = (x) => (process.platform === "win32" ? x.toLowerCase() : x);
+  try { return fold(realpathSync(p)).startsWith(fold(realpathSync(root)) + PATH_SEP); }
+  catch { return false; }
+}
+
+// 실제 경로. 풀 수 없으면 받은 그대로.
+const realOr = (p) => {
+  try { return realpathSync(p); } catch { return p; }
+};
+
+// 같은 파일인지 셀 때 쓰는 열쇠. Windows 는 경로의 대소문자를 가리지 않아 소문자로 접는다. junction 이 대상을
+// 캐시 경로와 다른 글자로 적어 두면 같은 파일이 다른 철자로 풀리기 때문이다.
+const fileKey = (p) => (process.platform === "win32" ? realOr(p).toLowerCase() : realOr(p));
+
 // ── 3. PostToolUse 훅 제거 ───────────────────────────────────────────────────
 function patchHooksJson(root) {
   const hj = join(root, "hooks", "hooks.json");
-  const bak = `${hj}.omcbak`;
   if (!existsSync(hj)) return "no-file";
-  if (MODE === "revert") {
-    if (existsSync(bak)) { copyFileSync(bak, hj); unlinkSync(bak); log("  되돌림  hooks.json"); return "reverted"; }
-    // 이 도구가 만든 백업이 없어도, 손으로 만든 백업이 남아 있을 수 있다(실측: 4.15.7 의
-    // hooks.json.bak-20260906-postoolremove). PostToolUse 를 담고 있는 유효한 JSON 이
-    // 딱 하나면 그것이 제거 직전 상태다 — 무엇을 썼는지 밝히고 되돌린다.
-    const dir = join(root, "hooks");
-    const cands = readdirSync(dir)
-      .filter((f) => f.startsWith("hooks.json.") && f !== "hooks.json.omcbak")
-      .filter((f) => {
-        try { return !!JSON.parse(readFileSync(join(dir, f), "utf8"))?.hooks?.PostToolUse; }
-        catch { return false; }
-      });
-    if (cands.length === 1) {
-      copyFileSync(join(dir, cands[0]), hj);
-      log(`  되돌림  hooks.json  (수동 백업 사용: ${cands[0]})`);
-      return "reverted";
-    }
-    if (cands.length > 1) { bad(`hooks.json 수동 백업이 여러 개라 자동 복구하지 않음: ${cands.join(", ")}`); return "ambiguous"; }
-    return "no-backup";
+  if (MODE !== "check") {
+    const why = whyNotWrite(root, hj, `${hj}.omcbak`);
+    if (why) { bad(`hooks.json 을 건드리지 않음 (${why})`); return "unsafe"; }
+  }
+  return MODE === "revert" ? revertHooksJson(root, hj) : removePostToolUse(hj);
+}
+
+// 되돌린 결과. ambiguous 와 linked 는 hooks.json 을 되돌리지 못하고 남긴 것이라 끝 줄이 센다.
+function revertHooksJson(root, hj) {
+  const bak = `${hj}.omcbak`;
+  if (existsSync(bak)) { copyFileSync(bak, hj); unlinkSync(bak); log("  되돌림  hooks.json"); return "reverted"; }
+  // 이 도구의 백업이 없을 때 PostToolUse 가 그대로면 되돌릴 것이 없다. 옆의 수동 백업으로 덮어쓰면
+  // 지금 내용을 잃는다.
+  if (hasPostToolUse(hj)) return "no-backup";
+  // 손으로 만든 백업이 남아 있을 수 있다(실측: 4.15.7 의 hooks.json.bak-20260906-postoolremove).
+  // PostToolUse 를 담고 있는 유효한 JSON 이 딱 하나면 그것이 제거 직전 상태다 — 무엇을 썼는지 밝히고 되돌린다.
+  const dir = dirname(hj);
+  const { usable, unsafe } = manualBackups(root, dir);
+  if (unsafe.length) bad(`hooks.json 수동 백업 후보가 링크이거나 플러그인 폴더 밖이라 쓰지 않음: ${unsafe.map(shown).join(", ")}`);
+  if (usable.length === 1) {
+    copyFileSync(join(dir, usable[0]), hj);
+    log(`  되돌림  hooks.json  (수동 백업 사용: ${shown(usable[0])})`);
+    return "reverted";
+  }
+  if (usable.length > 1) { bad(`hooks.json 수동 백업이 여러 개라 자동 복구하지 않음: ${usable.map(shown).join(", ")}`); return "ambiguous"; }
+  return unsafe.length ? "linked" : "no-backup";
+}
+
+// 파일에서 읽은 값(파일 이름, PINNED 의 host)을 출력에 넣을 때 쓴다. 줄바꿈과 제어 문자를 ? 로 바꾸고 길이를 자른다.
+// SKILL 은 [!] 줄을 그대로 보고하라고 하므로, 값이 제 줄을 새로 시작하면 도구가 낸 줄처럼 읽힌다.
+// 줄을 바꾸거나 글자 순서를 바꾸는 문자: C0 과 C1 제어 문자, 폭 없는 공백과 방향 표시, 줄과 문단 구분자,
+// 방향 덮어쓰기와 격리, BOM. oneLine 은 길이를 두고(URL), shown 은 120자로 자른다(이름, host).
+const UNSAFE_CH = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g;
+const oneLine = (s) => String(s).replace(UNSAFE_CH, "?");
+const shown = (s) => oneLine(s).slice(0, 120);
+
+// hooks.json 옆의 수동 백업 후보. usable 은 PostToolUse 를 담은 유효한 JSON 이다. 링크로 심은 후보는
+// unsafe 로 따로 두고 읽지도 않는다. 폴더 밖 파일(PostToolUse 키가 있는 settings.json 등)이 hooks.json 이 된다.
+function manualBackups(root, dir) {
+  const usable = [], unsafe = [];
+  for (const f of readdirSync(dir)) {
+    if (!f.startsWith("hooks.json.") || f === "hooks.json.omcbak") continue;
+    const p = join(dir, f);
+    if (isLink(p) || !insideRoot(root, p)) unsafe.push(f);
+    else if (hasPostToolUse(p)) usable.push(f);
   }
+  return { usable, unsafe };
+}
+
+const hasPostToolUse = (p) => {
+  try { return !!JSON.parse(readFileSync(p, "utf8"))?.hooks?.PostToolUse; }
+  catch { return false; }
+};
+
+function removePostToolUse(hj) {
+  const bak = `${hj}.omcbak`;
   const j = JSON.parse(readFileSync(hj, "utf8"));
   if (!j.hooks?.PostToolUse) return "already";
   const list = j.hooks.PostToolUse.flatMap((g) => (g.hooks || []).map((h) => (h.command || "").match(/([\w-]+)\.mjs/)?.[1] || "?"));
@@ -472,38 +679,20 @@ function patchHooksJson(root) {
 // 올릴 수 있다. 그러면 위 패치가 통째로 덮어써진다. 로컬에서 막을 수 있는
 // 지점은 "마켓플레이스 저장소가 새 커밋을 가져오지 못하게" 하는 것뿐이다.
 // origin remote 의 URL 을 무효 주소로 바꿔 fetch 를 실패시킨다(원래 URL 은
-// PINNED 파일에 적어 두고 --revert 로 복구한다). 저장소 자체는 그대로라
-// 이미 받은 태그로 재설치·검증이 가능하다.
+// `omc-pinned://` 뒤에 그대로 남기고 --revert 가 거기서 복구한다. PINNED 파일은 기록이다).
+// 저장소 자체는 그대로라 이미 받은 태그로 재설치·검증이 가능하다.
 function pinMarketplace() {
   if (!existsSync(MARKET)) return "no-marketplace";
   // 마켓플레이스 폴더가 제 git 저장소가 아니면 git 이 위쪽 저장소(예: dotfiles 로 관리하는
-  // ~/.claude)를 찾아 그 origin 을 바꾼다. 제 .git 이 있을 때만 고정하고 되돌린다.
+  // ~/.claude)를 찾아 그 origin 을 바꾼다. 제 .git 이 있을 때만 고정하고 되돌린다. .git 이 있어도
+  // 깨졌으면 git 이 위로 올라가는데, 그것은 gitEnv 의 천장이 막는다(origin 을 못 읽어 no-remote).
   if (!existsSync(join(MARKET, ".git"))) return "no-git";
   let url;
   try { url = git(["remote", "get-url", "origin"]); } catch { return "no-remote"; }
 
-  if (MODE === "revert") {
-    // 원본 URL 은 현재 origin 안에 그대로 들어 있다(`omc-pinned://` + 원본). 파일이 아니라
-    // 거기서 복원한다. PINNED 는 배포 폴더에 같이 딸려 오므로 다른 PC 의 값일 수 있고,
-    // PINFILE 은 스크립트 위치가 아니라 homedir() 기준이라 그 사실이 눈에 띄지도 않는다.
-    const PIN_PREFIX = "omc-pinned://";
-    let restored = null;
-    if (url.startsWith(PIN_PREFIX)) restored = url.slice(PIN_PREFIX.length);
-    if (existsSync(PINFILE)) {
-      let saved = {};
-      try { saved = JSON.parse(readFileSync(PINFILE, "utf8")); } catch { /* 깨졌으면 무시 */ }
-      if (saved.host && saved.host !== hostname()) {
-        bad(`PINNED 는 다른 기기(${saved.host})의 기록입니다 — 그 값은 쓰지 않고 현재 origin 에서 복원합니다.`);
-      }
-      if (!restored && saved.originUrl) restored = saved.originUrl;
-      unlinkSync(PINFILE);
-    }
-    if (!restored) return "not-pinned";
-    try { git(["remote", "set-url", "origin", restored]); } catch { /* noop */ }
-    return "unpinned";
-  }
+  if (MODE === "revert") return unpinMarketplace(url);
   if (url.startsWith("omc-pinned://")) return "already";
-  if (MODE === "check") { bad(`마켓플레이스 미고정 (origin=${url})`); return "needs"; }
+  if (MODE === "check") { bad(`마켓플레이스 미고정 (origin=${oneLine(url)})`); return "needs"; }
 
   mkdirSync(dirname(PINFILE), { recursive: true });
   // host 를 남긴다. 이 폴더는 통째로 복사해 배포하므로 PINNED 도 같이 딸려 가는데,
@@ -513,6 +702,44 @@ function pinMarketplace() {
   return "pinned";
 }
 
+// 원본 URL 은 현재 origin 안에 그대로 들어 있다(`omc-pinned://` + 원본). 거기서만 복원한다.
+// PINNED 의 값으로 origin 을 쓰지 않는다. PINNED 는 배포 폴더에 같이 딸려 오므로 다른 PC 의 값일 수 있고,
+// host 가 없는 기록은 어느 기기의 것인지 모른다. origin 이 고정 상태가 아니면 되돌릴 것도 없다.
+function unpinMarketplace(url) {
+  const PIN_PREFIX = "omc-pinned://";
+  if (existsSync(PINFILE)) dropPinRecord();
+  const restored = url.startsWith(PIN_PREFIX) ? url.slice(PIN_PREFIX.length) : "";
+  if (!restored) return "not-pinned";
+  try { git(["remote", "set-url", "origin", restored]); } catch { /* noop */ }
+  return "unpinned";
+}
+
+// PINNED 를 지운다. 다른 기기의 기록이면 알린다. 깨진 기록(JSON 이 아니거나, null 처럼 객체가 아닌 값)은 말없이 지운다.
+function dropPinRecord() {
+  let saved = null;
+  try { saved = JSON.parse(readFileSync(PINFILE, "utf8")); } catch { /* 깨졌으면 무시 */ }
+  unlinkSync(PINFILE);
+  if (saved && typeof saved === "object" && saved.host && saved.host !== hostname()) {
+    bad(`PINNED 는 다른 기기(${shown(saved.host)})의 기록입니다 — 그 값은 쓰지 않습니다.`);
+  }
+}
+
+// --root 폴더의 이름표. .claude-plugin/plugin.json 의 name 이 있으면 그것으로, 없으면 package.json 의 name
+// 으로 정한다. OMC 가 아니면 그 설명을, 아니면 null. 둘 다 없거나 읽을 수 없으면 확인할 길이 없어 null 이다
+// (번들 사본에는 없을 수 있다). 다른 폴더를 잘못 준 실수를 막는 확인이다. 폴더 밖 쓰기를 막는 것은 whyNotWrite.
+const OMC_NAMES = [[".claude-plugin/plugin.json", "oh-my-claudecode"], ["package.json", "oh-my-claude-sisyphus"]];
+function otherPluginName(root) {
+  for (const [rel, want] of OMC_NAMES) {
+    let name;
+    try { name = JSON.parse(readFileSync(join(root, rel), "utf8")).name; } catch { continue; }
+    if (name === undefined) continue;
+    if (name === want) return null;
+    const quoted = JSON.stringify(name);
+    return `${rel} 의 name 이 ${quoted.length > 80 ? `${quoted.slice(0, 80)}...` : quoted}`;
+  }
+  return null;
+}
+
 // ── --scan: 사실만 내고 끝낸다 ───────────────────────────────────────────────
 // 아래 main 보다 먼저 끝나야 한다. 이 모드는 installed_plugins.json 도 플러그인 캐시도 읽지 않는다.
 // 결과는 입력 순서대로 JSON 배열 한 줄이다. 동기 쓰기로 내보내야 process.exit 가 잘라먹지 않는다.
@@ -520,7 +747,7 @@ if (SCAN_AT >= 0) {
   const files = args.slice(SCAN_AT + 1);
   if (!files.length) { console.error("--scan 뒤에 파일 경로가 필요합니다."); process.exit(1); }
   const out = files.map((file) => {
-    try { return { file, ...scanFacts(readFileSync(file, "utf8")) }; }
+    try { return { file, ...publicFacts(scanFacts(readFileSync(file, "utf8"))) }; }
     catch (e) { return { file, error: String(e.code || e.message) }; }
   });
   writeSync(1, JSON.stringify(out) + "\n");
@@ -529,28 +756,36 @@ if (SCAN_AT >= 0) {
 
 // ── main ─────────────────────────────────────────────────────────────────────
 if (ROOT_AT >= 0 && !ROOT) { bad("--root 뒤에 플러그인 폴더 경로가 필요합니다."); process.exit(1); }
+// --check 는 읽기 전용이다. --revert 와 함께 받으면 예전에는 되돌리기가 이겨 파일을 썼다. 무엇도 하지 않고 멈춘다.
+if (argv.has("--check") && argv.has("--revert")) {
+  bad("--check 와 --revert 는 함께 쓸 수 없습니다. 진단만 하려면 --check 만 주십시오.");
+  process.exit(1);
+}
 log(ROOT
   ? `OMC 패치  (대상 폴더 ${ROOT})  모드: ${MODE}`
   : `OMC 패치  (대상 ${TARGET_VERSION})  모드: ${MODE}${NO_UPDATE ? " --no-update" : ""}`);
 log(`플랫폼: ${process.platform}  node ${process.version}`);
 log();
 
-// 헬퍼 자리 결함은 이 판의 apply 로 고칠 수 없다(이미 감싼 파일). 원본으로 되돌린 뒤 다시 적용한다.
-const MISPLACED_HINT = ROOT
-  ? "--revert --root 로 되돌린 뒤 같은 --root 로 다시 적용하십시오."
-  : "--revert 로 되돌린 뒤 다시 적용하십시오.";
-
 // targets 는 «고칠 플러그인 폴더» 의 이름표 목록이다. 기본은 캐시의 판 번호이고, --root 는
 // 그 폴더 경로 하나다. rootOf 가 이름표를 폴더로 바꾼다.
 let active, targets;
 const rootOf = (v) => (ROOT ? v : join(CACHE, v));
+// 헬퍼 자리 결함은 이 판의 apply 로 고칠 수 없다(이미 감싼 파일). 원본으로 되돌린 뒤 다시 적용한다.
+// 되돌리기는 그 폴더 하나만 한다. 인자 없는 --revert 는 설치된 모든 판을 되돌리고 고정까지 푼다.
+// active 는 아래에서 정해지므로 쓰는 자리에서 부른다.
+const misplacedHint = () => (ROOT
+  ? "--revert --root 로 되돌린 뒤 같은 --root 로 다시 적용하십시오."
+  : `--revert --root "${join(CACHE, active)}" 로 활성 폴더만 되돌린 뒤 다시 적용하십시오.`);
 if (ROOT) {
-  // 판 폴더도 installed_plugins.json 도 없는 트리(번들 사본)를 고친다. 판 바꾸기([1/4])와
-  // 마켓플레이스 고정([4/4])은 하지 않는다 — 그 둘은 이 PC 의 설정이고 이 폴더의 것이 아니다.
+  // 그 폴더 하나만 고친다(판 폴더도 installed_plugins.json 도 없는 번들 사본, 또는 활성 캐시 폴더).
+  // 판 바꾸기([1/4])와 마켓플레이스 고정([4/4])은 하지 않는다 — 그 둘은 이 PC 의 설정이고 이 폴더의 것이 아니다.
   if (!existsSync(join(ROOT, "hooks", "hooks.json")) || !existsSync(join(ROOT, "scripts"))) {
     bad(`플러그인 폴더가 아님 (hooks/hooks.json 과 scripts/ 가 있어야 함): ${ROOT}`);
     process.exit(1);
   }
+  const other = otherPluginName(ROOT);
+  if (other) { bad(`OMC 플러그인 폴더가 아님 (${other}): ${ROOT}`); process.exit(1); }
   log("[1/4] 버전");
   log("  건너뜀 (--root 는 판을 바꾸지 않음)");
   active = ROOT;
@@ -560,7 +795,7 @@ if (ROOT) {
 
   log("[1/4] 버전");
   if (NO_UPDATE) log("  건너뜀 (--no-update)");
-  else if (MODE === "revert") log("  건너뜀 (revert 는 버전을 되돌리지 않음 — README 의 롤백 절차 참고)");
+  else if (MODE === "revert") log("  건너뜀 (revert 는 버전을 되돌리지 않음 — 킷 배포 폴더 README 의 롤백 절차 참고)");
   else if (!ensureVersion() && MODE !== "check") { bad("버전 확보 실패 — 중단"); process.exit(1); }
 
   const versions = installedVersions();
@@ -586,6 +821,11 @@ const r = { done: 0, skip: 0, fail: 0, need: 0, misplaced: 0 };
 const needBy = {};
 const misplacedBy = {};
 const foreignBy = {};
+const orphanBy = {};
+// 되돌리기 끝 줄이 세는 파일. 쓰지 못한 것(failed)과 백업이 없어 남은 것(left)이다. 링크로 이어진 판 폴더는
+// 같은 파일을 여러 이름으로 보이므로 fileKey 로 한 번만 센다. 위 [2/4] 줄의 건수는 판 폴더마다 센다.
+const failed = new Set();
+const left = new Set();
 for (const v of targets) {
   const root = rootOf(v);
   if (!existsSync(root)) continue;
@@ -595,16 +835,21 @@ for (const v of targets) {
   misplacedBy[v] = x.misplaced;
   for (const k of ["done", "skip", "fail", "need", "misplaced"]) r[k] += x[k];
   if (x.foreign?.length) foreignBy[v] = x.foreign;
+  if (x.orphan?.length) orphanBy[v] = x.orphan;
+  for (const n of [...x.foreign, ...x.orphan]) left.add(fileKey(join(root, "scripts", `${n}.mjs`)));
+  for (const p of x.failed) failed.add(fileKey(p));
 }
-log(`  ${MODE === "check" ? `패치 필요 ${r.need}건` : MODE === "revert" ? `되돌림 ${r.done}건` : `패치 ${r.done}건 / 실패 ${r.fail}건`}${r.misplaced ? ` / 헬퍼 자리 결함 ${r.misplaced}건` : ""} / 대상 아님 ${r.skip}건`);
-// 이 도구가 만들지 않은 수정은 되돌릴 원본이 디스크에 없다. 조용히 넘기면 «완전히
+log(`  ${MODE === "check" ? `패치 필요 ${r.need}건` : MODE === "revert" ? `되돌림 ${r.done}건${r.fail ? ` / 실패 ${r.fail}건` : ""}` : `패치 ${r.done}건 / 실패 ${r.fail}건`}${r.misplaced ? ` / 헬퍼 자리 결함 ${r.misplaced}건` : ""} / 대상 아님 ${r.skip}건`);
+// 백업이 없어 되돌리지 못한 파일은 되돌릴 원본이 디스크에 없다. 조용히 넘기면 «완전히
 // 되돌렸다» 는 잘못된 인상을 준다 — 무엇이 남았고 어떻게 되찾는지 정확히 말한다.
-for (const [v, list] of Object.entries(foreignBy)) {
-  bad(`${v}: 이 도구가 만들지 않은 수정이 남아 있습니다 — ${list.join(", ")}`);
+function reportNoBackup(v, list, what) {
+  bad(`${v}: ${what} — ${list.map(shown).join(", ")}`);
   log(`      백업(.omcbak)이 없어 되돌릴 원본이 디스크에 없습니다. 원본이 필요하면:`);
   if (ROOT) log(`      같은 판의 상류 원본에서 scripts/<이름>.mjs 를 다시 가져오십시오.`);
   else log(`      git -C "${MARKET}" archive v${v} scripts/<이름>.mjs | tar -x -C "${join(CACHE, v)}"`);
 }
+for (const [v, list] of Object.entries(foreignBy)) reportNoBackup(v, list, "이 도구가 만들지 않은 수정이 남아 있습니다");
+for (const [v, list] of Object.entries(orphanBy)) reportNoBackup(v, list, "패치는 있는데 백업이 없어 되돌리지 못했습니다");
 
 log();
 log("[3/4] PostToolUse 훅 제거");
@@ -617,9 +862,11 @@ for (const v of targets) {
   if (Array.isArray(hj)) ok(`${tag}제거: ${hj.join(", ")}`);
   else if (hj === "already") ok(`${tag}이미 제거됨`);
   else if (hj === "needs") hjNeedBy[v] = true;
-  else if (hj === "reverted" || hj === "ambiguous") { /* patchHooksJson 이 출력함 */ }
+  else if (hj === "reverted" || hj === "ambiguous" || hj === "linked") { /* patchHooksJson 이 출력함 */ }
   else if (hj === "no-backup") ok(`${tag}되돌릴 백업 없음 (이 도구가 지운 적 없음)`);
   else if (hj === "no-file") bad(`${tag}hooks.json 파일 자체가 없음`);
+  else if (hj === "unsafe") { r.fail++; failed.add(fileKey(join(root, "hooks", "hooks.json"))); }
+  if (hj === "ambiguous" || hj === "linked") left.add(fileKey(join(root, "hooks", "hooks.json")));
 }
 
 log();
@@ -661,19 +908,24 @@ if (MODE === "check") {
   const clean = (needBy[active] || 0) === 0 && !hjNeedBy[active] && pin !== "needs" && misplacedActive === 0;
   const others = targets.filter((v) => v !== active && ((needBy[v] || 0) > 0 || hjNeedBy[v] || (misplacedBy[v] || 0) > 0));
   log(clean ? "결과: 모두 적용된 상태입니다."
-    : misplacedActive ? `결과: 헬퍼 자리 결함 ${misplacedActive}건이 있습니다. ${MISPLACED_HINT}`
+    : misplacedActive ? `결과: 헬퍼 자리 결함 ${misplacedActive}건이 있습니다. ${misplacedHint()}`
     : ROOT ? "결과: 적용되지 않은 항목이 있습니다. --check 없이 같은 --root 로 다시 실행하십시오."
+    : NO_UPDATE ? "결과: 적용되지 않은 항목이 있습니다. --check 없이 --no-update 로 다시 실행하십시오."
     : "결과: 적용되지 않은 항목이 있습니다. 인자 없이 다시 실행하십시오.");
   if (others.length) {
     log(`    참고: 비활성 버전 ${others.join(", ")} 에 미적용분이 있습니다.`);
     log("          지금 쓰이지 않는 버전이라 판정에 넣지 않았습니다. 그 버전으로 되돌릴 계획이면 함께 적용하십시오.");
   }
 } else if (MODE === "revert") {
-  log("되돌리기 완료. Claude Code 를 재시작해야 반영됩니다.");
+  // 백업이 없어 남은 파일과 hooks.json 도 «끝내지 못함» 이다. 완료라고 하면 남은 것을 보지 못하고 넘어간다.
+  const why = [failed.size && `실패 ${failed.size}건`, left.size && `되돌리지 못한 것 ${left.size}건`].filter(Boolean);
+  log(why.length
+    ? `되돌리기를 끝내지 못했습니다. ${why.join(", ")}. 위의 [!] 줄을 확인하십시오.`
+    : "되돌리기 완료. Claude Code 를 재시작해야 반영됩니다.");
 } else {
   log(`완료. 실패 ${r.fail}건.`);
-  if (r.misplaced) log(`[!] 헬퍼 자리 결함 ${r.misplaced}건은 고치지 않았습니다. ${MISPLACED_HINT}`);
+  if (r.misplaced) log(`[!] 헬퍼 자리 결함 ${r.misplaced}건은 고치지 않았습니다. ${misplacedHint()}`);
   log("    훅 스크립트 패치는 즉시 적용됩니다 (훅이 호출될 때마다 파일을 새로 읽습니다).");
   log("[!] PostToolUse 훅 제거는 hooks.json 변경이라 각 세션이 다시 시작될 때부터 적용됩니다.");
 }
-process.exit(r.fail > 0 ? 1 : 0);
+process.exit(r.fail > 0 || left.size > 0 ? 1 : 0);