Skip to content

hashgraph-online/awesome-codex-plugins / plugins/beastlabai/multi-llm-plugin/skills/multi-llm

multi-llm

Flagged

Orchestrate plan reviews, task generation, implementation and code reviews across several LLM CLIs in parallel, or ask every model one free-text question about a plan. Use when the user says: review my plan, multi-llm, run a code review, generate tasks from a plan, implement this plan, ask the models about my plan.

FileKindSize
SKILL.mdskill md4.0 KB
apply_code_fixes_orchestrator.pyscript56.6 KB
apply_commit_fixes_orchestrator.pyscript2.3 KB
apply_suggestions_orchestrator.pyscript4.5 KB
apply_task_suggestions_orchestrator.pyscript19.1 KB
ask_orchestrator.pyscript162.5 KB
assets/icons/Anthropic.svgother584 B
assets/icons/Codex.svgother1.3 KB
assets/icons/Copilot.svgother1.5 KB
assets/icons/Cursor.svgother793 B
assets/icons/GoogleGemini.svgother623 B
assets/icons/Goose.svgother3.2 KB
assets/icons/Kilocode.svgother531 B
assets/icons/MiniMax.pngbinary1.5 KB
assets/icons/Mistral.svgother717 B
assets/icons/MoonshotAI.svgother957 B
assets/icons/Nvidia.svgother2.4 KB
assets/icons/OhMyPi.svgother434 B
assets/icons/OpenAI.svgother1.7 KB
assets/icons/Opencode.svgother325 B
assets/icons/Pi.svgother440 B
assets/icons/Qwen.svgother1.7 KB
assets/icons/Zhipu.pngbinary442 B
assets/icons/xAI.svgother343 B
assets/omp/overlay.ymlconfig2.4 KB
check_workflow_prerequisites.pyscript74.5 KB
code_review_orchestrator.pyscript324.0 KB
display_decisions.pyscript9.8 KB
finalize_tracking.pyscript1.3 KB
full_workflow_orchestrator.pyscript58.8 KB
generate_tasks_orchestrator.pyscript44.2 KB
hosts/capabilities.yamlconfig49.9 KB
hosts/codex/plugin-skill.md.tmplother2.8 KB
hosts/codex/shim.md.tmplother7.3 KB
hosts/opencode/plugin-command.md.tmplother2.2 KB
hosts/opencode/shim.md.tmplother6.8 KB
hosts/render_capabilities.pyscript48.4 KB
hosts/snippets/poll-loop.mdmarkdown4.4 KB
hosts/snippets/uv-preflight.mdmarkdown2.2 KB
hosts/uv-missing.txtmarkdown1.5 KB
implement_orchestrator.pyscript156.0 KB
improve_code_orchestrator.pyscript1.6 KB
improve_commits_orchestrator.pyscript2.5 KB
improve_plan_orchestrator.pyscript1.6 KB
init_config.pyscript57.6 KB
instructions/apply-code-fixes.mdmarkdown52.0 KB
instructions/apply-commit-fixes.mdmarkdown10.3 KB
instructions/apply-suggestions.mdmarkdown48.2 KB
instructions/apply-task-suggestions.mdmarkdown53.9 KB
instructions/ask.mdmarkdown27.6 KB
instructions/full-workflow.mdmarkdown24.6 KB
instructions/generate-tasks.mdmarkdown18.1 KB
instructions/implement.mdmarkdown54.0 KB
instructions/improve-code.mdmarkdown25.0 KB
instructions/improve-commits.mdmarkdown24.8 KB
instructions/improve-plan.mdmarkdown26.2 KB
instructions/init-config.mdmarkdown6.6 KB
instructions/review-code.mdmarkdown43.5 KB
instructions/review-commits.mdmarkdown11.4 KB
instructions/review-plan.mdmarkdown38.4 KB
instructions/review-tasks.mdmarkdown37.8 KB
modes.pyscript58.8 KB
multi_llm.pyscript101.1 KB
prompts/ask.txtmarkdown948 B
prompts/code_review.txtmarkdown4.5 KB
prompts/commit_review.txtmarkdown6.2 KB
prompts/consolidate_suggestions.txtmarkdown3.1 KB
prompts/implementation_task.txtmarkdown1.4 KB
prompts/plan_review.txtmarkdown8.0 KB
prompts/task_review.txtmarkdown8.3 KB
providers.yamlconfig19.6 KB
pyproject.tomlmanifest6.8 KB
references/apply-write-executor.mdmarkdown3.0 KB
references/consolidation.mdmarkdown5.6 KB
references/host-capabilities.mdmarkdown13.5 KB
references/human-decision-batch.mdmarkdown17.2 KB
references/implement-prerequisites.mdmarkdown6.0 KB
references/implement-write-executor.mdmarkdown4.9 KB
references/interrupted-run-recovery.mdmarkdown3.1 KB
references/own-check.mdmarkdown4.3 KB
references/resume-detection.mdmarkdown8.5 KB
references/revalidation.mdmarkdown6.9 KB
references/review-code-apply-fixes.mdmarkdown4.3 KB
references/salvage-handling.mdmarkdown12.5 KB
references/summary-format.mdmarkdown10.0 KB
references/uv-check.mdmarkdown5.7 KB
references/wave-batching.mdmarkdown5.2 KB
review_commits_orchestrator.pyscript2.3 KB
review_plan_orchestrator.pyexecutablescript22.3 KB
review_tasks_orchestrator.pyscript10.7 KB
schemas/cascade_record.schema.jsonconfig6.6 KB
schemas/code_review_issues.schema.jsonconfig2.0 KB
schemas/consolidated.schema.jsonconfig6.8 KB
schemas/consolidation_batch.schema.jsonconfig3.7 KB
schemas/generated_tasks.schema.jsonconfig3.1 KB
schemas/host_capabilities.schema.jsonconfig38.3 KB
schemas/human_decision_verdicts.schema.jsonconfig2.6 KB
schemas/result_line.schema.jsonconfig10.1 KB
schemas/review_suggestions.schema.jsonconfig2.4 KB
schemas/state_file.schema.jsonconfig21.5 KB
schemas/status_file.schema.jsonconfig24.9 KB
schemas/status_json.schema.jsonconfig10.8 KB
schemas/subagent_tasks.schema.jsonconfig20.5 KB
schemas/task_decomposition.schema.jsonconfig1.2 KB
schemas/write_batch_result.schema.jsonconfig8.8 KB
templates/config/providers.override.yamlconfig17.2 KB
templates/consolidated_report_template.htmlother44.1 KB
templates/pr_report_template.htmlother181.2 KB
templates/report_template.htmlother67.5 KB
templates/shared/report_core.cssother4.1 KB
templates/shared/report_core.jsscript25.5 KB
update_plan_tasks.pyscript20.9 KB
utils/__init__.pyscript284 B
utils/advisory.pyscript4.8 KB
utils/apply_orchestrator_base.pyscript220.6 KB
utils/apply_output_helpers.pyscript10.9 KB
utils/apply_path_helpers.pyscript683 B
utils/apply_report.pyscript51.2 KB
utils/apply_selection_helpers.pyscript6.8 KB
utils/apply_suggestion_phase.pyscript11.7 KB
utils/atomic_io.pyscript12.9 KB
utils/attempt_classifier.pyscript31.4 KB
utils/backup.pyscript2.0 KB
utils/batch_done.pyscript79.2 KB
utils/batch_ledger.pyscript27.4 KB
utils/batch_prompt.pyscript29.3 KB
utils/batch_prompt_builder.pyscript12.2 KB
utils/batch_reply.pyscript32.9 KB
utils/cascade_archive.pyscript50.6 KB
utils/cascade_ledger.pyscript39.3 KB
utils/cascade_provenance.pyscript22.0 KB
utils/check_records.pyscript59.3 KB
utils/check_reply.pyscript9.5 KB
utils/check_tree.pyscript1.2 KB
utils/cli_common.pyscript91.2 KB
utils/cli_version_cache.pyscript14.0 KB
utils/clock.pyscript3.5 KB
utils/code_fix_batcher.pyscript30.6 KB
utils/codex_trust.pyscript12.9 KB
utils/commit_apply.pyscript73.3 KB
utils/commit_attribution.pyscript21.2 KB
utils/commit_brief.pyscript32.2 KB
utils/commit_front_door.pyscript81.6 KB
utils/commit_paths.pyscript18.0 KB
utils/commit_range.pyscript61.2 KB
utils/commit_report.pyscript19.9 KB
utils/commit_review.pyscript413 B
utils/commit_spelling.pyscript7.9 KB
utils/commit_write_guard.pyscript9.9 KB
utils/concurrency.pyscript11.6 KB
utils/consolidation.pyscript87.3 KB
utils/detach.pyscript186.8 KB
utils/dispatch_spawn.pyscript56.3 KB
utils/doctor.pyscript76.7 KB
utils/env_vars.pyscript20.5 KB
utils/failure_capture.pyscript10.1 KB
utils/file_discovery.pyscript11.0 KB
utils/filtering.pyscript19.9 KB
utils/git_diff.pyscript23.6 KB
utils/git_utils.pyscript86.6 KB
utils/held_folder.pyscript21.3 KB
utils/host_capabilities.pyscript48.0 KB
utils/host_install.pyscript77.6 KB
utils/host_paths.pyscript12.0 KB
utils/host_routes/__init__.pyscript5.7 KB
utils/host_routes/codex.pyscript18.3 KB
utils/host_routes/npm.pyscript12.2 KB
utils/host_shim.pyscript14.7 KB
utils/html_report_generator.pyscript118.9 KB
utils/human_decisions.pyscript38.3 KB
utils/human_task_plan.pyscript30.2 KB
utils/importance.pyscript6.2 KB
utils/improve_cascade.pyscript63.7 KB
utils/improve_cascade_next.pyscript22.2 KB
utils/improve_steps.pyscript32.4 KB
utils/improve_workflow.pyscript114.4 KB
utils/interactive.pyscript31.6 KB
utils/json_extractor.pyscript61.5 KB
utils/judge_vocab.pyscript5.3 KB
utils/known_checks.pyscript37.5 KB
utils/landlock_dispatch.pyscript103.8 KB
utils/landlock_exec.pyscript21.4 KB
utils/launch_limiter.pyscript13.5 KB
utils/llm_client.pyscript126.9 KB
utils/manual_tasks.pyscript14.9 KB
utils/metrics.pyscript68.1 KB
utils/next_phase.pyscript96.1 KB
utils/next_phase_words.pyscript6.4 KB
utils/output_handler.pyscript23.2 KB
utils/phase_walk.pyscript6.4 KB
utils/plan_updater.pyscript17.9 KB
utils/positionals.pyscript5.8 KB
utils/prior_changes.pyscript28.7 KB
utils/probe_state.pyscript17.9 KB
utils/process_capture.pyscript37.6 KB
utils/process_control.pyscript228.7 KB
utils/process_state.pyscript6.6 KB
utils/progress_tracker.pyscript92.2 KB
utils/prompt_channels.pyscript34.1 KB
utils/prompt_files.pyscript24.5 KB

