boost-skill-cli 1.2.97__tar.gz → 1.2.99__tar.gz

{boost_skill_cli-1.2.97/boost_skill_cli.egg-info → boost_skill_cli-1.2.99}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.97
+Version: 1.2.99
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -468,6 +468,7 @@ is the whole setup.
 boost mcp register                 # every installed host (default: --host auto)
 boost mcp register --host gemini   # just one
 boost mcp register --no-seed       # register only; tap nothing
+boost mcp register --dry-run       # print the resolved command per host; change nothing
 boost mcp unregister               # same host selection, in reverse
 ```
 

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.99}/README.md

@@ -426,6 +426,7 @@ is the whole setup.
 boost mcp register                 # every installed host (default: --host auto)
 boost mcp register --host gemini   # just one
 boost mcp register --no-seed       # register only; tap nothing
+boost mcp register --dry-run       # print the resolved command per host; change nothing
 boost mcp unregister               # same host selection, in reverse
 ```
 

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.99}/boost

@@ -2,7 +2,7 @@
 # Copyright the boost contributors.
 # SPDX-License-Identifier: Apache-2.0
 # boost — Homebrew for AI coding skills.
-# Thin shim: finds Python 3.9+, runs the boost_cli package that lives
+# Thin shim: finds Python 3.12+, runs the boost_cli package that lives
 # next to this script (resolving symlinks, so `ln -s .../boost ~/bin/boost`
 # just works). No PyPI, no Artifactory — stdlib only.
 set -euo pipefail
@@ -24,7 +24,7 @@ fi
 find_python() {
   for py in python3 python; do
     if command -v "$py" >/dev/null 2>&1; then
-      if "$py" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 9) else 1)' 2>/dev/null; then
+      if "$py" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 12) else 1)' 2>/dev/null; then
         echo "$py"
         return 0
       fi
@@ -34,7 +34,7 @@ find_python() {
 }
 
 PY="$(find_python)" || {
-  echo "boost: Python 3.9+ is required but was not found on PATH" >&2
+  echo "boost: Python 3.12+ is required but was not found on PATH" >&2
   echo "  hint: brew install python3" >&2
   exit 1
 }

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.99}/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.97'
-__version_tuple__ = version_tuple = (1, 2, 97)
+__version__ = version = '1.2.99'
+__version_tuple__ = version_tuple = (1, 2, 99)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.99}/boost_cli/cli.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import contextlib
 import difflib
 import importlib
+import os
 import sys
 import time
 
@@ -195,6 +196,9 @@ def print_help() -> None:
     else:
         print(usage)
         print("  " + detail)
+    print(out.c(
+        "Options:  -V/--version   -v/--verbose   --debug   -q/--quiet",
+        out.DIM))
 
     width = max(len(n) for n, _, _, _ in COMMANDS)
     for idx, (gkey, (_icon, title, desc)) in enumerate(GROUPS.items()):
@@ -220,6 +224,21 @@ def print_help() -> None:
 
 
 def print_command_help(name: str) -> int:
+    # `main`'s own aliases (-h/--help, -V/--version/version, help itself)
+    # never appear in COMMANDS, so `boost help --help` used to fall straight
+    # into `_unknown` and get difflib-guessed at an unrelated command
+    # (`--help` -> "heal", `version` -> "verify"). Resolve them the same way
+    # `main` does before treating the name as an unrecognized command.
+    if name in ("-h", "--help"):
+        print_help()
+        return 0
+    if name in ("-V", "--version", "version"):
+        print_version()
+        return 0
+    if name == "help":
+        print(out.c("boost help [COMMAND]", out.BOLD)
+              + " — show this index, or one command's own --help")
+        return 0
     meta = resolve(name)
     if not meta:
         return _unknown(name)
@@ -237,6 +256,13 @@ def _crash_hint(report) -> str:
 
 
 def _unknown(name: str) -> int:
