@clawpump/claw-agent 0.1.5 → 0.1.6

package/agent/tools/skills_hub.py

@@ -301,6 +301,7 @@ class GitHubAuth:
             result = subprocess.run(
                 ["gh", "auth", "token"],
                 capture_output=True, text=True, timeout=5,
+                stdin=subprocess.DEVNULL,
             )
             if result.returncode == 0 and result.stdout.strip():
                 return result.stdout.strip()
@@ -550,11 +551,8 @@ class GitHubSource(SkillSource):
             return [SkillMeta(**s) for s in cached]
 
         url = f"https://api.github.com/repos/{repo}/contents/{path.rstrip('/')}"
-        try:
-            resp = httpx.get(url, headers=self.auth.get_headers(), timeout=15, follow_redirects=True)
-            if resp.status_code != 200:
-                return []
-        except httpx.HTTPError:
+        resp = self._github_get(url)
+        if resp is None or resp.status_code != 200:
             return []
 
         entries = resp.json()
@@ -639,15 +637,98 @@ class GitHubSource(SkillSource):
 
     def _check_rate_limit_response(self, resp: "httpx.Response") -> None:
         """Flag the instance as rate-limited when GitHub returns 403 + exhausted quota."""
-        if resp.status_code == 403:
+        if resp.status_code in (403, 429):
             remaining = resp.headers.get("X-RateLimit-Remaining", "")
-            if remaining == "0":
+            if remaining == "0" or resp.status_code == 429:
                 self._rate_limited = True
                 logger.warning(
                     "GitHub API rate limit exhausted (unauthenticated: 60 req/hr). "
                     "Set GITHUB_TOKEN or install the gh CLI to raise the limit to 5,000/hr."
                 )
 
+    def _github_get(
+        self,
+        url: str,
+        *,
+        params: Optional[Dict] = None,
+        headers: Optional[Dict] = None,
+        timeout: float = 15.0,
+        max_retries: int = 3,
+    ) -> Optional["httpx.Response"]:
+        """GET against the GitHub API with retry/backoff on transient failures.
+
+        Returns the final ``httpx.Response`` (caller inspects status) or
+        ``None`` when every attempt raised a transport error.
+
+        Retries on:
+          - 403/429 with ``X-RateLimit-Remaining: 0`` — waits until the
+            reset time (capped) when the header is present, else exponential
+            backoff. This is the all-GitHub-tap-collapse case: a single
+            shared rate limit zeroes github + claude-marketplace + well-known
+            at once during the index build.
+          - 5xx and connection/timeout errors — exponential backoff.
+
+        On terminal rate-limit exhaustion the instance is flagged via
+        ``_check_rate_limit_response`` so the build can fail loud instead of
+        silently shipping an index with the GitHub sources dropped to zero.
+        """
+        hdrs = headers if headers is not None else self.auth.get_headers()
+        backoff = 1.0
+        last_resp: Optional["httpx.Response"] = None
+        for attempt in range(max_retries):
+            try:
+                resp = httpx.get(
+                    url, params=params, headers=hdrs,
+                    timeout=timeout, follow_redirects=True,
+                )
+            except httpx.HTTPError as e:
+                logger.debug("GitHub GET %s failed (attempt %d/%d): %s",
+                             url, attempt + 1, max_retries, e)
+                if attempt < max_retries - 1:
+                    time.sleep(backoff)
+                    backoff = min(backoff * 2, 30.0)
+                    continue
+                return None
+
+            last_resp = resp
+            if resp.status_code == 200:
+                return resp
+
+            # Rate-limited: honor the reset header when present, else back off.
+            if resp.status_code in (403, 429):
+                remaining = resp.headers.get("X-RateLimit-Remaining", "")
+                is_rl = remaining == "0" or resp.status_code == 429
+                if is_rl and attempt < max_retries - 1:
+                    wait = backoff
+                    reset = resp.headers.get("X-RateLimit-Reset", "")
+                    retry_after = resp.headers.get("Retry-After", "")
+                    if retry_after.isdigit():
+                        wait = min(float(retry_after), 60.0)
+                    elif reset.isdigit():
+                        delta = float(reset) - time.time()
+                        if 0 < delta <= 60.0:
+                            wait = delta
+                    logger.debug(
+                        "GitHub rate limited on %s, waiting %.1fs (attempt %d/%d)",
+                        url, wait, attempt + 1, max_retries,
+                    )
+                    time.sleep(wait)
+                    backoff = min(backoff * 2, 30.0)
+                    continue
+                # Out of retries (or not a rate-limit 403) — flag and return.
+                self._check_rate_limit_response(resp)
+                return resp
+
+            # 5xx — retry; 4xx (other than rate limit) — return immediately.
+            if 500 <= resp.status_code < 600 and attempt < max_retries - 1:
+                time.sleep(backoff)
+                backoff = min(backoff * 2, 30.0)
+                continue
+            return resp
+
+        return last_resp
+
+
     def _download_directory(self, repo: str, path: str) -> Dict[str, str]:
         """Recursively download all text files from a GitHub directory.
 
@@ -768,17 +849,12 @@ class GitHubSource(SkillSource):
     def _fetch_file_content(self, repo: str, path: str) -> Optional[str]:
         """Fetch a single file's content from GitHub."""
         url = f"https://api.github.com/repos/{repo}/contents/{path}"
