@event4u/agent-config 4.9.0 → 5.0.0

package/scripts/hooks/dispatch_issues.py

@@ -0,0 +1,136 @@
+"""Append-only log of dispatch-time issues — Phase 1 of `road-to-hooks-actually-fire-in-consumers`.
+
+When a concern's resolver returns `None` (script missing, regenerator
+missing, `./agent-config` symlink unresolvable) the dispatcher (or the
+concern hook itself, when invoked as a subprocess) records ONE line in
+`agents/runtime/state/dispatch-issues.jsonl` so the failure is
+discoverable post-hoc instead of vanishing into the never-block
+contract.
+
+**Schema** (locked by Council R3 pre-check, 2026-05-29):
+
+    {
+      "timestamp": "<ISO-8601 UTC>",
+      "hook":      "<concern-id>",
+      "issue":     "prerequisite_missing | script_not_found | "
+                   "permission_denied | execution_failed",
+      "detail":    "<freeform one-line explanation>",
+      "resolution": "<one-line command or doc link>"
+    }
+
+**Cap:** 200 entries (council-revised from the original 50; debug
+sessions with many tool calls would have lost evidence at the old
+cap). Rotation drops the oldest line.
+
+Errors writing the log are swallowed — observability never breaks
+the agent loop.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+
+LOG_CAP = 200
+
+VALID_ISSUE = frozenset({
+    "prerequisite_missing",
+    "script_not_found",
+    "permission_denied",
+    "execution_failed",
+})
+
+
+def _utc_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds").replace(
+        "+00:00", "Z"
+    )
+
+
+def _log_path(workspace_root: Path) -> Path:
+    return Path(workspace_root) / "agents" / "runtime" / "state" / "dispatch-issues.jsonl"
+
+
+def log_dispatch_issue(
+    workspace_root: Path,
+    hook: str,
+    issue: str,
+    detail: str,
+    resolution: str,
+) -> None:
+    """Append one dispatch-issue line. Best-effort; never raises.
+
+    No-op when `AGENT_CONFIG_REPLAY=1` is set — fixture-driven replay
+    must not mutate state (contract: `docs/contracts/hook-architecture-v1.md`
+    § Replay mode).
+    """
+    if os.environ.get("AGENT_CONFIG_REPLAY") == "1":
+        return
+
+    if issue not in VALID_ISSUE:
+        # Schema violation is a bug in the caller, not a runtime
+        # failure — surface on stderr so it's noticed during dev, but
+        # do not crash.
+        sys.stderr.write(
+            f"dispatch_issues: invalid issue {issue!r} (valid: "
+            f"{sorted(VALID_ISSUE)})\n"
+        )
+        return
+
+    log = _log_path(workspace_root)
+    entry = {
+        "timestamp": _utc_iso(),
+        "hook": str(hook),
+        "issue": issue,
+        "detail": str(detail),
+        "resolution": str(resolution),
+    }
+
+    try:
+        log.parent.mkdir(parents=True, exist_ok=True)
+        # Read existing lines (cheap — bounded log).
+        existing: list[str] = []
+        if log.exists():
+            try:
+                existing = log.read_text(encoding="utf-8").splitlines()
+            except OSError:
+                existing = []
+        existing.append(json.dumps(entry, ensure_ascii=False))
+        # Cap rotation: drop the oldest entries.
+        if len(existing) > LOG_CAP:
+            existing = existing[-LOG_CAP:]
+        log.write_text("\n".join(existing) + "\n", encoding="utf-8")
+    except OSError as exc:
+        # Observability never blocks the agent.
+        sys.stderr.write(
+            f"dispatch_issues: failed to append to {log}: {exc}\n"
+        )
+
+
+def read_dispatch_issues(workspace_root: Path) -> list[dict]:
+    """Return the log as a list of dicts. Empty list when missing."""
+    log = _log_path(workspace_root)
+    if not log.exists():
+        return []
+    out: list[dict] = []
+    try:
+        for line in log.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    except OSError:
+        return []
+    return out
+
+
+def fix_hint(workspace_root: Optional[Path] = None) -> str:
+    """Best-known fix hint string. Returned for use in `resolution` field."""
+    return "./agent-config init"

package/scripts/hooks_doctor.py

@@ -111,16 +111,41 @@ def collect(project_root: Path, manifest: dict,
             "missing": needs_trampoline and not tpath.is_file(),
         })
 
+    # Phase 1 of road-to-hooks-actually-fire-in-consumers: surface
+    # the dispatch-issues log so users see hooks that tried and failed.
+    state_root = REPO_ROOT / STATE_DIR_DEFAULT
+    issues: list[dict] = []
+    try:
+        sys.path.insert(0, str(REPO_ROOT / "scripts" / "hooks"))
+        from dispatch_issues import read_dispatch_issues  # noqa: PLC0415
+        issues = read_dispatch_issues(REPO_ROOT)[-20:]  # last 20
+    except (ImportError, OSError):
+        issues = []
+
     return {
         "schema_version": 1,
         "platforms": matrix["platforms"],
         "concerns": concerns,
         "trampolines": trampolines,
+        "dispatch_issues": issues,
     }
 
 
 def _render_table(payload: dict) -> str:
-    lines: list[str] = [hooks_status._render_table(payload), ""]
+    lines: list[str] = []
+    # Phase 1 CTA — surfaces at the TOP when issues exist, so a user
+    # reading the report can't miss it.
+    if payload.get("dispatch_issues"):
+        n = len(payload["dispatch_issues"])
+        lines.append(
+            f"⚠️  Hooks tried to fire but couldn't ({n} entry"
+            f"{'ies' if n != 1 else 'y'} in dispatch-issues.jsonl) — "
+            "run `./agent-config hooks:install --claude --regen` "
+            "(or follow the per-concern hints below)"
+        )
+        lines.append("")
+    lines.append(hooks_status._render_table(payload))
+    lines.append("")
     lines.append("Concerns")
     lines.append("-" * 60)
     for c in payload["concerns"]:
@@ -138,6 +163,20 @@ def _render_table(payload: dict) -> str:
         marker = "❌ " if t["missing"] else ("·  " if not t["required"] else "✅ ")
         suffix = "" if t["required"] else "  (not required)"
         lines.append(f"{marker}{t['platform']:<9} {t['expected']}{suffix}")
+    # Dispatch-issues detail — last 20 grouped by concern.
+    if payload.get("dispatch_issues"):
+        lines.append("")
+        lines.append("Dispatch issues (last 20)")
+        lines.append("-" * 60)
+        grouped: dict[str, list[dict]] = {}
+        for entry in payload["dispatch_issues"]:
+            grouped.setdefault(entry.get("hook", "?"), []).append(entry)
+        for hook, entries in sorted(grouped.items()):
+            lines.append(f"⚠️  {hook}: {len(entries)} issue(s)")
+            # Show the most recent reason + resolution per concern.
+            latest = entries[-1]
+            lines.append(f"    {latest.get('issue')}: {latest.get('detail')}")
+            lines.append(f"    fix → {latest.get('resolution')}")
     return "\n".join(lines)
 
 

package/scripts/install.py

@@ -3009,13 +3009,14 @@ CONSUMER_BRIDGE_MARKER_RELPATH = Path("agents") / ".event4u-bridge.yml"
 
 
 # ---------------------------------------------------------------------------
-# Phase 5.2 — migrate-to-global first-run hook
+# First-run migration hook
 # ---------------------------------------------------------------------------
 #
 # Legacy artefacts that signal a pre-ADR-020 install in the project root.
-# Same surface the ``migrate-to-global`` command detects (see
-# ``scripts/_cli/cmd_migrate_to_global.py``). Kept in sync intentionally so
-# the prompt and the migration tool agree on what counts as "legacy".
+# Same surface the unified ``migrate`` command detects (see
+# ``scripts/_cli/cmd_migrate.py`` and ``docs/contracts/migrate-command.md``).
+# Kept in sync intentionally so the prompt and the migration tool agree on
+# what counts as "legacy".
 MIGRATE_LEGACY_YAML_FILES = (".agent-settings.yml", ".agent-user.yml")
 MIGRATE_LEGACY_TOOL_DIRS = (".augment", ".claude", ".cursor")
 
@@ -3125,19 +3126,22 @@ def _detect_legacy_for_migration(project_root: Path) -> list[str]:
 
 
 def _prompt_migrate_to_global(project_root: Path, artefacts: list[str]) -> bool:
-    """Ask the user whether to run ``migrate-to-global`` now.
+    """Ask the user whether to run the unified ``migrate`` command now.
 
     Interactive TTY → ``[Y/n]`` prompt (Enter = yes). Non-interactive (CI
-    or no TTY) → auto-yes per roadmap Phase 5.2 contract. Three invalid
-    replies short-circuit to "no" (defensive, never blocks the install).
+    or no TTY) → auto-yes. Three invalid replies short-circuit to "no"
+    (defensive, never blocks the install). The function name is kept for
+    compatibility with the install flow; the legacy ``migrate-to-global``
+    command was collapsed into the unified ``migrate`` (see
+    ``docs/contracts/migrate-command.md``).
     """
     if not QUIET:
         print()
         warn("Legacy project-local artefacts detected — pre-ADR-020 layout:")
         for rel in artefacts:
             info(f"  {project_root / rel}")