utils/host_install.py

View on GitHub
#!/usr/bin/env python3
"""``install-host`` / ``uninstall-host`` — the D7 install contract.

One file is written per invocation, and the rules for that write are the whole
design; every lifecycle question (upgrade, relocate, repair, uninstall) is a
consequence of them.

* **Always a rendered copy — never a symlink, junction or hardlink.** The
  installed artifact is *output*: ``hosts/<host>/shim.md.tmpl`` still carries an
  unexpanded ``{SKILL_DIR}`` and unfilled slots, so a link would install a
  template no host can run. It also takes symlink privileges out of the Windows
  story entirely (D7c) — nothing here needs elevation or Developer Mode.
* **The baked absolute prefix is the one staleness we can *check*.** The Claude
  plugin cache is keyed by commit hash, so the skill dir moves on every plugin
  update (D1c). An env var, a stable symlink or a shim-relative path each trade a
  checkable staleness for an unchecked one; a literal absolute path in a known
  slot can be compared against the running skill dir, which is what turns a moved
  skill dir into ``--check`` row 2 — a named failure with a one-line repair —
  instead of a ``No such file or directory`` surfacing from inside ``uv``.
* **The write is atomic and reversible.** Render into a temp file *in the target
  directory*, ``fsync``, ``os.replace``. An existing shim's bytes are read into
  memory first; a failure after the replace restores them exactly, and a
  first-time install rolls back by deleting what it wrote. Nothing is left behind
  on success — no ``.bak`` litter, no temp file.
* **An install ends with verification, not with the write.** After the replace the
  same ``--check`` runs inline. A shim whose *bytes* do not verify (rows 1-4) is a
  failed install and is rolled back; a byte-correct shim whose *environment* is
  not ready (row 5: uv, the runner CLI) is reported with exit 3 and **kept**,
  because deleting a correct file cannot make a missing CLI appear and the user's
  next step is to install that CLI, not to re-render.
* **Local edits are detected, never silently overwritten.** Every rendered shim
  carries a ``multi_llm_shim`` header (host id, ``shim_version``, template hash,
  hash of the body as written) in the file's own comment syntax. On re-install the
  body is re-hashed: an unchanged hash is a routine re-render, a changed one means
  the user edited the installed shim and the install stops with exit 3 naming the
  path and the two ways forward.

**No per-host branch exists in this module.** Paths, scopes, precedence, the
reload requirement, the shim's format and the verb sentences are all read from
``hosts/capabilities.yaml``; if a host needs something this code cannot express,
the missing information belongs in that data file.

``link-skill.sh``/``sync-skill.sh`` are Claude-Code-only dev tooling and
deliberately **not** an install backend: neither writes a shim, neither knows about
``--host``, and one of them collides with the installed plugin. ``install-host
claude-code`` is ``--check``-only (D5c): that host's shim is the plugin's own
``SKILL.md``, which the host itself resolves.
"""

from __future__ import annotations

if __name__ == "__main__" and not __package__:
    # Run by path: put the skill root on sys.path, found from this file's real
    # location as Python finds sys.path[0], then call the package module's entry
    # point with sys.argv untouched, so the program name stays the one typed
    # (docs/development/dispatcher.md#import-safety).
    import os
    import sys

    _UTILS_DIR = os.path.dirname(os.path.realpath(__file__))
    sys.path[:] = [os.path.dirname(_UTILS_DIR)] + [
        p for p in sys.path if os.path.realpath(p) != _UTILS_DIR]
    from utils.host_install import main

    raise SystemExit(main(sys.argv[1:]))

import argparse
import os
import re
import shutil
import sys
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Dict, List, Optional, Sequence, Tuple

from . import host_capabilities as caps
from .atomic_io import atomic_write_bytes as _atomic_write_bytes
from .cli_common import (
    EXIT_NEEDS_HUMAN,
    EXIT_NOTHING_TO_DO,
    EXIT_OK,
    dispatcher_prefix,
    record_artifact,
    skill_dir,
)
from .stream_bootstrap import bootstrap_streams
from .unattended import find_uv, uv_missing_text


# The shim's paths, text and package routes live in their own modules; every
# name stays importable from here, the installer's public surface.
from .host_paths import (  # noqa: F401
    Refused,
    SCOPE_PROJECT,
    SCOPE_GLOBAL,
    SCOPE_LEGACY,
    WRITABLE_SCOPES,
    DEFAULT_SCOPE,
    _HOME_TOKENS,
    _XDG_TOKENS,
    _ABSOLUTE_RE,
    user_home,
    expand_path_tokens,
    checked_entry,
    _join,
    Location,
    shim_filename,
    locations,
    _is_user_rooted,
    target_location,
    existing_copies,
)
from .host_shim import (  # noqa: F401
    SHIM_VERSION,
    HEADER_KEY,
    _HEADER_SYNTAX,
    _HEADER_RE,
    SLOT_UV_MISSING_TEXT,
    SLOT_UV_MISSING_FILE,
    _SLOT_RE,
    _UV_RUN_FLAGS_RE,
    _BAKED_PREFIX_QUOTED_RE,
    _BAKED_PREFIX_BARE_RE,
    FORBIDDEN_IN_INSTALLED,
    _HOST_EXPANDED_PLACEHOLDER,
    UV_MISSING_RELATIVE,
    SNIPPET_DIR,
    _MAX_SNIPPET_DEPTH,
    PLUGIN_SKILL_DESCRIPTION_MAX,
    template_path,
    snippets,
    render,
    baked_prefix,
    _sha256,
    body_of,
    parse_header,
    _header_line,
    with_header,
    _template_sha,
    render_installed,
    local_edit,
    _is_pristine_shim,
)
from .host_routes import (  # noqa: F401
    PackageRoute,
    _NOTE_FORMS,
)
from .host_routes.npm import (  # noqa: F401
    _package_name,
    _config_dirs,
    _config_env_names,
    _project_config_dirs,
    _config_files,
    _cache_root,
    _npm_payload_path,
    _PAYLOAD_PROBES,
    _npm_route,
    _declared_spec,
)
from .host_routes.codex import (  # noqa: F401
    CODEX_SERVER_MIN_PYTHON,
    CODEX_LIST_TIMEOUT_S,
    _CODEX_PAYLOAD_MARKERS,
    codex_home,
    _codex_payload_dir,
    _codex_payload_answers,
    _codex_plugin_list,
    _strip_toml_comment,
    _TOML_ENABLED_KEY_RE,
    _TOML_ENABLED_RE,
    _TOML_TOP_LEVEL_PLUGINS_RE,
    _is_plugins_family_header,
    _Abstain,
    _scan_codex_config,
    _codex_route,
    _with_enabled,
    _with_siblings,
    _python3_problem,
    _codex_note,
)


# ---------------------------------------------------------------------------
# Package routes: which resolver answers for a host, and what --check says
# ---------------------------------------------------------------------------

def package_route(
    host_id: str,
    *,
    base: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
    project_root: Optional[Path] = None,
) -> Optional[PackageRoute]:
    """Is a package route installed? Dispatched on ``package.registry``.

    Each registry has its own resolver in :data:`_ROUTE_RESOLVERS`, because
    what counts as *evidence of an install* is registry-shaped: a spec listed in
    a JSON config on npm, a ``codex plugin list`` entry or a ``config.toml``
    table on the codex marketplace. Neither resolver bends the other's helpers.
    """
    entry = caps.entry(host_id, base)
    package = entry.get("package")
    if not package:
        return None
    registry = package["registry"]
    resolver = _ROUTE_RESOLVERS.get(registry)
    if resolver is None:
        # **Refuse rather than probe nothing.** A missing resolver used to mean
        # `payload=None` and `resolved=False` — which reads out as row 1 FAILing
        # with "no payload resolved at None" and a repair line telling the user
        # to reconnect to a network or delete an entry that is, in fact, exactly
        # right. A correctly installed route mislabelled as broken is the one
        # answer this probe must never give, so the gap is reported as ours.
        # `render_capabilities._package_section` refuses the same way.
        raise Refused(
            f"ERROR: host '{host_id}' declares package registry '{registry}', "
            "which this route probe has no resolver for.\n"
            "       Add a row to _ROUTE_RESOLVERS in host_install.py rather than "
            "letting `--check` report an installed route as unresolved."
        )
    return resolver(host_id, entry, package, env=env, project_root=project_root)


#: One resolver per registry. Keyed on the ``package.registry`` discriminator,
#: so a second host on a known registry needs no code and a new registry is one
#: row — and :func:`package_route` refuses an unkeyed registry rather than
#: reporting an installed route as unresolved.
_ROUTE_RESOLVERS: Dict[str, Any] = {
    "npm": _npm_route,
    "codex-marketplace": _codex_route,
}

#: Whether a detected route answers row 1 ("is a route present and
#: loadable?") on its own. On npm the package's command *replaces* the file
#: shim's, so a resolved package is the route and `install-host` would be the
#: wrong repair. On the codex marketplace **both** skills are advertised under
#: different names, the check keeps its five rows as they were, and the route is
#: reported in a note that never moves an exit status (D5).
_ROUTE_ANSWERS_ROW_ONE: Dict[str, bool] = {
    "npm": True,
    "codex-marketplace": False,
}


