@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/hooks/_boxlib.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+# codeArbiter — statusline box-drawing layout (extracted from statusline.py,
+# architecture-004).
+#
+# Owns the sectioned box shell (top/row/sep/bottom) and the two small layout
+# helpers (left+right justify, equal-width columns) segments use to lay content
+# out inside a row. Carries no segment CONTENT — purely the box structure and
+# column math, built on the ANSI/width-aware primitives in _colorlib.
+#
+# Design principles (mirroring _ledgerlib.py):
+#   - Stdlib only; no third-party imports ever.
+#   - Zero side effects at import time.
+#
+# Public API:
+#   Box(width)                        the box shell: .top/.row/.sep/.bottom/.render
+#   lr(left, right, inner) -> str     left+right justified within inner
+#   cols(cells, inner) -> (str, list) equal-column layout with tee-aligned separators
+
+try:
+    import _colorlib
+    _RESET = _colorlib.RESET
+    _V0 = _colorlib.V0
+    _TL, _TR, _BL, _BR = _colorlib.TL, _colorlib.TR, _colorlib.BL, _colorlib.BR
+    _H, _V, _LT, _RT = _colorlib.H, _colorlib.V, _colorlib.LT, _colorlib.RT
+    _TD, _TU, _DOTH = _colorlib.TD, _colorlib.TU, _colorlib.DOTH
+    _pad, _vlen, _clip, _gradient_h = (_colorlib.pad, _colorlib.vlen,
+                                       _colorlib.clip, _colorlib.gradient_h)
+    _box_gradient_h = _colorlib.box_gradient_h
+    _ANSI = _colorlib.ANSI
+except Exception:  # pragma: no cover — never let an import break the statusline
+    _colorlib = None
+    _RESET = _V0 = ""
+    _TL = _TR = _BL = _BR = _H = _V = _LT = _RT = _TD = _TU = _DOTH = ""
+
+    def _pad(s, w):
+        return s
+
+    def _vlen(s):
+        return len(s)
+
+    def _clip(s, w):
+        return s[:w]
+
+    def _gradient_h(text, width, c_from=None, c_to=None):
+        return text
+
+    _box_gradient_h = _gradient_h
+
+    import re as _re
+    _ANSI = _re.compile(r"\033\[[0-9;]*m")
+
+
+def sync_palette():
+    """Refresh captured color exports after _colorlib runtime activation."""
+    global _RESET, _V0, _gradient_h, _box_gradient_h
+    if _colorlib is not None:
+        _RESET, _V0 = _colorlib.RESET, _colorlib.V0
+        _gradient_h = _colorlib.gradient_h
+        _box_gradient_h = _colorlib.box_gradient_h
+
+class Box:
+    def __init__(self, width):
+        self.W = width
+        self.inner = width - 4   # "│ " + content + " │"
+        self.lines = []
+
+    def top(self, title, badge=""):
+        left = f"{_V0}{_TL}{_H}{_H}{_RESET} "          # 4 visible cols
+        b = f" {badge} " if badge else " "
+        budget = max(1, self.W - 5 - _vlen(b))     # keep room for ╮ + >=0 fill
+        title = _clip(title, budget) if _vlen(title) > budget else title
+        t = _gradient_h(_ANSI.sub("", title), _vlen(title))
+        used = 3 + _vlen(title) + _vlen(b)
+        fillw = max(0, self.W - 1 - used - 1)
+        fill = _box_gradient_h(_H * fillw, fillw) if fillw else ""
+        self.lines.append(f"{left}{t}{b}{fill}{_V0}{_TR}{_RESET}")
+
+    def row(self, content):
+        self.lines.append(f"{_V0}{_V}{_RESET} {_pad(content, self.inner)} {_V0}{_V}{_RESET}")
+
+    def sep(self, tees=None):
+        mid = [_DOTH] * (self.inner + 2)
+        for k in (tees or []):
+            if 0 <= k + 1 < len(mid):
+                mid[k + 1] = _TD
+        self.lines.append(f"{_V0}{_LT}{''.join(mid)}{_RT}{_RESET}")
+
+    def bottom(self, tees=None):
+        mid = [_H] * (self.inner + 2)
+        for k in (tees or []):
+            if 0 <= k + 1 < len(mid):
+                mid[k + 1] = _TU
+        self.lines.append(f"{_V0}{_BL}{''.join(mid)}{_BR}{_RESET}")
+
+    def render(self):
+        # No trailing newline: a multi-line statusline that ends in '\n' adds a
+        # phantom row, so the host's height accounting drifts on re-render and the
+        # bar eventually clears itself. Lines are separated, not terminated.
+        return "\n".join(self.lines)
+
+
+def lr(left, right, inner):
+    """Left + right justified within inner; never exceeds inner (clips left)."""
+    right = _clip(right, inner)
+    rw = _vlen(right)
+    left = _clip(left, max(0, inner - rw - 1))
+    gap = max(1, inner - _vlen(left) - rw)
+    return left + " " * gap + right
+
+
+def cols(cells, inner):
+    """Lay out cells in equal columns with ' │ ' joins. Each cell is clamped to
+    its column via pad(), so total visible width == inner exactly and the
+    separator tees line up with the content joins. Returns (content, bounds)."""
+    n = len(cells)
+    if n == 1:
+        return _pad(cells[0], inner), []
+    seps = n - 1
+    avail = inner - seps * 3
+    base = avail // n
+    widths = [base] * n
+    widths[-1] = avail - base * (n - 1)
+    parts, bounds, pos = [], [], 0
+    for i, c in enumerate(cells):
+        parts.append(_pad(c, widths[i]))
+        pos += widths[i]
+        if i < n - 1:
+            parts.append(f" {_V0}{_V}{_RESET} ")
+            bounds.append(pos + 1)
+            pos += 3
+    return "".join(parts), bounds

