@kaydash9999/banker-plugins 0.20.1 → 0.20.2

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code skills + commands — QA, audit, docs, architecture, dependency setup, and wiki; the banker plugin marketplace.",
-    "version": "0.20.1"
+    "version": "0.20.2"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "banker",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "description": "Claude Code plugin: QA/audit/docs/architecture skills + commands, a /banker:setup installer for OS dependencies (playwright, etc.), and wiki compaction.",
   "author": {
     "name": "smallOpenSource",

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.20.2] - 2026-10-19
+
+### Added
+- `setup-omc-hud` 설치 스크립트가 끝에 상태표시줄 래퍼를 입력 없이 한 번 돌려, OMC 를 불러오는지와 어느 판이 그리는지 알린다(`Render check`). 새 OMC 판이 불러오기에 실패해 옛 판으로 넘어가면 그 이유와 함께 알린다. 네트워크는 쓰지 않고, 설치 결과(종료 코드)는 바꾸지 않는다.
+
+### Changed
+- 유지보수자용: payload-mon `status` 의 모듈 사본 없음 분기와 래퍼 v4 판별 꼴(주석의 `PL:` 글자)을 시험하고, 난수 대체 시험의 주석을 바로잡는다.
+
+### Fixed
+- `setup-omc-hud` 를 다시 설치할 때마다 래퍼와 `settings.json` 의 백업이 하나씩 쌓이던 것. payload-mon, claude-update-last 블록만 다른 래퍼와 바뀌는 내용이 없는 `settings.json` 은 이제 백업하지 않는다.
+- `setup-omc-hud` 설치 스크립트가 빈 `settings.json` 을 "JSON 객체가 아님" 으로 거부하던 것. Claude Code 처럼 `{}` 로 읽는다.
+- `setup-omc-hud` 설치 스크립트가 주석이나 끝 쉼표가 든 `settings.json` 을 거부할 때 이유를 말하지 않던 것. 이제 그 이유와, Claude Code 도 이 파일을 읽지 못한다는 것을 알린다. Node 가 위치를 알려 주면 줄과 칸도 적는다. 파일 내용은 출력에 넣지 않는다.
+- `payload-mon` 의 `on`, `off` 가 BOM 으로 시작하는 래퍼를 "node --check 실패" 로 거부하던 것. 그 래퍼는 node 로 정상 실행된다.
+- `payload-mon` 블록이 CRLF 래퍼에 LF 줄끝으로 들어가던 것. 이제 래퍼의 줄끝을 따른다. 편집기가 래퍼 전체를 CRLF 로 저장한 뒤 `status` 가 "켜짐이 불완전" 이라 하던 것도 고친다. Windows 에서 Git 기본 설정으로 받은 설치본이 이런 꼴일 수 있다.
+- 래퍼 파일만 다른 폴더로 링크하면(dotfiles 등) 래퍼 v4 의 `PL:` 칸이 보이지 않는데 `on` 과 `status` 는 PL 칸을 안내하던 것. 모듈 사본을 링크가 가리키는 파일 옆에 둔다. 0.20.1 로 켠 이런 설치는 `status` 가 불완전으로 알리고, `on` 한 번으로 고쳐진다.
+
 ## [0.20.1] - 2026-10-19
 
 ### Changed

package/README.md

