boost-skill-cli 1.2.197__tar.gz → 1.2.198__tar.gz

{boost_skill_cli-1.2.197 → boost_skill_cli-1.2.198}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.197
+Version: 1.2.198
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.197 → boost_skill_cli-1.2.198}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.197'
-__version_tuple__ = version_tuple = (1, 2, 197)
+__version__ = version = '1.2.198'
+__version_tuple__ = version_tuple = (1, 2, 198)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.197 → boost_skill_cli-1.2.198}/boost_cli/commands/configuration.py

@@ -26,7 +26,6 @@ from ..core import (
     catalog,
     complete,
     config,
-    foreign,
     frontmatter,
     gitutil,
     installscan,
@@ -1592,6 +1591,12 @@ def _tool_install(args: dict):
     if res.native:
         lines.append("available without linking (reads %s directly): %s"
                      % (res.dest.parent, ", ".join(res.native)))
+    # A workflow's copy in the skill store is how a skills-only agent reaches
+    # it; an agent told nothing concludes the same as above.
+    if res.skill_copy is not None:
+        lines.append("as a skill: %s" % res.skill_copy)
+    if res.skill_note:
+        lines.append(res.skill_note)
     lines.append("quality score: %d/100" % res.score)
     if res.conflicts:
         lines.append("conflicts (left in place): %s" % ", ".join(res.conflicts))
@@ -1791,7 +1796,7 @@ def _doctor_verdict(plan: dict[str, list], total: int, lock_bad: bool,
     prune = (len(plan.get("foreign_store", ())) - repos
              + len(plan.get("out_of_scope_links", ()))
              + sum(1 for r in plan.get("plugin_duplicates", ())
-                   if r[3] == foreign.IDENTICAL))
+                   if store.plugin_serves(r[3])))
     if not user and not prune:
         return "%d issue(s) — run `boost sync` to fix" % total
     parts = []

{boost_skill_cli-1.2.197 → boost_skill_cli-1.2.198}/boost_cli/commands/pkg.py

@@ -267,6 +267,7 @@ def _report_result(res: store.InstallResult, no_mcp: bool = False) -> None:
         where = " (this repo)" if res.scope == "project" else ""
         out.ok("materialized%s → %s"
                % (where, " · ".join(res.linked) or "(no enabled agents)"))
+        _report_skill_copy(res)
         _warn_unwritable(res)
         out.ok("lock updated (.skill-lock.json)")
         _warn_injection(res)
@@ -302,6 +303,16 @@ def _report_result(res: store.InstallResult, no_mcp: bool = False) -> None:
     _offer_mcp(res, no_mcp=no_mcp)
 
 
+def _report_skill_copy(res) -> None:
+    """The workflow's copy in the skill store, on its own line. Its own line
+    so the ``materialized →`` field stays the list of agents a dry run
+    predicts. Why there is none is :func:`_warn_unwritable`'s to say, so
+    update, reinstall and sync say it too."""
+    copy = getattr(res, "skill_copy", None)
+    if copy is not None:
+        out.ok("as a skill → %s" % _tilde(copy))
+
+
 def _warn_unwritable(res, stream=None) -> None:
     """Name what an install skipped, and the remedy — every path that
     installs, reinstall and update included, so none reports success over an
@@ -313,6 +324,12 @@ def _warn_unwritable(res, stream=None) -> None:
 
     ``stream`` for a caller speaking JSON on stdout: relinking under
     `focus --json` must still say what it skipped, on stderr."""
+    # What became of the workflow's skill copy: retired, kept as edited, or
+    # skipped for a name something else holds. Every caller that installs
+    # passes through here, so none removes a copy without a word.
+    note = getattr(res, "skill_note", None)
+    if note:
+        out.info(note, stream=stream, wrap=True)
     conflicts, refused = _skipped_agent_lines(res)
     for line in conflicts:
         out.warn(line, stream=stream)