package/plugins/ca-pi/hooks/_colorlib.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+# codeArbiter — statusline color palette, box-drawing glyphs, and ANSI/width-aware
+# string primitives (extracted from statusline.py, architecture-004).
+#
+# Owns the neon-violet palette, native-safe glyph set, the ANSI-escape regex, and
+# the terminal-column-width-aware string ops (clip/pad/vlen) the box layout relies
+# on to stay aligned regardless of color codes or wide (CJK/emoji) glyphs. Carries
+# NO rendering-decision logic (no segment content, no box structure) — purely the
+# color/glyph vocabulary and the width primitives built on it.
+#
+# Design principles (mirroring _ledgerlib.py):
+#   - Stdlib only; no third-party imports ever.
+#   - Zero side effects at import time.
+#   - Pure functions, fully testable with synthetic input.
+#
+# Public API:
+#   fg(r,g,b) -> str                          truecolor foreground SGR
+#   bg(r,g,b) -> str                          truecolor background SGR
+#   vlen(s) -> int                            visible terminal-column width (ANSI-aware, wide-glyph-aware)
+#   clip(s, w) -> str                         truncate to <= w visible columns (ANSI-preserving)
+#   pad(s, w) -> str                          pad/clip to exactly w visible columns
+#   gradient_h(text, width, c_from, c_to) -> str   per-character violet sheen
+#   strip_control(s) -> str                   strip C0 control bytes + OSC/CSI escape sequences
+
+import json
+import os
+import re
+import unicodedata
+from dataclasses import dataclass, replace
+from types import MappingProxyType
+
+
+@dataclass(frozen=True)
+class RGB:
+    r: int
+    g: int
+    b: int
+
+    def __iter__(self):
+        return iter((self.r, self.g, self.b))
+
+    def __getitem__(self, index):
+        return (self.r, self.g, self.b)[index]
+
+
+@dataclass(frozen=True)
+class Palette:
+    accent_deep: RGB
+    accent_mid: RGB
+    accent_primary: RGB
+    accent_bright: RGB
+    text_muted: RGB
+    text_normal: RGB
+    text_on_accent: RGB
+    semantic_ok: RGB
+    semantic_warn: RGB
+    semantic_danger: RGB
+    gradient_from: RGB
+    gradient_to: RGB
+
+
+def _palette(values):
+    return Palette(*(RGB(*value) for value in values))
+
+
+BUILTIN_PALETTES = MappingProxyType({
+    "violet": _palette(((108, 70, 180), (150, 92, 230), (178, 102, 255), (208, 140, 255),
+                         (150, 150, 162), (232, 232, 240), (18, 14, 26),
+                         (120, 220, 150), (255, 184, 76), (255, 86, 110),
+                         (120, 80, 200), (205, 140, 255))),
+    "blue": _palette(((35, 91, 155), (52, 130, 205), (69, 155, 255), (125, 190, 255),
+                       (145, 158, 174), (232, 240, 248), (8, 22, 36),
+                       (107, 214, 158), (255, 187, 79), (255, 91, 109),
+                       (40, 105, 190), (113, 190, 255))),
+    "green": _palette(((31, 112, 78), (42, 157, 103), (55, 201, 132), (111, 231, 169),
+                        (142, 164, 153), (230, 242, 235), (7, 30, 20),
+                        (83, 219, 139), (255, 190, 76), (255, 91, 105),
+                        (33, 126, 86), (102, 225, 159))),
+    "amber": _palette(((145, 87, 20), (199, 123, 29), (240, 157, 43), (255, 199, 104),
+                        (165, 154, 139), (244, 237, 226), (35, 22, 7),
+                        (100, 210, 137), (255, 184, 76), (255, 83, 98),
+                        (166, 96, 20), (255, 190, 76))),
+    "mono": _palette(((104, 104, 110), (145, 145, 152), (190, 190, 198), (226, 226, 232),
+                       (145, 145, 152), (232, 232, 236), (18, 18, 20),
+                       (199, 224, 205), (235, 213, 174), (239, 174, 181),
+                       (112, 112, 118), (218, 218, 224))),
+})
+
+MAX_THEME_BYTES = 16 * 1024
+_CUSTOM_FIELDS = MappingProxyType({
+    "accent": MappingProxyType({"deep": "accent_deep", "mid": "accent_mid",
+                                "primary": "accent_primary", "bright": "accent_bright"}),
+    "text": MappingProxyType({"muted": "text_muted", "normal": "text_normal",
+                              "on_accent": "text_on_accent"}),
+    "semantic": MappingProxyType({"ok": "semantic_ok", "warn": "semantic_warn",
+                                  "danger": "semantic_danger"}),
+    "gradient": MappingProxyType({"from": "gradient_from", "to": "gradient_to"}),
+})
+_HEX = re.compile(r"^#[0-9a-fA-F]{6}$")
+
+
+def _read_custom(path):
+    """Read one bounded local JSON object; return None for every failure mode."""
+    try:
+        path = os.path.expanduser(os.path.expandvars(path))
+        if os.path.getsize(path) > MAX_THEME_BYTES:
+            return None
+        with open(path, "rb") as handle:
+            raw = handle.read(MAX_THEME_BYTES + 1)
+        if len(raw) > MAX_THEME_BYTES:
+            return None
+        value = json.loads(raw.decode("utf-8"))
+        return value if isinstance(value, dict) else None
+    except (OSError, UnicodeError, ValueError, TypeError, RecursionError):
+        return None
+
+
+def _resolve_palette(theme_name=None, custom_path=None):
+    """Return (effective theme name, palette), falling back wholly to violet."""
+    violet = BUILTIN_PALETTES["violet"]
+    name = str(theme_name or "violet").strip().lower()
+    if name != "custom":
+        return (name, BUILTIN_PALETTES[name]) if name in BUILTIN_PALETTES else ("violet", violet)
+    path = custom_path or os.environ.get("CODEARBITER_THEME_FILE") or os.path.join(
+        "~", ".codearbiter", "statusline-theme.json")
+    data = _read_custom(path)
+    if data is None:
+        return "violet", violet
+    updates = {}
+    for group_name, fields in _CUSTOM_FIELDS.items():
+        group = data.get(group_name)
+        if not isinstance(group, dict):
+            continue
+        for key, field_name in fields.items():
+            value = group.get(key)
+            if isinstance(value, str) and _HEX.fullmatch(value):
+                updates[field_name] = RGB(int(value[1:3], 16), int(value[3:5], 16), int(value[5:7], 16))
+    return "custom", replace(violet, **updates)
+
+
+def resolve_palette(theme_name=None, custom_path=None):
+    """Resolve a built-in or partial custom palette, always falling back to violet."""
+    return _resolve_palette(theme_name, custom_path)[1]
+
+
+def fg(r, g, b):
+    return f"\033[38;2;{r};{g};{b}m"
+
+
+RESET, BOLD, DIM, ITAL = "\033[0m", "\033[1m", "\033[2m", "\033[3m"
+
+
+def bg(r, g, b):
+    return f"\033[48;2;{r};{g};{b}m"
+
+# neon-violet ramp (dark -> bright) — used for the box sheen and accents
+ACTIVE_THEME_NAME = str(os.environ.get("CODEARBITER_THEME") or "violet").strip().lower()
+if ACTIVE_THEME_NAME not in (*BUILTIN_PALETTES, "custom"):
+    ACTIVE_THEME_NAME = "violet"
+ACTIVE_PALETTE = (BUILTIN_PALETTES["violet"] if ACTIVE_THEME_NAME == "custom"
+                  else resolve_palette(ACTIVE_THEME_NAME))
+
+
+def _project_palette(name, palette):
+    global ACTIVE_THEME_NAME, ACTIVE_PALETTE
+    global V0, V1, V2, V3, GREY, WHITE, OK, WARN, DANGER, PILL_FG
+    ACTIVE_THEME_NAME, ACTIVE_PALETTE = name, palette
+    V0 = fg(*palette.accent_deep)
+    V1 = fg(*palette.accent_mid)
+    V2 = fg(*palette.accent_primary)
+    V3 = fg(*palette.accent_bright)
+    GREY = fg(*palette.text_muted)
+    WHITE = fg(*palette.text_normal)
+    OK = fg(*palette.semantic_ok)
+    WARN = fg(*palette.semantic_warn)
+    DANGER = fg(*palette.semantic_danger)
+    PILL_FG = fg(*palette.text_on_accent)
+
+
+def activate_palette(theme_name=None, custom_path=None):
+    """Resolve and project the process palette at render time.
+
+    Custom themes may touch the filesystem, so callers must invoke this from a
+    runtime path rather than relying on module import. Repeated calls re-resolve
+    the current environment deterministically.
+    """
+    name = str(theme_name if theme_name is not None else
+               (os.environ.get("CODEARBITER_THEME") or "violet")).strip().lower()
+    if name not in (*BUILTIN_PALETTES, "custom"):
+        name = "violet"
+    effective_name, palette = _resolve_palette(name, custom_path)
+    _project_palette(effective_name, palette)
+    return palette
+
+
+# Built-ins are pure data and retain legacy import-time exports. Custom stays
+# violet until the explicit render-time activation above.
+_project_palette(ACTIVE_THEME_NAME, ACTIVE_PALETTE)
+
+# native-safe glyphs only
+TL, TR, BL, BR = "╭", "╮", "╰", "╯"
+H, V, LT, RT = "─", "│", "├", "┤"
+TD, TU = "┬", "┴"                 # tee down / up (column joins)
+DOTH = "┄"                        # dotted horizontal (section separators)
+DOT = "●"
+SUBDOT = "◦"
+ELL = "…"
+BFULL, BEMPTY = "█", "░"
+DN, UP = "↓", "↑"
+ARR = "▸"
+BOLT = "↯"
+SPARK = "▁▂▃▄▅▆▇█"
+
+ANSI = re.compile(r"\033\[[0-9;]*m")
+
+# Host-controlled strings (a model display name, a subagent's derived label)
+# reach the render path verbatim. Neither the host payload nor a subagent
+# transcript is a trusted source, so any C0 control byte or OSC/CSI escape
+# sequence embedded in one is terminal-escape injection into the user's
+# prompt line — strip it before the string is ever composed into a row.
+_OSC_RE = re.compile(r"\033\][^\007\033]*(?:\007|\033\\)?")
+_CSI_RE = re.compile(r"\033\[[0-?]*[ -/]*[@-~]?")
+_C0_RE = re.compile(r"[\000-\037]")
+
+
+def strip_control(s):
+    """Strip OSC/CSI escape sequences and any remaining C0 control byte
+    (0x00-0x1f) from a host- or transcript-derived string. Non-string input
+    passes through unchanged; this must never raise."""
+    if not isinstance(s, str):
+        return s
+    s = _OSC_RE.sub("", s)
+    s = _CSI_RE.sub("", s)
+    return _C0_RE.sub("", s)
+
+
+def _cw(ch):
+    """Terminal column width of one character: 0 for a combining mark, 2 for an
+    East-Asian Wide/Fullwidth glyph (CJK, many emoji), 1 otherwise. Ambiguous-
+    width glyphs (box-drawing, blocks, arrows used in this bar) render as 1 in a
+    non-CJK terminal, so they stay 1 — only genuinely wide content counts as 2."""
+    if unicodedata.combining(ch):
+        return 0
+    return 2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1
+
+
+def vlen(s):
+    """Visible terminal-column width of s, ignoring ANSI codes and counting wide
+    glyphs as 2 columns — so the box never overflows on CJK/emoji content."""
+    return sum(_cw(c) for c in ANSI.sub("", s))
+
+
+def clip(s, w):
+    """Truncate a (possibly ANSI-colored) string to <= w visible columns,
+    preserving color codes and appending an ellipsis + RESET when cut."""
+    if w <= 0:
+        return ""
+    if vlen(s) <= w:
+        return s
+    out, vis, i, n = [], 0, 0, len(s)
+    limit = w - 1   # leave one column for the ellipsis
+    while i < n:
+        m = ANSI.match(s, i)
+        if m:
+            out.append(m.group(0))
+            i = m.end()
+            continue
+        cw = _cw(s[i])
+        if vis + cw > limit:   # a wide glyph that would cross the limit stops here
+            break
+        out.append(s[i])
+        vis += cw
+        i += 1
+    return "".join(out) + ELL + RESET
+
+
+def pad(s, w):
+    """Return s at exactly w visible columns: clip if over, space-pad if under."""
+    v = vlen(s)
+    if v > w:
+        return clip(s, w)
+    return s + " " * (w - v)
+
+
+def gradient_h(text, width, c_from=None, c_to=None):
+    """Per-character violet sheen across `width` columns (dark->bright)."""
+    c_from = ACTIVE_PALETTE.gradient_from if c_from is None else c_from
+    c_to = ACTIVE_PALETTE.gradient_to if c_to is None else c_to
+    out = []
+    n = max(1, width - 1)
+    for i, ch in enumerate(text):
+        t = i / n
+        r = int(c_from[0] + (c_to[0] - c_from[0]) * t)
+        g = int(c_from[1] + (c_to[1] - c_from[1]) * t)
+        b = int(c_from[2] + (c_to[2] - c_from[2]) * t)
+        out.append(f"\033[38;2;{r};{g};{b}m{ch}")
+    return "".join(out) + RESET
+
+
+def box_gradient_h(text, width):
+    """Header-border sheen, retaining the original violet bytes by default."""
+    if ACTIVE_THEME_NAME == "violet":
+        return gradient_h(text, width, (90, 60, 150), (170, 110, 240))
+    return gradient_h(text, width)