@@ -180,7 +180,7 @@ USER_RESOURCES 가이드의 공통 요소를 OS별·런타임별(Claude Code/Cod
 | `setup-omc` | oh-my-claudecode(OMC) 설치·갱신 (Codex는 OMX) |
 | `setup-harness-factory` | revfactory/harness 팀 아키텍처 팩토리 설치·구성·사용안내 (Codex=meta-harness) |
 | `setup-playwright` | Playwright + headless 브라우저 (RHEL8/Rocky8·non-root·no-conda 폴백) |
-| `setup-omc-hud` | omc_hud 상태표시줄(래퍼 v4). 스킬에 든 파일로 오프라인 설치, 모든 OS 같은 명령 |
+| `setup-omc-hud` | omc_hud 상태표시줄(래퍼 v4). 스킬에 든 파일로 오프라인 설치, 모든 OS 같은 명령, 설치 직후 렌더 확인 |
 | `setup-insane-search` | insane-search 플러그인 설치 (Claude·Codex) |
 | `setup-stitch` | Stitch 디자인 MCP 프록시 등록(RockyLinux8 proxy) |
 | `docs-setup` | arch-diagram·pdf-vision-extract 의존성(pptx·pymupdf·plantuml) 설치 |
@@ -247,7 +247,7 @@ banker uninstall        # 제거
 | `setup-mcp` | `claude mcp add` (context7·seq-thinking·filesystem·git·fetch) | `[mcp_servers.*]` |
 | `setup-lsp` | LSP MCP 등록 | `[mcp_servers.lsp_bridge]` |
 | `setup-stitch` | `claude mcp add stitch` | `codex mcp add stitch` |
-| `setup-omc-hud` | `statusLine`(`settings.json` 백업) + `hud/omc-hud-custom.mjs`, `hud/omc-hud.mjs`, `.omc/hud-config.json`(바뀐 파일은 `.backup.<시각>` 백업) + payload-mon 켜기. 옛 판이 넣은 갱신 안내 블록은 `off` 로 원복 | — (Codex는 OMX `hud`) |
+| `setup-omc-hud` | `statusLine`(바뀔 때 `settings.json` 백업) + `hud/omc-hud-custom.mjs`, `hud/omc-hud.mjs`, `.omc/hud-config.json`(바뀐 파일은 `.backup.<시각>` 백업) + payload-mon 켜기. 옛 판이 넣은 갱신 안내 블록은 `off` 로 원복 | — (Codex는 OMX `hud`) |
 | `setup-pwsh` | `env.CLAUDE_CODE_GIT_BASH_PATH` (병합) | — (네이티브 셸, 배선 불필요) |
 | `setup-harness-factory` | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (env 영속) | — |
 | `smart-compact` | `statusLine.command` 래핑 + `UserPromptSubmit` 훅 추가 (백업·멱등) | `~/.codex/` 대응 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaydash9999/banker-plugins",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "description": "banker — Claude Code + Codex CLI plugin (QA, audit, docs, architecture, wiki skills). Install via Claude Code marketplace, or `npm i -g @kaydash9999/banker-plugins` then `banker setup`.",
   "bin": {
     "banker": "bin/banker.js"

package/skills/payload-mon/SKILL.md

@@ -40,6 +40,7 @@ node "<이 스킬 디렉터리 절대경로>/scripts/payload-mon.mjs" <on|off|st
 
 - `on`: Claude Code 설정 폴더(`$CLAUDE_CONFIG_DIR`, 없으면 `~/.claude`)의 `hud/omc-hud-custom.mjs` 에서, ctx 를 넣는 줄 바로 뒤에 `// >>> payload-mon >>>` 블록 하나를 넣는다.
   블록이 불러오는 추정 모듈은 래퍼 옆 `hud/payload-mon/payload-size.mjs` 에 사본으로 둔다. 플러그인 설치 경로는 버전마다 바뀌어 업데이트 뒤에 사라지기 때문이다.
+  래퍼 파일이 다른 곳을 가리키는 링크면 사본은 그 파일 옆에 둔다. 래퍼 v4 가 링크를 푼 자리에서 사본을 찾기 때문이다.
   이미 켜져 있으면 래퍼를 바꾸지 않고, 모듈 사본이 이 버전과 다를 때만 사본을 맞춘다. 예전 방식(블록 2개)으로 켜져 있었다면 새 방식으로 바꾼다.
   바꾸기 전 내용은 `omc-hud-custom.mjs.payload-mon.bak` 에 남는다.
 - `off`: 그 블록만 빼서 래퍼를 켜기 전 상태로 되돌리고, 모듈 사본과 추정치 캐시를 지운다. 래퍼 v4 에서는 모듈 사본이 없어져 `PL:` 칸도 사라진다.
@@ -59,7 +60,7 @@ node "<이 스킬 디렉터리 절대경로>/scripts/payload-mon.mjs" <on|off|st
   플러그인 파일을 손으로 고치지 말고, banker 를 최신으로 올린 뒤(`update-banker`) 다시 시도한다. 그래도 안 되면 banker 이슈로 알린다.
 - "node --check 실패": 블록을 넣은 결과가 문법 검사를 통과하지 못했다(예: 래퍼가 ctx 를 넣는 줄을 비동기가 아닌 함수 안으로 옮김). 파일은 그대로다.
 - "래퍼에 쓸 권한이 없습니다", 또는 `status` 의 "HUD 래퍼를 읽을 수 없음": 래퍼 파일의 권한을 확인한다. 파일은 그대로다.
-- "모듈 사본을 쓰지 못했습니다": 래퍼 옆 `hud/payload-mon/` 에 쓸 수 없다(권한, 같은 이름의 파일, 디스크 공간). 래퍼는 그대로다.
+- "모듈 사본을 쓰지 못했습니다": 래퍼 옆(래퍼 파일이 링크면 링크가 가리키는 파일 옆) `payload-mon/` 에 쓸 수 없다(권한, 같은 이름의 파일, 디스크 공간). 래퍼는 그대로다.
 - "표시(>>> / <<<)의 짝이 맞지 않습니다": 래퍼에 payload-mon 표시 줄이 한쪽만 남았다. `on`·`off` 모두 거부하므로, 손으로 고치지 말라는 원칙의 유일한 예외다.
   `setup-omc-hud` 로 HUD 를 재설치하거나, 래퍼에서 짝 없이 남은 `// >>> payload-mon >>>` 또는 `// <<< payload-mon <<<` 줄을 지운 뒤 다시 실행한다.
 - HUD 를 재설치한 뒤 payload 가 안 보이면 `on` 을 다시 실행한다. `setup-omc-hud` 는 설치할 때마다 이 스킬을 늘 켠다(래퍼 v4 의 `PL:` 칸이 모듈 사본을 씀).

package/skills/payload-mon/scripts/payload-mon.mjs

@@ -25,6 +25,12 @@
  * install lives under a versioned path that the next update retires, and an
  * import pointing there would go dark without a word. `on` writes the copy and
  * refreshes it when this version's module differs; `status` says when it does.
+ * When the wrapper file itself is a symlink, the copy goes beside the file it
+ * points at, where wrapper v4 looks.
+ *
+ * The block takes the ctx line's line ending, so a CRLF wrapper stays CRLF, and
+ * a block whose line endings an editor rewrote still counts as on. A wrapper
+ * that starts with a BOM is taken as it is.
  *
  * `on` converges on the current block and is a no-op when it is in place. It
  * writes only into the OMC custom HUD (signature-gated); `off` removes only
@@ -39,6 +45,7 @@ import {
   accessSync,
   constants,
   existsSync,
+  lstatSync,
   mkdirSync,
   mkdtempSync,
   readdirSync,
@@ -86,13 +93,29 @@ const DEFAULTS = {
   sessionId: process.env.CLAUDE_CODE_SESSION_ID,
 };
 
-// Where the block's module lives: beside the wrapper, outside any versioned path.
-const moduleCopy = (hudFile) => join(dirname(hudFile), "payload-mon", "payload-size.mjs");
+// The file a wrapper that is itself a symlink (dotfiles) points at; any other path as it is. A wrapper
+// reached through a linked folder keeps the path as configured.
+function linkTarget(hudFile) {
+  try {
+    return lstatSync(hudFile).isSymbolicLink() ? realpathSync(hudFile) : hudFile;
+  } catch {
+    return hudFile;
+  }
+}
+// Where the block's module lives: beside the wrapper, outside any versioned path. For a wrapper file
+// that is a link, beside the file it points at: wrapper v4 resolves its own path through the link and
+// looks there for its PL segment.
+const moduleCopy = (hudFile) => join(dirname(linkTarget(hudFile)), "payload-mon", "payload-size.mjs");
+// Where 0.20.1 put the copy for such a link; `off` clears it too.
+const besideLink = (hudFile) => join(dirname(hudFile), "payload-mon", "payload-size.mjs");
 const moduleUrl = (hudFile) => pathToFileURL(moduleCopy(hudFile)).href;
 
+// The ctx line's line ending, which the block takes so that a CRLF wrapper stays CRLF.
+const eolOf = (src) => (CTX_LINE.exec(src)?.[0].endsWith("\r\n") ? "\r\n" : "\n");
+
 // Right after ctx, colored like the 5h/wk rates: % on the ctx scale, MB in cyan.
 // Its names are block-scoped, so none can clash with the wrapper's own.
-const placeBlock = (url) =>
+const placeBlock = (url, eol = "\n") =>
   [
     "  " + OPEN,
     "  // payload-mon: estimated API request payload against the 32MB request limit, shown",
@@ -110,9 +133,9 @@ const placeBlock = (url) =>
     "  }",
     "  " + CLOSE,
     "",
-  ].join("\n");
+  ].join(eol);
 
-const insertBlock = (base, url) => base.replace(CTX_LINE, (line) => line + placeBlock(url));
+const insertBlock = (base, url) => base.replace(CTX_LINE, (line) => line + placeBlock(url, eolOf(line)));
 
 const count = (text, needle) => text.split(needle).length - 1;
 
@@ -137,11 +160,14 @@ const readBytes = (file) => {
 
 const refusal = (why, hudFile) => ({ ok: false, message: `${why}. 래퍼를 그대로 두었습니다: ${hudFile}` });
 
-// The block exactly as `on` writes it for this URL, once, right after the ctx line.
-function inPlace(src, url) {
-  if (count(src, OPEN) !== 1 || count(src, CLOSE) !== 1) return false;
+// The line ending ("\n" or "\r\n") of the block that sits, exactly as `on` writes it for this URL,
+// once, right after the ctx line; "" when it does not. Either ending counts as in place, so a block
+// whose line endings an editor rewrote is still on.
+function blockEol(src, url) {
+  if (count(src, OPEN) !== 1 || count(src, CLOSE) !== 1) return "";
   const ctx = CTX_LINE.exec(src);
-  return ctx !== null && src.startsWith(placeBlock(url), ctx.index + ctx[0].length);
+  if (ctx === null) return "";
+  return ["\n", "\r\n"].find((eol) => src.startsWith(placeBlock(url, eol), ctx.index + ctx[0].length)) ?? "";
 }
 
 // Why the block cannot go into this wrapper, or "" when it can. Markers that do
@@ -202,12 +228,14 @@ function syncModule(o) {
   return true;
 }
 
-// The first lines of node's complaint about `text` as an ES module, "" if it parses.
+// The first lines of node's complaint about `text` as an ES module, "" if it parses. A leading BOM
+// is left out: node runs a wrapper that starts with one, but `node --check` rejects a BOM before a
+// shebang (Node 20, 24).
 function syntaxError(text) {
   const dir = mkdtempSync(join(tmpdir(), "payload-mon-"));
   try {
     const file = join(dir, "check.mjs");
-    writeFileSync(file, text);
+    writeFileSync(file, text.replace(/^\uFEFF/, ""));
     const r = spawnSync(process.execPath, ["--check", file], { encoding: "utf8" });
     return r.status === 0 ? "" : String(r.stderr || r.error).trim().split("\n").slice(0, 3).join(" | ");
   } finally {
@@ -257,7 +285,7 @@ const showsPL = (src) => src !== null && PL_SEGMENT.test(src);
 // Where the size shows, named only while it does: the block in place and a
 // module copy to import. "" otherwise, so status never promises a segment.
 function displayWhere(o, src) {
-  if (src === null || !inPlace(src, moduleUrl(o.hudFile)) || copyState(o) === "missing") return "";
+  if (src === null || blockEol(src, moduleUrl(o.hudFile)) === "" || copyState(o) === "missing") return "";
   return showsPL(src) ? "PL 칸에 늘 표시" : `${SHOW_FROM_BYTES / MB}MB부터 표시`;
 }
 
@@ -265,7 +293,8 @@ export function turnOn(opts = {}) {
   const o = { ...DEFAULTS, ...opts };
   const src = readText(o.hudFile);
   if (src === null) return { ok: false, message: `HUD 래퍼가 없습니다: ${o.hudFile}` };
-  if (inPlace(src, moduleUrl(o.hudFile))) {
+  // In place with the wrapper's own line ending; a block whose ending differs is written again.
+  if (blockEol(src, moduleUrl(o.hudFile)) === eolOf(src)) {
     try {
       const refreshed = syncModule(o);
       return { ok: true, message: (refreshed ? "모듈 사본을 이 버전으로 맞췄습니다." : "이미 켜져 있습니다 (변경 없음).") + notShownNote(o) };
@@ -292,20 +321,22 @@ function removeBlocks(o, src) {
 
 // What off leaves behind otherwise: the cache (when this account controls its
 // folder), and the module copy with its folder (only when nothing else is in
-// it). Neither failing undoes off.
+// it), also the one 0.20.1 left beside a linked wrapper. None failing undoes off.
 function removeLeftovers(o) {
-  const copy = moduleCopy(o.hudFile);
-  for (const remove of [() => clearCache(o.cacheDir), () => rmSync(copy, { force: true })]) {
+  const copies = [...new Set([moduleCopy(o.hudFile), besideLink(o.hudFile)])];
+  for (const remove of [() => clearCache(o.cacheDir), ...copies.map((copy) => () => rmSync(copy, { force: true }))]) {
     try {
       remove();
     } catch {
       /* stale numbers or an unused copy; off stands */
     }
   }
-  try {
-    rmdirSync(dirname(copy));
-  } catch {
-    /* absent, or holds something that is not ours */
+  for (const copy of copies) {
+    try {
+      rmdirSync(dirname(copy));
+    } catch {
+      /* absent, or holds something that is not ours */
+    }
   }
 }
 
@@ -346,7 +377,7 @@ function stateOf(src, o) {
   if (count(src, OPEN) + count(src, CLOSE) === 0) return "꺼짐";
   // on and off both refuse this, so pointing at on would be a dead end.
   if (count(src, OPEN) !== count(src, CLOSE)) return "표시(>>> / <<<)의 짝이 맞지 않습니다 (on·off 모두 거부: HUD 재설치 또는 남은 표시 줄 정리)";
-  if (!inPlace(src, moduleUrl(o.hudFile))) return "켜짐이 불완전하거나 오래됨 (on 으로 복구)";
+  if (blockEol(src, moduleUrl(o.hudFile)) === "") return "켜짐이 불완전하거나 오래됨 (on 으로 복구)";
   return "켜짐" + COPY_NOTE[copyState(o)];
 }
 

package/skills/setup-omc-hud/SKILL.md

@@ -72,13 +72,14 @@ node "<이 스킬 디렉터리 절대경로>\assets\apply-hud.mjs"
 ```
 
 - `[ok] statusLine -> node "<설정 폴더>/hud/omc-hud-custom.mjs"` 줄을 확인한다.
+- `Render check` 줄을 확인한다. `[ok]` 면 정상이다. `[!!]` 나 `[..]` 면 그 줄을 그대로 보고한다. 이때도 설치는 끝났다(종료 0).
 - 기존 statusLine 이 다른 명령이었으면 `[..] statusLine ran ...` 줄이 나온다. 보고에 그대로 넣는다.
 - 종료 코드 1 이면 출력의 `[x]` 줄을 그대로 보고하고 멈춘다. 이때 바뀐 파일은 없다.
-  - `settings.json` 이 JSON 객체가 아니면 사용자가 고친 뒤 다시 실행한다.
+  - `settings.json` 이 JSON 문법에 맞지 않거나(주석, 끝 쉼표 포함) 객체가 아니면 사용자가 고친 뒤 다시 실행한다. 빈 파일은 Claude Code 처럼 `{}` 로 읽는다.
   - OMC 가 없으면 OMC 를 먼저 설치한다(`setup-omc` 스킬). 이 스킬은 OMC 를 설치하지 않는다.
   - 설정 폴더 경로에 셸이 해석하는 글자가 있으면 그 글자가 없는 폴더를 쓰게 안내한다.
   - 쓸 수 없는 파일이나 폴더가 있으면 권한을 고친 뒤 다시 실행한다.
-- 종료 코드 2 면 예기치 못한 오류로 중간에 멈춘 것이다. 출력을 그대로 보고하고, 바뀐 파일의 이전 판은 `<파일>.backup.<시각>` 에 있다고 알린다.
+- 종료 코드 2 면 예기치 못한 오류로 중간에 멈춘 것이다. 출력을 그대로 보고하고, 바꾼 파일의 이전 판은 `<파일>.backup.<시각>` 에 있다고 알린다. 로더와 도구 블록은 백업하지 않는다.
 
 ## 2. payload-mon 켜기
 
@@ -89,12 +90,13 @@ node "<이 스킬 디렉터리 절대경로>/../payload-mon/scripts/payload-mon.
 ```
 
 - Codex 사본에서 실행할 때 경로는 `<이 스킬 디렉터리 절대경로>/../banker-payload-mon/scripts/payload-mon.mjs` 다.
-- 이유: `PL:` 칸은 payload-mon 이 래퍼 옆(`hud/payload-mon/`)에 두는 크기 계산 모듈을 쓴다. 모듈이 없으면 `PL:` 이 나오지 않는다.
+- 이유: `PL:` 칸은 payload-mon 이 래퍼 옆(`hud/payload-mon/`)에 두는 크기 계산 모듈을 쓴다. 모듈이 없으면 `PL:` 이 나오지 않는다. 래퍼 파일이 링크면 링크가 가리키는 파일 옆에 둔다.
 - 출력 `켰습니다. 다음 statusline 갱신부터 PL 칸에 요청 크기가 늘 표시됩니다.` 를 확인한다. `이미 켜져 있습니다`, `모듈 사본을 이 버전으로 맞췄습니다` 도 정상이다.
 
 ## 3. 보고
 
 - 1단계 출력의 statusLine 줄과 백업 경로
+- 1단계의 `Render check` 줄
 - 2단계 결과
 - statusLine 이 바뀌었으면 Claude Code 재시작 안내
 
@@ -113,6 +115,7 @@ node "<이 스킬 디렉터리 절대경로>/scripts/claude-update-last.mjs" off
 ## 함정
 
 - 다시 설치하면 래퍼와 `hud-config.json` 을 첨부 파일로 덮어쓴다. 손으로 고친 내용은 `.backup.<시각>` 에만 남는다.
+- payload-mon, claude-update-last 블록만 다른 래퍼와 바뀌는 내용이 없는 `settings.json` 은 백업하지 않는다.
 - `settings.json` 의 `omcHud` 값은 `hud-config.json` 의 같은 키를 덮어쓴다. 래퍼가 기대는 아래 키를 바꾸면 칸이 달라지거나 OMC 원문이 그대로 나온다.
   - `omcLabel`, `useBars`
   - `maxWidth`, `maxOutputLines`
@@ -132,3 +135,5 @@ node "<이 스킬 디렉터리 절대경로>/scripts/claude-update-last.mjs" off
 - 설치는 네트워크를 쓰지 않는다. 다만 OMC 가 렌더할 때 네트워크로 얻는 정보(새 Claude Code 판 같은)는 오프라인에서 빠질 수 있다.
 - 래퍼, HUD 설정, 모듈 사본은 플러그인 밖(`<설정 폴더>/hud/`, `<설정 폴더>/.omc/`)에 있다. 플러그인을 지워도 상태표시줄은 남는다.
 - OMC 를 지울 때는 statusLine 도 지운다. OMC 로더는 플러그인을 못 찾으면 작업 폴더의 `node_modules` 에서 OMC HUD 를 찾아 불러오기 때문이다.
+- 설치 끝의 렌더 확인은 래퍼를 입력 없이 한 번 돌려, OMC 진단의 첫 줄(`[OMC] HUD v<판> | preset: <이름>`)로 OMC 를 불러왔는지와 그린 판을 본다. 네트워크는 쓰지 않는다.
+- 렌더 확인이 OMC 를 불러오지 못한다거나 옛 판이 그린다고 하면 OMC 쪽 문제다. `/oh-my-claudecode:omc-setup` 은 고치면서 statusLine 을 OMC 명령으로 되돌리므로, 쓴 뒤에는 이 스킬을 다시 실행한다. omc-patch 를 쓰는 PC 는 omc-patch 도 다시 적용한다.

package/skills/setup-omc-hud/assets/apply-hud.mjs

@@ -7,7 +7,7 @@
  *   - hud/lib/config-dir.mjs (loader dependency)
  *   - hud/omc-hud-custom.mjs (the custom compact/colored formatter)
  *   - .omc/hud-config.json   (HUD preset/elements)
- *   - settings.json          (statusLine -> the custom formatter; existing file backed up)
+ *   - settings.json          (statusLine -> the custom formatter; backed up when it changes)
  *
  * Runs identically on Linux, macOS, and Windows (only needs node + an OMC install).
  * Run it directly with `node apply-hud.mjs` on every OS; the templates are read
@@ -15,16 +15,23 @@
  *
  * Based on smallOpenSource/omc_hud d3cedd5 (MIT, see LICENSE-omc_hud). Changes:
  * statusLine path quoted; a settings.json that is not a JSON object is refused
- * before any file changes (the original replaced it); UTF-8 BOM accepted;
- * CLAUDE_CONFIG_DIR trimmed, "~" expanded and made absolute; formatter and HUD
- * config backed up when they differ; pre-releases sort below their release; no
+ * before any file changes (the original replaced it), naming the line and
+ * column when Node reports one but never quoting it; one holding only white
+ * space is read as {}, as Claude Code does; UTF-8 BOM accepted; CLAUDE_CONFIG_DIR trimmed, "~" expanded
+ * and made absolute; formatter and HUD config backed up when they differ (the
+ * blocks payload-mon and claude-update-last add do not count), settings.json only
+ * when it changes; pre-releases sort below their release; no
  * folder is made when OMC is missing. Also refused before any change: a config
  * folder path the statusLine shell would act on, a file or folder it cannot
  * write, an OMC folder without both loader files, a relative OMC_PLUGIN_ROOT.
  * Backups keep the original bytes and mode; the files it writes are 0644 and new
  * folders 0755; the other statusLine fields (padding, ...) stay.
+ * At the end it runs the installed formatter once with no input and reports
+ * whether OMC's HUD loads and which version draws (the render check); that never
+ * changes the exit code. APPLY_HUD_CHECK_TIMEOUT_MS (tests) shortens its 25s limit.
  * Exit 1 means nothing changed; exit 2 means an unexpected error stopped it partway.
  */
+import { spawnSync } from "node:child_process";
 import {
   accessSync,
   chmodSync,
@@ -34,10 +41,11 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const SELF = dirname(fileURLToPath(import.meta.url));
@@ -72,18 +80,42 @@ const refuse = (lines) => {
 //    file as it was. Refuse rather than replace: a fresh file would drop every
 //    other setting. A BOM (Windows editors) is dropped when the file is written
 //    back; the backup keeps the original bytes.
+//    Read as Claude Code (2.1.303) reads it: white space only is {}, and JSON
+//    with comments or trailing commas is invalid. A refusal says where the JSON
+//    breaks (from Node's "at position N") but never quotes it: Node's own message
+//    does, and the file can hold tokens.
+function jsonErrorAt(text, message) {
+  const m = /at position (\d+)/.exec(message);
+  if (!m) return "";
+  const before = text.slice(0, Number(m[1]));
+  return `line ${before.split("\n").length}, column ${before.length - before.lastIndexOf("\n")}`;
+}
+const kindOf = (v) => (v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`);
+function readSettings(raw) {
+  const text = raw.replace(/^\uFEFF/, "");
+  if (text.trim() === "") return { settings: {}, empty: true };
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (e) {
+    const at = jsonErrorAt(text, String(e && e.message));
+    return {
+      refusal:
+        `[x] settings.json is not valid JSON${at ? ` (${at})` : ""}; nothing changed. ` +
+        "Claude Code cannot read it either: comments and trailing commas are not allowed. Fix it and re-run.",
+    };
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) return { settings: value, empty: false };
+  return { refusal: `[x] settings.json holds ${kindOf(value)}, not a JSON object; nothing changed. Fix it and re-run.` };
+}
 let settings = {};
 let settingsRaw = null;
 if (existsSync(settingsPath)) {
   settingsRaw = readFileSync(settingsPath, "utf8");
-  try {
-    settings = JSON.parse(settingsRaw.replace(/^\uFEFF/, ""));
-  } catch {
-    settings = undefined;
-  }
-  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
-    refuse(["[x] Existing settings.json is not a JSON object; nothing changed. Fix it and re-run."]);
-  }
+  const read = readSettings(settingsRaw);
+  if (read.refusal) refuse([read.refusal]);
+  settings = read.settings;
+  if (read.empty) log("[..] settings.json is empty; read as {} as Claude Code does");
 }
 
 // Inside the command's double quotes these still act: a quote ends the path, $ and `
@@ -166,10 +198,23 @@ function writeOwned(file, data) {
   if (process.platform !== "win32") chmodSync(file, FILE_MODE);
 }
 
+// The marker blocks payload-mon and claude-update-last add to the installed formatter, matched as those
+// tools match them (payload-mon.mjs BLOCKS, claude-update-last.mjs's block pattern). Read as latin1,
+// which maps every byte to one character, so text outside the blocks compares byte for byte.
+const TOOL_BLOCKS = [
+  /^[ \t]*\/\/ >>> payload-mon >>>[\s\S]*?\/\/ <<< payload-mon <<<[ \t]*\r?\n/gm,
+  /^[ \t]*\/\/ >>> claude-update-last >>>(?:(?!\/\/ >>> claude-update-last >>>)[\s\S])*?\/\/ <<< claude-update-last <<<[ \t]*(?:\r?\n|(?![\s\S]))/gm,
+];
+const withoutToolBlocks = (text) => TOOL_BLOCKS.reduce((t, blocks) => t.replace(blocks, ""), text);
+const sameBytes = (a, b) => a.equals(b);
+// Those blocks alone are no reason for a backup: `payload-mon on` puts its block back, and wrapper v4
+// needs no claude-update-last block.
+const sameFormatter = (a, b) => withoutToolBlocks(a.toString("latin1")) === withoutToolBlocks(b.toString("latin1"));
+
 // Keep a timestamped copy, with its bytes and mode, of a file that differs from what replaces it.
-function backupIfDifferent(dst, next, label) {
+function backupIfDifferent(dst, next, label, same = sameBytes) {
   if (!existsSync(dst)) return;
-  if (readFileSync(dst).equals(next)) return;
+  if (same(readFileSync(dst), next)) return;
   const keep = dst + ".backup." + stamp;
   copyFileSync(dst, keep);
   log(`[ok] Backed up ${label} -> ${keep}`);
@@ -188,12 +233,12 @@ function installLoader() {
 }
 
 // 3. Install the custom formatter and HUD config from the bundled templates.
-//    Files that differ from the templates (local edits, blocks added by
-//    payload-mon / claude-update-last) are kept as timestamped backups first.
+//    Files that differ from the templates (local edits) are kept as timestamped
+//    backups first; the blocks payload-mon / claude-update-last add do not count.
 function installTemplates() {
   const wrapperSrc = readFileSync(join(SELF, "omc-hud-custom.mjs"));
   const configSrc = readFileSync(join(SELF, "hud-config.json"));
-  backupIfDifferent(wrapperDst, wrapperSrc, "previous formatter");
+  backupIfDifferent(wrapperDst, wrapperSrc, "previous formatter", sameFormatter);
   backupIfDifferent(configDst, configSrc, "previous HUD config");
   writeOwned(wrapperDst, wrapperSrc);
   writeOwned(configDst, configSrc);
@@ -202,13 +247,9 @@ function installTemplates() {
 }
 
 // 4. Point settings.json statusLine at the custom formatter; its other fields (padding, ...) stay.
+//    A settings.json that already says exactly this is neither backed up nor written.
 const objectOr = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : {});
 function pointStatusLine() {
-  if (settingsRaw !== null) {
-    const backup = settingsPath + ".backup." + stamp;
-    copyFileSync(settingsPath, backup); // the original bytes and mode
-    log("[ok] Backed up settings.json -> " + backup);
-  }
   // Quoted so a config dir with spaces (C:/Users/First Last/.claude) still runs.
   const command = `node "${cmdPath}"`;
   const prior = objectOr(settings.statusLine);
@@ -216,19 +257,117 @@ function pointStatusLine() {
     log(`[..] statusLine ran ${JSON.stringify(prior.command)}; it now runs the custom HUD (the old value is in the backup)`);
   }
   settings.statusLine = { ...prior, type: "command", command };
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  const next = JSON.stringify(settings, null, 2) + "\n";
+  if (next === settingsRaw) {
+    log(`[ok] statusLine -> ${command} (settings.json unchanged, no backup)`);
+    return;
+  }
+  if (settingsRaw !== null) {
+    const backup = settingsPath + ".backup." + stamp;
+    copyFileSync(settingsPath, backup); // the original bytes and mode
+    log("[ok] Backed up settings.json -> " + backup);
+  }
+  writeFileSync(settingsPath, next);
   log("[ok] statusLine -> " + command);
 }
 
+// 5. Render check: run the installed formatter once with no input, as the statusLine command does,
+//    with `node` from PATH. With no input OMC prints its diagnostic, whose first line names the version
+//    that loaded ("[OMC] HUD v5.7.4 | preset: full"), and uses no network. Reported only: the install
+//    is done either way. The 25s limit outwaits the formatter, which gives up on its own within 20s
+//    and then ends its fallback child; killing it sooner would leave that child running.
+//    APPLY_HUD_CHECK_TIMEOUT_MS shortens the limit for tests.
+const CHECK_MS = Number(process.env.APPLY_HUD_CHECK_TIMEOUT_MS) || 25000;
+const BLAME =
+  "    OMC's install is at fault. /oh-my-claudecode:omc-setup repairs it but points statusLine back at OMC, so run setup-omc-hud again after it.";
+const clip = (s, n = 200) => String(s).slice(0, n);
+// No input, and the config folder as working folder: OMC's loader looks in the working folder's
+// node_modules and runs git from it, and Windows looks there first for a bare program name, so the
+// folder the installer was started in (a project, say) must not be it.
+const RUN_OPTS = { input: "", encoding: "utf8", timeout: CHECK_MS, windowsHide: true, cwd: CONFIG_DIR };
+
+// node as the statusLine shell finds it, but only in PATH folders given as absolute paths: spawning the
+// bare name would on Windows try the working folder first, where a project's own node.exe could run.
+function findNode(pathEnv) {
+  const name = process.platform === "win32" ? "node.exe" : "node";
+  for (const entry of (pathEnv || "").split(delimiter)) {
+    const dir = entry.replace(/^"(.*)"$/, "$1");
+    if (!dir || !isAbsolute(dir)) continue;
+    try {
+      if (statSync(join(dir, name)).isFile()) return join(dir, name);
+    } catch {
+      /* not in this folder */
+    }
+  }
+  return null;
+}
+
+function omcVersion(root) {
+  if (!root) return null;
+  try {
+    const v = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+    return typeof v === "string" ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// Why an OMC version does not load: its HUD's own error when run directly.
+function loadReason(node, root) {
+  const hud = join(root, "dist", "hud", "index.js");
+  if (!existsSync(hud)) return "no dist/hud/index.js";
+  const r = spawnSync(node, [hud], RUN_OPTS);
+  const line = /^\w*Error\b.*$/m.exec(r.stderr || "");
+  return line ? clip(line[0]) : "";
+}
+
+// What the formatter printed, as report lines.
+function judgeRender(out, node) {
+  const banner = /^\[OMC\] HUD v(\S+) \| preset: /m.exec(out);
+  if (banner) {
+    const installed = omcVersion(pluginRoot);
+    if (!installed || installed === banner[1]) return [`[ok] Render check: the statusline loads OMC ${banner[1]}.`];
+    const why = loadReason(node, pluginRoot);
+    const line = `[!!] Render check: the statusline loads OMC ${banner[1]}, not the installed ${installed}; ${installed} does not load`;
+    return [`${line}${why ? ` (${why})` : ""}.`, BLAME];
+  }
+  // OMC's line ends with the reason, after a path that can be long: keep it whole within reason.
+  const failed = /^\[OMC HUD\] .*$/m.exec(out);
+  if (failed) return [`[!!] Render check: OMC's HUD does not load: ${clip(failed[0], 1000)}`, BLAME];
+  return [`[..] Render check: unrecognized output: ${clip(out.split("\n")[0])}`];
+}
+
+function renderReport() {
+  const node = findNode(process.env.PATH);
+  if (!node) return ['[!!] Render check: no "node" on PATH; the statusLine command runs "node", so the statusline will not show.'];
+  const r = spawnSync(node, [wrapperDst], RUN_OPTS);
+  if (r.error && r.error.code === "ETIMEDOUT") return [`[!!] Render check: the statusline gave no answer in ${CHECK_MS / 1000}s.`];
+  if (r.error) throw r.error;
+  if (r.status !== 0) {
+    const err = (r.stderr || "").trim().split("\n")[0];
+    return [`[!!] Render check: the statusline command failed (exit ${r.status ?? r.signal})${err ? `: ${clip(err)}` : ""}`];
+  }
+  return judgeRender((r.stdout || "").replace(/\x1b\[[0-9;]*m/g, ""), node);
+}
+
+function renderCheck() {
+  try {
+    for (const line of renderReport()) log(line);
+  } catch (e) {
+    log(`[..] Render check: skipped (${e.code || e.message})`);
+  }
+}
+
 try {
   installLoader();
   installTemplates();
   pointStatusLine();
 } catch (e) {
   log(`[x] Stopped partway (${e.code || e.message}); some files may have changed.`);
-  log(`    A replaced file's earlier version is in <file>.backup.${stamp}.`);
+  log(`    Earlier versions it replaced, apart from the loader and the tool blocks, are in <file>.backup.${stamp}.`);
   process.exit(2);
 }
 
+renderCheck();
 log("");
 log("Done. Restart Claude Code to load the new statusline.");