@@ -488,6 +505,29 @@ def _expand_dependencies(entries: list[dict]) -> tuple[list[dict], resolve.Resol
 
 # ── install ──────────────────────────────────────────────────────────────
 
+def _preview_skill_copy(e: dict, seen: dict | None, as_skill: bool | None,
+                        scope: str) -> None:
+    """The dry run's line for a workflow's skill copy, asked the way the run
+    decides it, so the two agree."""
+    from ..core import workflows
+    if scope == scopes.SCOPE_PROJECT or not store.wants_skill_copy(as_skill,
+                                                                   seen):
+        return
+    try:
+        raw = (registry.get(e["tap"]).path / e.get("skill_md", "")).read_text(
+            encoding="utf-8", errors="replace")
+    except (OSError, BoostError):
+        return
+    slot = workflows.detect_slot(e.get("skill_md", ""))
+    if workflows.skill_description(slot, frontmatter.parse(raw)[0]) is None:
+        return
+    blocker = store.skill_copy_blocker(e["name"], seen)
+    if blocker:
+        out.info("  %s" % blocker, wrap=True)
+        return
+    out.info("  as a skill → %s" % _tilde(store.skill_store_dir(e["name"])))
+
+
 def cmd_install(argv: list[str]) -> int:
     ap = cliparse.parser(prog="boost install",
                                  description="Install a skill from a tap registry")
@@ -518,6 +558,16 @@ def cmd_install(argv: list[str]) -> int:
                          "(the wider spellings are reported, never installed)")
     ap.add_argument("--no-mcp", action="store_true",
                     help="don't offer to register MCP servers a skill declares")
+    skill_g = ap.add_mutually_exclusive_group()
+    skill_g.add_argument("--as-skill", dest="as_skill", action="store_const",
+                         const=True, default=None,
+                         help="also put a workflow in the skill store, for "
+                              "agents that read only skills (default: the "
+                              "workflows_as_skills config); remembered")
+    skill_g.add_argument("--no-as-skill", dest="as_skill",
+                         action="store_const", const=False,
+                         help="don't put a workflow in the skill store; "
+                              "remembered")
     args = ap.parse_args(argv)
     args.scope = args.scope or scopes.SCOPE_USER
     # Resolved before the dry-run branch, because both sides need it and only
@@ -705,6 +755,9 @@ def cmd_install(argv: list[str]) -> int:
                                                                   e["version"], e["tap"],
                                                                   where))
                     out.info("  materialize → %s" % " · ".join(mat))
+                    if k == "workflow":
+                        _preview_skill_copy(e, seen, args.as_skill,
+                                            args.scope)
                     continue
                 seen = lockfile.get_skill(e["name"])
                 verb = "upgrade" if seen else "install"
@@ -752,7 +805,8 @@ def cmd_install(argv: list[str]) -> int:
         if multi:
             out.heading("%s v%s (%s)" % (e["name"], e["version"], e["tap"]))
         try:
-            res = store.install(e, force=args.force, only_agents=only, scope=args.scope)
+            res = store.install(e, force=args.force, only_agents=only,
+                                scope=args.scope, as_skill=args.as_skill)
         except BoostError as err:
             if not multi:
                 raise
@@ -891,6 +945,9 @@ def cmd_uninstall(argv: list[str]) -> int:
             verb = "unlinked ←" if kind == "skill" and not is_project \
                 else "removed from"
             out.ok("%s %s" % (verb, " · ".join(info["unlinked"])))
+        for path in info.get("kept") or ():
+            out.warn("left %s in place: it was edited since boost wrote it"
+                     % _tilde(path), wrap=True)
         if is_project:
             refused = info.get("refused") or []
             escaped = info.get("escaped") or []
@@ -1137,14 +1194,17 @@ def cmd_sync(argv: list[str]) -> int:
         else:
             declined_copies = True
     left = [r for r in copies if r[0] not in pruned]