package/plugins/ca-pi/hooks/_durabilitylib.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+# codeArbiter — durable-vs-ephemeral install-root detection.
+#
+# WHY THIS EXISTS (found in-session on 2026-07-25, after it broke the
+# maintainer's statusline three times in one day):
+#
+# A plugin cannot own a statusLine and ${CLAUDE_PLUGIN_ROOT} is NOT expanded
+# inside settings.json, so codeArbiter has to write an ABSOLUTE, version-pinned
+# renderer path into the user's GLOBAL ~/.claude/settings.json — and re-point it
+# on every SessionStart so a plugin update does not leave the old version wired.
+# That refresh had no notion of a root that will not survive the session. When a
+# session starts inside a git worktree (subagents routinely run in
+# <repo>/.claude/worktrees/<id>/), the plugin root IS the worktree's plugins/ca,
+# and the heal happily pinned the user's global config there:
+#
+#   "...\.claude\worktrees\wf_58ee3fa6-de1-8\plugins\ca\hooks\statusline.py"
+#
+# The worktree is then pruned — that is what worktrees are FOR — and the
+# statusline renders nothing until someone notices and re-runs /ca:statusline.
+#
+# This module answers exactly one question, for callers about to write a path
+# into a long-lived config: may this path be trusted to still be there?
+#
+# TWO INDEPENDENT SIGNALS, because each alone has a blind spot:
+#   1. LEXICAL (has_worktree_segment) — a `worktrees` or `*-worktrees` path
+#      segment. Free, no I/O at all, works even when the checkout is already
+#      gone. Covers the confirmed `.claude/worktrees/<id>/` case and the
+#      `../.codearbiter-worktrees/<slug>` layout the using-git-worktrees skill
+#      creates.
+#   2. GIT (in_linked_worktree) — the path lives in a LINKED worktree, read
+#      straight off git's own on-disk marker. Generalizes to a worktree parked
+#      anywhere under any name, which the lexical rule cannot see.
+#
+# NO SUBPROCESS, DELIBERATELY. This predicate is consulted on EVERY SessionStart,
+# before the dormant gate, in every repo on the machine. An earlier draft shelled
+# out to `git rev-parse --git-dir --git-common-dir`; that probe fails by design
+# in the ordinary plugin-cache install (which is not a git repository at all), so
+# it bought nothing in the common case while charging every session a process
+# spawn plus a timeout hazard. Git writes the answer to disk anyway: a LINKED
+# worktree's `.git` is a FILE reading `gitdir: <common>/.git/worktrees/<name>`,
+# while a normal checkout's `.git` is a DIRECTORY. A handful of stat() calls
+# gives the same answer, with no dependency on git being installed at all.
+#
+# FAILURE DIRECTION IS "DURABLE", DELIBERATELY. Anything unreadable, unparseable
+# or absent reads as durable. Reading uncertainty as "ephemeral" would silently
+# disable the self-heal for users whose installs are perfectly fine — a far worse
+# outcome than the residual it protects against.
+#
+# The lexical rule is deliberately a little broad (any `worktrees` segment, not
+# only one under `.claude`). The asymmetry justifies it: a false positive costs
+# an un-refreshed pin the user fixes with one explicit /ca:statusline run, while
+# a false negative corrupts their global config.
+#
+# Design principles (mirroring _gitexec.py / _gitlib.py):
+#   - Stdlib only; no third-party imports ever (ADR-0004).
+#   - Zero side effects at import time.
+#   - NEVER raises. This sits on the SessionStart path; it must not be the thing
+#     that crashes startup, whatever it is handed.
+#
+# Public API:
+#   has_worktree_segment(path) -> bool   lexical signal, no I/O
+#   in_linked_worktree(path) -> bool     git's on-disk marker, no subprocess
+#   is_ephemeral_path(path) -> bool      either signal
+
+import os
+import re
+
+# The walk from a plugin root to the filesystem root is a handful of levels; the
+# bound exists only so a pathological path can never spin this on the hot path.
+MAX_ANCESTOR_WALK = 64
+
+# A `.git` FILE is at most a line or two. Reading a bounded prefix means a
+# directory entry that is unexpectedly enormous cannot stall startup.
+GITFILE_READ_BYTES = 4096
+
+_SEP_RE = re.compile(r"[\\/]+")
+
+
+def _segments(path):
+    """Path segments of `path`, split on BOTH separators (a Windows path may be
+    read from a POSIX host and vice versa). Empty tuple on any non-string."""
+    if not isinstance(path, str) or not path:
+        return ()
+    return tuple(part for part in _SEP_RE.split(path) if part)
+
+
+def has_worktree_segment(path):
+    """True iff `path` contains a segment named `worktrees` or `*-worktrees`
+    (case-insensitive). Purely lexical — no filesystem access, no subprocess.
+
+    Matches `<repo>/.claude/worktrees/<id>/...` (Claude Code's own subagent
+    worktrees) and `../.codearbiter-worktrees/<slug>/...` (the
+    using-git-worktrees skill). Compares whole SEGMENTS, never substrings: a
+    directory literally called `worktrees-archive` is a name of its own, not a
+    container of worktrees, and matching it would decline to heal a perfectly
+    durable root."""
+    for part in _segments(path):
+        low = part.lower()
+        if low == "worktrees" or low.endswith("-worktrees"):
+            return True
+    return False
+
+
+def _ancestors(path):
+    """`path` (or its directory, if it names a file) and every parent above it,
+    nearest first, bounded by MAX_ANCESTOR_WALK. Yields nothing for junk."""
+    if not isinstance(path, str) or not path:
+        return
+    try:
+        cur = os.path.abspath(path)
+        if not os.path.isdir(cur):
+            cur = os.path.dirname(cur)
+    except Exception:  # noqa: BLE001 — a probe must never crash its caller
+        return
+    for _ in range(MAX_ANCESTOR_WALK):
+        if not cur:
+            return
+        yield cur
+        parent = os.path.dirname(cur)
+        if parent == cur:  # filesystem root: dirname is a fixed point
+            return
+        cur = parent
+
+
+def _gitfile_points_at_worktree(gitfile):
+    """True iff the `.git` FILE at `gitfile` is a LINKED WORKTREE pointer.
+
+    Git writes `gitdir: <path>` into `.git` for both linked worktrees and
+    submodules, and the two must not be confused: a worktree points into
+    `<common>/.git/worktrees/<name>` (disposable), a submodule into
+    `<super>/.git/modules/<name>` (an ordinary long-lived checkout). The
+    `worktrees` segment in the TARGET is what separates them."""
+    try:
+        with open(gitfile, "rb") as f:
+            head = f.read(GITFILE_READ_BYTES)
+        lines = head.decode("utf-8", "replace").splitlines()
+        if not lines:
+            return False
+        first = lines[0].strip()
+        if not first.lower().startswith("gitdir:"):
+            return False
+        # split(":", 1) — the FIRST colon only, so a Windows target like
+        # `C:/Users/...` survives intact.
+        return has_worktree_segment(first.split(":", 1)[1].strip())
+    except Exception:  # noqa: BLE001 — unreadable reads as durable, by design
+        return False
+
+
+def in_linked_worktree(path):
+    """True iff `path` sits inside a LINKED git worktree.
+
+    Walks up from `path` to the first `.git` it meets — the boundary of the
+    repository the path actually belongs to — and decides there:
+      - `.git` is a DIRECTORY -> the main worktree. Durable. Stop.
+      - `.git` is a FILE      -> a linked worktree or a submodule; the pointer's
+                                 target says which. Stop either way.
+      - no `.git` at any level -> not in a repository at all (the ordinary
+                                 plugin-cache install). Durable.
+    Stopping at the NEAREST boundary is load-bearing: a real checkout nested
+    below some unrelated worktree marker must read as durable.
+
+    `path` may name a file (its directory is walked) or a directory, and need
+    not exist. Never raises."""
+    try:
+        for cur in _ancestors(path):
+            gitpath = os.path.join(cur, ".git")
+            if os.path.isdir(gitpath):
+                return False
+            if os.path.isfile(gitpath):
+                return _gitfile_points_at_worktree(gitpath)
+        return False
+    except Exception:  # noqa: BLE001 — a probe must never crash its caller
+        return False
+
+
+def is_ephemeral_path(path):
+    """True iff `path` must NOT be pinned into a long-lived global config.
+
+    Checks the free lexical signal FIRST and short-circuits on it, so the
+    confirmed production case is decided with zero I/O. Never raises."""
+    try:
+        if has_worktree_segment(path):
+            return True
+        return in_linked_worktree(path)
+    except Exception:  # noqa: BLE001 — a probe must never crash its caller
+        return False