def package_route_note(
    host_id: str,
    route: PackageRoute,
    *,
    file_present: bool,
    base: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
) -> str:
    """What ``--check`` says about a detected package route.

    Sentences come from the route's registry row in :data:`_NOTE_FORMS`. A
    note is never a row: it cannot fail the check or move an exit status.

    **npm — flat rather than hedged, because the winner is a decision and not
    a discovery.** The host merges every command file into one map first, then
    hands that same object *by reference* to each plugin's config hook — hooks
    run in load order, return nothing, and nothing is validated or checked for
    collisions. Since the plugin is ours and it assigns unconditionally, the
    package route wins by construction and the file shim becomes inert: still on
    disk, never invoked, with no warning of any kind from the host.

    **codex — both skills are advertised**, under different names, so the note
    exists to warn about the double advertisement, and only an installed *and
    enabled* plugin earns that warning (plus a second line when the plugin's
    server cannot start on this ``PATH``).
    """
    if route.registry == "codex-marketplace":
        return _codex_note(route, file_present=file_present,
                           uninstall=uninstall_line(host_id, base), env=env)
    forms = _NOTE_FORMS["npm"]
    words = {
        "declared_in": route.declared_in,
        "spec": route.spec,
        "payload": route.payload,
        "where": f" at {route.payload}" if route.payload else "",
        "uninstall": uninstall_line(host_id, base),
    }
    if not route.resolved:
        return forms["unresolved"].format(**words)
    if not file_present:
        return forms["package_only"].format(**words)
    return forms["both"].format(**words)


# ---------------------------------------------------------------------------
# --check: exactly five assertions, in order
# ---------------------------------------------------------------------------

ROW_PRESENT = 1
ROW_PREFIX = 2
ROW_SHAPE = 3
ROW_GENERATION = 4
ROW_ENVIRONMENT = 5

ROW_NAMES: Dict[int, str] = {
    ROW_PRESENT: "present",
    ROW_PREFIX: "baked prefix current",
    ROW_SHAPE: "rendered shape valid",
    ROW_GENERATION: "generation current",
    ROW_ENVIRONMENT: "environment",
}

#: Windows needs Git Bash: every shim we write is a POSIX-shell command block, so
#: a Windows host without it would get a shim it cannot run. Same prerequisite the
#: the README and ``references/uv-check.md`` state; no second detector.
GIT_BASH_MISSING = (
    "Git for Windows (Git Bash) is required on Windows: every command in a "
    "rendered shim is POSIX shell, and there is no PowerShell instruction path. "
    "Install it from https://git-scm.com/download/win and re-run."
)

#: The directories a Windows ``bash`` on ``PATH`` may resolve to *without* being a
#: POSIX shell: ``%SystemRoot%\\System32\\bash.exe`` is WSL's launcher, installed
#: by enabling the feature, and it starts a Linux VM whose filesystem is not the
#: one the baked ``C:\\…`` prefix names. A bare ``which("bash")`` accepts it and
#: reports the prerequisite as met on exactly the PowerShell-only machine
#: ``references/uv-check.md`` tells the agent to stop on.
_NOT_GIT_BASH_DIRS: Tuple[str, ...] = ("system32", "syswow64")

#: Where Git for Windows keeps its shell, relative to the install root, and where
#: that root sits relative to a ``git`` found on ``PATH``
#: (``<root>\\cmd\\git.exe``, ``<root>\\bin\\git.exe``, ``<root>\\mingw64\\bin\\git.exe``).
_GIT_BASH_RELATIVE: Tuple[Tuple[str, ...], ...] = (
    ("bin", "bash.exe"), ("usr", "bin", "bash.exe"),
)
_GIT_ROOT_PARENTS: Tuple[int, ...] = (1, 2)

#: The default install roots, for a Git that is installed but not on ``PATH``.
_GIT_ROOT_ENV: Tuple[Tuple[str, Tuple[str, ...]], ...] = (
    ("ProgramFiles", ("Git",)),
    ("ProgramW6432", ("Git",)),
    ("ProgramFiles(x86)", ("Git",)),
    ("LOCALAPPDATA", ("Programs", "Git")),
)


def git_bash(env: Optional[Dict[str, str]] = None) -> Optional[str]:
    """The POSIX shell a rendered shim runs under, or ``None``.

    Same probe ``references/uv-check.md`` (D6c) describes — look for ``bash`` on
    ``PATH`` — with the one correction that document's own "Supported shells"
    section already states in prose: on Windows the answer must be *Git Bash*.
    With WSL enabled, ``bash`` on ``PATH`` is ``%SystemRoot%\\System32\\bash.exe``,
    so a bare ``which`` reports the prerequisite as met on precisely the machine
    that has no POSIX shell for the shim. When ``PATH``'s answer is that launcher
    (or there is none), Git's own installation is asked instead — Git for Windows
    ships ``bash.exe`` inside its root — which is what the row claims to assert.
    """
    env = os.environ if env is None else env
    found = shutil.which("bash")
    if found and not _is_wsl_launcher(found):
        return os.path.abspath(found)
    for candidate in _git_bash_candidates(env):
        if os.path.isfile(candidate):
            return os.path.abspath(candidate)
    return None


def _is_wsl_launcher(path: str) -> bool:
    # Split on both separators rather than through ``os.path``: the Windows seam
    # is asserted on POSIX too, and there ``dirname`` treats a backslash as an
    # ordinary character, which would hide the very path this rejects.
    parts = [part for part in re.split(r"[/\\]", path) if part]
    return len(parts) > 1 and parts[-2].lower() in _NOT_GIT_BASH_DIRS


def _git_bash_candidates(env: Dict[str, str]) -> List[str]:
    """Every place Git for Windows' own ``bash.exe`` may sit, PATH's git first."""
    roots: List[Path] = []
    git = shutil.which("git")
    if git:
        parents = Path(os.path.abspath(git)).parents
        roots.extend(
            parents[index] for index in _GIT_ROOT_PARENTS if index < len(parents)
        )
    for name, tail in _GIT_ROOT_ENV:
        value = (env.get(name) or "").strip()
        if value:
            roots.append(Path(value).joinpath(*tail))
    seen: set = set()
    candidates: List[str] = []
    for root in roots:
        for relative in _GIT_BASH_RELATIVE:
            candidate = str(root.joinpath(*relative))
            if candidate not in seen:
                seen.add(candidate)
                candidates.append(candidate)
    return candidates


@dataclass
class Row:
    number: int
    ok: bool
    detail: str
    fix: str = ""

    @property
    def name(self) -> str:
        return ROW_NAMES[self.number]


@dataclass
class CheckResult:
    host_id: str
    rows: List[Row] = field(default_factory=list)
    copies: List[Location] = field(default_factory=list)
    loaded: Optional[Location] = None
    notes: List[str] = field(default_factory=list)

    @property
    def ok(self) -> bool:
        return all(row.ok for row in self.rows)

    @property
    def failures(self) -> List[Row]:
        return [row for row in self.rows if not row.ok]

    def row(self, number: int) -> Optional[Row]:
        for row in self.rows:
            if row.number == number:
                return row
        return None


def uninstall_line(host_id: str, base: Optional[str] = None) -> str:
    """The command that removes a file shim, spelled once.

    ``uninstall-host``, never ``install-host --uninstall``: there is no such
    flag, and a note that printed one would hand a user a command the dispatcher
    answers with exit 3.
    """
    prefix = dispatcher_prefix(Path(str(base)) if base else None)
    return f"{prefix} uninstall-host {host_id}"


def repair_line(host_id: str, base: Optional[str] = None) -> str:
    """The one string a stale shim is repaired with, everywhere it is printed.

    The same string D1c's moved-skill-dir message and the `docs/hosts.md`
    quickstart print: the instruction a user sees and the command that repairs
    are never two different things.
    """
    prefix = dispatcher_prefix(Path(str(base)) if base else None)
    return f"{prefix} install-host {host_id}"