-    same = [r for r in plan["plugin_duplicates"] if r[3] == foreign.IDENTICAL]
+    same = [r for r in plan["plugin_duplicates"] if store.plugin_serves(r[3])]
     dropped: list[str] = []
     declined_dups = False
     if args.prune and same:
+        newer = any(r[3] != foreign.IDENTICAL for r in same)
         if _go(args, "Drop boost's Claude Code link for %s an enabled plugin "
-                     "ships with the same files (Claude Code goes on loading "
-                     "the plugin's copy): %s?"
+                     "ships %s (Claude Code goes on loading the plugin's "
+                     "copy): %s?"
                      % (_plural(len(same), "skill"),
+                        "with the same files or in a newer copy" if newer
+                        else "with the same files",
                         ", ".join(r[0] for r in same))):
             for row in same:
                 ok, line = store.drop_plugin_link(row)
@@ -1254,7 +1314,7 @@ def cmd_sync(argv: list[str]) -> int:
     for path in occupied:
         out.warn("%s, then re-run `boost sync`" % store.occupied_refusal(path),
                  wrap=True)
-    unfixed = left or kept or any(r[3] == foreign.IDENTICAL for r in dups)
+    unfixed = left or kept or any(store.plugin_serves(r[3]) for r in dups)
     if (not actions and not pruned and not unfixed and not oos and not blocked
             and not stuck and not in_way and not occupied and not lock_bad
             and not plan["unreadable_store"]):
@@ -1726,6 +1786,9 @@ def cmd_update(argv: list[str]) -> int:
             out.ok("refreshed %s v%s (source changed)" % (name, new_v))
         upgraded += 1
     # Rules and workflows refresh from the same tap update.
+    # Skills installed before boost dated them, so a plugin's copy of the
+    # same name can be weighed against them (store.serving_plugin).
+    store.backfill_source_dates(results)
     upgraded += _update_materialized("rule", lockfile.installed_rules(), results)
     upgraded += _update_materialized("workflow", lockfile.installed_workflows(), results)
     if not upgraded:

{boost_skill_cli-1.2.197 → boost_skill_cli-1.2.198}/boost_cli/commands/quality.py

@@ -876,9 +876,20 @@ def cmd_doctor(argv):
             if not store.materialization_is_written("workflow", entry, m):
                 continue
             if not m.get("unwritable") and not os.path.isfile(m.get("path", "")):
-                bad("workflow", "workflow %s missing its %s file — run `boost reinstall %s`"
-                    % (name, m.get("agent", "?"), name))
+                if lockfile.is_skill_copy(m):
+                    bad("workflow", "workflow %s missing its skill copy at %s "
+                        "— run `boost sync`" % (name, _tilde(m.get("path", ""))),
+                        wrap=True)
+                else:
+                    bad("workflow", "workflow %s missing its %s file — run "
+                        "`boost reinstall %s`"
+                        % (name, m.get("agent", "?"), name))
                 mat_issues += 1
+    # A note, not an issue: the workflow works for every agent with a workflow
+    # format. Only an agent that reads skills alone (Codex) misses it.
+    unreached = store.workflows_without_skill_copy() if agents_ok else []
+    if unreached:
+        rep.note("workflows-as-skills", _as_skill_note(unreached), wrap=True)
     # Said once, as a note rather than an issue: the row is there because the
     # user changed that agent's config after installing, which is their
     # decision, and the two ways out are theirs to pick. Reporting it as a
@@ -1000,6 +1011,8 @@ def cmd_doctor(argv):
             "drops boost's Claude Code link"
             % (len(same), _s(len(same)), "s" if len(same) == 1 else "",
                "it" if len(same) == 1 else "them", _first(same)), wrap=True)
+    for line in store.plugin_newer_lines(dups):
+        bad("plugin-newer", line, wrap=True)
     for line in store.plugin_variant_lines(dups):
         rep.note("plugin-variants", line, wrap=True)
 