package/plugins/ca-pi/hooks/_entrylib.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+# codeArbiter — shared entry-point dispatch helper (jscpd dedup, #320/#334 item 2).
+#
+# Every hook/tool entry file (doctor.py, pre-edit.py, pre-write.py, pre-read.py,
+# git-enforce.py, post-write-edit.py, migration-pass.py, security-pass.py,
+# statusline.py, boardsync.py, metrics.py, preview.py, taskwrite.py, babysit.py,
+# init-codearbiter.py, ...) carries the identically-shaped `run(host, argv=None)`
+# body: wire the process-cached Host live (#257, ADR-0011) via a `set_host`
+# callable BEFORE `main` runs, invoke `main` (with or without `argv`), and either
+# discard its return (always `return 0`) or propagate it as the exit code —
+# jscpd flags this near-duplicate boilerplate across ~15 files. This module
+# hoists the shared BODY only; each caller keeps its own `run(host, argv=None)`
+# signature/docstring and passes its own `main`/`set_host` callables plus the
+# two booleans that capture its file's variant behavior (verbatim-equivalent —
+# behavior is unchanged, not "improved").
+#
+# Zero import-time side effects; pure function; no filesystem/git access.
+#
+# Public API:
+#   dispatch(host, argv, main_fn, set_host_fn, pass_argv, propagate_result) -> int
+#       Wire `host` via set_host_fn(host), call main_fn() or main_fn(argv)
+#       (per pass_argv), then return that result or 0 (per propagate_result).
+
+def dispatch(host, argv, main_fn, set_host_fn, pass_argv, propagate_result):
+    """Shared body of an entry file's `run(host, argv=None)`.
+
+    set_host_fn(host)     -- primes the process-cached Host (#257) BEFORE
+                              main_fn runs, so any get_host() call downstream
+                              resolves to the SAME instance the caller passed
+                              here (no second hostapi.load_host()).
+    main_fn()/main_fn(argv) -- per `pass_argv`: some entry files' main() takes
+                              no arguments, others take `argv=None`.
+    return result or 0    -- per `propagate_result`: some callers discard
+                              main_fn's return value (always exit 0, matching
+                              the old bare `main()` guard); others propagate
+                              main_fn's return value as the exit code
+                              (matching the old `sys.exit(main())` guard).
+    """
+    set_host_fn(host)
+    result = main_fn(argv) if pass_argv else main_fn()
+    return result if propagate_result else 0