-        info("ADR-020 ships consumer installs as global-only.")
-        info("`agent-config migrate-to-global` copies → verifies → moves them safely.")
+        info("The unified `agent-config migrate` sweeps these in one pass.")
+        info("The wizard recreates fresh config afterwards.")
 
     if not _is_interactive():
         if not QUIET:
@@ -3147,7 +3151,7 @@ def _prompt_migrate_to_global(project_root: Path, artefacts: list[str]) -> bool:
     attempts = 0
     while attempts < 3:
         try:
-            reply = _read_line("Run `agent-config migrate-to-global` now? [Y/n]: ")
+            reply = _read_line("Run `agent-config migrate` now? [Y/n]: ")
         except EOFError:
             return False
         if reply == "" or reply.lower() in ("y", "yes"):
@@ -3160,23 +3164,22 @@ def _prompt_migrate_to_global(project_root: Path, artefacts: list[str]) -> bool:
 
 
 def _run_migrate_to_global(project_root: Path) -> int:
-    """Invoke ``cmd_migrate_to_global._do_migrate`` against ``project_root``.
+    """Invoke the unified ``cmd_migrate`` against ``project_root``.
 
     Returns the migrator's exit code so the caller can abort the install
-    on failure. The perms gate is skipped because the install path runs
-    its own checks; surfacing two perm errors back-to-back would be
-    confusing for first-run users.
+    on failure. The function name is kept for compatibility with the
+    install flow; the legacy ``migrate-to-global`` command was collapsed
+    into the unified ``migrate`` (see ``docs/contracts/migrate-command.md``).
     """
     import importlib  # noqa: PLC0415 — local to keep startup lean.
 
     try:
-        cmd_mod = importlib.import_module("scripts._cli.cmd_migrate_to_global")
+        cmd_mod = importlib.import_module("scripts._cli.cmd_migrate")
     except ImportError as exc:
-        warn(f"migrate-to-global unavailable: {exc}")
+        warn(f"migrate unavailable: {exc}")
         return 1
 
-    install_mod = sys.modules[__name__]
-    return cmd_mod._do_migrate(project_root, force=False, install_mod=install_mod, out=sys.stdout)
+    return cmd_mod.main([], cwd=project_root, out=sys.stdout)
 
 
 def _format_global_root_for_marker(global_root: Path) -> str:
@@ -4976,9 +4979,10 @@ def main(argv: list[str]) -> int:
 
     try:
         if scope == "global":
-            # Phase 5.2 — first-run hook: when legacy artefacts live in the
-            # project tree, prompt before laying down the global surface so
-            # the user is not left with a dual-stack install.
+            # First-run hook: when legacy artefacts live in the project tree,
+            # prompt before laying down the global surface so the user is
+            # not left with a dual-stack install. Delegates to the unified
+            # `agent-config migrate` (see docs/contracts/migrate-command.md).
             artefacts = _detect_legacy_for_migration(detect_root)
             if artefacts and _prompt_migrate_to_global(detect_root, artefacts):
                 rc = _run_migrate_to_global(detect_root)

package/scripts/lint_agents_layout.py

@@ -72,10 +72,11 @@ CONSUMER_EXPECTED_ENTRIES: frozenset[str] = frozenset(
 )
 
 MIGRATE_HINT = (
-    "Run `agent-config settings migrate` (or `npx @event4u/agent-config "
-    "migrate-to-global`) to move legacy project-scope artefacts under "
-    "`~/.event4u/agent-config/` and leave `agents/overrides/` + "
-    "`agents/.event4u-bridge.yml` as the only consumer-side files."
+    "Run `npx @event4u/agent-config migrate` to sweep legacy project-scope "
+    "artefacts in one pass. The unified `migrate` command (see "
+    "`docs/contracts/migrate-command.md`) leaves `agents/overrides/` + "
+    "`agents/.event4u-bridge.yml` as the only consumer-side files; the "
+    "wizard recreates fresh config on `agent-config setup`."
 )
 
 

package/scripts/lint_bench_corpus.py

@@ -23,6 +23,7 @@ Flags:
 """
 from __future__ import annotations
 