@@ -1556,6 +1569,16 @@ def cmd_decay(argv):
     return 0
 
 
+def _as_skill_note(names: list[str]) -> str:
+    """The doctor/heal line for workflows installed without a skill copy."""
+    n = len(names)
+    shown = ", ".join(names[:_MAT_NOTE_SHOWN]) + (
+        " and %d more" % (n - _MAT_NOTE_SHOWN) if n > _MAT_NOTE_SHOWN else "")
+    return ("%d workflow%s not reachable as skill%s (%s) — `boost heal "
+            "--as-skill` puts %s in the skill store"
+            % (n, _s(n), _s(n), shown, "it" if n == 1 else "them"))
+
+
 def cmd_heal(argv):
     ap = cliparse.parser(
         prog="boost heal",
@@ -1566,6 +1589,9 @@ def cmd_heal(argv):
                     help="remove the duplicate-discovery symlinks `boost doctor` "
                          "reports (an agent that collapses them silently is "
                          "never reported, so never pruned)")
+    ap.add_argument("--as-skill", action="store_true",
+                    help="give installed workflows their copy in the skill "
+                         "store, for agents that read only skills")
     args = ap.parse_args(argv)
     dry = args.dry_run
     actions: list[str] = []
@@ -1673,7 +1699,25 @@ def cmd_heal(argv):
     if plan["misnamed_store"]:
         out.info(store.misnamed_line(plan["misnamed_store"]), wrap=True)
     declined_copies = bool(plan["foreign_store"]) or any(
-        r[3] == foreign.IDENTICAL for r in plan["plugin_duplicates"])
+        store.plugin_serves(r[3]) for r in plan["plugin_duplicates"])
+
+    # Opt-in like --prune-duplicates, though it removes nothing: it writes into
+    # the skill store, which a plain heal only ever repairs.
+    if args.as_skill:
+        if not config.get("workflows_as_skills", True):
+            out.info("workflows_as_skills is off, so no workflow gets a skill "
+                     "copy — `boost config set workflows_as_skills true` "
+                     "turns it on", wrap=True)
+        for line in store.backfill_skill_copies(dry=dry):
+            if dry or line.startswith("workflow "):
+                out.info(line, wrap=True)
+            else:
+                out.ok(line)
+            actions.append(line)
+    else:
+        unreached = store.workflows_without_skill_copy()
+        if unreached:
+            out.info(_as_skill_note(unreached), wrap=True)
 
     duplicates = store.duplicate_discovery()
     declined_duplicates = bool(duplicates) and not args.prune_duplicates

{boost_skill_cli-1.2.197 → boost_skill_cli-1.2.198}/boost_cli/commands/safety.py

@@ -593,9 +593,14 @@ def cmd_quarantine(argv):
             out.ok("released %s (linked: %s)"
                    % (name, ", ".join(res.linked) or "none"))
         else:
-            restored = store.release_materialized(kind, name, entry)
+            skipped: list[str] = []
+            restored = store.release_materialized(kind, name, entry,
+                                                  skipped=skipped)
             out.ok("released %s %s (restored: %s)"
                    % (kind, name, ", ".join(restored) or "none"))
+            for d in skipped:
+                out.info("not restored as a skill: %s now holds something "
+                         "else — left alone" % paths.tilde(d), wrap=True)
         return 0
 
     name = args.name

{boost_skill_cli-1.2.197 → boost_skill_cli-1.2.198}/boost_cli/core/config.py

@@ -114,6 +114,13 @@ DEFAULTS = {
     },
     "serve": {"port": 8787},
     "policy_enforce": True,