-        try:
-            resp = httpx.get(
-                url,
-                headers={**self.auth.get_headers(), "Accept": "application/vnd.github.v3.raw"},
-                timeout=15, follow_redirects=True,
-            )
-            if resp.status_code == 200:
-                return resp.text
-            self._check_rate_limit_response(resp)
-        except httpx.HTTPError as e:
-            logger.debug("GitHub contents API fetch failed: %s", e)
+        resp = self._github_get(
+            url,
+            headers={**self.auth.get_headers(), "Accept": "application/vnd.github.v3.raw"},
+        )
+        if resp is not None and resp.status_code == 200:
+            return resp.text
         return None
 
     def _get_skillsh_groupings(self, repo: str) -> Optional[Dict[str, str]]:
@@ -1870,6 +1946,12 @@ class ClawHubSource(SkillSource):
 
     BASE_URL = "https://clawhub.ai/api/v1"
 
+    # Wall-clock budget for a full catalog walk. ClawHub has 50k+ skills and
+    # the walk is sequential (~250 requests, each under per-request
+    # timeout=30 so nothing errors), so an unbounded walk can block for
+    # minutes. Bound it so a slow/large catalog cannot hang the caller.
+    CATALOG_WALK_BUDGET_SECONDS = 12
+
     def source_id(self) -> str:
         return "clawhub"
 
@@ -2037,12 +2119,13 @@ class ClawHubSource(SkillSource):
             if results:
                 return results
         else:
-            # Empty query: route through the paginating catalog walker so the
-            # full ClawHub catalog (20k+ skills) lands in the index. The
-            # single-request listing path below caps at one page (200 items)
-            # regardless of `limit`, which silently truncates the public
-            # skills index. The catalog walker follows `nextCursor`.
-            catalog = self._load_catalog_index()
+            # Empty query: route through the paginating catalog walker. When
+            # the full catalog is already disk-cached this returns it whole and
+            # the caller paginates client-side. On a cold cache, bound the walk
+            # to `limit` so a browse command renders its first page without
+            # walking the entire 50k+ catalog (max_items=0 → unbounded, used
+            # only by the offline index builder via search("", limit=0)).
+            catalog = self._load_catalog_index(max_items=limit if limit > 0 else 0)
             if catalog:
                 return self._dedupe_results(catalog)[:limit] if limit > 0 else self._dedupe_results(catalog)
 
@@ -2167,7 +2250,21 @@ class ClawHubSource(SkillSource):
         _write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in results])
         return results
 
-    def _load_catalog_index(self) -> List[SkillMeta]:
+    def _load_catalog_index(self, max_items: int = 0) -> List[SkillMeta]:
+        """Walk the ClawHub catalog via cursor pagination.
+
+        ``max_items`` bounds the walk: once at least that many distinct skills
+        have been gathered the walk stops early. This is what browse's
+        cold-start fallback wants — it only renders one page, so walking the
+        entire 50k+ catalog just to slice off the first N is pure waste.
+        ``max_items=0`` (the default, used by the offline index builder) means
+        walk to exhaustion.
+
+        Caching: only a *complete* catalog (cursor exhausted or page cap) is
+        written to the shared ``clawhub_catalog_v1`` cache. A walk truncated by
+        ``max_items`` OR the wall-clock budget is partial, so caching it would
+        poison the full-catalog cache with an incomplete slice.
+        """
         cache_key = "clawhub_catalog_v1"
         cached = _read_index_cache(cache_key)
         if cached is not None:
@@ -2182,8 +2279,22 @@ class ClawHubSource(SkillSource):
         # terminates well before this on `nextCursor` going None — the cap is
         # a safety rail against an infinite-cursor loop.
         max_pages = 750
+        # Wall-clock budget is for interactive browse (max_items > 0) only.
+        # The offline index builder passes max_items=0 and must walk the full
+        # catalog — a 12s cap there ships ~3k skills and trips the deploy
+        # health floor (20k).
+        deadline = (
+            time.monotonic() + self.CATALOG_WALK_BUDGET_SECONDS
+            if max_items > 0
+            else None
+        )
+        hit_deadline = False
+        hit_max_items = False
 
         for _ in range(max_pages):
+            if deadline is not None and time.monotonic() > deadline:
+                hit_deadline = True
+                break
             params: Dict[str, Any] = {"limit": 200}
             if cursor:
                 params["cursor"] = cursor
@@ -2221,7 +2332,19 @@ class ClawHubSource(SkillSource):
             if not isinstance(cursor, str) or not cursor:
                 break
 
-        _write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in results])
+            # Browse's cold-start fallback only renders one page, so stop as
+            # soon as we have enough to satisfy the caller's bound. The index
+            # builder passes max_items=0 (unbounded) and walks to exhaustion.
+            if max_items > 0 and len(results) >= max_items:
+                hit_max_items = True
+                break
+
+        # Only cache a walk that reached a natural stop (cursor exhausted or
+        # page cap). A walk truncated by the wall-clock budget OR by max_items
+        # is partial, so writing it would poison the shared full-catalog cache
+        # with incomplete data.
+        if not hit_deadline and not hit_max_items:
+            _write_index_cache(cache_key, [_skill_meta_to_dict(s) for s in results])
         return results
 
     def _get_json(self, url: str, timeout: int = 20) -> Optional[Any]:
@@ -2373,10 +2496,19 @@ class ClaudeMarketplaceSource(SkillSource):
 
     def __init__(self, auth: GitHubAuth):
         self.auth = auth
+        # Persistent GitHubSource so rate-limit state survives across the
+        # marketplace-index fetch + per-skill inspect calls and can be
+        # surfaced to the index builder (see is_rate_limited).
+        self.github = GitHubSource(auth=auth)
 
     def source_id(self) -> str:
         return "claude-marketplace"
 
+    @property
+    def is_rate_limited(self) -> bool:
+        """Whether the underlying GitHub API hit a rate limit during the crawl."""
+        return self.github.is_rate_limited
+
     def trust_level_for(self, identifier: str) -> str:
         parts = identifier.split("/", 2)
         if len(parts) >= 2:
@@ -2415,15 +2547,13 @@ class ClaudeMarketplaceSource(SkillSource):
 
     def fetch(self, identifier: str) -> Optional[SkillBundle]:
         # Delegate to GitHub Contents API since marketplace skills live in GitHub repos
-        gh = GitHubSource(auth=self.auth)
-        bundle = gh.fetch(identifier)
+        bundle = self.github.fetch(identifier)
         if bundle:
             bundle.source = "claude-marketplace"
         return bundle
 
     def inspect(self, identifier: str) -> Optional[SkillMeta]:
-        gh = GitHubSource(auth=self.auth)
-        meta = gh.inspect(identifier)
+        meta = self.github.inspect(identifier)
         if meta:
             meta.source = "claude-marketplace"
             meta.trust_level = self.trust_level_for(identifier)
@@ -2437,16 +2567,15 @@ class ClaudeMarketplaceSource(SkillSource):
             return cached
 
         url = f"https://api.github.com/repos/{repo}/contents/.claude-plugin/marketplace.json"
+        resp = self.github._github_get(
+            url,
+            headers={**self.auth.get_headers(), "Accept": "application/vnd.github.v3.raw"},
+        )
+        if resp is None or resp.status_code != 200:
+            return []
         try:
-            resp = httpx.get(
-                url,
-                headers={**self.auth.get_headers(), "Accept": "application/vnd.github.v3.raw"},
-                timeout=15,
-            )
-            if resp.status_code != 200:
-                return []
             data = json.loads(resp.text)
-        except (httpx.HTTPError, json.JSONDecodeError):
+        except json.JSONDecodeError:
             return []
 
         plugins = data.get("plugins", [])