+    # A dash-prefixed token is a mistyped flag, not a command guess — nothing
+    # in _BY_NAME is a plausible correction for e.g. `--hepl`, and guessing
+    # one anyway ("did you mean: heal?") reads as a wrong command suggestion
+    # rather than what actually happened.
+    if name.startswith("-"):
+        out.err("unknown option: %s" % name, hint="see `boost --help`")
+        return 2
     close = difflib.get_close_matches(name, list(_BY_NAME), n=3)
     out.err("unknown command: %s" % name,
             hint=("did you mean: %s?" % ", ".join(close)) if close
@@ -286,6 +312,102 @@ def _extract_globals(argv: list[str]) -> tuple[dict, list[str]]:
     return opts, argv[i:]
 
 
+def _seal_broken_stdout() -> None:
+    """Stop CPython's own exit-time flush from re-raising BrokenPipeError.
+
+    A downstream reader closing early (``boost --help | head``) does not
+    raise the moment boost prints — small writes fit the pipe's kernel buffer
+    and succeed silently, so the error only surfaces on the next explicit
+    flush. Left unhandled it surfaces on the *interpreter's own* final flush
+    of stdout at shutdown, which happens outside any of boost's try/except
+    blocks: Python prints "Exception ignored on flushing sys.stdout:
+    BrokenPipeError" straight to stderr and the process exits non-zero.
+    Redirecting the fd to devnull means that final flush lands somewhere
+    that cannot raise.
+    """
+    with contextlib.suppress(Exception):
+        sys.stdout.flush()
+    with contextlib.suppress(Exception):
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        try:
+            os.dup2(devnull, sys.stdout.fileno())
+        finally:
+            os.close(devnull)
+
+
+def _route(argv: list[str]) -> int:
+    try:
+        if not argv or argv[0] in ("-h", "--help"):
+            print_help()
+            return 0
+        if argv[0] in ("-V", "--version", "version"):
+            print_version()
+            return 0
+        if argv[0] == "help":
+            if len(argv) > 1:
+                return print_command_help(argv[1])
+            print_help()
+            return 0
+        name, rest = argv[0], argv[1:]
+        if name in _PLUMBING:
+            # Before the _BY_NAME guard (it is not a command) and before
+            # log_invocation: this runs on every TAB, and logging a line per
+            # keystroke would bury the diagnostic log in completion noise.
+            return _PLUMBING[name](rest)
+        if name not in _BY_NAME:
+            return _unknown(name)
+        logs.log_invocation([name, *rest])
+        start = time.perf_counter()
+        rc = 70  # assume the worst until a handler proves otherwise
+        try:
+            rc = _dispatch(name, rest)
+            return rc
+        except BoostError as e:
+            logs.get_logger().info("BoostError: %s", e.message)
+            rc = 1
+            out.err(e.message, hint=e.hint)
+            return rc
+        except KeyboardInterrupt:
+            logs.get_logger().debug("interrupted by user")
+            rc = 130
+            print()
+            return rc
+        except BrokenPipeError:
+            # Reclassify before `except Exception` below can mistake a
+            # closed pipe for a crash and write a spurious crash report.
+            rc = 0
+            return rc
+        except SystemExit as e:
+            # argparse (--help, usage errors) exits via SystemExit, which is
+            # a BaseException and so skips the `except Exception` below
+            # entirely — left uncaught, the trail journaled the preset rc=70
+            # for every benign --help and usage exit instead of the real 0
+            # or 2.
+            code = e.code
+            rc = 0 if code is None else code if isinstance(code, int) else 1
+            raise
+        except Exception as e:
+            report = logs.write_crash_report(e, [name, *rest])
+            if logs.is_debug():
+                raise
+            out.err("boost hit an unexpected error: %s: %s"
+                    % (type(e).__name__, e),
+                    hint=_crash_hint(report))
+            return 70  # EX_SOFTWARE
+        finally:
+            # Bookend every invocation with its exit code + duration, even
+            # when the --debug path re-raises the traceback above.
+            logs.log_completion([name, *rest], rc,
+                                (time.perf_counter() - start) * 1000)
+    finally:
+        # Force any buffered output through now, still inside `main`'s own
+        # BrokenPipeError handler below — a `--help`/`--version`/`count`
+        # write that merely fit the pipe's buffer never raised above, and
+        # would otherwise wait until the unhandled, uncatchable flush at
+        # interpreter shutdown to report the broken pipe.
+        sys.stdout.flush()
+
+
 def main(argv: list[str] | None = None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
     out.harden_console_encoding()
@@ -297,64 +419,12 @@ def main(argv: list[str] | None = None) -> int:
     opts, argv = _extract_globals(argv)
     logs.configure(verbose=opts["verbose"], debug=opts["debug"],
                    quiet=opts["quiet"])
-    if not argv or argv[0] in ("-h", "--help"):
-        print_help()
-        return 0
-    if argv[0] in ("-V", "--version", "version"):
-        print_version()
-        return 0
-    if argv[0] == "help":
-        if len(argv) > 1:
-            return print_command_help(argv[1])
-        print_help()
-        return 0
-    name, rest = argv[0], argv[1:]
-    if name in _PLUMBING:
-        # Before the _BY_NAME guard (it is not a command) and before
-        # log_invocation: this runs on every TAB, and logging a line per
-        # keystroke would bury the diagnostic log in completion noise.
-        return _PLUMBING[name](rest)
-    if name not in _BY_NAME:
-        return _unknown(name)
-    logs.log_invocation([name, *rest])
-    start = time.perf_counter()
-    rc = 70  # assume the worst until a handler proves otherwise
     try:
-        rc = _dispatch(name, rest)
-        return rc
-    except BoostError as e:
-        logs.get_logger().info("BoostError: %s", e.message)
-        rc = 1
-        out.err(e.message, hint=e.hint)
-        return rc
-    except KeyboardInterrupt:
-        logs.get_logger().debug("interrupted by user")
-        rc = 130
-        print()
-        return rc
+        return _route(argv)
     except BrokenPipeError:
-        with contextlib.suppress(Exception):
-            sys.stdout.close()
-        rc = 0
-        return rc
-    except SystemExit as e:
-        # argparse (--help, usage errors) exits via SystemExit, which is a
-        # BaseException and so skips the `except Exception` below entirely —
-        # left uncaught, the trail journaled the preset rc=70 for every
-        # benign --help and usage exit instead of the real 0 or 2.
-        code = e.code
-        rc = 0 if code is None else code if isinstance(code, int) else 1
-        raise
-    except Exception as e:
-        report = logs.write_crash_report(e, [name, *rest])
-        if logs.is_debug():
-            raise
-        out.err("boost hit an unexpected error: %s: %s"
-                % (type(e).__name__, e),
-                hint=_crash_hint(report))
-        return 70  # EX_SOFTWARE
-    finally:
-        # Bookend every invocation with its exit code + duration, even when the
-        # --debug path re-raises the traceback above.
-        logs.log_completion([name, *rest], rc,
-                            (time.perf_counter() - start) * 1000)
+        # Covers the early-return paths above (`--help`, `--version`,
+        # `help`, `__complete`) that have no try/except of their own, plus
+        # the final flush in `_route`'s own `finally` surfacing a pipe error
+        # the dispatch path's flush-free writes didn't.
+        _seal_broken_stdout()
+        return 0

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.99}/boost_cli/commands/_common.py

@@ -80,6 +80,7 @@ def _iter_installed(names: list[str] | None = None) -> list[tuple[str, dict]]:
     """
     skills = lockfile.installed()
     if names:
+        names = list(dict.fromkeys(names))  # order-preserving dedupe
         missing, other_kind = [], []
         for n in names:
             if n in skills:
@@ -118,6 +119,7 @@ def _iter_installed_all(
         names: list[str] | None = None) -> list[tuple[str, str, dict]]:
     """[(kind, name, lock_entry)] across every section, or the given names."""
     if names:
+        names = list(dict.fromkeys(names))  # order-preserving dedupe
         out, missing = [], []
         for n in names:
             found = lockfile.find_any(n)

{boost_skill_cli-1.2.97 → boost_skill_cli-1.2.99}/boost_cli/commands/configuration.py

@@ -125,13 +125,21 @@ def cmd_config(argv) -> int:
                                  "`boost config unset` it first") from e
         val = config.get(args.key)
         journal.log("config", args.key, op="set")
+        if args.json:
+            print(json.dumps({"key": args.key, "value": val}))
+            return 0
         out.ok("set %s = %s"
                % (args.key, val if isinstance(val, str) else json.dumps(val)))
         return 0
 
     # unset
-    if config.unset(args.key):
+    was_set = config.unset(args.key)
+    if was_set:
         journal.log("config", args.key, op="unset")
+    if args.json:
+        print(json.dumps({"key": args.key, "unset": was_set}))
+        return 0
+    if was_set:
         out.ok("unset %s" % args.key)
     else:
         out.info("%s not set" % args.key)
@@ -512,6 +520,9 @@ def cmd_policy(argv) -> int:
         pol[args.key] = _parse_policy_value(args.key, args.value)
         policy.save(pol)
         journal.log("policy", args.key, op="set")
+        if args.json:
+            print(json.dumps({"key": args.key, "value": pol[args.key]}))
+            return 0
         out.ok("set %s = %s" % (args.key, json.dumps(pol[args.key])))
         return 0
 
@@ -520,6 +531,9 @@ def cmd_policy(argv) -> int:
         pol[args.key] = policy.DEFAULTS[args.key]
         policy.save(pol)
         journal.log("policy", args.key, op="unset")
+        if args.json:
+            print(json.dumps({"key": args.key, "value": policy.DEFAULTS[args.key]}))
+            return 0
         out.ok("reset %s to default (%s)"
                % (args.key, json.dumps(policy.DEFAULTS[args.key])))
         return 0
@@ -529,7 +543,9 @@ def cmd_policy(argv) -> int:
     everything = lockfile.all_installed()
     min_score = int(pol.get("min_quality_score") or 0)
     violations = []  # (name, problem)
+    not_checked: set[str] = set()
     total = 0
+    skill_count = len(everything.get("skill", {}))
     for kind, section in everything.items():
         for name, entry in sorted(section.items()):
             total += 1
@@ -541,12 +557,36 @@ def cmd_policy(argv) -> int:
                 violations.append((label, "tap %s is blocked" % tap))
             if pol["allowed_taps"] and tap not in pol["allowed_taps"] and tap != "local":
                 violations.append((label, "tap %s is not on the allowlist" % tap))
+            violations.extend(
+                (label, msg) for msg in policy.check_installed_version(entry))
+            # require_description and denied_capabilities need the item's
+            # own content, which only a skill has on disk (see
+            # store.read_skill_meta) — a rule or workflow lands in a shared
+            # agent file with no per-item body to check.
+            if kind == "skill" and (pol["require_description"] or pol["denied_capabilities"]):
+                meta_body = store.read_skill_meta(name)
+                if meta_body is None:
+                    not_checked.add(
+                        "require_description/denied_capabilities "
+                        "(store copy unreadable)")
+                else:
+                    meta, body = meta_body
+                    violations.extend(
+                        (label, msg)
+                        for msg in policy.check_installed_meta(meta, body))
+            elif kind != "skill" and (pol["require_description"] or pol["denied_capabilities"]):
+                not_checked.add(
+                    "require_description/denied_capabilities for %s items "
+                    "(no on-disk body to check)" % kind)
             # Quality scoring reads a store directory, which only skills have.
             if min_score and kind == "skill":
                 score, _notes = util.score_skill(store.skill_store_dir(name))
                 if score < min_score:
                     violations.append(
                         (label, "quality score %d < required %d" % (score, min_score)))
+    max_skills_msg = policy.max_skills_violation(skill_count)
+    if max_skills_msg:
+        violations.append(("(environment)", max_skills_msg))
     unpinned = sorted(
         n if k == "skill" else "%s (%s)" % (n, k)
         for k, section in everything.items()
@@ -560,6 +600,8 @@ def cmd_policy(argv) -> int:
                else ", ".join("%d %s%s" % (n, kind, _s(n))
                               for kind, n in counts.items()))
 
+    enforce = config.get("policy_enforce", True)
+
     if args.json:
         print(json.dumps({
             # "skills" keeps its original meaning — the skill count — with the
@@ -570,14 +612,23 @@ def cmd_policy(argv) -> int:
             "violations": [{"skill": s, "violation": v} for s, v in violations],
             "pin_only": bool(pol["pin_only"]),
             "unpinned": unpinned if pol["pin_only"] else [],
+            "enforce": enforce,
+            "not_checked": sorted(not_checked),
         }, indent=2))
         return 1 if violations else 0
 
     _warn_invalid_policy_values()
+    if not enforce:
+        out.warn("policy_enforce is off — `boost install` does not enforce "
+                 "any of the rules below; this report names what would be "
+                 "flagged, not what is currently blocked")
     if pol["pin_only"]:
-        out.info("pin-only mode is on — installs/updates are frozen"
+        out.info("pin-only mode is on — new installs and skill updates are "
+                 "frozen (tap refreshes via `boost update` are unaffected)"
                  + (" (%d unpinned item(s): %s)"
                     % (len(unpinned), ", ".join(unpinned)) if unpinned else ""))
+    for note in sorted(not_checked):
+        out.dim("  not checked: %s" % note)
     if violations:
         out.table(violations, headers=("ITEM", "VIOLATION"))
         print()
@@ -960,6 +1011,21 @@ def _interval_label(seconds) -> str:
     return "%ss" % seconds
 
 
+def _plist_interval_seconds(text: str) -> int | None:
+    """Parse a usable ``StartInterval`` out of plist ``text``.
+
+    None for both "no ``StartInterval`` key" and "``StartInterval`` present
+    but not positive" — a zero or negative interval can never fire, and
+    treating it as usable is what let the next-run loop in ``cmd_schedule``
+    spin forever advancing ``nxt`` by zero seconds each pass.
+    """
+    m = re.search(r"<key>StartInterval</key>\s*<integer>(-?\d+)</integer>", text)
+    if not m:
+        return None
+    secs = int(m.group(1))
+    return secs if secs > 0 else None
+
+
 def cmd_schedule(argv) -> int:
     """boost schedule [status|enable [--interval 6h|12h|daily]|disable]"""
     p = cliparse.parser(
@@ -985,10 +1051,8 @@ def cmd_schedule(argv) -> int:
             plist = _plist_path()
             if plist.exists():
                 present = True
-                m = re.search(r"<key>StartInterval</key>\s*<integer>(\d+)</integer>",
-                              plist.read_text(encoding="utf-8"))
-                if m:
-                    secs = int(m.group(1))
+                secs = _plist_interval_seconds(plist.read_text(encoding="utf-8"))
+                if secs is not None:
                     interval = _interval_label(secs)
                     nxt = datetime.fromtimestamp(plist.stat().st_mtime + secs)
                     while nxt < datetime.now():
@@ -1015,7 +1079,8 @@ def cmd_schedule(argv) -> int:
         out.kv("platform", "%s (%s)" % (sys.platform, "launchd" if darwin else "cron"))
         out.kv("scheduled", "yes" if present else "no")
         if present:
-            out.kv("interval", "every %s" % interval)
+            out.kv("interval", "every %s" % interval if interval is not None
+                   else "unknown (plist has no usable StartInterval)")
             out.kv("next run", next_run.strftime("%Y-%m-%d %H:%M (approx)")
                    if next_run else "unknown")
         else:
@@ -1639,29 +1704,26 @@ def _mcp_tool(tool: str, args: dict):
     return REGISTRY.call(tool, args)
 
 
-#: Substrings an agent CLI uses to say "this server is already registered".
-#: Registering twice is not a failure — it is the state the user asked for —
-#: and treating it as one is what made `--host auto` abort on host one and
-#: never reach host two on any machine where boost was already in Claude.
-_ALREADY = ("already exists", "already registered", "already configured")
-
-
 def _run_mcp_host(host: str, action: str, cmd) -> tuple[str, str]:
     """Run one host's register/unregister argv.
 
     Returns ``(status, detail)`` where status is:
 
-    * ``"ran"``      — the CLI ran and succeeded;
-    * ``"already"``  — it reported the server is already in the state asked
-      for, which is success with a different wording;
-    * ``"missing"``  — the CLI is not installed. Not an error: most machines
-      have one agent CLI, not all of them;
-    * ``"failed"``   — it is installed and something else went wrong.
+    * ``"ran"``            — the CLI ran and did what was asked;
+    * ``"already"``        — register reported the server is already in that
+      state, which is success with a different wording;
+    * ``"not_registered"`` — unregister reported there was nothing to remove,
+      likewise success with a different wording;
+    * ``"missing"``        — the CLI is not installed. Not an error: most
+      machines have one agent CLI, not all of them;
+    * ``"failed"``         — it is installed and something else went wrong.
 
     It **returns** rather than raises so one host cannot end the sweep. That
     was the bug: a present CLI exiting non-zero raised straight out of the
     loop, so with boost already registered in Claude, `--host auto` died on
-    "already exists" and never reached the second agent.
+    "already exists" and never reached the second agent. The text
+    classification itself lives in :func:`mcphost.classify_result`, which is
+    pure and mutation-tested without a real agent CLI on PATH.
     """
     exe = mcphost.cli(host)
     if not shutil.which(exe):
@@ -1672,13 +1734,8 @@ def _run_mcp_host(host: str, action: str, cmd) -> tuple[str, str]:
         return "failed", str(e)
     for ln in (proc.stdout or "").strip().splitlines():
         out.info(ln)
-    if proc.returncode == 0:
-        return "ran", ""
-    blob = ((proc.stderr or "") + (proc.stdout or "")).lower()
-    if action == "register" and any(k in blob for k in _ALREADY):
-        return "already", ""
-    tail = (proc.stderr or "").strip().splitlines()
-    return "failed", tail[-1] if tail else "unknown error"
+    return mcphost.classify_result(action, proc.returncode,
+                                   proc.stdout, proc.stderr)
 
 
 def _seed_catalog_for_mcp(force: bool) -> None:
@@ -1787,7 +1844,7 @@ def _offer_boost_first(hosts: list[str]) -> None:
 
 
 def cmd_mcp(argv) -> int:
-    """boost mcp [register|unregister] [--host H] [--stdio] [--seed|--no-seed]"""
+    """boost mcp [register|unregister] [--host H] [--stdio] [--seed|--no-seed] [--dry-run]"""
     p = cliparse.parser(
         prog="boost mcp",
         description="Register boost as an MCP server for your agent CLIs")
@@ -1800,6 +1857,9 @@ def cmd_mcp(argv) -> int:
                         % ", ".join(mcphost.hosts()))
     p.add_argument("--stdio", action="store_true",
                    help="run the MCP server on stdin/stdout (used by the agent)")
+    p.add_argument("--dry-run", action="store_true",
+                   help="print the resolved command and install status per "
+                        "host; register or tap nothing")
     # Mutually exclusive: `--seed --no-seed` used to resolve silently to the
     # network-touching side, which is the wrong way for an ambiguous pair of
     # explicitly typed flags to break.
@@ -1821,6 +1881,25 @@ def cmd_mcp(argv) -> int:
         raise BoostError("unknown MCP host %r" % args.host,
                         hint="known hosts: %s" % ", ".join(mcphost.hosts())) from e
 
+    shim = str(paths.launcher())
+    verb = "register" if args.action == "register" else "unregister"
+
+    if args.dry_run:
+        # Before seeding and before any subprocess runs — the flag exists so
+        # the argv boost would run is visible in the one case that mattered
+        # (`--host gemini` with `gemini` on PATH), not only the one case that
+        # was already visible for free (the CLI missing entirely).
+        for host in targets:
+            installed = shutil.which(mcphost.cli(host)) is not None
+            cmd = mcphost.argv(host, args.action, shim)
+            out.info("%s %s: %s" % (
+                mcphost.label(host),
+                out.role("(installed)" if installed else "(not installed)",
+                         "muted"),
+                " ".join(cmd)))
+        out.dim("  dry run — nothing was %sed, nothing tapped" % verb)
+        return 0
+
     # After the host name is validated and before anything is registered. The
     # ordering is not cosmetic in either direction: seeding first meant a
     # typo'd `--host` spent 14-45s and half a gigabyte before argparse's own
@@ -1829,12 +1908,14 @@ def cmd_mcp(argv) -> int:
     if args.action == "register" and (args.seed_ok or args.seed):
         _seed_catalog_for_mcp(args.seed)
 
-    shim = str(paths.launcher())
     # `auto` skips hosts that are not installed; naming a host explicitly (or
     # `all`) always reports it, so a user setting up a machine can see the argv
-    # for an agent CLI they have not installed yet.
+    # for an agent CLI they have not installed yet. `named` is narrower than
+    # `explicit`: it excludes `all`, which — like `auto` — deliberately shows
+    # every host's argv without treating "not installed" as a failure.
     explicit = args.host not in (None, "", "auto")
-    done, already, missing, failed = [], [], [], {}
+    named = mcphost.is_named(args.host)
+    done, already, not_registered, missing, failed = [], [], [], [], {}
     for host in targets:
         cmd = mcphost.argv(host, args.action, shim)
         status, detail = _run_mcp_host(host, args.action, cmd)
@@ -1842,6 +1923,8 @@ def cmd_mcp(argv) -> int:
             done.append(host)
         elif status == "already":
             already.append(host)
+        elif status == "not_registered":
+            not_registered.append(host)
         elif status == "failed":
             # Collected, not raised: the next host is a different agent on a
             # different config file and has nothing to do with this failure.
@@ -1853,7 +1936,6 @@ def cmd_mcp(argv) -> int:
                          % mcphost.cli(host))
                 out.info(" ".join(cmd))
 
-    verb = "register" if args.action == "register" else "unregister"
     for host in done:
         # agy has no scopes — one global file — so claiming "(scope: user)"
         # would describe a distinction its CLI does not have.
@@ -1863,6 +1945,8 @@ def cmd_mcp(argv) -> int:
     for host in already:
         out.ok("already registered with %s — nothing to do"
                % mcphost.label(host))
+    for host in not_registered:
+        out.ok("%s: not registered — nothing to do" % mcphost.label(host))
     for host, detail in failed.items():
         out.warn("%s: %s mcp %s failed — %s"
                  % (mcphost.label(host), mcphost.cli(host), args.action,
@@ -1870,7 +1954,7 @@ def cmd_mcp(argv) -> int:
         out.info(out.role("run it yourself: %s"
                           % " ".join(mcphost.argv(host, args.action, shim)),
                           "muted"))
-    settled = done + already
+    settled = done + already + not_registered
     if not settled:
         if failed:
             # Every installed CLI failed. That is a real error — but only after
@@ -1885,7 +1969,10 @@ def cmd_mcp(argv) -> int:
             for host in missing:
                 out.info(" ".join(mcphost.argv(host, args.action, shim)))
         journal.log("mcp", args.action, hosts="")
-        return 0
+        # A single named host whose CLI is missing is a no-op, not a success:
+        # `--host all` and `auto` both tolerate an absent CLI by design (see
+        # `mcphost.is_named`), so only a one-host request fails here.
+        return 1 if named else 0
     if args.action == "register":
         _offer_boost_first(settled)
     journal.log("mcp", args.action, hosts=",".join(settled))