def check(
    host_id: str,
    *,
    base: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
    project_root: Optional[Path] = None,
    path: Optional[Path] = None,
    windows: Optional[bool] = None,
) -> CheckResult:
    """Verify an install: five assertions, in order, each failing on its own.

    *path* pins the file to check (an install verifying what it just wrote);
    otherwise every location is searched and the copy the host would actually load
    is the one rows 2-4 are asserted against. A host whose shim is not ours to
    install (``installable: false``) runs rows 3-5 only: there is no file of ours
    to find (row 1) and no prefix we baked (row 2).
    """
    entry = caps.entry(host_id, base)
    result = CheckResult(host_id=host_id)
    installable = bool(entry["installable"])
    root = str(base) if base else str(skill_dir())

    # A host fact, not a file fact, so it is reported before anything is read —
    # a check that cannot find a shim at all still names the knob (below).
    knob = timeout_note(host_id, base)
    if knob:
        result.notes.append(knob)

    # The route note fires **ungated by `path`**, which is the gate easiest to
    # get backwards and the one that matters most: `install()` runs `check()`
    # and prints its result, so `install-host --all` — the command the docs
    # prescribe after every plugin update — is exactly the moment a shadowed
    # duplicate gets created, and it is exactly the moment a user can act on
    # being told. Only the *row* carve-out below is gated on `path is None`, so
    # an install still grades the file it just wrote.
    route = package_route(host_id, base=base, env=env, project_root=project_root)

    subject: Optional[Path]
    if not installable:
        subject = Path(root) / entry["shim"]["installed"]
        result.notes.append(
            f"host '{host_id}' is not installable: its shim is the plugin's own "
            f"{entry['shim']['installed']}, which the host resolves itself. "
            "Rows 1-2 do not apply."
        )
    elif path is not None:
        subject = Path(path)
        result.copies = existing_copies(
            host_id, base=base, env=env, project_root=project_root
        )
        result.loaded = result.copies[0] if result.copies else None
        if subject.is_file():
            result.rows.append(Row(ROW_PRESENT, True, str(subject)))
        else:
            result.rows.append(
                Row(
                    ROW_PRESENT, False, f"{subject} is missing",
                    f"run `{repair_line(host_id, base)}`",
                )
            )
    else:
        result.copies = existing_copies(
            host_id, base=base, env=env, project_root=project_root
        )
        result.loaded = result.copies[0] if result.copies else None
        subject = result.loaded.path if result.loaded else None
        if (
            subject is None and route is not None
            and _ROUTE_ANSWERS_ROW_ONE.get(route.registry, True)
        ):
            # Row 1's question is "is a route to this skill present and
            # loadable?", not "is there a file?". Answering it with the file
            # question would tell a package user to run `install-host` — which
            # writes the second, shadowed route this probe exists to detect —
            # and then they would be running two.
            #
            # Keeping it a *row* rather than skipping it is what keeps
            # `result.ok` meaningful: "rows 1-4 N/A" would return success on a
            # machine whose declared route never resolved.
            if route.resolved:
                result.rows.append(
                    Row(
                        ROW_PRESENT, True,
                        f"installed as a package: '{route.spec}' at "
                        f"{route.payload}",
                    )
                )
            else:
                result.rows.append(
                    Row(
                        ROW_PRESENT, False,
                        f"'{route.spec}' is declared in {route.declared_in} but "
                        f"no payload resolved at {route.payload}",
                        # The package route's own repair, never `install-host`.
                        f"restart {host_id} with a network connection, or "
                        f"remove the '{route.spec}' entry",
                    )
                )
        elif subject is None:
            target = target_location(
                host_id, DEFAULT_SCOPE, base=base, env=env,
                project_root=project_root,
            )
            result.rows.append(
                Row(
                    ROW_PRESENT, False,
                    f"no shim found in any of {host_id}'s install paths",
                    f"run `{repair_line(host_id, base)}` (writes {target.path})",
                )
            )
        else:
            detail = f"{len(result.copies)} copy(ies); loads {subject}"
            result.rows.append(Row(ROW_PRESENT, True, detail))

    if subject is None or not subject.is_file():
        # Rows 2-4 read the file; without one they are unanswerable rather than
        # failed, and row 5 is still worth reporting.
        result.rows.append(
            _environment_row(
                host_id, base=base, project_root=project_root, windows=windows
            )
        )
        if route is not None:
            result.notes.append(
                package_route_note(
                    host_id, route, file_present=False, base=base, env=env
                )
            )
        return result

    text = subject.read_text(encoding="utf-8")

    if installable:
        result.rows.append(_prefix_row(host_id, text, root, base))
    result.rows.append(_shape_row(host_id, text, base))
    result.rows.append(_generation_row(host_id, text, base, installable))
    result.rows.append(
        _environment_row(
            host_id, base=base, project_root=project_root, windows=windows
        )
    )

    if installable and local_edit(text):
        result.notes.append(
            f"{subject} has local edits (its body no longer matches the hash it "
            "records). Re-installing needs --force, which preserves the edited "
            "file as <shim>.local.bak."
        )
    if route is not None:
        result.notes.append(
            package_route_note(
                host_id, route,
                file_present=subject is not None and subject.is_file(),
                base=base, env=env,
            )
        )
    if installable and str(entry["reload"]) != "none" and path is None:
        # An install prints this line itself, on success and once (see `install`);
        # a standalone check carries it as a note, because "installed but not yet
        # loaded" is a state a reader has to be told about either way.
        result.notes.append(reload_note(host_id, base))
    return result


def reload_note(host_id: str, base: Optional[str] = None) -> str:
    """The host's own reload requirement — a state, never a failure.

    "Installed but not yet loaded" is a distinct, non-failing condition: a
    file-scanning command host picks a new shim up on the next invocation, a host
    that enumerates skills at session start needs a fresh session, and the
    reference host takes a plugin update rather than an install.
    """
    entry = caps.entry(host_id, base)
    value = str(entry["reload"])
    if value == "none":
        return (
            f"host '{host_id}' needs no reload: its shim ships with the plugin, so "
            "a plugin update is the only refresh."
        )
    if value == "restart":
        return (
            f"[NOT_YET_LOADED] restart {host_id} before invoking the command; it "
            "reads its configuration once at startup."
        )
    return (
        f"[NOT_YET_LOADED] start a new {host_id} session before invoking the "
        "command; this host enumerates its commands/skills at session start."
    )


#: The three surfaces a host's command-timeout ceiling can move through (D5b
#: ``timeout_override``), in the order they are reported.
TIMEOUT_CHANNELS: Tuple[str, ...] = ("frontmatter", "env", "config")


def timeout_note(host_id: str, base: Optional[str] = None) -> str:
    """The host's own timeout-raise knob, reported — empty when it has none.

    ``timeout_ceiling_s`` is how long one *foreground* command may run before the
    host kills it; ``timeout_override`` records the channels that ceiling moves
    through — ``none`` where the host has no such surface at all (OpenCode's V2
    frontmatter has no ``timeout`` field, so rendering one would be ignored
    rather than honored) and ``unknown`` until a smoke confirms the key.

    Only a *named* channel is actionable, so only a named channel is reported,
    and where the channel is an environment variable the line to export is
    printed rather than described. An ``unknown`` channel stays silent: an
    install that told the user to export ``unknown`` would be worse than saying
    nothing. Both shipped hosts are ``unknown`` on every raisable channel today,
    so this returns ``""`` for them until one is confirmed.
    """
    entry = caps.entry(host_id, base)
    declared = entry.get("timeout_override") or {}
    named: List[str] = []
    for channel in TIMEOUT_CHANNELS:
        value = str(declared.get(channel) or "none").strip()
        if value in ("", "none", "unknown"):
            continue
        if channel == "env":
            named.append(
                f"export {value}=<seconds> in the shell that starts {host_id}"
            )
        elif channel == "config":
            named.append(f"set `{value}` in {host_id}'s own config")
        else:
            named.append(f"the shim's `{value}:` frontmatter key")
    if not named:
        return ""
    try:
        ceiling = int(entry.get("timeout_ceiling_s") or 0)
    except (TypeError, ValueError):  # pragma: no cover - schema keeps this an int
        ceiling = 0
    cap = (
        f"caps one foreground command at {ceiling}s"
        if ceiling
        else "documents no command-timeout cap"
    )
    return (
        f"host '{host_id}' {cap}; the entry names how that ceiling is raised — "
        + "; ".join(named)
        + ". install-host reports the knob and never writes it for you."
    )


def _prefix_row(
    host_id: str, text: str, root: str, base: Optional[str]
) -> Row:
    prefix = baked_prefix(text)
    if not prefix:
        return Row(
            ROW_PREFIX, False,
            "the file carries no `uv run [flags…] --project \"<abs>\"` prefix, so "
            "nothing binds it to a skill dir",
            f"run `{repair_line(host_id, base)}`",
        )
    if not Path(prefix).is_dir():
        return Row(
            ROW_PREFIX, False,
            f"the baked skill dir no longer exists: {prefix} (the plugin was "
            "updated or removed — the cache is keyed by commit hash)",
            f"run `{repair_line(host_id, base)}`",
        )
    if os.path.normcase(os.path.abspath(prefix)) != os.path.normcase(
        os.path.abspath(root)
    ):
        return Row(
            ROW_PREFIX, False,
            f"the baked skill dir moved: shim says {prefix}, running skill dir is "
            f"{root}",
            f"run `{repair_line(host_id, base)}`",
        )
    return Row(ROW_PREFIX, True, prefix)


#: The one dispatcher command a shim renders: ``… multi_llm.py" <mode> …``.
_DISPATCHER_RE = re.compile(r'multi_llm\.py"?\s+<mode>')


def dispatcher_commands(text: str) -> List[str]:
    """Every dispatcher command in *text*, one logical command per entry.

    Row 3's assertions about the command a host actually *runs* have to read that
    command, not the file: the same shim bakes in verb sentences that discuss the
    unattended default in prose ("… which implies ``--yes``"), so a whole-file
    substring test still passes on a shim whose dispatcher lost the flag. A
    trailing backslash continues a command onto the next line.
    """
    lines = text.splitlines()
    commands: List[str] = []
    for index, line in enumerate(lines):
        if not _DISPATCHER_RE.search(line):
            continue
        command = [line]
        cursor = index
        while command[-1].rstrip().endswith("\\") and cursor + 1 < len(lines):
            cursor += 1
            command.append(lines[cursor])
        commands.append("\n".join(command))
    return commands


#: The substitution words that make ``--interactive`` a replacement, not an extra.
_SUBSTITUTES_RE = re.compile(r"replac\w*|in place of|instead of|substitut\w*", re.I)


def substitution_rule(text: str) -> bool:
    """Does *text* tell the agent to swap ``--interactive`` **for** ``--yes`` (D6b)?

    Every non-reference shim bakes ``--yes``; the user's ``--interactive`` is the
    one flag that may not simply pass through alongside it, because the dispatcher
    rejects the pair with exit 3 and interactive mode would be unreachable on a
    ``ask: free-text`` host. The rule has to be *stated* in the shim — one sentence
    naming both flags and the substitution — so this reads sentences rather than
    the whole file: naming the two flags paragraphs apart is not a rule.
    """
    flat = " ".join(text.split())
    for sentence in re.split(r"(?<=[.;:])\s", flat):
        if (
            "--interactive" in sentence
            and "--yes" in sentence
            and _SUBSTITUTES_RE.search(sentence)
        ):
            return True
    return False