+import json
 import re
 import sys
 from pathlib import Path
@@ -38,6 +39,8 @@ REQUIRE_FULL = "--require-full" in sys.argv
 
 REPO = Path(__file__).resolve().parents[1]
 CORPUS_DIR = REPO / "tests" / "eval"
+ROUTER_COVERAGE_DIR = REPO / "internal" / "bench" / "corpora" / "router-coverage"
+ROUTER_JSON = REPO / "dist" / "router.json"
 
 # Live skill directories live under every artefact root post-monorepo
 # Phase 4 (legacy + packages/*/.agent-src.uncondensed/skills/).
@@ -46,7 +49,7 @@ from _lib.agent_src import artefact_roots  # noqa: E402
 
 SKILLS_DIRS = [root / "skills" for root in artefact_roots() if (root / "skills").is_dir()]
 
-VALID_CATEGORIES = frozenset({"canonical", "ambiguous", "destructive", "long-context"})
+VALID_CATEGORIES = frozenset({"canonical", "ambiguous", "destructive", "long-context", "router-coverage"})
 # Non-dev corpus (pre-spec) uses legacy categories — accept them so the
 # new linter does not break that file. Migration is a follow-up.
 LEGACY_CATEGORIES = frozenset({"content", "consulting", "finance", "ops", "safety"})