@@ -3692,13 +3821,20 @@ def parallel_search_sources(
     if not active:
         return all_results, source_counts, timed_out_ids
 
-    with ThreadPoolExecutor(max_workers=min(len(active), 8)) as pool:
-        futures = {}
-        for src in active:
-            lim = per_source_limits.get(src.source_id(), 50)
-            fut = pool.submit(_search_one_source, src, query, lim)
-            futures[fut] = src.source_id()
+    # NOTE: a `with ThreadPoolExecutor(...) as pool` block calls
+    # ``shutdown(wait=True)`` on exit, which blocks until every submitted
+    # worker finishes — so a single slow source (e.g. ClawHub) keeps the
+    # caller blocked for minutes and renders ``overall_timeout`` a no-op.
+    # Manage the executor manually and shut it down with ``wait=False`` so
+    # the timeout is actually honoured.
+    pool = ThreadPoolExecutor(max_workers=min(len(active), 8))
+    futures = {}
+    for src in active:
+        lim = per_source_limits.get(src.source_id(), 50)
+        fut = pool.submit(_search_one_source, src, query, lim)
+        futures[fut] = src.source_id()
 
+    try:
         try:
             for fut in as_completed(futures, timeout=overall_timeout):
                 try:
@@ -3718,6 +3854,10 @@ def parallel_search_sources(
                     "Skills browse timed out waiting for: %s",
                     ", ".join(timed_out_ids),
                 )
+    finally:
+        # wait=False so a slow source cannot block the caller's return;
+        # cancel_futures drops not-yet-started work.
+        pool.shutdown(wait=False, cancel_futures=True)
 
     return all_results, source_counts, timed_out_ids
 

package/agent/tools/skills_sync.py

@@ -30,7 +30,7 @@ from datetime import datetime, timezone
 from pathlib import Path, PurePosixPath
 from hermes_constants import get_bundled_skills_dir, get_hermes_home, get_optional_skills_dir
 from agent.skill_utils import is_excluded_skill_path
-from typing import Dict, List, Tuple
+from typing import Dict, List, Optional, Tuple
 from utils import atomic_replace
 
 logger = logging.getLogger(__name__)
@@ -506,6 +506,24 @@ def sync_skills(quiet: bool = False) -> dict:
         dest = _compute_relative_dest(skill_src, bundled_dir)
         bundled_hash = _dir_hash(skill_src)
 
+        # Recover an orphaned backup before classifying. If a previous
+        # update was interrupted between moving dest aside and copying the
+        # new version in, the user's only copy sits in ``dest.bak`` while
+        # dest is gone — without this, the "in manifest but not on disk"
+        # branch below misreads the skill as user-deleted and it silently
+        # vanishes from discovery.
+        _orphan = dest.with_suffix(".bak")
+        if _orphan.exists() and not dest.exists():
+            try:
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                shutil.move(str(_orphan), str(dest))
+                logger.info("Recovered orphaned skill backup: %s", _orphan)
+            except (OSError, IOError):
+                logger.warning(
+                    "Could not recover orphaned skill backup %s", _orphan,
+                    exc_info=True,
+                )
+
         if skill_name not in manifest:
             # ── New skill — never offered before ──
             try:
@@ -557,7 +575,7 @@ def sync_skills(quiet: bool = False) -> dict:
                     skipped += 1
                 continue
 
-            if user_hash != origin_hash:
+            if _is_tracked_user_modification(origin_hash, user_hash):
                 # User modified this skill — don't overwrite their changes
                 user_modified.append(skill_name)
                 if not quiet:
@@ -569,6 +587,12 @@ def sync_skills(quiet: bool = False) -> dict:
                 try:
                     # Move old copy to a backup so we can restore on failure
                     backup = dest.with_suffix(".bak")
+                    # A stale backup left by an earlier failure would make
+                    # shutil.move() nest dest *inside* it (or fail outright)
+                    # and would poison the restore path below. The current
+                    # dest is the authoritative copy — clear the leftover.
+                    if backup.exists():
+                        _rmtree_writable(backup)
                     shutil.move(str(dest), str(backup))
                     try:
                         shutil.copytree(skill_src, dest)
@@ -582,9 +606,20 @@ def sync_skills(quiet: bool = False) -> dict:
                         except (OSError, IOError):
                             logger.debug("Could not remove backup %s", backup, exc_info=True)
                     except (OSError, IOError):
-                        # Restore from backup
-                        if backup.exists() and not dest.exists():
-                            shutil.move(str(backup), str(dest))
+                        # Restore from backup. A partially-written dest must
+                        # not shadow the user's copy or block the restore —
+                        # clear it first, then move the backup home.
+                        if backup.exists():
+                            if dest.exists():
+                                try:
+                                    _rmtree_writable(dest)
+                                except (OSError, IOError):
+                                    logger.warning(
+                                        "Could not clear partial copy %s during restore",
+                                        dest, exc_info=True,
+                                    )
+                            if not dest.exists():
+                                shutil.move(str(backup), str(dest))
                         raise
                 except (OSError, IOError) as e:
                     if not quiet:
@@ -636,6 +671,31 @@ def _rmtree_writable(path: Path) -> None:
     parent directory, so the retry handler makes the failing path **and its
     parent** writable before re-attempting.  See #34860, #34972.
     """
+    # Defense in depth (#48200): refuse to rmtree anything outside
+    # ``HERMES_HOME/skills/`` to prevent the catastrophic wipe of
+    # ``~/.hermes/`` (``.env``, ``MEMORY.md``, ``kanban.db``, custom
+    # skills, scripts, …) that an earlier incident observed. Five call
+    # sites in this file invoke this helper; if any one of them ever
+    # computes a destination outside the skills root — through a bad
+    # path join, a missing ``HERMES_HOME`` default, a malicious
+    # bundled-manifest entry, or a mid-flight exception that leaves a
+    # stale path in scope — this guard turns the resulting
+    # ``shutil.rmtree(~/.hermes)`` into a loud, recoverable ``ValueError``
+    # instead of silently destroying the user's install.
+    target = Path(path).resolve()
+    skills_root = SKILLS_DIR.resolve()
+    # Every legitimate caller passes a skill directory or its ``.bak``
+    # sibling — always a strict child of the skills root. The skills root
+    # itself must never be removed: a ``dest`` that collapses to
+    # ``SKILLS_DIR`` (e.g. a relative path resolving to ``.``) would wipe
+    # every installed skill, and its ``.bak`` sibling lands one level up in
+    # ``HERMES_HOME``. Require a strict-child relationship so both escape
+    # into the skills root and out of it are refused.
+    if skills_root not in target.parents:
+        raise ValueError(
+            f"refusing to rmtree {target!r}: not strictly under {skills_root!r} "
+            f"(scope guard — see #48200)"
+        )
     import stat
 
     def _on_error(func, fpath, exc_info):
@@ -750,6 +810,173 @@ def reset_bundled_skill(name: str, restore: bool = False) -> dict:
     return {"ok": True, "action": action, "message": message, "synced": synced}
 
 
+def _is_tracked_user_modification(origin_hash: str, user_hash: str) -> bool:
+    """Whether an on-disk skill counts as a user modification ``hermes update`` keeps.
+
+    Shared by the sync loop (which decides what to skip) and
+    ``list_user_modified_bundled_skills`` (which surfaces the names) so the two
+    can never drift. A skill is a tracked modification only when it has a
+    recorded origin hash (an un-baselined / v1 entry with an empty hash is not)
+    and its current content hash differs from that origin.
+    """
+    return bool(origin_hash) and user_hash != origin_hash
+
+
+def list_user_modified_bundled_skills() -> List[dict]:
+    """Return the bundled skills that ``hermes update`` keeps because the user
+    edited them locally.
+
+    A skill counts as user-modified when its on-disk copy no longer matches the
+    origin hash recorded in the manifest the last time it was synced — the exact
+    same test the sync loop uses to decide what to skip. This is the discovery
+    half of that behavior, so a user can find the names the ``~ N user-modified
+    (kept)`` notice only counts.
+
+    Returns a list (sorted by name) of dicts:
+        ``{"name": str, "dest": Path, "bundled_src": Path}``
+    where ``dest`` is the user's copy and ``bundled_src`` is the current stock
+    copy (so callers can diff or restore).
+    """
+    manifest = _read_manifest()
+    if not manifest:
+        return []
+    bundled_dir = _get_bundled_dir()
+    modified: List[dict] = []
+    for skill_name, skill_dir in _discover_bundled_skills(bundled_dir):
+        origin_hash = manifest.get(skill_name, "")
+        # No entry, or a v1 entry not yet baselined (empty hash): not a tracked
+        # modification — the next sync handles it.
+        if not origin_hash:
+            continue
+        dest = _compute_relative_dest(skill_dir, bundled_dir)
+        if not dest.exists():
+            continue
+        if _is_tracked_user_modification(origin_hash, _dir_hash(dest)):
+            modified.append(
+                {"name": skill_name, "dest": dest, "bundled_src": skill_dir}
+            )
+    modified.sort(key=lambda e: e["name"])
+    return modified
+
+
+def _read_for_diff(path: Path) -> Tuple[Optional[bytes], Optional[str]]:
+    """Read a file once for diffing.
+
+    Returns ``(raw_bytes, text)`` where ``text`` is ``None`` if the file is
+    binary; ``(None, None)`` if it could not be read. Returning the raw bytes
+    lets the caller compare binary files without re-reading them.
+    """
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return None, None
+    if b"\x00" in data:
+        return data, None
+    try:
+        return data, data.decode("utf-8")
+    except UnicodeDecodeError:
+        return data, None
+
+
+def diff_bundled_skill(name: str) -> dict:
+    """Diff a user's copy of a bundled skill against the current stock version.
+
+    Lets a user see exactly what diverged before deciding whether to keep their
+    edits or ``hermes skills reset`` back to upstream.
+
+    Returns a dict:
+        ``ok`` (bool), ``name`` (str), ``found`` (bool — bundled source exists),
+        ``modified`` (bool), ``message`` (str),
+        ``diffs``: list of ``{"path": str, "status": str, "diff": str}`` where
+        status is one of ``modified`` / ``added`` (only in user copy) /
+        ``removed`` (only in bundled) / ``binary``.
+    """
+    import difflib
+
+    bundled_dir = _get_bundled_dir()
+    bundled_by_name = dict(_discover_bundled_skills(bundled_dir))
+    bundled_src = bundled_by_name.get(name)
+    if bundled_src is None:
+        return {
+            "ok": False,
+            "name": name,
+            "found": False,
+            "modified": False,
+            "diffs": [],
+            "message": (
+                f"'{name}' is not a tracked bundled skill (no stock version to "
+                f"diff against). Hub-installed skills use `hermes skills inspect`."
+            ),
+        }
+    dest = _compute_relative_dest(bundled_src, bundled_dir)
+    if not dest.exists():
+        return {
+            "ok": False,
+            "name": name,
+            "found": True,
+            "modified": False,
+            "diffs": [],
+            "message": f"No local copy of '{name}' found at {dest}.",
+        }
+
+    user_files = set(_skill_file_list(dest))
+    stock_files = set(_skill_file_list(bundled_src))
+
+    diffs: List[dict] = []
+    for rel in sorted(user_files | stock_files):
+        in_user = rel in user_files
+        in_stock = rel in stock_files
+        user_bytes, user_text = (
+            _read_for_diff(dest / rel) if in_user else (None, None)
+        )
+        stock_bytes, stock_text = (
+            _read_for_diff(bundled_src / rel) if in_stock else (None, None)
+        )
+
+        if in_user and in_stock:
+            if user_text is None or stock_text is None:
+                # At least one side is binary — report only if bytes differ
+                # (reuse the bytes already read above, no second read).
+                if user_bytes != stock_bytes:
+                    diffs.append(
+                        {"path": rel, "status": "binary", "diff": "<binary file differs>"}
+                    )
+                continue
+            if user_text == stock_text:
+                continue
+            text = "".join(
+                difflib.unified_diff(
+                    stock_text.splitlines(keepends=True),
+                    user_text.splitlines(keepends=True),
+                    fromfile=f"stock/{rel}",
+                    tofile=f"yours/{rel}",
+                )
+            )
+            diffs.append({"path": rel, "status": "modified", "diff": text})
+        elif in_user:
+            diffs.append(
+                {"path": rel, "status": "added", "diff": f"+ only in your copy: {rel}"}
+            )
+        else:
+            diffs.append(
+                {"path": rel, "status": "removed", "diff": f"- only in stock: {rel}"}
+            )
+
+    modified = bool(diffs)
+    return {
+        "ok": True,
+        "name": name,
+        "found": True,
+        "modified": modified,
+        "diffs": diffs,
+        "message": (
+            f"'{name}' matches the stock version."
+            if not modified
+            else f"'{name}' differs from the stock version in {len(diffs)} file(s)."
+        ),
+    }
+
+
 def set_bundled_skills_opt_out(enabled: bool) -> dict:
     """Toggle the .no-bundled-skills opt-out marker for the active profile.