def shape_problems(
    host_id: str, text: str, base: Optional[str] = None
) -> List[str]:
    """Row 3's list: does the file parse the way the shipped-shim guard parses it?

    Frontmatter where the host requires one, exactly one dispatcher command block,
    the uv preflight ahead of the first ``uv run``, no surviving placeholder or
    unfilled slot, the three verb sentences filled once each, and a baked
    ``--host`` id that is a key in the capability data.
    """
    entry = caps.entry(host_id, base)
    problems: List[str] = []
    fmt = str(entry["shim"]["format"])
    if fmt.endswith("+frontmatter"):
        lines = text.splitlines()
        if not lines or lines[0].strip() != "---" or "---" not in lines[1:]:
            problems.append(
                f"this host's shim format is {fmt}, but the file opens with no "
                "`---` frontmatter block"
            )
    forbidden = FORBIDDEN_IN_INSTALLED if entry["installable"] else tuple(
        token for token in FORBIDDEN_IN_INSTALLED
        if token != _HOST_EXPANDED_PLACEHOLDER
    )
    for token in forbidden:
        if token in text:
            problems.append(f"the placeholder {token} survived rendering")
    for slot in sorted(set(_SLOT_RE.findall(text))):
        problems.append(f"the slot {slot} was never filled")

    dispatchers = _DISPATCHER_RE.findall(text)
    if len(dispatchers) != 1:
        problems.append(
            f"expected exactly one dispatcher command block, found "
            f"{len(dispatchers)}"
        )
    probe = text.find("command -v uv")
    # Searched as a pattern, not as the literal `uv run --project`: the rendered
    # dispatcher carries the uv flag list between the two.
    dispatch = _BAKED_PREFIX_BARE_RE.search(text)
    first_run = dispatch.start() if dispatch else -1
    if probe < 0:
        problems.append("no `command -v uv` preflight")
    elif 0 <= first_run < probe:
        problems.append(
            "the uv preflight comes after the first `uv run`, so a missing uv "
            "surfaces as a bare `command not found`"
        )
    baked = set(re.findall(r"--host\s+([a-z][a-z0-9-]*)", text))
    if not baked:
        problems.append("no `--host <id>` is baked into the dispatcher command")
    elif baked != {host_id}:
        problems.append(
            f"the file bakes --host {sorted(baked)} but is the shim for "
            f"'{host_id}'"
        )
    else:
        known = caps.host_ids(base)
        for candidate in baked:
            if candidate not in known:
                problems.append(
                    f"the baked --host '{candidate}' is not a key in the "
                    "capability data"
                )
    for verb, sentence in zip(caps.VERBS, caps.verb_sentences(host_id, base)):
        if text.count(sentence) != 1:
            problems.append(
                f"the *{caps.VERB_WORDING[verb]}* resolution appears "
                f"{text.count(sentence)} times; exactly one per verb, byte-"
                "identical to the capability data's own render"
            )
    if bool(entry["installable"]):
        commands = "\n".join(dispatcher_commands(text))
        if "--yes" not in commands:
            problems.append(
                "the dispatcher command never passes --yes; unattended is the "
                "default on every host that is not the interactive reference host. "
                "(A verb sentence mentioning --yes is prose about the flag, not the "
                "command the host runs, so the assertion reads the command itself.)"
            )
        if "--interactive" in commands:
            problems.append(
                "the dispatcher command bakes --interactive alongside --yes; the "
                "two together are exit 3, so --interactive is only ever a "
                "substitution the agent makes for the user-typed flag"
            )
        elif not substitution_rule(text):
            problems.append(
                "no rule tells the agent to substitute --interactive for the baked "
                "--yes (D6b): without it a user who types --interactive gets "
                "`--yes --interactive`, which the dispatcher rejects with exit 3, "
                "and interactive mode is unreachable on this host"
            )
    return problems


def _shape_row(host_id: str, text: str, base: Optional[str]) -> Row:
    problems = shape_problems(host_id, text, base)
    if problems:
        return Row(
            ROW_SHAPE, False, "; ".join(problems),
            f"run `{repair_line(host_id, base)}` to re-render from the template",
        )
    return Row(ROW_SHAPE, True, "frontmatter, one dispatcher block, uv preflight, "
                                "no unfilled slot")


def _generation_row(
    host_id: str, text: str, base: Optional[str], installable: bool
) -> Row:
    """Row 4 — is this file what the *running* skill would render today?

    Two signals, coarse first, because they answer the same question at different
    resolutions. ``shim_version`` is the hand-maintained shape counter, and its
    unique reach is everything the renderer contributes that no digest of a
    template can see — a changed snippet, a changed verb sentence, a changed
    :func:`render`. ``template_sha256`` is the digest of the
    ``hosts/<host>/shim.md.tmpl`` this file was actually rendered from, recorded
    in the header since D7 and — until this row read it — never compared against
    anything. That gap had a concrete consequence: a template body edited without
    the counter being bumped left every shim already installed from it reporting
    "generation current" while missing whatever the edit added, which is exactly
    how an installed OpenCode shim kept a dispatcher line with no
    ``--exec-subagents`` in it and still passed row 4.

    They are one row rather than a fifth plus a sixth: "generated by an older
    multi-llm" and "rendered from a superseded template" are the same fact to a
    reader ("this shim predates the skill that is running") with the same repair,
    and five is a count `docs/hosts.md`, `references/host-capabilities.md` and the
    tests all state.
    """
    if not installable:
        return Row(
            ROW_GENERATION, True,
            "n/a — this shim is not rendered, so it carries no generation",
        )
    header = parse_header(text)
    if header is None:
        return Row(
            ROW_GENERATION, False,
            f"no {HEADER_KEY} block: this file was not written by install-host "
            "(hand-authored, or from a copy of an older layout)",
            f"run `{repair_line(host_id, base)}`",
        )
    recorded = header.get("shim_version")
    if recorded != SHIM_VERSION:
        return Row(
            ROW_GENERATION, False,
            f"shim generated by an older multi-llm (shim_version {recorded!r}, "
            f"current {SHIM_VERSION})",
            f"run `{repair_line(host_id, base)}`",
        )
    template_problem = _template_problem(host_id, header, base)
    if template_problem:
        return Row(
            ROW_GENERATION, False, template_problem,
            f"run `{repair_line(host_id, base)}` to re-render from the template",
        )
    return Row(
        ROW_GENERATION, True,
        f"shim_version {SHIM_VERSION}, rendered from the current template",
    )


def _template_problem(
    host_id: str, header: Dict[str, object], base: Optional[str]
) -> str:
    """Why this shim's recorded template digest is not the current one, or ``""``.

    Two non-failures are deliberate. A host whose entry sets ``shim.template:
    null`` has no template to have moved — ``_template_sha`` returns ``""`` for
    it — and reporting that as a stale render would fail the one host (the
    reference host, `installable: false`) whose shim is a file nobody renders.
    Everything else is a failure, **including a header carrying no
    ``template_sha256`` key at all**: that field has been written by every
    ``install-host`` that has ever shipped, so its absence means the header was
    hand-assembled or truncated rather than that the file is merely old, and it
    is not something ``shim_version`` can catch — the counter has never left 1,
    so a "this predates the field" reading would pass the file silently.
    """
    expected = _template_sha(host_id, base)
    if not expected:
        return ""
    template = str(caps.entry(host_id, base)["shim"]["template"])
    if "template_sha256" not in header:
        return (
            f"header records no template_sha256, so the {template} this file was "
            "rendered from cannot be identified: every install-host that has "
            "shipped writes that field, which makes this header hand-assembled "
            "or truncated rather than simply older"
        )
    recorded = header.get("template_sha256")
    if recorded != expected:
        return (
            f"rendered from a superseded {template}: the template body has "
            f"changed since this shim was written (records template_sha256 "
            f"{_abbreviate(recorded)}, current {_abbreviate(expected)}), so the "
            "file is missing whatever that change added"
        )
    return ""


def _abbreviate(digest: object) -> str:
    """A digest short enough to read in a one-line row, or what was there instead."""
    if isinstance(digest, str) and len(digest) > 12:
        return digest[:12] + "…"
    return repr(digest)


def _environment_row(
    host_id: str,
    *,
    base: Optional[str] = None,
    project_root: Optional[Path] = None,
    windows: Optional[bool] = None,
) -> Row:
    """Row 5 — the install-time half of the uv bootstrap (D6c layer 1).

    Layer 1 exists because layer 3 cannot run: every invocation goes through
    ``uv run``, so on a machine with no uv the shell fails with exit 127 before any
    Python could print the message. What this row certifies is narrower than it
    looks: on a host where it runs and passes, :func:`find_uv` found uv at
    install time. It says nothing about a host that never runs it (Claude Code is
    ``installable: false``, so no install route evaluates this row), nothing about
    an install kept after this row failed (:func:`install` excludes
    ``ROW_ENVIRONMENT`` from the failures that roll a write back), and nothing
    about whether a bare ``uv`` resolves in the shell the shim later dispatches
    in — the row can pass on ``$MULTI_LLM_UV`` or on an absolute candidate.
    Layers 2 and 3 are what cover the rest.

    The runner leg is :func:`_runner_facts`, which resolves the runner this
    project would really dispatch — never the capability entry's default read on
    its own — and reports the four facts that decide whether it can serve a phase.
    """
    problems: List[str] = []
    details: List[str] = []
    uv = find_uv()
    if uv is None:
        problems.append(uv_missing_text(base))
    else:
        details.append(f"uv={uv}")

    runner_problems, runner_details = _runner_facts(
        host_id, base=base, project_root=project_root
    )
    problems.extend(runner_problems)
    details.extend(runner_details)

    is_windows = os.name == "nt" if windows is None else bool(windows)
    if is_windows:
        shell = git_bash()
        if shell is None:
            problems.append(GIT_BASH_MISSING)
        else:
            details.append(f"bash={shell}")

    if problems:
        return Row(
            ROW_ENVIRONMENT, False, "; ".join(problems),
            "install the missing prerequisite named above, then re-run "
            f"`{repair_line(host_id, base)} --check`",
        )
    return Row(ROW_ENVIRONMENT, True, ", ".join(details))


#: The config key row 5 reports on, spelled the way the executor's own rejections
#: spell it, so the string a user greps for is the same in both places.
RUNNER_KEY = "driver.subagent_runner"

#: The three independent ways a host can stop a dispatched runner (D3c), each
#: declared per host in ``nested_exec``.
NESTED_EXEC_LEGS: Tuple[str, ...] = ("spawn", "network", "credentials")