+    # A workflow (a subagent, or a slash command with a description) also gets
+    # a copy in the canonical store, ``~/.agents/skills/<name>/SKILL.md``, so
+    # agents that read skills and no workflow format — Codex — can reach it.
+    # `boost install --as-skill/--no-as-skill` overrides it per install, and
+    # that choice sticks; with neither flag an install follows this. See
+    # store._skill_copy.
+    "workflows_as_skills": True,
     "telemetry": False,
     "logging": {
         # Console verbosity for the diagnostic log on stderr. "OFF" keeps

{boost_skill_cli-1.2.197 → boost_skill_cli-1.2.198}/boost_cli/core/foreign.py

@@ -60,7 +60,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from ..errors import BoostError
-from . import agents, frontmatter, jsonstate, paths, util
+from . import agents, frontmatter, gitutil, jsonstate, paths, util
 
 VENDOR = "vendor"
 PLUGIN = "plugin"
@@ -70,8 +70,21 @@ AGENT = "agent"
 CLAUDE = "claude-code"
 
 #: How two copies of a skill compare, as plans record it and messages word it.
+#: A variant pair — the same name, different files — is :data:`DIFFERS` until
+#: the dates say which is newer (:func:`newest_copy`).
 IDENTICAL = "identical"
 DIFFERS = "differs"
+NEWER_IN_PLUGIN = "newer-in-plugin"
+NEWER_IN_BOOST = "newer-in-boost"
+
+#: Where a plugin skill's date came from (:func:`plugin_skill_updated_at`).
+#: The first two are when it really last changed; a bound is no earlier than
+#: that, and can only show that boost's copy is the newer one.
+DATE_GIT = "git"
+DATE_FILES = "files"
+DATE_BOUND = "upper-bound"
+DATE_UNKNOWN = "unknown"
+EXACT_DATES = (DATE_GIT, DATE_FILES)
 
 #: The fields a marketplace entry may add to a plugin. Beside a
 #: ``plugin.json``, an entry that sets ``strict: false`` and declares any of
@@ -388,17 +401,11 @@ def _read_from(plugin: Plugin) -> Path | None:
     branch there, from a directory boost has not seen recorded, so it keeps
     its ``installPath`` here.
     """
-    found = _marketplace(plugin)
-    if found is None:
+    source = _folder_source(plugin)
+    if source is None:
         return plugin.path
-    record, root = found
-    kind = record.get("source")
-    entry = _marketplace_entry(plugin)
-    if (not isinstance(kind, dict) or kind.get("source") != "directory"
-            or entry is None or not isinstance(entry.get("source"), str)):
-        return plugin.path
-    rel = entry["source"]
-    if os.path.isabs(rel):
+    root, rel = source
+    if Path(rel).is_absolute():
         return None
     folder = root / rel
     base = os.path.realpath(root)
@@ -409,6 +416,30 @@ def _read_from(plugin: Plugin) -> Path | None:
     return folder if inside else None
 
 
+def _folder_source(plugin: Plugin) -> tuple[Path, str] | None:
+    """``(marketplace dir, entry source)`` for a plugin Claude Code reads
+    from a local folder (:func:`_read_from`), else None."""
+    found = _marketplace(plugin)
+    if found is None:
+        return None
+    record, root = found
+    kind = record.get("source")
+    entry = _marketplace_entry(plugin)
+    if (not isinstance(kind, dict) or kind.get("source") != "directory"
+            or entry is None or not isinstance(entry.get("source"), str)):
+        return None
+    return root, entry["source"]
+
+
+def reads_folder(plugin: Plugin) -> bool:
+    """True when Claude Code reads ``plugin`` from a folder of the user's.
+
+    Its file times are then real edit times, unlike a cache copy's, which are
+    when Claude Code installed it.
+    """
+    return _folder_source(plugin) is not None
+
+
 def _source_is_root(entry: dict) -> bool:
     """True when a marketplace entry's ``source`` is the marketplace root."""
     src = entry.get("source")
@@ -711,3 +742,109 @@ def newest_mtime(path: Path) -> float:
             except OSError:
                 continue
     return best
+
+
+def _inside(path: Path, root: Path) -> bool:
+    """True when ``path`` is ``root`` or below it, both resolved."""
+    a, b = os.path.realpath(path), os.path.realpath(root)
+    try:
+        return os.path.commonpath([a, b]) == b
+    except ValueError:
+        return False
+
+
+def _repo_root(path: Path) -> Path | None:
+    """The top of the git work tree ``path`` is in, or None."""
+    if not gitutil.has_git():
+        return None
+    proc = gitutil.run(["-C", str(path), "rev-parse", "--show-toplevel"],
+                       check=False)
+    top = proc.stdout.strip()
+    return Path(top) if proc.returncode == 0 and top else None
+
+
+def _clean(path: Path) -> bool:
+    """True when git sees no edit, and no untracked file, under ``path``."""
+    proc = gitutil.run(["-C", str(path), "status", "--porcelain", "--", "."],
+                       check=False)
+    return proc.returncode == 0 and not proc.stdout.strip()
+
+
+def plugin_skill_updated_at(plugin: Plugin, path: Path) -> tuple[float | None, str]:
+    """``(when, source)``: when a plugin's skill dir last changed, and how that is known.
+
+    Only read, never fetched: the dirs are Claude Code's. In order:
+
+    * :data:`DATE_GIT` — the dir is in a git checkout with the history to
+      date it (:func:`gitutil.path_updated_at`) and nothing in it is edited.
+      For a cache or marketplace checkout the repository must be Claude
+      Code's own, under :func:`plugins_root`: a dotfiles repo at ``$HOME``
+      that tracks ``~/.claude`` dates the user's commit, not the plugin's.
+    * :data:`DATE_FILES` — a plugin read from a folder of the user's
+      (:func:`reads_folder`): its newest file time is when it was edited.
+    * :data:`DATE_BOUND` — anything else. The checkouts Claude Code makes
+      are ``--depth 1`` or not git at all, so the best on hand is the HEAD's
+      date or the install's file times, the earlier of the two. Both are no
+      earlier than the skill's real last change.
+    * :data:`DATE_UNKNOWN` — no file to date, ``when`` None.
+    """
+    files = newest_mtime(path) or None
+    folder = reads_folder(plugin)
+    root = _repo_root(path)
+    ours = root is not None and (folder or _inside(root, plugins_root()))
+    if ours and _clean(path):
+        exact = gitutil.path_updated_at(path, ".")
+        if exact is not None:
+            return float(exact), DATE_GIT
+    if folder:
+        return (files, DATE_FILES) if files is not None else (None, DATE_UNKNOWN)
+    head = gitutil.head_time(path) if ours else None
+    bounds = [b for b in (files, head) if b is not None]
+    return (float(min(bounds)), DATE_BOUND) if bounds else (None, DATE_UNKNOWN)
+
+
+def newest_copy(boost_at: float | None, plugin_at: float | None, source: str) -> str:
+    """Which copy of a variant pair is newer: a :data:`NEWER_IN_BOOST`,
+    :data:`NEWER_IN_PLUGIN` or :data:`DIFFERS` (not known).
+
+    ``boost_at`` is exact: the commit date of boost's copy in a complete tap
+    clone. ``plugin_at`` is exact only for a :data:`EXACT_DATES` ``source``;
+    otherwise it is an upper bound, so a boost date past it shows boost's copy
+    is newer, and a boost date before it shows nothing. Reading a bound both
+    ways called nearly every plugin newer, because Claude Code installs a
+    plugin after the commit boost's copy dates from. Equal dates decide
+    nothing either: two copies changed in the same second are not one newer.
+    """
+    if boost_at is None or plugin_at is None:
+        return DIFFERS
+    if boost_at > plugin_at:
+        return NEWER_IN_BOOST
+    if plugin_at > boost_at and source in EXACT_DATES:
+        return NEWER_IN_PLUGIN
+    return DIFFERS
+
+
+def dated_how(verdict: str, source: str) -> str:
+    """A :func:`newest_copy` verdict as plans record it: ``"<verdict>:<source>"``
+    for a dated one, so the wording can say how it is known; :data:`DIFFERS`
+    as it is."""
+    return verdict if verdict == DIFFERS else "%s:%s" % (verdict, source)
+
+
+def split_how(how: str) -> tuple[str, str]:
+    """``(verdict, date source)`` from a recorded verdict (:func:`dated_how`);
+    the source is "" for an undated one."""
+    verdict, _sep, source = how.partition(":")
+    return verdict, source
+
+
+#: How each date source reads after "by": what boost's last commit was
+#: weighed against.
+DATE_WORDS = {DATE_GIT: "commit dates",
+              DATE_FILES: "boost's commits against the plugin's file times",
+              DATE_BOUND: "boost's commits against the plugin's install date"}
+
+
+def date_words(source: str) -> str:
+    """``source`` (:data:`DATE_GIT` and the rest) worded to follow "by"."""
+    return DATE_WORDS.get(source, "dates boost could not place")

{boost_skill_cli-1.2.197 → boost_skill_cli-1.2.198}/boost_cli/core/gitutil.py

@@ -363,10 +363,20 @@ def materialize(repo: Path, rel_dir: str) -> None:
             hint="this needs network — the tap stores only Markdown locally") from None
 
 
