@kaydash9999/banker-plugins 0.18.0 → 0.19.1

package/skills/lineage/lineage.py

@@ -4,7 +4,7 @@
 Deterministic core. One-line summary per assistant turn (cached, redacted).
 Renders assistant markdown, filters harness noise, folds long messages, and
 self-verifies the output markup. See SKILL.md for the full design and the
-`work/lineage-change-request.html` spec for the classification rules.
+`docs/lineage-change-request.html` spec for the classification rules.
 
 Runtime-agnostic: works from any transcript via --session / --from-transcript.
 Auto-discovery assumes Claude Code's ~/.claude/projects/<encoded-cwd>/ layout.
@@ -18,8 +18,10 @@ import math
 import os
 import pathlib
 import re
+import stat
 import sys
 import tempfile
+import unicodedata
 from html.parser import HTMLParser
 
 if sys.version_info < (3, 7):
@@ -424,6 +426,96 @@ KNOWN_CONTENT_ITEMS = {"text", "tool_use", "tool_result", "thinking"}
 _CTRL_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f]")   # strip control chars (keeps \t\n)
 
 
+def _json_object(raw, line_no):
+    """The JSON object a transcript line holds, else None after a WARN: a line that is not JSON, is nested
+    deeper than the parser reads, holds a number longer than it reads (ValueError since 3.11), or holds
+    something other than an object is skipped, not fatal."""
+    try:
+        obj = json.loads(raw)
+    except (ValueError, RecursionError):                  # JSONDecodeError is a ValueError
+        print(f"[WARN] line {line_no}: invalid JSON skipped", file=sys.stderr)
+        return None
+    if not isinstance(obj, dict):
+        print(f"[WARN] line {line_no}: not a JSON object skipped", file=sys.stderr)
+        return None
+    return obj
+
+
+def _is_turn_record(obj, seen_unknown_type, unsafe_schema, line_no):
+    """Whether a record is a user or assistant turn. A side chain or a team record is not, nor is another type:
+    one nobody knows is named once, and a schema marker (v...) stops the run unless --unsafe-schema. A record
+    whose type, or a turn whose message, has a shape a transcript does not give is named and skipped."""
+    if obj.get("isSidechain") or obj.get("teamName") or obj.get("agentName"):
+        return False
+    t = obj.get("type")
+    if (t and not isinstance(t, str)) or (t in ("user", "assistant") and _odd_message(obj.get("message"))):
+        print(f"[WARN] line {line_no}: record of an unknown shape skipped", file=sys.stderr)
+        return False
+    if t in ("user", "assistant"):
+        return True
+    if t and t not in KNOWN_TYPES and t not in seen_unknown_type:
+        seen_unknown_type.add(t)
+        print(f"[WARN] unknown record type {t!r} skipped", file=sys.stderr)    # repr: no raw control character
+        if not unsafe_schema and t.startswith("v"):
+            print(f"[ERROR] schema marker {t!r} unrecognized — "
+                  "rerun with --unsafe-schema to proceed",
+                  file=sys.stderr)
+            raise SystemExit(2)
+    return False
+
+
+def _stamp(ts):
+    """A record's timestamp when it is text, else None: a number or another shape reads as a missing one."""
+    return ts if isinstance(ts, str) else None
+
+
+def _odd_message(msg):
+    """Whether a turn's message has a shape a transcript does not give (a missing or empty one reads as empty)."""
+    return bool(msg) and not isinstance(msg, dict)
+
+
+def _odd_item(it, text, name):
+    """Whether a content item's type, text or tool name has a shape a transcript does not give. A missing or empty
+    text reads as empty and a missing or null tool name as '?'."""
+    return ((it is not None and not isinstance(it, str)) or (it == "text" and not isinstance(text, str))
+            or (it == "tool_use" and not isinstance(name, str)))
+
+
+def _take_item(item, line_no, text_parts, tools):
+    """Add one item of a message's content list to the text parts or the tool counts. An item whose type, text or
+    tool name has a shape a transcript does not give is named and skipped."""
+    if not isinstance(item, dict):
+        return
+    it, text, name = item.get("type"), item.get("text") or "", item.get("name")
+    name = "?" if name is None else name
+    if _odd_item(it, text, name):
+        print(f"[WARN] line {line_no}: content item of an unknown shape skipped", file=sys.stderr)
+    elif it == "text":
+        text_parts.append(text)
+    elif it == "tool_use":
+        tools[name] = tools.get(name, 0) + 1
+    elif it not in KNOWN_CONTENT_ITEMS:
+        print(f"[WARN] line {line_no}: unknown content type "
+              f"{it!r} skipped", file=sys.stderr)
+
+
+def _content_parts(content, line_no):
+    """(text parts, tool counts) of a message's content, or None for a shape nobody knows (named in a WARN
+    unless the content is missing)."""
+    text_parts, tools = [], {}
+    if isinstance(content, str):
+        text_parts.append(content)
+    elif isinstance(content, list):
+        for item in content:
+            _take_item(item, line_no, text_parts, tools)
+    else:
+        if content is not None:
+            print(f"[WARN] line {line_no}: unknown content shape "
+                  f"({type(content).__name__})", file=sys.stderr)
+        return None
+    return text_parts, tools
+
+
 def parse_turns(stream, unsafe_schema: bool = False, session_id=None,
                 session_name=None):
     """Yield dicts: {role, text, ts, uuid, tools, line_no, parts, session,
@@ -438,59 +530,18 @@ def parse_turns(stream, unsafe_schema: bool = False, session_id=None,
         raw = raw.strip()
         if not raw:
             continue
-        try:
-            obj = json.loads(raw)
-        except json.JSONDecodeError:
-            print(f"[WARN] line {line_no}: invalid JSON skipped", file=sys.stderr)
-            continue
-        if obj.get("isSidechain"):
-            continue
-        if obj.get("teamName") or obj.get("agentName"):
+        obj = _json_object(raw, line_no)
+        if obj is None or not _is_turn_record(obj, seen_unknown_type, unsafe_schema, line_no):
             continue
-        t = obj.get("type")
-        if t not in ("user", "assistant"):
-            if t and t not in KNOWN_TYPES and t not in seen_unknown_type:
-                seen_unknown_type.add(t)
-                print(f"[WARN] unknown record type '{t}' skipped", file=sys.stderr)
-                if not unsafe_schema and t and t.startswith("v"):
-                    print(f"[ERROR] schema marker '{t}' unrecognized — "
-                          "rerun with --unsafe-schema to proceed",
-                          file=sys.stderr)
-                    raise SystemExit(2)
-            continue
-
         msg = obj.get("message") or {}
-        role = msg.get("role") or t
-        content = msg.get("content")
-        ts = obj.get("timestamp")
+        role = msg.get("role") or obj.get("type")
+        ts = _stamp(obj.get("timestamp"))
         uuid_ = obj.get("uuid") or hashlib.sha256(
             f"{line_no}:{ts}".encode()).hexdigest()[:16]
-
-        text_parts = []
-        tools = {}
-        if isinstance(content, str):
-            text_parts.append(content)
-        elif isinstance(content, list):
-            for item in content:
-                if not isinstance(item, dict):
-                    continue
-                it = item.get("type")
-                if it == "text":
-                    text_parts.append(item.get("text") or "")
-                elif it == "tool_use":
-                    tools[item.get("name", "?")] = tools.get(
-                        item.get("name", "?"), 0) + 1
-                elif it in ("tool_result", "thinking"):
-                    continue
-                elif it not in KNOWN_CONTENT_ITEMS:
-                    print(f"[WARN] line {line_no}: unknown content type "
-                          f"'{it}' skipped", file=sys.stderr)
-        else:
-            if content is not None:
-                print(f"[WARN] line {line_no}: unknown content shape "
-                      f"({type(content).__name__})", file=sys.stderr)
+        got = _content_parts(msg.get("content"), line_no)
+        if got is None:
             continue
-
+        text_parts, tools = got
         text = _CTRL_RE.sub("", "\n".join(p for p in text_parts if p).strip())
         if not text and not tools:
             continue
@@ -692,18 +743,16 @@ def _stdin_id_key():
     to a model that never sees the key, so an id gives no way to test a guessed password. With no
     cache folder to keep it in, the key lasts one run."""
     path = CACHE_BASE / "stdin-id.key"