def configured_runner(
    host_id: str,
    *,
    base: Optional[str] = None,
    project_root: Optional[Path] = None,
) -> Tuple[str, str]:
    """The runner this project would really dispatch, and the layer that set it.

    Row 5 has to ask the question the **executor** asks — ``get_subagent_runner``
    with this host id and this project as the discovery anchor (D3o) — never the
    capability entry's ``default_subagent_runner`` read on its own. That entry
    value is only the middle rung of the ladder: an explicit
    ``driver.subagent_runner`` in ``<git-root>/.multi-llm/providers.yaml`` or in
    ``MULTI_LLM_PROVIDERS_CONFIG`` outranks it, and the host default is itself
    skipped when its own CLI is not detected. Checking the entry default alone
    therefore reports green on a project whose configured runner is absent,
    logged out or too old, and red on a project over a default that nothing
    running there would ever dispatch.

    The layer is reported alongside the spec because "I set it and nothing
    changed" is otherwise a support question (D3o).
    """
    # Imported here to keep host_install light.
    from .provider_registry import resolve_subagent_runner
    anchor = str(project_root) if project_root is not None else None
    # The resolver reports the layer it actually took, so the middle rung is named
    # as itself: re-deriving the provenance here would let the check and the
    # dispatch disagree, and reporting the host default as `base` would point a
    # reader at a file that did not supply the value.
    spec, layer = resolve_subagent_runner("full", anchor=anchor, host_id=host_id)
    return str(spec).strip(), layer


def probe_runner(spec: str, *, anchor: Optional[str] = None) -> Dict[str, str]:
    """Auth and version for one runner spec, through the executor's own preflight.

    The very call the executor makes once per phase (``preflight_runner``:
    profile support, ``version_cmd`` against ``min_version``, the adapter's
    ``auth_check``), so a green ``--check`` and the first dispatch cannot
    disagree about the same CLI. **Installed is not authenticated** (D3c): every
    ``is_available()`` is a bare ``shutil.which``, so a logged-out runner passes
    detection here and is otherwise discovered one spawned child at a time, once
    per task in the batch.

    Nothing a probe cannot answer blocks — an adapter declaring no ``auth_check``,
    a CLI that dropped ``--version``, a probe that fails to run all report
    ``unknown`` — but a recognized refusal (no read-only profile, a build below
    the minimum this release parses, a login notice) is exactly what row 5 exists
    to surface before a batch discovers it.

    One thing this runs that a dispatch preflight does not: the adapter's
    optional ``setup_probe`` readout (M13, §5.2) — cursor-agent's
    ``about --format json`` plan tier is the only one declared today. It is a
    *metadata* probe and never a verdict: it cannot make this function report
    ``problem``, it never touches ``auth``, and a readout that will not run is
    simply one less fact on the row. It is spawned here rather than in
    ``preflight_runner`` because ``--check`` is invoked by a human, once, while a
    preflight runs every phase and would pay a subprocess for a sentence no
    dispatch decision reads.

    Returns:
        ``{"auth", "version", "problem", "metadata"}``; ``problem`` is empty when
        the preflight passed, and ``metadata`` is the rendered ``label=value``
        readout — empty for every adapter that declares none.
    """
    unknown = {
        "auth": "unknown", "version": "unknown", "problem": "", "metadata": "",
    }
    try:
        # Imported here to keep host_install light.
        from .providers.base import PROFILE_AGENT_READONLY
        from .task_outcome import RunnerRejected
        from .runner_preflight import (
            preflight_runner,
            probe_setup_metadata,
        )
    except Exception:  # pragma: no cover - a partial install never fails a check
        return dict(unknown)
    try:
        info = preflight_runner(
            spec, profile=PROFILE_AGENT_READONLY, key=RUNNER_KEY, anchor=anchor
        )
    except RunnerRejected as exc:
        if getattr(exc, "reason_code", "") == "binary_absent":
            # Presence is `runner_available`'s verdict — the two ask the same
            # question of the same adapter, and row 5 reports it once.
            return dict(unknown)
        return {
            "auth": "unknown", "version": "unknown", "problem": str(exc),
            "metadata": "",
        }
    except Exception:  # pragma: no cover - a probe reports; it never blocks
        return dict(unknown)
    try:
        readout = probe_setup_metadata(spec.split(":", 1)[0].strip())
    except Exception:  # pragma: no cover - a readout never fails a check
        readout = {}
    return {
        "auth": str(info.get("auth") or "unknown"),
        "version": str(info.get("version") or "unknown"),
        "problem": "",
        "metadata": ", ".join(f"{k}={v}" for k, v in sorted(readout.items())),
    }


def _runner_state(provider: str, facts: Dict[str, str]) -> str:
    """The typed availability state for a runner row 5 already probed (M10, §5.1).

    Row 5 runs the two probes anyway (``preflight_runner`` → ``probe_runner``),
    so this costs nothing extra and turns three separate facts into the one word
    a reader acts on. It reads the probe *results* — never re-running them.

    ``probe_runner`` never reports a negative auth verdict in its ``auth`` field:
    a recognised login notice is raised by the preflight and arrives here as
    ``problem`` instead, so that is where the ``needs-auth`` reading comes from.
    Anything unresolvable is ``""`` — a diagnostic never fails a ``--check``.
    """
    try:
        # Imported here to keep host_install light.
        from .provider_registry import get_provider
        adapter = get_provider(provider)
        if adapter is None:
            return ""
        if "not_authenticated" in str(facts.get("problem") or ""):
            auth: Optional[bool] = False
        elif str(facts.get("auth") or "") in ("ok", "config"):
            # `config` (plan §8 T8.4): the model-aware preflight found the
            # runner's provider declared in the config its dispatch resolves.
            auth = True
        else:
            auth = None
        report = adapter.describe_availability(
            auth=auth, version=str(facts.get("version") or "")
        )
        return report.state.value
    except Exception:  # pragma: no cover - a diagnostic never fails a check
        return ""


def _runner_facts(
    host_id: str,
    *,
    base: Optional[str] = None,
    project_root: Optional[Path] = None,
) -> Tuple[List[str], List[str]]:
    """Row 5's runner leg: four facts about the runner this project resolves.

    Present, authenticated, version and nested-exec — because "on PATH" answers
    none of the other three, and each of them fails *quietly* at dispatch: a
    logged-out CLI prints a login notice and exits, a CLI below ``min_version``
    emits an event stream the adapter was not written against, and a host whose
    ``nested_exec`` says ``denied`` cannot exec a runner at all.
    """
    entry = caps.entry(host_id, base)
    try:
        spec, layer = configured_runner(
            host_id, base=base, project_root=project_root
        )
    except Exception as exc:  # a broken override layer is an environment miss
        return (
            [
                f"the configured subagent runner could not be resolved: {exc}. "
                f"Fix `{RUNNER_KEY}` in providers.yaml (or in the file "
                "MULTI_LLM_PROVIDERS_CONFIG points at) and re-check."
            ],
            [],
        )

    problems: List[str] = []
    details: List[str] = []
    native = str(entry["subagents"]) == "native"
    scope = (
        " (this host dispatches subagents natively, so the runner is consulted "
        "only under --exec-subagents)"
        if native else ""
    )
    provider = spec.split(":", 1)[0]
    version = "unknown"
    # M10 (§5.1) — `runner_available` stays the **bool**: present or absent is
    # the whole question this branch asks, and it is the same `is_available()`
    # `--init` asks. The typed state rides along in the message and in the facts
    # row below, which is where "installed but not usable" finally has a word.
    if not runner_available(provider):
        state = _runner_state(provider, {}) or "binary-missing"
        problems.append(
            f"the CLI for the configured subagent runner '{spec}' (supplied by "
            f"{layer}) is not installed [{state}], so every phase that dispatches "
            f"a subagent would fail{scope}. Install the '{provider}' CLI (or point "
            f"`{RUNNER_KEY}` in providers.yaml at one you have) and re-check."
        )
    else:
        facts = probe_runner(
            spec, anchor=str(project_root) if project_root is not None else None
        )
        problem = str(facts.get("problem") or "")
        if problem:
            problems.append(problem)
        version = str(facts.get("version") or "unknown")
        details.append(f"runner={spec} (supplied by {layer}){scope}")
        details.append(f"auth={facts.get('auth') or 'unknown'}")
        details.append(f"version={version}")
        state = _runner_state(provider, facts)
        if state:
            details.append(f"state={state}")
        # The adapter's own metadata readout (M13, §5.2), if it declares one.
        # It sits *after* `state` on purpose: it is context for a verdict this
        # row has already reached, never an input to one — `_runner_state` reads
        # `auth`, `version` and `problem`, and this key reaches none of them.
        readout = str(facts.get("metadata") or "").strip()
        if readout:
            details.append(readout)

    nested = entry.get("nested_exec") or {}
    states = {leg: str(nested.get(leg) or "unknown") for leg in NESTED_EXEC_LEGS}
    denied = [leg for leg in NESTED_EXEC_LEGS if states[leg] == "denied"]
    if denied:
        notes = str(nested.get("notes") or "").strip()
        line = (
            f"this host's nested_exec declares {', '.join(denied)} denied, so a "
            f"runner dispatched from inside it cannot run at all — the executor "
            f"refuses the run naming the field rather than dispatching into a "
            f"sandbox that eats the failure. {notes}"
        ).strip()
        # A `denied` leg is fatal only where the executor *is* the dispatch path:
        # a native host resolves the verb to its own subagents, and `denied` there
        # says only that its opt-in `--exec-subagents` fallback is unavailable.
        (details if native else problems).append(line)
    details.append(
        "nested_exec=" + "/".join(f"{leg}:{states[leg]}" for leg in NESTED_EXEC_LEGS)
    )
    if version != "unknown" and states["spawn"] == "unknown":
        # The version probe *is* a spawn probe: the runner CLI started as a child
        # of this host's own shell, which is the one nested_exec leg a check can
        # observe without dispatching a real, billed turn.
        details.append("spawn probed here: the runner CLI started under this host")
    return problems, details


def runner_available(provider: str) -> bool:
    """Is this provider's CLI installed?

    Reuses ``init_config``'s detection path — ``provider_registry.get_provider``
    plus the adapter's own ``is_available()`` — rather than re-implementing a
    second probe that could disagree with ``--init``.
    """
    try:
        # Imported here to keep host_install light.
        from .provider_registry import get_provider
        adapter = get_provider(provider)
    except Exception:  # pragma: no cover - a config error is not a check failure
        return False
    if adapter is None:
        return False
    try:
        return bool(adapter.is_available())
    except Exception:  # pragma: no cover - a probe that raises is a miss
        return False


# ---------------------------------------------------------------------------
# The write
# ---------------------------------------------------------------------------