+def _depth(repo: Path) -> list[str]:
+    """``--depth 1`` for a shallow clone, nothing for a complete one.
+
+    A clone :func:`unshallow` deepened so its skills' dates can be read must
+    stay deep: a ``fetch --depth 1`` puts ``.git/shallow`` back and cuts the
+    history to one commit again, and every date read after it is the HEAD's.
+    """
+    return ["--depth", "1"] if is_shallow(repo) else []
+
+
 def pull(repo: Path) -> str:
-    """Update a shallow clone. Returns a one-line summary."""
+    """Update a clone, keeping it as shallow as it is. Returns a one-line summary."""
     before = head_commit(repo)
-    proc = run(["-C", str(repo), "fetch", "--depth", "1", "--quiet", "origin"],
+    proc = run(["-C", str(repo), "fetch", *_depth(repo), "--quiet", "origin"],
               check=False)
     if proc.returncode != 0:
         stderr = (proc.stderr or "") + (proc.stdout or "")
@@ -396,7 +406,8 @@ def checkout_commit(repo: Path, sha: str) -> None:
 
     The fetch keeps `--depth 1` and the blobless filter for the same reason the
     clone does — pinning a tap must not cost the history and blobs the sparse
-    clone was built to avoid (458 taps held 12 GB before that work).
+    clone was built to avoid (458 taps held 12 GB before that work). A clone
+    that is already complete stays so (:func:`_depth`).
     """
     if not _is_sha(sha):
         raise BoostError("%r is not a full commit SHA" % sha,
@@ -404,7 +415,7 @@ def checkout_commit(repo: Path, sha: str) -> None:
     have = run(["-C", str(repo), "cat-file", "-e", sha + "^{commit}"],
                check=False)
     if have.returncode != 0:
-        run(["-C", str(repo), "fetch", "--quiet", "--depth", "1",
+        run(["-C", str(repo), "fetch", "--quiet", *_depth(repo),
              "--filter=blob:none", "origin", sha])
     run(["-C", str(repo), "checkout", "--quiet", "--detach", sha])
     # A detached checkout leaves the sparse cone as it was, but re-applying is
@@ -442,6 +453,90 @@ def is_shallow(repo: Path) -> bool:
     return (Path(repo) / ".git" / "shallow").is_file()
 
 
+#: Seconds :func:`unshallow` waits for history before giving the date up.
+UNSHALLOW_TIMEOUT = 60
+
+
+def unshallow(repo: Path) -> bool:
+    """Fetch the rest of a shallow clone's history, still without blobs.
+
+    What makes a skill's date readable (:func:`path_updated_at`). Measured on
+    real taps: 0.5 s and 156 KB for ``anthropics/skills`` (60 commits), 3 s
+    and 11.5 MB for one with 3,220; a second run costs nothing. Commits and
+    trees only — a blobless fetch brings no file outside the sparse cone.
+    True when the clone is complete afterwards; a failure (offline, a remote
+    that is gone) is False and raises nothing, since a date is never worth
+    failing the install or update that asked for it. The fetch gets
+    :data:`UNSHALLOW_TIMEOUT` rather than :func:`run`'s five minutes, so a
+    huge or stalled remote costs an install a minute and an undated skill,
+    not five.
+
+    A timeout kills git, which then cannot remove the ``.git/shallow.lock``
+    it took, and every later fetch of that tap (``boost update``) fails on
+    "Unable to create ... shallow.lock: File exists". So a lock this fetch
+    created is removed when it dies; one that was there before is another
+    git process's and is left alone.
+    """
+    if not is_shallow(repo):
+        return True
+    lock = Path(repo) / ".git" / "shallow.lock"
+    held = lock.exists()
+    try:
+        proc = run(["-C", str(repo), "fetch", "--quiet", "--unshallow",
+                    "--filter=blob:none", "origin"], check=False,
+                   timeout=UNSHALLOW_TIMEOUT)
+    except BoostError:
+        if not held:
+            lock.unlink(missing_ok=True)
+        return False
+    return proc.returncode == 0 and not is_shallow(repo)
+
+
+def _graft_points(repo: Path) -> set[str]:
+    """The commits a shallow repo's history is cut at; empty for a complete one.
+
+    Located with ``rev-parse --git-path``, so a worktree or submodule whose
+    ``.git`` is a file finds its repository's list too.
+    """
+    proc = run(["-C", str(repo), "rev-parse", "--git-path", "shallow"], check=False)
+    rel = proc.stdout.strip()
+    if proc.returncode != 0 or not rel:
+        return set()
+    try:
+        text = (Path(repo) / rel).read_text(encoding="utf-8")
+    except OSError:
+        return set()
+    return {ln.strip() for ln in text.splitlines() if ln.strip()}
+
+
+def path_updated_at(repo: Path, rel_dir: str = ".", rev: str = "HEAD") -> int | None:
+    """When ``rel_dir`` last changed at ``rev``: a Unix time, or None.
+
+    The committer time of the newest commit touching any file under the dir,
+    so a change to a script or an asset counts as much as one to ``SKILL.md``.
+    None when no commit touched it, git fails, or the commit found is one the
+    history is cut at (:func:`_graft_points`). That last is not caution: git
+    reads a graft point as a root commit that added every file, so in a
+    ``--depth 1`` clone every dir "changed" in the HEAD commit, and the date
+    is the HEAD's for all of them. Only the trees are read, which a blobless
+    clone holds.
+    """
+    proc = run(["-C", str(repo), "log", "-1", "--format=%H" + _LOG_SEP + "%ct",
+                rev or "HEAD", "--", rel_dir or "."], check=False)
+    sha, _sep, when = proc.stdout.strip().partition(_LOG_SEP)
+    if proc.returncode != 0 or not when.isdigit():
+        return None
+    return None if sha in _graft_points(repo) else int(when)
+
+
+def head_time(repo: Path) -> int | None:
+    """The HEAD commit's committer time, or None. No earlier than any date
+    :func:`path_updated_at` can find at HEAD, shallow clone or not."""
+    proc = run(["-C", str(repo), "log", "-1", "--format=%ct", "HEAD"], check=False)
+    when = proc.stdout.strip()
+    return int(when) if proc.returncode == 0 and when.isdigit() else None
+
+
 def log_for_path(repo: Path, rel_path: str = ".", n: int = 20) -> list[str]:
     """Formatted one-line log entries for a path inside a repo."""
     proc = run(["-C", str(repo), "log", "--date=short", "-n", str(n),