@@ -66,7 +69,40 @@ def live_skills() -> set[str]:
     return slugs
 
 
-def lint_corpus(path: Path, skills: set[str]) -> list[str]:
+def live_rule_ids() -> set[str] | None:
+    """Return all rule ids known to dist/router.json (kernel + tier_1 + tier_2).
+
+    Returns ``None`` (not an empty set) when the router is missing or
+    unparseable, signalling "cannot validate rule ids — skip the
+    unknown-trigger checks" rather than "every referenced id is unknown".
+    A missing router is expected on a fresh clone before ``task sync``;
+    returning an empty set there would falsely flag every intended /
+    opaque trigger as ``unknown_intended_trigger``.
+    """
+    if not ROUTER_JSON.exists():
+        sys.stderr.write(
+            f"warning: {ROUTER_JSON.relative_to(REPO)} missing — skipping "
+            "trigger rule-id validation (run `task sync` to generate it)\n"
+        )
+        return None
+    try:
+        data = json.loads(ROUTER_JSON.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        sys.stderr.write(
+            f"warning: {ROUTER_JSON.relative_to(REPO)} unparseable — "
+            "skipping trigger rule-id validation\n"
+        )
+        return None
+    ids: set[str] = set()
+    ids.update(data.get("kernel", []) or [])
+    for tier in ("tier_1", "tier_2"):
+        ids.update(
+            r.get("id") for r in (data.get(tier, []) or []) if r.get("id")
+        )
+    return ids
+
+
+def lint_corpus(path: Path, skills: set[str], rule_ids: set[str] | None = None) -> list[str]:
     errors: list[str] = []
     try:
         data = yaml.safe_load(path.read_text(encoding="utf-8"))
@@ -121,7 +157,12 @@ def lint_corpus(path: Path, skills: set[str]) -> list[str]:
             errors.append(f"{loc}: empty_prompt")
 
         expected = p.get("expected_skills") or []
-        if not isinstance(expected, list) or not expected:
+        if not isinstance(expected, list):
+            errors.append(f"{loc}: bad_expected_shape")
+        elif not expected and cat != "router-coverage":
+            # router-coverage corpora can have empty expected_skills —
+            # the focus is rule-trigger activation, not skill selection.
+            # The intended_triggers field is the load-bearing assertion.
             errors.append(f"{loc}: empty_expected")
         else:
             for slug in expected:
@@ -133,6 +174,40 @@ def lint_corpus(path: Path, skills: set[str]) -> list[str]:
             if not isinstance(carve, list) or not carve:
                 errors.append(f"{loc}: missing_carve_out")
 
+        # router-coverage invariants (Council R3 honesty floor).
+        # A task's trigger prediction lives in two buckets:
+        #   intended_triggers      — deterministically replayable (keyword /
+        #                            phrase / command / path with supplied
+        #                            open_files or command context).
+        #   replay_opaque_triggers — fires at runtime only via an `intent`
+        #                            trigger (or a router coverage gap) the
+        #                            static replay cannot verify. Declared so
+        #                            the telemetry reports it separately, not
+        #                            as false `missed_intended` drift.
+        # router-coverage requires at least one bucket non-empty.
+        intended = p.get("intended_triggers")
+        opaque = p.get("replay_opaque_triggers")
+        intended_list = intended if isinstance(intended, list) else []
+        opaque_list = opaque if isinstance(opaque, list) else []
+
+        if intended is not None and not isinstance(intended, list):
+            errors.append(f"{loc}: bad_intended_triggers_shape")
+        if opaque is not None and not isinstance(opaque, list):
+            errors.append(f"{loc}: bad_replay_opaque_triggers_shape")
+
+        if cat == "router-coverage" and not intended_list and not opaque_list:
+            errors.append(f"{loc}: missing_intended_triggers")
+
+        # A rule belongs to exactly one bucket — both is a contradiction.
+        for rid in sorted(set(intended_list) & set(opaque_list)):
+            errors.append(f"{loc}: trigger_in_both_buckets: {rid}")
+
+        # Every referenced id (either bucket) must be a real router rule id.
+        if rule_ids is not None:
+            for rid in intended_list + opaque_list:
+                if rid not in rule_ids:
+                    errors.append(f"{loc}: unknown_intended_trigger: {rid}")
+
     if REQUIRE_FULL and not is_legacy:
         for bucket, want in FULL_COUNTS.items():
             have = bucket_counts.get(bucket, 0)
@@ -147,14 +222,21 @@ def main() -> int:
         sys.stderr.write(f"error: corpus dir missing: {CORPUS_DIR}\n")
         return 2
     corpora = sorted(CORPUS_DIR.glob("corpus-*.yaml"))
+    # Phase 2 of road-to-corpus-expansion-evidence-based-cuts adds a second
+    # corpus tree under internal/bench/corpora/router-coverage/. Linter scans
+    # both with the same invariants — router-coverage corpora additionally
+    # require `intended_triggers` per prompt.
+    if ROUTER_COVERAGE_DIR.is_dir():
+        corpora.extend(sorted(ROUTER_COVERAGE_DIR.glob("*.yaml")))
     if not corpora:
         sys.stderr.write("error: no corpora found\n")
         return 2
 
     skills = live_skills()
+    rule_ids = live_rule_ids()
     all_errors: list[str] = []
     for path in corpora:
-        errs = lint_corpus(path, skills)
+        errs = lint_corpus(path, skills, rule_ids)
         if errs:
             all_errors.extend(errs)
         elif not QUIET:

package/scripts/lint_global_paths.py

@@ -3,9 +3,10 @@
 
 Phase 5.0 / amendment A7 of road-to-global-only-install. Runs BEFORE
 any legacy snapshot write so a perms leak cannot be created by the
-migration itself: `agent-config migrate-to-global` is expected to call
-this script first, abort on any failure, and only then proceed with
-the copy → verify → move → bridge sequence.
+migration itself. Historically invoked by `agent-config migrate-to-global`;
+that command was collapsed into `agent-config migrate` (see
+`docs/contracts/migrate-command.md`). The audit now runs standalone via
+`agent-config doctor` or directly through this script.
 
 Policy source: scripts/expected_perms.json (parameterised so the policy
 can evolve without code changes).

package/scripts/lint_marketplace_install_completeness.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Lint that every command in `hooks/hooks.json` resolves to a real
+dispatcher subcommand in `scripts/_dispatch.bash`.
+
+Phase 6 of `road-to-hooks-actually-fire-in-consumers`.
+
+The linter checks **plugin-side completeness** — the package ships a
+valid `hooks.json` whose every command line points at a subcommand
+the dispatcher knows about. It does NOT check consumer-side
+scaffolding (that's the runtime `dispatch-issues.jsonl` log's job
+from Phase 1).
+
+This distinction is load-bearing — see Council R3 finding #1:
+"A valid plugin against an unscaffolded consumer is a PASS;
+the linter must not produce a false-positive on that state."
+
+Exit codes:
+  0 — every command resolves; clean.
+  1 — at least one command references an unknown subcommand.
+  2 — schema / file error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+HOOKS_JSON = REPO_ROOT / "hooks" / "hooks.json"
+DISPATCH_BASH = REPO_ROOT / "scripts" / "_dispatch.bash"
+
+
+# Map agent-config-cli subcommand → dispatcher function name. The
+# subcommand is what appears after `./agent-config <subcommand>` in
+# the hooks.json command line; the function is what's defined in
+# _dispatch.bash. The user-facing subcommand uses colons; the
+# function uses underscores (e.g. `dispatch:hook` → `cmd_dispatch_hook`).
+def subcommand_to_function(subcommand: str) -> str:
+    # Normalise: replace `:` and `-` with `_`.
+    sanitised = subcommand.replace(":", "_").replace("-", "_")
+    return f"cmd_{sanitised}"
+
+
+def load_hook_commands(hooks_path: Path) -> list[tuple[str, str]]:
+    """Return [(event_name, command_line)] for every hook entry."""
+    try:
+        data = json.loads(hooks_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise SystemExit(f"lint-marketplace-install: cannot read {hooks_path}: {exc}")
+
+    hooks = data.get("hooks") or {}
+    if not isinstance(hooks, dict):
+        raise SystemExit(f"lint-marketplace-install: {hooks_path} `hooks` is not an object")
+
+    out: list[tuple[str, str]] = []
+    for event, groups in hooks.items():
+        if not isinstance(groups, list):
+            continue
+        for group in groups:
+            if not isinstance(group, dict):
+                continue
+            for entry in group.get("hooks", []) or []:
+                if not isinstance(entry, dict):
+                    continue
+                cmd = entry.get("command")
+                if isinstance(cmd, str) and cmd.strip():
+                    out.append((str(event), cmd))
+    return out
+
+
+# Pattern: `"$CLAUDE_PROJECT_DIR"/agent-config <subcommand> [args...]`.
+# Accepts both quoted and bare CLAUDE_PROJECT_DIR.
+_CMD_RE = re.compile(
+    r'(?:"?\$\{?CLAUDE_PROJECT_DIR\}?"?/)?agent-config\s+([a-zA-Z0-9:_-]+)'
+)
+
+
+def extract_subcommand(command_line: str) -> str | None:
+    """Pull the agent-config subcommand out of a hooks.json command line."""
+    m = _CMD_RE.search(command_line)
+    if m:
+        return m.group(1)
+    return None
+
+
+def load_dispatcher_subcommands(dispatch_path: Path) -> set[str]:
+    """Return the set of subcommand identifiers the dispatcher knows.
+
+    Reads `cmd_<name>` function definitions from _dispatch.bash and
+    converts back to subcommand form (underscores → colons / hyphens
+    is ambiguous, so we keep BOTH forms in the set — `dispatch_hook`
+    AND `dispatch:hook` — so the linter accepts either).
+    """
+    try:
+        text = dispatch_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SystemExit(f"lint-marketplace-install: cannot read {dispatch_path}: {exc}")
+
+    out: set[str] = set()
+    for match in re.finditer(r"^cmd_([a-zA-Z0-9_]+)\(\)", text, flags=re.MULTILINE):
+        ident = match.group(1)
+        # Add the underscore form.
+        out.add(ident)
+        # Also add a colon-substituted variant — agent-config supports
+        # `:` in user-facing subcommand names; the function strips them
+        # to underscores. We accept either spelling on the hook side.
+        # First _ → `:`, the rest stay (heuristic; covers `dispatch:hook`,
+        # `mcp:render`, `hooks:install` etc.).
+        if "_" in ident:
+            head, _, tail = ident.partition("_")
+            out.add(f"{head}:{tail}")
+    return out
+
+
+def lint(hooks_path: Path = HOOKS_JSON, dispatch_path: Path = DISPATCH_BASH) -> int:
+    if not hooks_path.is_file():
+        sys.stderr.write(f"lint-marketplace-install: {hooks_path} not found\n")
+        return 2
+    if not dispatch_path.is_file():
+        sys.stderr.write(f"lint-marketplace-install: {dispatch_path} not found\n")
+        return 2
+
+    commands = load_hook_commands(hooks_path)
+    known = load_dispatcher_subcommands(dispatch_path)
+
+    issues: list[str] = []
+    checked = 0
+    for event, cmd in commands:
+        sub = extract_subcommand(cmd)
+        if sub is None:
+            issues.append(
+                f"  {event}: command does not reference `agent-config <subcommand>`: "
+                f"{cmd!r}"
+            )
+            continue
+        checked += 1
+        if sub not in known:
+            issues.append(
+                f"  {event}: unknown_dispatcher_subcommand: {sub!r} "
+                f"(not in scripts/_dispatch.bash)"
+            )
+
+    if issues:
+        try:
+            relative = hooks_path.resolve().relative_to(REPO_ROOT)
+        except ValueError:
+            relative = hooks_path
+        sys.stderr.write(
+            f"lint-marketplace-install: {len(issues)} issue(s) in {relative}:\n"
+        )
+        for line in issues:
+            sys.stderr.write(line + "\n")
+        return 1
+
+    print(
+        f"✅  lint-marketplace-install: {checked} hook command(s) checked, "
+        f"all resolve to known dispatcher subcommands."
+    )
+    return 0
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument(
+        "--hooks-json",
+        type=Path,
+        default=HOOKS_JSON,
+        help="Path to hooks/hooks.json (default: %(default)s)",
+    )
+    p.add_argument(
+        "--dispatch-bash",
+        type=Path,
+        default=DISPATCH_BASH,
+        help="Path to scripts/_dispatch.bash (default: %(default)s)",
+    )
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv if argv is not None else sys.argv[1:])
+    return lint(args.hooks_json, args.dispatch_bash)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())