def atomic_write(target: Path, text: str) -> None:
    """Render into the target directory, ``fsync``, then ``os.replace``
    (:func:`atomic_write_bytes`).

    The text is encoded here rather than handed to a newline-translating stream,
    which is the same guarantee ``newline="\\n"`` used to give: the bytes are
    identical on every platform (idempotency and the body hash both depend on
    that).
    """
    atomic_write_bytes(target, text.encode("utf-8"))


def atomic_write_bytes(target: Path, data: bytes) -> None:
    """The same write, for bytes that must land exactly as they were read.

    Same volume by construction, which is what makes ``os.replace`` atomic on
    Windows too. Directories come from ``mkdir(parents=True, exist_ok=True)`` —
    no symlink, no junction, no elevation.

    A backup and a rollback cannot go through the text path: reading a file with
    ``read_text`` translates CRLF/CR to LF, so round-tripping a user's edited
    shim through it would rewrite the line endings of the very bytes D7a
    promises to preserve.

    The written file is owner-only (0600), as every shim, backup and rollback
    this installer has written is.
    """
    target.parent.mkdir(parents=True, exist_ok=True)
    _atomic_write_bytes(target, data, mode=0o600, temp_prefix=".multi-llm-shim-")


def _as_text(data: bytes) -> str:
    """Decode an existing file the way every other reader in this module does.

    ``read_text`` — which ``check``'s row 3 and the header parser both go
    through — translates CRLF/CR to LF, so hashing and comparison must see the
    same translation or an install would disagree with the ``--check`` that
    follows it. Undecodable bytes are replaced rather than raised on: a file
    that is not UTF-8 is certainly not a pristine shim of ours, and it belongs
    in ``_guard_existing``'s refusal, not in a traceback.
    """
    return (
        data.decode("utf-8", errors="replace")
        .replace("\r\n", "\n")
        .replace("\r", "\n")
    )


class _VerifyFailed(Exception):
    """A post-replace verification failure, on its way to one rollback site.

    Both a failed ``--check`` row and a probe that raised have to restore the
    previous bytes before they surface (D7a); routing them through one exception
    keeps that from being two rollback calls that can drift apart.
    """


def install(
    host_id: str,
    *,
    scope: str = DEFAULT_SCOPE,
    base: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
    project_root: Optional[Path] = None,
    force: bool = False,
    windows: Optional[bool] = None,
) -> int:
    """Render, write atomically, verify — or roll back. Returns an exit code."""
    entry = caps.entry(host_id, base)
    if not entry["installable"]:
        raise Refused(
            f"ERROR: `install-host {host_id}` is --check-only.\n"
            f"       This host's entry is installable: false — its shim is the "
            f"plugin's own {entry['shim']['installed']}, which the host resolves "
            "itself, so there is nothing for an installer to write. Run "
            f"`install-host {host_id} --check` to verify the shipped shim and this "
            "machine's prerequisites."
        )
    location = target_location(
        host_id, scope, base=base, env=env, project_root=project_root
    )
    target = location.path
    if target.exists() and not target.is_file():
        raise Refused(
            f"ERROR: {target} exists and is not a regular file, so the shim "
            "cannot be written there.\n"
            "       install-host writes one file per host and never replaces a "
            "directory or anything else it did not write. Move whatever is at "
            "that path aside, or fix the install_paths entry for "
            f"'{host_id}' in hosts/capabilities.yaml."
        )
    previous_bytes: Optional[bytes] = None
    previous: Optional[str] = None
    if target.is_file():
        # The bytes are what the backup and the rollback restore; the decoded
        # text is only ever hashed or compared.
        previous_bytes = target.read_bytes()
        previous = _as_text(previous_bytes)
        _guard_existing(host_id, target, previous, force)

    rendered = render_installed(host_id, base=base)
    if previous is not None and previous == rendered:
        # Idempotency is a property, not a coincidence: nothing is written, no
        # rollback is possible, and the verification below still runs.
        print(f"[SHIM_UNCHANGED] {target}")
    else:
        if previous_bytes is not None and force and not _is_pristine_shim(previous):
            # Anything --force had to override — a hand-edited shim or a file that
            # was never ours — is preserved rather than destroyed, byte for byte.
            # A pristine shim of ours needs no backup: re-rendering it reproduces
            # it exactly.
            backup = Path(str(target) + ".local.bak")
            atomic_write_bytes(backup, previous_bytes)
            print(f"[SHIM_EDIT_PRESERVED] {backup}")
        atomic_write(target, rendered)
        print(f"[SHIM_INSTALLED] {target}")

    # Everything from here to the reload note runs against bytes already on disk,
    # so every way out of it — a failed row, an unreadable file, a probe that
    # raised — is one failed install with one rollback (D7a).
    try:
        record_artifact(target)
        result = check(
            host_id, base=base, env=env, project_root=project_root, path=target,
            windows=windows,
        )
        print_check(result)
        byte_failures = [
            row for row in result.failures if row.number != ROW_ENVIRONMENT
        ]
        if byte_failures:
            raise _VerifyFailed(
                "did not verify:\n"
                + "\n".join(
                    f"       row {row.number} ({row.name}): {row.detail}"
                    for row in byte_failures
                )
            )
        _report_neighbours(result, location)
    except Exception as error:
        expected = isinstance(error, _VerifyFailed)
        detail = str(error) if expected else (
            f"could not be verified — {type(error).__name__}: {error}"
        )
        outcome = _rollback(target, previous_bytes)
        raise Refused(
            f"ERROR: the shim written to {target} {detail}\n"
            f"       The install failed and was rolled back ({outcome})."
        ) from (None if expected else error)
    print(reload_note(host_id, base))
    if result.failures:
        raise Refused(
            f"ERROR: {target} is installed and correct, but this machine is not "
            "ready to run it:\n"
            + "\n".join(
                f"       row {row.number} ({row.name}): {row.detail}"
                for row in result.failures
            )
            + "\n       The shim was kept: installing the missing prerequisite is "
            "the fix, not re-rendering."
        )
    return EXIT_OK


def _guard_existing(
    host_id: str, target: Path, previous: str, force: bool
) -> None:
    """Refuse to overwrite a foreign or hand-edited file (D7a/D7b)."""
    header = parse_header(previous)
    if header is None:
        if force:
            return
        raise Refused(
            f"ERROR: {target} exists and carries no {HEADER_KEY} block, so it was "
            "not written by install-host.\n"
            "       Overwriting it could destroy a file that is not ours. Move it "
            "aside, or pass --force to overwrite (the existing file is preserved "
            "as <shim>.local.bak)."
        )
    owner = header.get("host")
    if owner != host_id:
        raise Refused(
            f"ERROR: {target} already carries a {HEADER_KEY} block for host "
            f"'{owner}', not '{host_id}'.\n"
            "       Two hosts resolving to one path is a conflict, and it is "
            "reported rather than resolved: overwriting would swap the baked "
            "--host, and with it the whole capability profile, out from under "
            f"'{owner}'. Fix the install_paths collision in "
            "hosts/capabilities.yaml, or uninstall the other host first."
        )
    if local_edit(previous) and not force:
        raise Refused(
            f"ERROR: {target} has local edits — its body no longer matches the "
            "hash it records.\n"
            "       A shim that needs repair and a shim you deliberately "
            "customized are different situations, and the installer refuses to "
            "guess between them. Either re-run with --force (overwrites, keeping "
            "your file as <shim>.local.bak) or migrate the edit into the template "
            "by hand."
        )


def _rollback(target: Path, previous: Optional[bytes]) -> str:
    """Undo the write, and report what actually happened.

    The refusal quotes this clause verbatim, so it only ever claims the cleanup
    that succeeded: telling a user nothing was left behind when the unlink
    failed sends them looking in the wrong place for a file that is still there.
    """
    if previous is not None:
        atomic_write_bytes(target, previous)
        return "the previous file was restored"
    try:
        target.unlink()
    except FileNotFoundError:  # pragma: no cover - nothing to remove
        pass
    except OSError as error:
        return (
            f"except that {target} could not be removed and must be deleted by "
            f"hand: {error}"
        )
    return "nothing was left behind"


def _report_neighbours(result: CheckResult, written: Location) -> None:
    """Name the copy that will actually load, and every one that will not.

    A stale global shim shadowing nothing is harmless; a stale project shim
    shadowing a fresh global install is exactly the failure this reporting exists
    to surface, and it is caught here at install time rather than at the first
    confusing run.
    """
    for copy in result.copies:
        if copy.path == written.path:
            continue
        if _precedes(result.copies, copy, written):
            print(
                f"[SHIM_SHADOWED] {copy.path} ({copy.label}) takes precedence "
                f"over the shim just written to {written.path} "
                f"({written.label}), so that copy is what this host will actually "
                f"load. Install into {copy.scope} scope instead, or remove the "
                "older copy."
            )
        else:
            print(
                f"[SHIM_ALSO_FOUND] {copy.path} ({copy.label}) — lower precedence "
                "than what was just written"
                + ("; a compatibility location is never written by install-host, "
                   "so removing it is safe once the new shim loads."
                   if not copy.writable else ".")
            )


def _precedes(order: Sequence[Location], one: Location, other: Location) -> bool:
    paths = [location.path for location in order]
    if one.path not in paths or other.path not in paths:
        return False
    return paths.index(one.path) < paths.index(other.path)


# ---------------------------------------------------------------------------
# Reporting
# ---------------------------------------------------------------------------

def print_check(result: CheckResult) -> None:
    print(f"[INSTALL_CHECK] host={result.host_id}")
    for copy in result.copies:
        marker = " <- loads" if result.loaded and copy.path == result.loaded.path else ""
        print(f"  found: {copy.path} ({copy.label}){marker}")
    for row in result.rows:
        status = "OK  " if row.ok else "FAIL"
        print(f"  {row.number}. {row.name:<22} {status} {row.detail}")
        if not row.ok and row.fix:
            print(f"     FIX: {row.fix}")
    for note in result.notes:
        first, *rest = note.split("\n")
        print(f"  note: {first}")
        for line in rest:
            print(f"        {line}")


# ---------------------------------------------------------------------------
# uninstall-host
# ---------------------------------------------------------------------------