-    try:
-        key = path.read_bytes()
-        if len(key) == 32:
-            return key
-    except OSError:
-        pass
+    key = _read_small(path, 64)
+    if key is not None and len(key) == 32:
+        return key
     key = os.urandom(32)
     tmp = path.with_name("%s.%d" % (path.name, os.getpid()))
     try:
         CACHE_BASE.mkdir(parents=True, exist_ok=True)
         os.chmod(str(CACHE_BASE), 0o700)
-        fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_BINARY", 0), 0o600)
+        # O_EXCL: a name that is already there (a link planted at this guessable name among them) is refused
+        fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0), 0o600)
         with os.fdopen(fd, "wb") as f:
             f.write(key)
         os.replace(str(tmp), str(path))           # whole or not at all
@@ -734,14 +783,72 @@ def _page_clean_turn(t, extra, mode):
     return dict(t, text=clean(t["text"]), parts=[clean(p) for p in t.get("parts") or []])
 
 
+# Letters that print as nothing: the Hangul fillers, the braille blank, and the combining marks Unicode ignores by
+# default (the grapheme joiner, the Khmer inherent vowels, the Mongolian free variation selectors). With the control,
+# format, private-use, unassigned and separator categories, a cache made only of them holds no summary a person can
+# read (3.0.5).
+_BLANK_LETTERS = frozenset(map(chr, (0x115F, 0x1160, 0x3164, 0xFFA0, 0x2800,
+                                     0x034F, 0x17B4, 0x17B5, 0x180B, 0x180C, 0x180D, 0x180F)))
+# Cn follows the Unicode table of the Python that runs: a character newer than that table reads as unassigned, so
+# a cache made only of such characters is summarized again every run (the page is the same).
+_BLANK_CATEGORIES = frozenset(("Cc", "Cf", "Co", "Cn", "Zs", "Zl", "Zp"))
+
+
+def _blank(ch):
+    """Whether ch prints as nothing: whitespace, a blank-looking letter, or a variation selector.
+    White space is in the blank categories too (Zs, Zl, Zp, Cc); str.isspace() only answers it sooner."""
+    if ch.isspace() or ch in _BLANK_LETTERS or unicodedata.category(ch) in _BLANK_CATEGORIES:
+        return True
+    o = ord(ch)
+    return 0xFE00 <= o <= 0xFE0F or 0xE0100 <= o <= 0xE01EF
+
+
+def _has_visible(text):
+    """Whether text holds a letter a person can see."""
+    return not all(_blank(ch) for ch in text)
+
+
+CACHE_READ_MAX = 64 * 1024  # bytes: a cached summary or decision is some hundred (120 characters), so this is generous
+
+
+def _read_small(path, limit=CACHE_READ_MAX):
+    """The bytes of the regular file at path when it holds at most `limit`, else None (missing, a link, a pipe, a
+    folder, a larger file). Opened without blocking and without following a link, so a pipe or a link left at a
+    cache place neither stops a run nor sends it to another file. Windows has neither flag: there the lstat
+    turns a link away, but a link swapped in between the lstat and the open is followed."""
+    flags = (os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_NOFOLLOW", 0)
+             | getattr(os, "O_BINARY", 0))
+    try:
+        if not stat.S_ISREG(os.lstat(str(path)).st_mode):      # a link (Windows has no O_NOFOLLOW), pipe, folder
+            return None
+        fd = os.open(str(path), flags)
+        with os.fdopen(fd, "rb") as f:
+            if not stat.S_ISREG(os.fstat(f.fileno()).st_mode):
+                return None
+            data = f.read(limit + 1)
+    except OSError:
+        return None
+    return data if len(data) <= limit else None
+
+
+def _read_text(path):
+    """The UTF-8 text _read_small gives, else None (bytes that are not UTF-8: a DRM encrypted them)."""
+    data = _read_small(path)
+    try:
+        return None if data is None else data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
 def _read_cached(p):
     """The summary cached at p, else at the same name with .txt, which 3.0.2 and earlier wrote.
-    None when neither can be read: missing, or bytes that are not UTF-8 (a DRM encrypted them)."""
+    None when neither holds one: missing, bytes that are not UTF-8 (a DRM encrypted them), or
+    nothing a person can see (a write that stopped early, or only blank-looking letters); the
+    turn is then summarized again (3.0.4, 3.0.5)."""
     for cached in (p, p.with_name(p.stem + ".txt")):
-        try:
-            return cached.read_text(encoding="utf-8").strip()
-        except (OSError, UnicodeDecodeError):
-            continue
+        text = (_read_text(cached) or "").strip()
+        if _has_visible(text):
+            return text
     return None
 
 
@@ -766,9 +873,7 @@ def read_or_summarize(turn: dict, session_id: str, rebuild: bool = False,
     redacted = summarize_turn(_page_clean_turn(turn, redact_extra, redact_mode))
     if p is not None:
         try:
-            fd = os.open(str(p), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-            with os.fdopen(fd, "w", encoding="utf-8") as f:
-                f.write(redacted)
+            _write_private(p, redacted)
         except OSError:
             pass
     return redacted, False
@@ -1371,7 +1476,7 @@ def _write_private(path, text):
     path.parent.mkdir(parents=True, exist_ok=True)
     fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp")
     try:
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
             f.write(text)
         os.replace(tmp, str(path))
     except BaseException:
@@ -1382,6 +1487,13 @@ def _write_private(path, text):
         raise
 
 
+def _write_text_lf(path, text):
+    """Write `text` to `path` as UTF-8 with LF line ends on every OS. Text mode on Windows
+    would write CRLF, so the same transcript would give a different page there."""
+    with open(str(path), "w", encoding="utf-8", newline="\n") as f:
+        f.write(text)
+
+
 def _safe_name(s):
     """A file-name-safe form of an id read from a transcript or a pack."""
     s = re.sub(r"[^A-Za-z0-9_.-]", "_", str(s or "default"))[:80]
@@ -1417,8 +1529,8 @@ def read_llm_cache(turn_id, session, digest):
                    "every turn is reviewed")
         return None
     try:
-        got = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, ValueError, UnicodeDecodeError):
+        got = json.loads(_read_text(path) or "")
+    except (ValueError, RecursionError):
         return None
     if not isinstance(got, dict):
         return None
@@ -1700,7 +1812,7 @@ def _is_pack_turn(x):
 def _load_pack(path):
     try:
         pack = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, ValueError, UnicodeDecodeError) as e:
+    except (OSError, ValueError, UnicodeDecodeError, RecursionError) as e:
         return _bad(f"cannot read review pack {path}: {e}")
     if not isinstance(pack, dict) or pack.get("schema") != REVIEW_SCHEMA:
         return _bad(f"{path} is not a {REVIEW_SCHEMA} pack (made by another lineage version? "
@@ -1819,7 +1931,8 @@ def _clean_summary(s, extra, mode):
     next reviewer and the gate's critic, so no part of a key may stay in it."""
     pre, n = review_redact(" ".join(s.split()), extra)
     red, found = redact(pre, extra=extra, mode=mode)
-    return (_cut(red, SUMMARY_MAX) or None), n + sum(found.values())
+    cut = _cut(red, SUMMARY_MAX)
+    return (cut if _has_visible(cut) else None), n + sum(found.values())
 
 
 def _warn_coverage(pack, decided):
@@ -2304,6 +2417,16 @@ def default_output(args, jsonl_path, session_id):
     return f"work/lineage-{slug}.html"
 
 
+# The controls that embed, override or isolate text direction (U+202A..U+202E, U+2066..U+2069). In a page they
+# reorder what a reader sees and can reach past the element that holds them, so the page shows each as a visible
+# [U+XXXX] instead. Plain letters of right-to-left scripts, and the direction marks, stay.
+_BIDI_CONTROLS = re.compile("[" + "".join(map(chr, (*range(0x202A, 0x202F), *range(0x2066, 0x206A)))) + "]")
+
+
+def _show_bidi_controls(text):
+    return _BIDI_CONTROLS.sub(lambda m: "[U+%04X]" % ord(m.group()), text)
+
+
 def render_and_write(turns, session_id, args, all_sessions=False, markdown=True,
                      open_details=False, title="Session Lineage", summaries=None,
                      prior_redactions=None):
@@ -2333,8 +2456,8 @@ def render_and_write(turns, session_id, args, all_sessions=False, markdown=True,
     html_doc = HTML_TEMPLATE
     html_doc = html_doc.replace("{{TITLE}}", html.escape(title), 1)
     html_doc = html_doc.replace("{{HEADER_TITLE}}", html.escape(title), 1)
-    html_doc = html_doc.replace("{{DATE_RANGE}}", html.escape(date_range), 1)
-    html_doc = html_doc.replace("{{TURNS}}", "\n".join(rows), 1)
+    html_doc = html_doc.replace("{{DATE_RANGE}}", html.escape(_show_bidi_controls(date_range)), 1)
+    html_doc = html_doc.replace("{{TURNS}}", _show_bidi_controls("\n".join(rows)), 1)
 
     errs = self_verify(html_doc)
     if errs:
@@ -2342,7 +2465,7 @@ def render_and_write(turns, session_id, args, all_sessions=False, markdown=True,
 
     out = _with_timestamp_suffix(args.output)
     out.parent.mkdir(parents=True, exist_ok=True)
-    out.write_text(html_doc, encoding="utf-8")
+    _write_text_lf(out, html_doc)
 
     _run_reviewer_gate(turns, out, session_id, args, summaries=summaries)
 
@@ -2586,7 +2709,7 @@ def _check_coverage(verdict, samples):
     """Exit 2 unless the verdict answers each of the samples in file `samples`."""
     try:
         gaps = _verdict_gaps(verdict, json.loads(samples.read_text(encoding="utf-8")))
-    except (OSError, ValueError, UnicodeDecodeError, AttributeError) as e:
+    except (OSError, ValueError, UnicodeDecodeError, AttributeError, RecursionError) as e:
         gaps = f"cannot read the samples: {e}"
     if gaps:
         print(f"[lineage] ERROR: the verdict does not answer {samples} ({gaps}); have the "

package/skills/omc-patch/SKILL.md

@@ -41,11 +41,17 @@ OMC(oh-my-claudecode)가 새 버전으로 자동 업데이트되면 로컬 훅
 - `--root` 는 폴더의 이름표가 OMC 가 아니면 `OMC 플러그인 폴더가 아님` 으로 멈춘다. `.claude-plugin/plugin.json` 의 name 이 있으면 그것으로, 없으면 `package.json` 의 name 으로 정한다. 다른 폴더를 잘못 준 실수를 막는 확인이고, 이름표가 없는 폴더는 통과한다.
 - 쓸 파일이 링크로 플러그인 폴더 밖을 가리키거나 백업 자리(`.omcbak`)가 링크면 도구는 쓰지 않고 실패로 센다. 문구는 적용 때 `쓰지 않음`, 되돌리기 때 `되돌리지 않음`, hooks.json 은 `hooks.json 을 건드리지 않음` 이다.
 - 패치 규칙은 OMC 훅 코드의 모양에 맞춰져 있다. 처음 보는 OMC 버전이면 반드시 `check` 를 먼저 실행한다.
-- `실패 N건` 이 1건 이상이면 멈추고 출력을 그대로 보고한다. 문법 오류가 난 파일은 도구가 원본으로 자동 롤백한다.
+- `실패 N건` 이 1건 이상이면 멈추고 출력을 그대로 보고한다. 예외는 2단계에서 남기기로 한 `PINNED` 줄 하나뿐이다(3단계 2). 문법 오류가 난 파일은 도구가 원본으로 자동 롤백한다. 고친 hooks.json 이 다시 읽어 JSON 이 아니어도 원본으로 되돌리고(`hooks.json 손상으로 롤백`) 실패로 센다.
 - 판정은 출력 문구로 한다. 종료 코드 0 만으로 완료라고 보고하지 않는다.
 - 캐시에는 정션이나 심볼릭 링크로 이어진 버전 폴더가 있을 수 있다(예: 옛 버전 폴더가 새 버전을 가리킴). 이때 한 번의 변경이 두 버전 폴더에 함께 보인다. 정상이다.
 - 도구는 `os.homedir()/.claude` 를 쓴다. `CLAUDE_CONFIG_DIR` 로 설정 폴더를 옮겼다면 이 도구는 그 폴더를 보지 않는다.
-- 출력의 origin 에 `https://사용자:토큰@...` 처럼 자격증명이 들어 있으면, 보고할 때 `//***@` 로 가린다. 출력을 그대로 보고하라는 단계에서도 이 가림은 지킨다. 그 URL 은 `PINNED` 에도 평문으로 남으니 사용자에게 알린다.
+- 출력의 origin 에 `https://사용자:토큰@...` 처럼 자격증명이 들어 있으면, 보고할 때 `//***@` 로 가린다. 출력을 그대로 보고하라는 단계에서도 이 가림은 지킨다. 옛 판의 도구가 만든 `PINNED` 에는 그 URL 이 남아 있을 수 있다. `--check` 는 그 칸을 `[!] 고정 기록(PINNED)에 옛 URL 칸이 남아 있음 (적용하면 지움)` 으로 알리고 모두 적용된 상태로 보지 않는다. 적용(`--check` 가 아닌 실행)은 그 칸을 지우고 권한을 0600 으로 맞춘다(POSIX. Windows 는 chmod 가 쓰기 비트만 다뤄 폴더의 상속 권한을 따른다). 이 도구가 다 지울 수 없으면(칸이 든 기록이 링크, JSON 이 아님, 폴더에 쓰지 못함, 읽지 못함, 같은 파일의 다른 이름이 있음) `[!] 고정 기록(PINNED)의 옛 URL 칸을 ...` 줄로 알리고 적용은 실패로 센다(종료 1). 다른 이름이 있으면 적용은 이 이름에서만 지우고 다른 이름에는 남긴다. 링크는 따라가 쓰지 않으며, 링크 너머에 그 칸이 없으면 알리지 않는다. 되돌리기는 `PINNED` 를 지운다. 링크 너머에 그 칸이 있거나 링크 너머를 읽지 못하거나, 지우지 못하거나, 같은 파일의 다른 이름이 있을 때만 실패로 세고, 링크가 아닌 기록은 JSON 이 아니거나 읽지 못해도 그냥 지운다. `PINNED` 는 기록일 뿐이라 지워도 고정과 되돌리기에 영향이 없다. 알린 줄은 아래 `PINNED` 줄 다루기대로 묻는다. 기록 파일의 내용은 읽어 보이지 않는다(인증 정보가 들 수 있음).
+- `PINNED` 줄 다루기. `[!] 고정 기록(PINNED)의 옛 URL 칸을 ...` 줄이 나오면 그 줄의 경로를 사용자에게 보이고 그 기록을 지울지 남길지 묻는다. `--check` 에서 나온 줄은 2단계 승인 질문에서 함께 묻는다. 적용이나 되돌리기에서 처음 나온 줄은 멈추고 보고한 뒤 묻는다. 이때도 기록의 내용은 읽지 않고 경로만 보인다.
+  - 폴더 권한이 원인(`쓰지 못함`)이면 권한을 고칠지도 묻는다.
+  - 링크면 URL 칸은 링크가 가리키는 파일에 있다. 그 파일의 경로도 보인다. 경로는 `node -e "console.log(require('fs').realpathSync(process.argv[1]))" "<링크 경로>"` 로 구한다(bash, PowerShell 같음). 그 파일이 `PINNED` 기록이 맞는지는 사용자가 직접 열어 확인한 뒤 답하게 한다(링크는 글자만 보고 막으므로 무관한 파일일 수 있다).
+  - 같은 파일의 다른 이름이 있다는 줄이면 그 아래 `다른 이름은 ... 로 찾습니다.` 줄의 번호로 다른 이름을 찾아 경로를 보인다. 찾은 이름 중 `PINNED` 가 아닌 것이 다른 이름이다. POSIX 는 `find "<맨 위 폴더>" -xdev -inum <번호> 2>/dev/null` 이고, 맨 위 폴더는 `df -P "<PINNED 가 든 폴더>"` 둘째 줄의 마지막 칸이다. Windows 는 `fsutil file queryFileNameById <드라이브>\ <번호>` 이다(관리자 셸에서만 확인함). 찾지 못하면(권한으로 못 본 폴더 등) 번호를 그대로 사용자에게 알린다.
+  - 사용자가 지우기를 고르면 그것이 승인이다. 보인 경로만 지운다. 링크면 링크와 그것이 가리키는 파일을, 다른 이름이 있으면 `PINNED` 와 찾은 다른 이름을 모두 지운다. 하나라도 남기면 그 안에 URL 이 남는다. 링크가 가리키는 파일이 `PINNED` 기록이 아니라고 사용자가 답하면 그 파일은 지우지 않고 링크만 지울지 묻는다.
+  - 남기기로 하면 그 줄은 예상된 실패다. 적용에서는 3단계 2 의 예외, 검증에서는 4단계 1 의 예외를 따른다. 다른 이름이 있는 기록을 남기고 적용하면 적용은 `PINNED` 의 칸만 지운다. 그 뒤 `--check` 는 다른 이름을 보지 못하니 5단계 보고에 그 경로를 적는다.
 
 ## 절차
 
@@ -70,23 +76,30 @@ node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --check --no
 
 - `활성 버전: X (installed_plugins.json)` 줄로 실제 활성 버전을 확인한다.
 - 그 줄이 `(추정: ...)` 로 끝나면 도구가 `installed_plugins.json` 에서 활성 버전을 찾지 못한 것이다. 적용하지 않고 출력을 그대로 보고하고 끝낸다. 추정한 폴더를 패치하면 실제 활성 버전은 그대로 남는데 `check` 는 적용된 것으로 보일 수 있다.
-- `패치 필요 N건` 은 설치된 모든 버전 폴더를 합친 수다. 판정은 맨 아래 `결과:` 줄로 한다.
+- `패치 필요 N건` 은 설치된 모든 버전 폴더를 합친 수다. 판정은 `결과:` 줄로 한다. 그 아래 `참고:` 줄은 아래 항목대로 다룬다.
 
 | `결과:` 줄 | 다음 |
 |---|---|
 | `모두 적용된 상태입니다.` | 4단계 검증으로 건너뜀 |
 | `헬퍼 자리 결함 N건이 있습니다.` | 2단계 확인 뒤 3단계에서 활성 폴더부터 되돌림 |
 | `적용되지 않은 항목이 있습니다.` | 2단계 확인 뒤 3단계 적용 |
+| `hooks.json 을 확인하지 못했습니다.` | 적용하지 않고 위의 `[!]` 줄을 그대로 보고 |
+| `마켓플레이스 origin 을 확인하지 못했습니다.` | 적용하지 않고 위의 `[!]` 줄을 그대로 보고(git 이 없거나 마켓플레이스 저장소를 읽지 못함) |
+| `고정 기록(PINNED)의 옛 URL 칸이 이 도구로 지울 수 없는 곳에 있습니다.` | 적용할 항목은 없다. 2단계에서 그 기록을 지울지 남길지만 묻는다(`규칙` 절의 `PINNED` 줄 다루기). 어느 쪽이든 그 뒤 4단계 검증으로 건너뜀 |
 
 - `참고: 비활성 버전 ...` 은 지금 쓰지 않는 버전이라 판정에 들어가지 않는다.
+- `결과:` 줄 아래의 `참고: 고정 기록(PINNED)의 옛 URL 칸이 이 도구로 지울 수 없는 곳에 있습니다.` 는 적용할 항목도 있다는 뜻이다. 적용해도 그곳의 칸은 남고 적용은 `실패 1건` 으로 끝난다. 2단계에서 함께 묻는다. 위 표의 같은 문구 결과 줄은 적용할 항목 없이 이것만 남았을 때 나온다.
 - 인자가 `check` 이면 여기서 결과만 보고하고 끝낸다.
 
 ### 2. 확인 (적용 전 필수)
 
-`--check` 결과를 보여 주고 사용자에게 적용해도 되는지 묻는다. 묻기 전에 아래를 알린다.
+`--check` 결과를 보여 주고 사용자에게 적용해도 되는지 묻는다. 묻기 전에 아래를 알린다. 1단계 결과가 위 표의 `PINNED` 줄이면 적용할 항목이 없다. 적용은 묻지 않고 아래 `PINNED` 항목만 한다.
 - 활성 OMC 버전의 `scripts/*.mjs` 와 `hooks/hooks.json` 을 고친다. 원본은 `.omcbak` 로 남는다.
 - 헬퍼 자리 결함이 있으면 활성 폴더를 `.omcbak` 원본으로 먼저 되돌린 뒤 다시 패치한다.
-- OMC 마켓플레이스 `origin` 을 `omc-pinned://` 로 바꾼다. OMC 가 더 이상 자동 업데이트되지 않는다. 되돌리기는 `revert`.
+- OMC 마켓플레이스 `origin` 을 `omc-pinned://` 로 바꾼다(`이미 고정됨` 이면 그대로 둔다). OMC 가 더 이상 자동 업데이트되지 않는다. 되돌리기는 `revert`.
+- 1단계에 `[!] 고정 기록(PINNED)의 옛 URL 칸을 ...` 줄이 있었으면 그 기록을 어떻게 할지 함께 묻는다(`규칙` 절의 `PINNED` 줄 다루기).
+  - 적용할 항목도 있으면 답은 셋이다. 지우고 적용(승인한 파일을 지운 뒤 3단계로, 적용은 실패 0건), 남기고 적용(3단계로, 그 줄 하나가 실패로 남아 `실패 1건`), 적용하지 않음(여기서 끝냄).
+  - 1단계 결과가 위 표의 `PINNED` 줄이면 적용할 항목이 없다. 적용은 묻지 않고 지울지 남길지만 묻는다. 어느 쪽이든 그 뒤 4단계로 건너뛴다.
 - 승인이 없으면 적용하지 않는다.
 
 ### 3. 적용
@@ -115,12 +128,13 @@ node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --check --no
    ```
 
    - `패치 N건 / 실패 0건`, `[3/4]` 의 PostToolUse 제거, `[4/4]` 의 고정 결과를 확인한다.
-   - 실패가 1건 이상이면 멈추고 출력 그대로 보고한다.
+   - 끝 줄 `완료. 실패 N건.` 의 N 이 1 이상이면 멈추고 출력 그대로 보고한다. 예외는 하나다. `완료. 실패 1건.` 이고 그 1건이 2단계에서 남기기로 한 `PINNED` 의 `[!]` 줄이면 멈추지 않고 4단계로 간다. 끝의 `[!] PostToolUse 훅 제거는 ...` 줄은 재시작 안내라 실패가 아니다.
+   - `완료. 실패 1건.` 이고 그 1건이 1단계에 없던 `[!] 고정 기록(PINNED)` 줄이면 멈추고 보고한 뒤 `PINNED` 줄 다루기대로 묻는다. 훅 패치는 이미 적용돼 있다. 지우기로 하면 지운 뒤, 남기기로 하면 그대로 4단계로 간다.
    - `[!] 헬퍼 자리 결함 N건은 고치지 않았습니다.` 가 나오면 1 을 건너뛰었거나 1 이 그 파일을 되돌리지 못한 것이다. 1 과 2 를 한 번만 다시 한다. 다시 해도 같으면 멈추고 보고한다.
 
 ### 4. 검증 (다섯 가지 모두)
 
-1. 다시 진단한다. `결과: 모두 적용된 상태입니다.` 가 나와야 하고, 활성 버전에 `헬퍼 자리 결함` 줄이 없어야 한다.
+1. 다시 진단한다. `결과: 모두 적용된 상태입니다.` 가 나와야 하고, 활성 버전에 `헬퍼 자리 결함` 줄이 없어야 한다. 사용자가 `PINNED` 를 남기기로 했으면 `결과: 고정 기록(PINNED)의 옛 URL 칸이 이 도구로 지울 수 없는 곳에 있습니다.` 와 그 `[!]` 줄이 나오는 것은 정상이다. 나머지 검증을 계속한다.
 
    ```bash
    node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --check --no-update
@@ -184,17 +198,22 @@ node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --check --no
    | 그 밖의 `probe-pm:` 줄(종료 코드 2) | 명령 오류다. 경로를 다시 구해 한 번만 다시 실행한다. 같으면 출력을 보고하고 멈춘다 |
    | 판정 줄 뒤의 `probe-pm: 임시 폴더를 지우지 못함` | 판정은 그대로 쓴다. 남은 임시 폴더 경로를 보고에 적어 사용자가 지우게 한다 |
 
-5. 마켓플레이스 고정을 확인한다. `omc-pinned://` 로 시작하면 고정된 것이다.
+5. 마켓플레이스 고정을 확인한다. 명령은 origin 이 `omc-pinned://` 로 시작하는지만 보고 `pinned` 나 `not-pinned` 한 단어를 낸다. origin 의 자격 증명과 쿼리 값은 출력에 나오지 않는다. `pinned` 면 고정된 것이다.
 
    ```bash
-   git -C "$HOME/.claude/plugins/marketplaces/omc" remote get-url origin
+   case "$(git -C "$HOME/.claude/plugins/marketplaces/omc" config --get remote.origin.url)" in omc-pinned://*) echo pinned;; *) echo not-pinned;; esac
    ```
 
-   PowerShell 에서는 `$HOME` 대신 `$env:USERPROFILE` 을 쓴다.
+   PowerShell:
+
+   ```powershell
+   if ((git -C "$env:USERPROFILE/.claude/plugins/marketplaces/omc" config --get remote.origin.url) -like 'omc-pinned://*') { 'pinned' } else { 'not-pinned' }
+   ```
 
 ### 5. 보고
 
 - 활성 버전, 패치 건수, 헬퍼 자리 결함 처리 여부, PostToolUse 제거 목록, 고정 상태, project-memory 확인 결과
+- `PINNED` 줄이 있었으면 어떻게 했는지(지운 경로, 또는 남긴 기록과 그 경로. 다른 이름이 있던 기록은 다른 이름의 경로)
 - 훅 스크립트 패치는 바로 적용된다. 훅이 호출될 때마다 파일을 새로 읽기 때문이다.
 - PostToolUse 제거는 `hooks.json` 변경이라 각 세션을 다시 시작해야 적용된다.
 - Windows 에서 이미 쌓인 커널 풀은 재부팅으로만 회수된다. 재부팅은 사용자가 직접 한다.
@@ -209,6 +228,7 @@ node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --revert
 - `.omcbak` 백업으로 설치된 모든 버전의 훅 스크립트와 `hooks.json` 을 되돌리고 마켓플레이스 `origin` 을 원래 URL 로 복구한다.
 - 되돌린 뒤 Claude Code 를 다시 시작해야 반영된다.
 - `되돌리기를 끝내지 못했습니다.` 가 나오면 위의 `[!]` 줄을 그대로 보고한다. 종료 코드는 1 이다. 백업이 없어 남은 파일과 hooks.json 도 이 끝 줄로 끝난다.
+- 고정 기록(`PINNED`)을 지우지 못하면(읽기 전용 폴더, 폴더인 `PINNED`) `[!] 고정 기록(PINNED)을 지우지 못함` 으로 알리고 실패로 센다. 링크인 `PINNED` 너머에 옛 URL 칸이 있으면 링크를 두고 `[!]` 로 알린다. 옛 URL 칸이 든 기록에 같은 파일의 다른 이름이 있으면 이 이름만 지우고 `[!]` 로 알린다. 셋 다 origin 은 그대로 되돌린다. 위 `규칙` 절의 `PINNED` 줄 다루기대로 사용자에게 묻는다.
 - `이 도구가 만들지 않은 수정이 남아 있습니다` 가 나오면 백업이 없는 손 수정이다. 출력에 적힌 복구 명령을 그대로 보고하고, 사용자 승인 없이 실행하지 않는다.
 
 ## 함정
@@ -218,9 +238,15 @@ node "<이 스킬 디렉터리 절대경로>/scripts/omc-patch.mjs" --revert
 - 헬퍼 자리 결함이 남은 채 `revert` 없이 적용을 다시 돌려도 바뀌는 것이 없다. 이미 감싼 파일은 건너뛰기 때문이다.
 - `--root` 와 `--revert --root` 는 그 폴더만 다룬다. 고정 해제까지 하려면 인자 없는 `--revert` 를 쓴다.
 - 고정을 풀지 않고 OMC 를 올리려면 먼저 `revert` 한다. 그렇지 않으면 마켓플레이스 fetch 가 계속 실패한다.
-- 고정 기록(`PINNED`)은 `~/.claude/omc-local-patches/PINNED` 에 생긴다. 기록일 뿐이라 지워도 고정은 풀리지 않고, 이미 고정된 상태에서는 다시 만들어지지 않는다. `revert` 는 origin 값에서만 원래 URL 을 되찾고, `PINNED` 의 값으로 origin 을 쓰지 않는다. 다른 기기의 기록이면 알리기만 한다.
+- 고정 기록(`PINNED`)은 `~/.claude/omc-local-patches/PINNED` 에 생긴다. 고정한 시각, 판, 기기 이름만 담고 URL 은 담지 않는다. 옛 판의 기록에 URL 칸이 있으면 `--check` 가 알리고 다음 적용 때 지운다. 지우지 못하면 `[!]` 로 알리고 실패로 센다(링크는 따라가 쓰지 않음). 하드 링크로 이어진 다른 이름에는 그 칸이 남는다. 도구는 그 이름을 찾을 번호를 알린다. POSIX 에서는 이 계정만 읽을 수 있다(0600). Windows 에서는 폴더의 상속 권한을 따른다. 기록일 뿐이라 지워도 고정은 풀리지 않고, 이미 고정된 상태에서는 다시 만들어지지 않는다. `revert` 는 origin 값에서만 원래 URL 을 되찾는다. 다른 기기의 기록이면 알리기만 한다.
 - `--check` 와 `--revert` 를 함께 주면 도구는 아무것도 하지 않고 종료 코드 1 로 멈춘다. 진단만 하려면 `--check` 만 준다.
 - 도구는 git 을 부를 때 저장소를 고르는 변수(`GIT_DIR`, `GIT_WORK_TREE` 등 `git rev-parse --local-env-vars` 목록)를 지운다. git 훅 안에서 불러도 마켓플레이스 저장소만 다룬다.
 - 마켓플레이스의 `.git` 이 깨졌으면(중단된 clone 등) git 이 위쪽 저장소로 올라가지 못하게 막는다. 그때 `[4/4]` 는 `origin remote 없음` 으로 끝나고 고정하지 않는다.
 - `--scan` 은 읽기만 한다. 플러그인 캐시도 `installed_plugins.json` 도 읽지 않고 준 파일만 본다.
+- 도구는 모르는 인자를 받지 않는다. `--check`, `--revert`, `--no-update`, `--root <폴더>`, `--scan <파일>...`, `--help` 밖의 인자나 `--root=<폴더>` 꼴을 주면 아무것도 하지 않고 사용법과 함께 종료 1 로 멈춘다.
+- 출력의 origin URL 에 사용자 이름과 비밀번호가 있으면 `//***@` 로 가린다. 도구는 origin 을 설정 값 그대로 읽어 고정하고 되돌린다(전역 `insteadOf` 를 펼치지 않음).
+- origin 을 바꾸지 못하면(`.git` 쓰기 권한 등) `[!] 고정 실패` 나 `[!] 고정 해제 실패` 와 종료 1 로 끝난다. 그 줄을 그대로 보고한다. 고정 해제에 실패하면 도구가 원래 URL 을 호스트까지만 보인다. 원문은 origin 의 `omc-pinned://` 뒤에 그대로 남는다.
+- `--check` 는 쓸 수 없는 파일을 `패치 필요, 쓸 수 없음` 으로 미리 알린다. 폴더 밖 링크 때문에 되돌리지 못한 파일은 손 복구 방법을 함께 낸다. 링크 대상 파일에 이 도구 계열의 패치가 보이지 않으면 덮어쓰라고 하지 않고, 링크가 가리키는 곳이 맞는지 먼저 확인하라고 한다. 사용자 승인 없이 그 방법을 실행하지 않는다.
+- 파일은 새 임시 파일을 디스크까지 내린 뒤 rename 으로 바꾼다. 하드 링크로 이어진 폴더 밖 파일은 바뀌지 않는다. 쓰지 못한 파일은 `쓰지 못함` 으로 이름을 대고 실패로 센다.
+- 읽을 수 없는 훅(권한, 폴더, FIFO)은 `읽지 못함: <이름> (<코드>)`, 쓸 권한이 없거나 일반 파일이 아닌 훅은 `쓰지 않음: <이름> (쓸 권한이 없음 또는 일반 파일이 아님)` 으로 알리고 실패로 센다. `--check` 는 읽지 못한 훅이 있으면 모두 적용된 상태로 보지 않는다. 설정 파일도 일반 파일만 읽는다. `installed_plugins.json` 이 FIFO 처럼 일반 파일이 아니면 활성 버전이 `(추정: ...)` 으로 나오고, `settings.json` 이면 `DISABLE_AUTOUPDATER` 줄을 생략한다. 도구가 처리하지 못한 오류는 경로를 정화한 한 줄과 종료 1 로 끝난다.
 - 도구의 주석과 출력 문구는 한글이다.