def uninstall(
    host_id: str,
    *,
    scopes: Sequence[str] = WRITABLE_SCOPES,
    base: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
    project_root: Optional[Path] = None,
    dry_run: bool = False,
    force: bool = False,
) -> int:
    """The missing inverse: remove only files carrying our header block.

    Identified by the ``multi_llm_shim`` block, never by filename. Compatibility
    locations (never ours to begin with) and locally edited shims are **reported,
    not deleted** — an edited shim needs ``--force`` exactly as a re-install does.
    Nothing outside the host's own ``install_paths`` is ever a candidate.
    """
    removed: List[Path] = []
    kept: List[str] = []
    for location in existing_copies(
        host_id, base=base, env=env, project_root=project_root
    ):
        if location.scope not in scopes:
            continue
        text = location.path.read_text(encoding="utf-8")
        header = parse_header(text)
        if header is None:
            kept.append(
                f"{location.path} ({location.label}) carries no {HEADER_KEY} "
                "block, so it is not ours to remove"
            )
            continue
        if header.get("host") != host_id:
            kept.append(
                f"{location.path} ({location.label}) belongs to host "
                f"'{header.get('host')}', not '{host_id}'"
            )
            continue
        if not location.writable:
            kept.append(
                f"{location.path} ({location.label}) is a compatibility location; "
                "install-host never creates one, so uninstall-host never deletes "
                "one"
            )
            continue
        if local_edit(text) and not force:
            kept.append(
                f"{location.path} ({location.label}) has local edits; pass --force "
                "to remove it anyway"
            )
            continue
        if dry_run:
            print(f"[SHIM_WOULD_REMOVE] {location.path}")
            removed.append(location.path)
            continue
        location.path.unlink()
        print(f"[SHIM_REMOVED] {location.path}")
        removed.append(location.path)
        _prune_empty_dir(location)

    for line in kept:
        print(f"[SHIM_KEPT] {line}")
    if not removed:
        print(
            f"[SHIM_NOT_FOUND] no removable multi-llm shim for host '{host_id}' in "
            f"scope(s) {', '.join(scopes)}."
        )
        return EXIT_NOTHING_TO_DO
    if dry_run:
        print("[DRY_RUN] nothing was changed.")
    return EXIT_OK


def _prune_empty_dir(location: Location) -> None:
    """Remove a skill directory we created and left empty — and only that.

    The directory is pruned only when its own name is the last segment of the
    install path (``…/skills/multi-llm``), so a shared command directory
    (``…/opencode/commands``) is never removed even when it ends up empty.
    """
    directory = location.directory
    if directory.name != "multi-llm":
        return
    try:
        next(directory.iterdir())
    except StopIteration:
        try:
            directory.rmdir()
            print(f"[SHIM_DIR_REMOVED] {directory}")
        except OSError:  # pragma: no cover - a racing writer keeps it
            pass
    except OSError:  # pragma: no cover - unreadable dir
        pass


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def _installed_hosts(
    *,
    base: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
    project_root: Optional[Path] = None,
) -> List[Location]:
    """Every writable location holding a shim, for every installable host.

    **Every** scope, not just the one that loads: a host installed in both scopes
    has two copies with the same baked prefix, and a plugin update staled both. If
    ``--all`` stopped at the highest-precedence copy, the global one would keep its
    dead prefix forever and load stale in every *other* project — the exact repair
    ``--all`` exists to perform, silently skipped. One entry per scope, because a
    scope's write target is its first preferred path however many of that scope's
    locations happen to hold a file.
    """
    found: List[Location] = []
    for host_id in sorted(caps.host_ids(base)):
        if not caps.entry(host_id, base)["installable"]:
            continue
        seen: set = set()
        for location in existing_copies(
            host_id, base=base, env=env, project_root=project_root
        ):
            if location.writable and location.scope not in seen:
                seen.add(location.scope)
                found.append(location)
    return found


def _scope_from(args: argparse.Namespace) -> str:
    if getattr(args, "scope_project", False):
        return SCOPE_PROJECT
    return SCOPE_GLOBAL


def _project_root(args: argparse.Namespace) -> Optional[Path]:
    value = getattr(args, "project_root", None)
    return Path(os.path.abspath(value)) if value else None


def main(argv: Optional[Sequence[str]] = None) -> int:
    """``multi_llm.py install-host <host> [--global|--project] [--check] [--all]``."""
    bootstrap_streams()
    parser = argparse.ArgumentParser(
        prog="multi_llm.py install-host",
        description=(
            "Render this skill's entry shim into another coding harness, or "
            "verify an existing install. Paths, precedence and the reload "
            "requirement all come from hosts/capabilities.yaml."
        ),
    )
    parser.add_argument(
        "host", nargs="?",
        help="Host id from hosts/capabilities.yaml (omit with --all).",
    )
    scope = parser.add_mutually_exclusive_group()
    scope.add_argument(
        "--global", dest="scope_global", action="store_true",
        help="Write the machine-wide copy (the default).",
    )
    scope.add_argument(
        "--project", dest="scope_project", action="store_true",
        help="Write the copy scoped to this project.",
    )
    parser.add_argument(
        "--check", action="store_true",
        help="Verify instead of writing: the five assertions, exit 3 on any "
             "failure.",
    )
    parser.add_argument(
        "--all", dest="every", action="store_true",
        help="Every installable host that already has a shim on disk, in every "
             "scope that holds one. This is the one command to run after a "
             "plugin update.",
    )
    parser.add_argument(
        "--force", action="store_true",
        help="Overwrite a locally edited or unrecognized shim, preserving it as "
             "<shim>.local.bak.",
    )
    parser.add_argument(
        "--project-root", dest="project_root", default=None,
        help="Where a project-scope path is resolved (default: the current "
             "directory).",
    )
    args = parser.parse_args(list(argv) if argv is not None else [])

    try:
        return _run_install(args)
    except Refused as exc:
        print(str(exc), file=sys.stderr)
        return EXIT_NEEDS_HUMAN
    except caps.UnknownHost as exc:
        print(exc.message, file=sys.stderr)
        return exc.exit_code


def _run_install(args: argparse.Namespace) -> int:
    project_root = _project_root(args)
    if args.every and args.host:
        raise Refused(
            "ERROR: pass either a host id or --all, not both. --all covers every "
            "installable host that already has a shim on disk."
        )
    if not args.every and not args.host:
        raise Refused(
            "ERROR: install-host needs a host id (or --all).\n"
            f"       Known hosts: {', '.join(sorted(caps.host_ids()))}"
        )

    if args.every:
        installed = _installed_hosts(project_root=project_root)
        if not installed:
            print(
                "[SHIM_NOT_FOUND] no installed shim to re-render. Install one "
                "first: `install-host <host>`."
            )
            return EXIT_NOTHING_TO_DO
        worst = EXIT_OK
        for location in installed:
            # `path` pins the check to *this* copy: the default search asserts
            # rows 2-4 against the copy that loads, which would pass a stale
            # global shim off as verified whenever a fresh project one shadows it.
            code = _one_install(
                location.host_id, scope=location.scope, check_only=args.check,
                force=args.force, project_root=project_root,
                path=location.path,
            )
            worst = code if code != EXIT_OK else worst
        return worst

    scope = _scope_from(args)
    return _one_install(
        args.host, scope=scope, check_only=args.check, force=args.force,
        project_root=project_root,
    )


def _one_install(
    host_id: str,
    *,
    scope: str,
    check_only: bool,
    force: bool,
    project_root: Optional[Path],
    path: Optional[Path] = None,
) -> int:
    caps.entry(host_id)  # exit 3 on an unknown id, before anything is touched
    if check_only:
        result = check(host_id, project_root=project_root, path=path)
        print_check(result)
        if result.ok:
            return EXIT_OK
        print(
            "[INSTALL_CHECK_FAILED] "
            + "; ".join(f"row {row.number} ({row.name})" for row in result.failures),
            file=sys.stderr,
        )
        return EXIT_NEEDS_HUMAN
    try:
        return install(
            host_id, scope=scope, force=force, project_root=project_root
        )
    except Refused as exc:
        print(str(exc), file=sys.stderr)
        return EXIT_NEEDS_HUMAN


def uninstall_main(argv: Optional[Sequence[str]] = None) -> int:
    """``multi_llm.py uninstall-host <host> [--global|--project|--all] [--dry-run]``."""
    bootstrap_streams()
    parser = argparse.ArgumentParser(
        prog="multi_llm.py uninstall-host",
        description=(
            "Remove a previously installed host shim. Only files carrying our "
            "multi_llm_shim block are candidates, and only inside that host's own "
            "install_paths."
        ),
    )
    parser.add_argument("host", help="Host id from hosts/capabilities.yaml.")
    scope = parser.add_mutually_exclusive_group()
    scope.add_argument(
        "--global", dest="scope_global", action="store_true",
        help="Only the machine-wide copy.",
    )
    scope.add_argument(
        "--project", dest="scope_project", action="store_true",
        help="Only this project's copy.",
    )
    scope.add_argument(
        "--all", dest="every_scope", action="store_true",
        help="Both scopes (the default).",
    )
    parser.add_argument(
        "--dry-run", action="store_true",
        help="List what would be removed and change nothing.",
    )
    parser.add_argument(
        "--force", action="store_true",
        help="Remove a locally edited shim too.",
    )
    parser.add_argument(
        "--project-root", dest="project_root", default=None,
        help="Where a project-scope path is resolved (default: the current "
             "directory).",
    )
    args = parser.parse_args(list(argv) if argv is not None else [])

    scopes: Tuple[str, ...] = WRITABLE_SCOPES
    if args.scope_global:
        scopes = (SCOPE_GLOBAL,)
    elif args.scope_project:
        scopes = (SCOPE_PROJECT,)
    try:
        caps.entry(args.host)
        return uninstall(
            args.host, scopes=scopes, dry_run=args.dry_run, force=args.force,
            project_root=_project_root(args),
        )
    except Refused as exc:
        print(str(exc), file=sys.stderr)
        return EXIT_NEEDS_HUMAN
    except caps.UnknownHost as exc:
        print(exc.message, file=sys.stderr)
        return exc.exit_code


if __name__ == "__main__":  # pragma: no cover - direct invocation is unadvertised
    raise SystemExit(main(sys.argv[1:]))
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall