Skip to content

try-works/role-model / .agents/skills/recursive-mode

recursive-mode

Unverified

Repository workflow orchestration skill for staged implementation, locked artifacts, late-phase receipts, and durable memory maintenance. Use when executing recursive-mode runs, resuming a run, locking a phase, or verifying locks.

FileKindSize
.agent/PLANS.mdmarkdown2.6 KB
.codex/AGENTS.mdmarkdown7.5 KB
.gitattributesother522 B
.gitignoreother553 B
.recursive/AGENTS.mdmarkdown3.3 KB
.recursive/DECISIONS.mdmarkdown1.1 KB
.recursive/README.mdmarkdown8.5 KB
.recursive/RECURSIVE.mdmarkdown107.5 KB
.recursive/STATE.mdmarkdown1.6 KB
.recursive/config/recursive-router.jsonconfig1.4 KB
.recursive/memory/MEMORY.mdmarkdown3.3 KB
.recursive/memory/archive/.gitkeepother1 B
.recursive/memory/domains/.gitkeepother1 B
.recursive/memory/episodes/.gitkeepother1 B
.recursive/memory/incidents/.gitkeepother1 B
.recursive/memory/patterns/.gitkeepother1 B
.recursive/memory/skills/SKILLS.mdmarkdown4.3 KB
.recursive/memory/skills/availability/.gitkeepother1 B
.recursive/memory/skills/issues/.gitkeepother1 B
.recursive/memory/skills/patterns/.gitkeepother1 B
.recursive/memory/skills/patterns/delegated-verification-and-refresh.mdmarkdown1.7 KB
.recursive/memory/skills/patterns/phase8-skill-memory-promotion.mdmarkdown1.4 KB
.recursive/memory/skills/usage/.gitkeepother1 B
.recursive/memory/skills/usage/skill-discovery-and-evaluation.mdmarkdown1.6 KB
.recursive/run/.gitkeepother1 B
AGENTS.mdmarkdown7.8 KB
LICENSEother11.1 KB
README.mdmarkdown17.8 KB
SKILL.mdskill md13.1 KB
agents/code-reviewer.mdmarkdown6.1 KB
agents/implementer.mdmarkdown6.3 KB
agents/openai.yamlconfig202 B
docs/templates/commands/check-reusable-repo-hygiene.mdmarkdown1.3 KB
docs/templates/commands/recursive-closeout.mdmarkdown2.8 KB
docs/templates/commands/recursive-init.mdmarkdown2.2 KB
docs/templates/commands/recursive-lock.mdmarkdown1.3 KB
docs/templates/commands/recursive-review-bundle.mdmarkdown3.6 KB
docs/templates/commands/recursive-status.mdmarkdown2.0 KB
docs/templates/commands/recursive-subagent-action.mdmarkdown4.2 KB
docs/templates/commands/test-recursive-mode-smoke.mdmarkdown3.4 KB
docs/templates/hooks/hooks.jsonconfig400 B
docs/templates/hooks/run-hook.cmdscript1.2 KB
docs/templates/hooks/session-start.ps1script3.6 KB
docs/templates/hooks/session-start.shscript3.5 KB
references/agents-block.mdmarkdown7.4 KB
references/artifact-template.mdmarkdown70.7 KB
references/benchmark-addon/recursive-benchmark/BENCHMARK-ADDON.mdmarkdown6.7 KB
references/benchmark-addon/recursive-benchmark/recursive-benchmark/BENCHMARK-ADDON.mdmarkdown6.7 KB
references/benchmark-addon/recursive-benchmark/recursive-benchmark/references/patterns.mdmarkdown4.9 KB
references/benchmark-addon/recursive-benchmark/references/patterns.mdmarkdown4.9 KB
references/benchmarks/README.mdmarkdown1.5 KB
references/benchmarks/local-first-planner/00-requirements.mdmarkdown3.3 KB
references/benchmarks/local-first-planner/README.mdmarkdown1.1 KB
references/benchmarks/local-first-planner/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/local-first-planner/prompt-recursive-on.mdmarkdown14.8 KB
references/benchmarks/local-first-planner/scoring-rubric.mdmarkdown1.3 KB
references/benchmarks/local-first-planner/starter/.gitignoreother30 B
references/benchmarks/local-first-planner/starter/README.mdmarkdown264 B
references/benchmarks/local-first-planner/starter/index.htmlother316 B
references/benchmarks/local-first-planner/starter/package.jsonmanifest628 B
references/benchmarks/local-first-planner/starter/src/App.test.tsxother334 B
references/benchmarks/local-first-planner/starter/src/App.tsxother971 B
references/benchmarks/local-first-planner/starter/src/main.tsxother238 B
references/benchmarks/local-first-planner/starter/src/styles.cssother976 B
references/benchmarks/local-first-planner/starter/src/test-setup.tsscript43 B
references/benchmarks/local-first-planner/starter/src/vite-env.d.tsscript38 B
references/benchmarks/local-first-planner/starter/tsconfig.app.jsonconfig552 B
references/benchmarks/local-first-planner/starter/tsconfig.jsonconfig89 B
references/benchmarks/local-first-planner/starter/vite.config.tsscript214 B
references/benchmarks/release-readiness-dashboard/00-requirements.mdmarkdown5.9 KB
references/benchmarks/release-readiness-dashboard/README.mdmarkdown1.2 KB
references/benchmarks/release-readiness-dashboard/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/release-readiness-dashboard/prompt-recursive-on.mdmarkdown14.8 KB
references/benchmarks/release-readiness-dashboard/scoring-rubric.mdmarkdown1.8 KB
references/benchmarks/release-readiness-dashboard/starter/.gitignoreother30 B
references/benchmarks/release-readiness-dashboard/starter/README.mdmarkdown272 B
references/benchmarks/release-readiness-dashboard/starter/index.htmlother324 B
references/benchmarks/release-readiness-dashboard/starter/package.jsonmanifest628 B
references/benchmarks/release-readiness-dashboard/starter/src/App.test.tsxother342 B
references/benchmarks/release-readiness-dashboard/starter/src/App.tsxother979 B
references/benchmarks/release-readiness-dashboard/starter/src/main.tsxother238 B
references/benchmarks/release-readiness-dashboard/starter/src/styles.cssother976 B
references/benchmarks/release-readiness-dashboard/starter/src/test-setup.tsscript43 B
references/benchmarks/release-readiness-dashboard/starter/src/vite-env.d.tsscript38 B
references/benchmarks/release-readiness-dashboard/starter/tsconfig.app.jsonconfig552 B
references/benchmarks/release-readiness-dashboard/starter/tsconfig.jsonconfig89 B
references/benchmarks/release-readiness-dashboard/starter/vite.config.tsscript214 B
references/benchmarks/scientific-calculator-rust/00-requirements.mdmarkdown4.1 KB
references/benchmarks/scientific-calculator-rust/README.mdmarkdown1.4 KB
references/benchmarks/scientific-calculator-rust/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/scientific-calculator-rust/prompt-recursive-on.mdmarkdown16.6 KB
references/benchmarks/scientific-calculator-rust/scoring-rubric.mdmarkdown1.5 KB
references/benchmarks/scientific-calculator-rust/starter/.gitignoreother14 B
references/benchmarks/scientific-calculator-rust/starter/Cargo.lockmanifest25.7 KB
references/benchmarks/scientific-calculator-rust/starter/Cargo.tomlmanifest226 B
references/benchmarks/team-capacity-board/00-requirements.mdmarkdown3.6 KB
references/benchmarks/team-capacity-board/README.mdmarkdown1.0 KB
references/benchmarks/team-capacity-board/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/team-capacity-board/prompt-recursive-on.mdmarkdown14.8 KB
references/benchmarks/team-capacity-board/scoring-rubric.mdmarkdown1.4 KB
references/benchmarks/team-capacity-board/starter/.gitignoreother30 B
references/benchmarks/team-capacity-board/starter/README.mdmarkdown264 B
references/benchmarks/team-capacity-board/starter/index.htmlother316 B
references/benchmarks/team-capacity-board/starter/package.jsonmanifest628 B
references/benchmarks/team-capacity-board/starter/src/App.test.tsxother334 B
references/benchmarks/team-capacity-board/starter/src/App.tsxother971 B
references/benchmarks/team-capacity-board/starter/src/main.tsxother238 B
references/benchmarks/team-capacity-board/starter/src/styles.cssother976 B
references/benchmarks/team-capacity-board/starter/src/test-setup.tsscript43 B
references/benchmarks/team-capacity-board/starter/src/vite-env.d.tsscript38 B
references/benchmarks/team-capacity-board/starter/tsconfig.app.jsonconfig552 B
references/benchmarks/team-capacity-board/starter/tsconfig.jsonconfig89 B
references/benchmarks/team-capacity-board/starter/vite.config.tsscript214 B
references/bootstrap/RECURSIVE.mdmarkdown109.9 KB
references/fixtures/tiny-tasks-smoke-recipe.mdmarkdown2.6 KB
references/local-first-web-app-checklist.mdmarkdown1.6 KB
references/plans-canonical.mdmarkdown10.8 KB
scripts/check-reusable-repo-hygiene.ps1script625 B
scripts/check-reusable-repo-hygiene.pyscript6.3 KB
scripts/install-recursive-mode.ps1script36.0 KB
scripts/install-recursive-mode.pyscript31.8 KB
scripts/install-recursive-mode.shscript363 B
scripts/lint-recursive-run.ps1script739 B
scripts/lint-recursive-run.pyscript127.4 KB
scripts/recursive-closeout.ps1script1015 B
scripts/recursive-closeout.pyscript24.0 KB
scripts/recursive-init.ps1script18.7 KB
scripts/recursive-init.pyscript12.6 KB
scripts/recursive-lock.ps1script677 B
scripts/recursive-lock.pyscript12.6 KB
scripts/recursive-review-bundle.ps1script2.9 KB
scripts/recursive-review-bundle.pyscript22.1 KB
scripts/recursive-router-cli-configure.ps1script86 B
scripts/recursive-router-cli-configure.pyscript230 B
scripts/recursive-router-cli-init.ps1script81 B
scripts/recursive-router-cli-init.pyscript225 B
scripts/recursive-router-cli-invoke.ps1script83 B
scripts/recursive-router-cli-invoke.pyscript227 B
scripts/recursive-router-cli-probe.ps1script82 B
scripts/recursive-router-cli-probe.pyscript226 B
scripts/recursive-router-cli-resolve.ps1script84 B
scripts/recursive-router-cli-resolve.pyscript228 B
scripts/recursive-router-cli-validate.ps1script85 B
scripts/recursive-router-cli-validate.pyscript229 B
scripts/recursive-router-configure.ps1script798 B
scripts/recursive-router-configure.pyscript2.8 KB
scripts/recursive-router-init.ps1script490 B
scripts/recursive-router-init.pyscript925 B
scripts/recursive-router-invoke.ps1script1.5 KB
scripts/recursive-router-invoke.pyscript4.4 KB
scripts/recursive-router-probe.ps1script735 B
scripts/recursive-router-probe.pyscript1.6 KB
scripts/recursive-router-resolve.ps1script803 B
scripts/recursive-router-resolve.pyscript1.6 KB
scripts/recursive-router-validate.ps1script494 B
scripts/recursive-router-validate.pyscript804 B
scripts/recursive-status.ps1script674 B
scripts/recursive-status.pyscript97.7 KB
scripts/recursive-subagent-action.ps1script5.8 KB
scripts/recursive-subagent-action.pyscript12.4 KB
scripts/recursive-training-extract.ps1script586 B
scripts/recursive-training-extract.pyscript1.0 KB
scripts/recursive-training-grpo.ps1script1.2 KB
scripts/recursive-training-grpo.pyscript47.2 KB
scripts/recursive-training-loader.ps1script2.3 KB
scripts/recursive-training-loader.pyscript20.1 KB
scripts/recursive-training-mcp.ps1script721 B
scripts/recursive-training-mcp.pyscript10.1 KB
scripts/recursive-training-phase8-trigger.ps1script1.4 KB
scripts/recursive-training-phase8-trigger.pyscript4.0 KB
scripts/recursive-training-sync.ps1script735 B
scripts/recursive-training-sync.pyscript6.9 KB
scripts/recursive_phase_rules.pyscript12.7 KB
scripts/recursive_router_cli_lib.pyscript77 B
scripts/recursive_router_lib.pyscript84.5 KB
scripts/run-recursive-benchmark.ps1script2.1 KB
scripts/run-recursive-benchmark.pyscript376.1 KB
scripts/test-recursive-mode-smoke.ps1script1.0 KB
scripts/test-recursive-mode-smoke.pyscript121.0 KB
scripts/test_install_recursive_mode.pyscript38.4 KB
scripts/test_lint_recursive_run.pyscript4.1 KB
scripts/test_recursive_phase_rules.pyscript21.4 KB
scripts/test_recursive_review_bundle.pyscript5.8 KB
scripts/test_recursive_router.pyscript53.3 KB
scripts/test_recursive_subagent_action.pyscript3.2 KB
scripts/test_recursive_training.pyscript12.0 KB
scripts/test_run_recursive_benchmark.pyscript160.0 KB
scripts/verify-locks.ps1script733 B
scripts/verify-locks.pyscript13.8 KB

scripts/recursive_router_lib.py

View on GitHub
#!/usr/bin/env python3
"""
Shared helpers for recursive-router scripts.
"""

from __future__ import annotations

import json
import os
import queue
import re
import shutil
import subprocess
import tempfile
import threading
import time
import tomllib
import uuid
from copy import deepcopy
from dataclasses import dataclass
from datetime import datetime, timezone
from pathlib import Path


CANONICAL_ROLES = [
    "orchestrator",
    "analyst",
    "planner",
    "implementer",
    "code-reviewer",
    "tester",
    "memory-auditor",
]
LEGACY_ROLE_ALIASES = {
    "phase-auditor": "analyst",
    "traceability-auditor": "planner",
    "bounded-implementer": "implementer",
    "test-reviewer": "tester",
}
DEFAULT_ROLE_ROUTE_SPECS = {
    "orchestrator": {
        "enabled": True,
        "mode": "local-only",
        "cli": None,
        "model": None,
        "fallback": "local-controller",
    },
    "analyst": {
        "enabled": True,
        "mode": "external-cli",
        "cli": None,
        "model": None,
        "fallback": "self-audit",
    },
    "planner": {
        "enabled": True,
        "mode": "external-cli",
        "cli": None,
        "model": None,
        "fallback": "self-audit",
    },
    "implementer": {
        "enabled": False,
        "mode": "external-cli",
        "cli": None,
        "model": None,
        "fallback": "local-controller",
    },
    "code-reviewer": {
        "enabled": True,
        "mode": "external-cli",
        "cli": None,
        "model": None,
        "fallback": "self-audit",
    },
    "tester": {
        "enabled": True,
        "mode": "external-cli",
        "cli": None,
        "model": None,
        "fallback": "self-audit",
    },
    "memory-auditor": {
        "enabled": True,
        "mode": "external-cli",
        "cli": None,
        "model": None,
        "fallback": "self-audit",
    },
}
CONFIG_VERSION = 1
DISCOVERY_VERSION = 1
ROUTER_NAME = "recursive-router"
LEGACY_ROUTER_NAME = "recursive-router-cli"
ROUTER_POLICY_FILENAME = "recursive-router.json"
LEGACY_ROUTER_POLICY_FILENAME = "recursive-router-cli.json"
ROUTER_DISCOVERY_FILENAME = "recursive-router-discovered.json"
LEGACY_ROUTER_DISCOVERY_FILENAME = "recursive-router-cli-discovered.json"
ALLOWED_ROLE_UNCONFIGURED = {"ask", "fallback-local", "block"}
ALLOWED_CLI_UNAVAILABLE = {"fallback-local", "ask", "block"}
ALLOWED_MODEL_UNKNOWN = {"ask", "use-as-literal", "fallback-local"}
ALLOWED_ROLE_MODES = {"external-cli", "local-only"}
ALLOWED_ROLE_FALLBACKS = {"self-audit", "local-controller", "ask", "block"}
ALLOWED_PROBE_STATUS = {"ok", "partial", "failed"}
ALLOWED_MODEL_SOURCE = {
    "app-server-model-list",
    "cli-list",
    "adapter-defaults",
    "cache-file",
    "configured-static-list",
    "config-file",
    "unsupported",
    "failed",
    "unknown",
}


class RouterConfigError(ValueError):
    """Raised when the router policy is invalid."""


@dataclass(frozen=True)
class CLIAdapter:
    id: str
    command: str | tuple[str, ...]
    probe_args: tuple[str, ...] = ("--version",)
    model_list_template: tuple[str, ...] | None = None
    builtin: bool = True
    default_models: tuple[str, ...] = ()
    invoke_template: tuple[str, ...] = ()
    transport: str = "cli-template"


BUILTIN_ADAPTERS: tuple[CLIAdapter, ...] = (
    CLIAdapter(
        id="codex",
        command="codex",
        invoke_template=("exec", "--model", "{model}", "--input-file", "{prompt_file}"),
        transport="app-server",
    ),
    CLIAdapter(
        id="kimi",
        command="kimi",
        invoke_template=(
            "--model",
            "{model}",
            "--work-dir",
            "{repo_root}",
            "--print",
            "--output-format",
            "stream-json",
            "--max-ralph-iterations",
            "0",
            "--prompt",
            "{prompt}",
        ),
    ),
    CLIAdapter(
        id="opencode",
        command="opencode",
        model_list_template=("models",),
        invoke_template=("run", "--model", "{model}", "--prompt-file", "{prompt_file}"),
    ),
)
BUILTIN_ADAPTER_BY_ID = {adapter.id: adapter for adapter in BUILTIN_ADAPTERS}


def utc_now_iso() -> str:
    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")


def normalize_repo_path(raw_path: str) -> str:
    return "/" + raw_path.replace("\\", "/").strip().lstrip("/")


def canonicalize_router_role(role: str) -> str:
    normalized = role.strip()
    if normalized in CANONICAL_ROLES:
        return normalized
    legacy = LEGACY_ROLE_ALIASES.get(normalized)
    if legacy is not None:
        return legacy
    raise RouterConfigError(f"Unknown router role: {role}")


def default_role_routes() -> dict[str, dict[str, object]]:
    return {role: deepcopy(route) for role, route in DEFAULT_ROLE_ROUTE_SPECS.items()}


def router_config_dir(repo_root: Path) -> Path:
    return repo_root / ".recursive" / "config"


def router_policy_path(repo_root: Path) -> Path:
    return router_config_dir(repo_root) / ROUTER_POLICY_FILENAME


def legacy_router_policy_path(repo_root: Path) -> Path:
    return router_config_dir(repo_root) / LEGACY_ROUTER_POLICY_FILENAME


def router_discovery_path(repo_root: Path) -> Path:
    return router_config_dir(repo_root) / ROUTER_DISCOVERY_FILENAME


def legacy_router_discovery_path(repo_root: Path) -> Path:
    return router_config_dir(repo_root) / LEGACY_ROUTER_DISCOVERY_FILENAME


def default_router_policy() -> dict[str, object]:
    return {
        "version": CONFIG_VERSION,
        "defaults": {
            "when_role_unconfigured": "ask",
            "when_cli_unavailable": "fallback-local",
            "when_model_unknown": "ask",
            "allow_auto_assign_if_single_cli": False,
            "probe_timeout_ms": 50000,
            "invoke_timeout_ms": 180000,
        },
        "role_routes": default_role_routes(),
        "cli_overrides": {},
        "custom_clis": [],
    }


def empty_discovery_inventory(*, probe_tool: str, probe_status: str = "partial", clis: list[dict[str, object]] | None = None) -> dict[str, object]:
    return {
        "version": DISCOVERY_VERSION,
        "generated_at": utc_now_iso(),
        "probe_tool": probe_tool,
        "probe_status": probe_status,
        "clis": clis or [],
    }


def pretty_json(payload: object) -> str:
    return json.dumps(payload, indent=2, ensure_ascii=True) + "\n"


def write_json(path: Path, payload: object) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(pretty_json(payload), encoding="utf-8", newline="\n")


def read_json(path: Path) -> object:
    return json.loads(path.read_text(encoding="utf-8"))


def load_policy(repo_root: Path) -> dict[str, object]:
    policy_path = router_policy_path(repo_root)
    if not policy_path.exists():
        legacy_policy = legacy_router_policy_path(repo_root)
        if legacy_policy.exists():
            policy_path = legacy_policy
        else:
            raise RouterConfigError(f"Missing routing policy file: {normalize_repo_path(str(policy_path.relative_to(repo_root)))}")
    try:
        policy = read_json(policy_path)
    except json.JSONDecodeError as exc:
        raise RouterConfigError(f"Routing policy file is not valid JSON: {exc}") from exc
    return validate_policy(policy)


def ensure_router_scaffold(repo_root: Path) -> tuple[Path, Path]:
    config_dir = router_config_dir(repo_root)
    config_dir.mkdir(parents=True, exist_ok=True)
    policy_path = router_policy_path(repo_root)
    discovery_path = router_discovery_path(repo_root)
    legacy_policy_path = legacy_router_policy_path(repo_root)
    legacy_discovery_path = legacy_router_discovery_path(repo_root)

    if policy_path.exists():
        try:
            existing_raw = read_json(policy_path)
        except json.JSONDecodeError as exc:
            raise RouterConfigError(f"Existing routing policy is invalid JSON and will not be overwritten: {exc}") from exc
        existing = validate_policy(existing_raw)
        if existing != existing_raw:
            write_json(policy_path, existing)
    elif legacy_policy_path.exists():
        try:
            existing_raw = read_json(legacy_policy_path)
        except json.JSONDecodeError as exc:
            raise RouterConfigError(f"Existing legacy routing policy is invalid JSON and will not be migrated: {exc}") from exc
        existing = validate_policy(existing_raw)
        write_json(policy_path, existing)
        legacy_policy_path.unlink(missing_ok=True)
    else:
        write_json(policy_path, default_router_policy())

    if discovery_path.exists():
        pass
    elif legacy_discovery_path.exists():
        legacy_discovery_path.replace(discovery_path)

    return policy_path, discovery_path


def _as_dict(payload: object, label: str) -> dict[str, object]:
    if not isinstance(payload, dict):
        raise RouterConfigError(f"{label} must be a JSON object.")
    return payload


def _as_list_of_strings(value: object, field_name: str, *, allow_empty: bool = True) -> list[str]:
    if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
        raise RouterConfigError(f"{field_name} must be a list of strings.")
    if not allow_empty and not value:
        raise RouterConfigError(f"{field_name} must not be empty.")
    return list(value)


def _normalize_command_spec(value: object, field_name: str) -> str | tuple[str, ...]:
    if isinstance(value, str):
        command = value.strip()
        if not command:
            raise RouterConfigError(f"{field_name} must be a non-empty string when provided.")
        return command
    if isinstance(value, list) and value and all(isinstance(item, str) and item.strip() for item in value):
        return tuple(item.strip() for item in value)
    raise RouterConfigError(f"{field_name} must be a non-empty string or a non-empty list of strings.")


def _validate_invoke_template(template: list[str], field_name: str) -> None:
    if not any("{model}" in piece for piece in template):
        raise RouterConfigError(f"{field_name} must contain a {{model}} placeholder.")
    if not any("{prompt_file}" in piece or "{prompt}" in piece for piece in template):
        raise RouterConfigError(f"{field_name} must contain either a {{prompt_file}} or {{prompt}} placeholder.")


def normalize_role_routes(role_routes_payload: object) -> dict[str, object]:
    raw_role_routes = _as_dict(role_routes_payload, "role_routes")
    normalized_routes: dict[str, object] = default_role_routes()
    sources_by_canonical: dict[str, str] = {}
    for role_name, route_payload in raw_role_routes.items():
        if not isinstance(role_name, str):
            raise RouterConfigError("role_routes keys must be strings.")
        canonical_role = canonicalize_router_role(role_name)
        prior_source = sources_by_canonical.get(canonical_role)
        if prior_source is not None and prior_source != role_name:
            raise RouterConfigError(
                f"role_routes.{role_name} duplicates canonical role {canonical_role!r}; keep only {canonical_role!r}."
            )
        normalized_routes[canonical_role] = route_payload
        sources_by_canonical[canonical_role] = role_name
    return normalized_routes


def validate_policy(policy: object) -> dict[str, object]:
    payload = deepcopy(_as_dict(policy, "Router policy"))
    payload["role_routes"] = normalize_role_routes(payload.get("role_routes"))
    default_defaults = _as_dict(default_router_policy()["defaults"], "default defaults")

    version = payload.get("version")
    if version != CONFIG_VERSION:
        raise RouterConfigError(f"Unsupported config version: {version!r}. Expected {CONFIG_VERSION}.")

    defaults = _as_dict(payload.get("defaults"), "defaults")
    if defaults.get("when_role_unconfigured") not in ALLOWED_ROLE_UNCONFIGURED:
        raise RouterConfigError("defaults.when_role_unconfigured must be one of: ask, fallback-local, block.")
    if defaults.get("when_cli_unavailable") not in ALLOWED_CLI_UNAVAILABLE:
        raise RouterConfigError("defaults.when_cli_unavailable must be one of: fallback-local, ask, block.")
    if defaults.get("when_model_unknown") not in ALLOWED_MODEL_UNKNOWN:
        raise RouterConfigError("defaults.when_model_unknown must be one of: ask, use-as-literal, fallback-local.")
    if not isinstance(defaults.get("allow_auto_assign_if_single_cli"), bool):
        raise RouterConfigError("defaults.allow_auto_assign_if_single_cli must be a boolean.")
    probe_timeout_ms = defaults.get("probe_timeout_ms")
    if not isinstance(probe_timeout_ms, int) or probe_timeout_ms < 500 or probe_timeout_ms > 60000:
        raise RouterConfigError("defaults.probe_timeout_ms must be an integer between 500 and 60000.")
    invoke_timeout_ms = defaults.get("invoke_timeout_ms", default_defaults["invoke_timeout_ms"])
    if not isinstance(invoke_timeout_ms, int) or invoke_timeout_ms < 1000 or invoke_timeout_ms > 600000:
        raise RouterConfigError("defaults.invoke_timeout_ms must be an integer between 1000 and 600000.")

    role_routes = _as_dict(payload.get("role_routes"), "role_routes")
    for role in CANONICAL_ROLES:
        if role not in role_routes:
            raise RouterConfigError(f"role_routes is missing canonical role: {role}")

    for role_name, route_payload in role_routes.items():
        route = _as_dict(route_payload, f"role_routes.{role_name}")
        if not isinstance(route.get("enabled"), bool):
            raise RouterConfigError(f"role_routes.{role_name}.enabled must be a boolean.")
        if route.get("mode") not in ALLOWED_ROLE_MODES:
            raise RouterConfigError(f"role_routes.{role_name}.mode must be one of: external-cli, local-only.")
        cli_value = route.get("cli")
        if cli_value is not None and not isinstance(cli_value, str):
            raise RouterConfigError(f"role_routes.{role_name}.cli must be a string or null.")
        model_value = route.get("model")
        if model_value is not None and not isinstance(model_value, str):
            raise RouterConfigError(f"role_routes.{role_name}.model must be a string or null.")
        if route.get("fallback") not in ALLOWED_ROLE_FALLBACKS:
            raise RouterConfigError(f"role_routes.{role_name}.fallback must be one of: self-audit, local-controller, ask, block.")

    cli_overrides = payload.get("cli_overrides")
    if not isinstance(cli_overrides, dict):
        raise RouterConfigError("cli_overrides must be a JSON object.")
    builtin_ids = set(BUILTIN_ADAPTER_BY_ID)
    for cli_id, override_payload in cli_overrides.items():
        if cli_id not in builtin_ids:
            raise RouterConfigError(f"cli_overrides references unknown built-in CLI id: {cli_id}")
        override = _as_dict(override_payload, f"cli_overrides.{cli_id}")
        if "command" in override:
            _normalize_command_spec(override["command"], f"cli_overrides.{cli_id}.command")
        if "probe_args" in override:
            _as_list_of_strings(override["probe_args"], f"cli_overrides.{cli_id}.probe_args")
        if "invoke_template" in override:
            invoke_template = _as_list_of_strings(override["invoke_template"], f"cli_overrides.{cli_id}.invoke_template", allow_empty=False)
            _validate_invoke_template(invoke_template, f"cli_overrides.{cli_id}.invoke_template")
        if "model_list_template" in override and override["model_list_template"] is not None:
            _as_list_of_strings(override["model_list_template"], f"cli_overrides.{cli_id}.model_list_template")
        if "default_models" in override:
            _as_list_of_strings(override["default_models"], f"cli_overrides.{cli_id}.default_models")
        transport = override.get("transport")
        if transport is not None and (not isinstance(transport, str) or not transport.strip()):
            raise RouterConfigError(f"cli_overrides.{cli_id}.transport must be a non-empty string when provided.")

    custom_clis = payload.get("custom_clis")
    if not isinstance(custom_clis, list):
        raise RouterConfigError("custom_clis must be a list.")

    known_ids = {adapter.id for adapter in BUILTIN_ADAPTERS}
    for index, entry in enumerate(custom_clis):
        item = _as_dict(entry, f"custom_clis[{index}]")
        cli_id = item.get("id")
        if not isinstance(cli_id, str) or not cli_id.strip():
            raise RouterConfigError(f"custom_clis[{index}].id must be a non-empty string.")
        if cli_id in known_ids:
            raise RouterConfigError(f"custom_clis[{index}].id duplicates an existing CLI id: {cli_id}")
        known_ids.add(cli_id)

        command = _normalize_command_spec(item.get("command"), f"custom_clis[{index}].command")

        probe_args = _as_list_of_strings(item.get("probe_args"), f"custom_clis[{index}].probe_args")
        invoke_template = _as_list_of_strings(item.get("invoke_template"), f"custom_clis[{index}].invoke_template", allow_empty=False)
        _validate_invoke_template(invoke_template, f"custom_clis[{index}].invoke_template")
        model_list_template = item.get("model_list_template")
        if model_list_template is not None:
            _as_list_of_strings(model_list_template, f"custom_clis[{index}].model_list_template")
        _as_list_of_strings(probe_args, f"custom_clis[{index}].probe_args")

    valid_ids = known_ids
    for role_name, route_payload in role_routes.items():
        cli_value = route_payload.get("cli")
        if cli_value is not None and cli_value not in valid_ids:
            raise RouterConfigError(f"role_routes.{role_name}.cli references unknown CLI id: {cli_value}")
    return payload


def adapters_from_policy(policy: dict[str, object] | None) -> list[CLIAdapter]:
    adapters: list[CLIAdapter] = []
    override_map = policy.get("cli_overrides", {}) if policy else {}
    for adapter in BUILTIN_ADAPTERS:
        override = override_map.get(adapter.id, {})
        model_list_template = adapter.model_list_template
        if "model_list_template" in override:
            raw_model_list = override["model_list_template"]
            model_list_template = None if raw_model_list is None else tuple(raw_model_list)
        adapters.append(
            CLIAdapter(
                id=adapter.id,
                command=_normalize_command_spec(override["command"], f"cli_overrides.{adapter.id}.command")
                if "command" in override
                else adapter.command,
                probe_args=tuple(override.get("probe_args", list(adapter.probe_args))),
                model_list_template=model_list_template,
                builtin=adapter.builtin,
                default_models=tuple(override.get("default_models", list(adapter.default_models))),
                invoke_template=tuple(override.get("invoke_template", list(adapter.invoke_template))),
                transport=override.get("transport", adapter.transport),
            )
        )
    if not policy:
        return adapters
    for index, entry in enumerate(policy.get("custom_clis", [])):
        item = _as_dict(entry, "custom CLI")
        model_list_template = item.get("model_list_template")
        adapters.append(
            CLIAdapter(
                id=item["id"],
                command=_normalize_command_spec(item["command"], f"custom_clis[{index}].command"),
                probe_args=tuple(item["probe_args"]),
                model_list_template=tuple(model_list_template) if model_list_template is not None else None,
                builtin=False,
                invoke_template=tuple(item["invoke_template"]),
            )
        )
    return adapters


def _command_display(command: str | tuple[str, ...]) -> str | list[str]:
    return command if isinstance(command, str) else list(command)


def _resolve_executable_token(token: str) -> str | None:
    stripped = token.strip().strip('"')
    if not stripped:
        return None
    if os.path.isabs(stripped):
        return stripped if Path(stripped).exists() else None
    return shutil.which(stripped)


def _parse_windows_wrapper_command(wrapper_path: Path) -> list[str] | None:
    suffix = wrapper_path.suffix.lower()
    if suffix not in {".ps1", ".cmd", ".bat"}:
        return None
    try:
        text = wrapper_path.read_text(encoding="utf-8")
    except OSError:
        return None
    if suffix == ".ps1":
        match = re.search(r"^\s*&\s+((?:\"[^\"]+\"|'[^']+')(?:(?:\s+)(?:\"[^\"]+\"|'[^']+'))*)\s+@args\b", text, re.MULTILINE)
    else:
        match = re.search(r"^\s*@?(?:echo off\s*)?[\r\n]+((?:\"[^\"]+\")(?:\s+\"[^\"]+\")*)\s+%\*\s*$", text, re.MULTILINE)
    if match is None:
        return None
    quoted = re.findall(r"\"([^\"]+)\"|'([^']+)'", match.group(1))
    tokens = [first or second for first, second in quoted if first or second]
    if not tokens:
        return None
    resolved = _resolve_executable_token(tokens[0])
    if resolved is None:
        return None
    return [resolved, *tokens[1:]]


def resolve_command_argv(command: str | tuple[str, ...]) -> list[str] | None:
    if isinstance(command, str):
        tokens = [command]
    else:
        tokens = list(command)
    if not tokens:
        return None
    stripped = tokens[0].strip().strip('"')
    if not stripped:
        return None
    resolved = _resolve_executable_token(stripped)
    if resolved is None:
        return None
    if os.name == "nt" and os.path.isabs(resolved):
        parsed = _parse_windows_wrapper_command(Path(resolved))
        if parsed is not None:
            return [*parsed, *tokens[1:]]
    return [resolved, *tokens[1:]]


def resolve_command_path(command: str | tuple[str, ...]) -> str | None:
    argv = resolve_command_argv(command)
    return argv[0] if argv else None


def _run_command(command: list[str], *, timeout_ms: int, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
    if command and os.name == "nt" and command[0].lower().endswith(".ps1"):
        shell_path = resolve_command_path("pwsh") or resolve_command_path("powershell")
        if shell_path is not None:
            command = [shell_path, "-NoProfile", "-File", command[0], *command[1:]]
    env = os.environ.copy()
    env.setdefault("PYTHONIOENCODING", "utf-8")
    env.setdefault("PYTHONUTF8", "1")
    try:
        return subprocess.run(
            command,
            cwd=str(cwd) if cwd else None,
            text=True,
            encoding="utf-8",
            errors="replace",
            capture_output=True,
            env=env,
            timeout=max(0.5, timeout_ms / 1000.0),
            check=False,
        )
    except OSError as exc:
        return subprocess.CompletedProcess(
            args=command,
            returncode=127,
            stdout="",
            stderr=f"Failed to start command: {exc}",
        )


def _normalize_version(stdout: str, stderr: str) -> str | None:
    for stream in (stdout, stderr):
        for line in stream.splitlines():
            if line.strip():
                return line.strip()
    return None


def _parse_models(stdout: str) -> list[str]:
    text = stdout.strip()
    if not text:
        return []
    if text.startswith("["):
        payload = json.loads(text)
        if isinstance(payload, list):
            return [str(item) for item in payload]
    if text.startswith("{"):
        payload = json.loads(text)
        if isinstance(payload, dict) and isinstance(payload.get("models"), list):
            return [str(item) for item in payload["models"]]
    normalized_text = text.replace("\\r\\n", "\n").replace("\\n", "\n")
    return [line.strip() for line in normalized_text.splitlines() if line.strip()]


def _dedupe_strings(values: list[str]) -> list[str]:
    result: list[str] = []
    seen: set[str] = set()
    for value in values:
        if value not in seen:
            seen.add(value)
            result.append(value)
    return result


def _discover_codex_cached_models() -> tuple[list[str], str | None, str | None]:
    cache_path = Path.home() / ".codex" / "models_cache.json"
    if not cache_path.exists():
        return [], None, f"Codex model cache not found at {cache_path}."
    try:
        payload = read_json(cache_path)
    except (OSError, json.JSONDecodeError) as exc:
        return [], None, f"Failed to parse Codex model cache at {cache_path}: {exc}"

    model_entries: object
    if isinstance(payload, dict):
        model_entries = payload.get("models", [])
    else:
        model_entries = payload

    if not isinstance(model_entries, list):
        return [], None, f"Codex model cache at {cache_path} does not contain a models list."

    models: list[str] = []
    for entry in model_entries:
        if isinstance(entry, str) and entry.strip():
            models.append(entry.strip())
        elif isinstance(entry, dict):
            slug = entry.get("slug")
            if isinstance(slug, str) and slug.strip():
                models.append(slug.strip())
    return _dedupe_strings(models), "cache-file", None


def _discover_codex_app_server_models(command_argv: list[str], *, timeout_ms: int) -> tuple[list[str], str | None, str | None]:
    process = subprocess.Popen(
        [*command_argv, "app-server", "--listen", "stdio://"],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.STDOUT,
        text=True,
        bufsize=1,
    )
    if process.stdin is None or process.stdout is None:
        try:
            process.terminate()
        except OSError:
            pass
        return [], None, "Failed to open Codex app-server stdio streams."

    events: "queue.Queue[str | None]" = queue.Queue()
    transcript_lines: list[str] = []

    def reader() -> None:
        try:
            for raw_line in process.stdout:
                events.put(raw_line.rstrip("\r\n"))
        finally:
            events.put(None)

    reader_thread = threading.Thread(target=reader, daemon=True)
    reader_thread.start()

    def send(message: dict[str, object]) -> None:
        process.stdin.write(json.dumps(message) + "\n")
        process.stdin.flush()

    def read_until(predicate) -> dict[str, object]:
        deadline = time.monotonic() + max(0.5, timeout_ms / 1000.0)
        while time.monotonic() < deadline:
            remaining = max(0.1, deadline - time.monotonic())
            try:
                raw = events.get(timeout=remaining)
            except queue.Empty as exc:
                raise TimeoutError from exc
            if raw is None:
                break
            transcript_lines.append(raw)
            try:
                payload = json.loads(raw)
            except json.JSONDecodeError:
                continue
            if predicate(payload):
                return payload
        raise TimeoutError

    try:
        send(
            {
                "id": "initialize",
                "method": "initialize",
                "params": {
                    "clientInfo": {
                        "name": ROUTER_NAME,
                        "title": ROUTER_NAME,
                        "version": "1.0",
                    },
                    "capabilities": {"experimentalApi": True},
                },
            }
        )
        read_until(lambda payload: payload.get("id") == "initialize")
        send({"method": "initialized"})
        send({"id": "model-list", "method": "model/list", "params": {}})
        response_line = read_until(lambda payload: payload.get("id") == "model-list")
    except TimeoutError:
        message = "\n".join(transcript_lines).strip()
        if message:
            return [], None, f"Codex app-server model/list timed out after {timeout_ms}ms. Transcript: {message}"
        return [], None, f"Codex app-server model/list timed out after {timeout_ms}ms."
    finally:
        try:
            process.terminate()
        except OSError:
            pass
        try:
            process.wait(timeout=5)
        except subprocess.TimeoutExpired:
            process.kill()
            process.wait(timeout=5)

    error = response_line.get("error")
    if isinstance(error, dict):
        message = error.get("message")
        return [], None, f"Codex app-server model/list failed: {message or error!r}"

    result = response_line.get("result")
    if not isinstance(result, dict):
        return [], None, "Codex app-server model/list returned an invalid result payload."

    data = result.get("data", [])
    if not isinstance(data, list):
        return [], None, "Codex app-server model/list returned a non-list data payload."

    models: list[str] = []
    for entry in data:
        if isinstance(entry, dict):
            model_value = entry.get("model") or entry.get("id")
            if isinstance(model_value, str) and model_value.strip():
                models.append(model_value.strip())
        elif isinstance(entry, str) and entry.strip():
            models.append(entry.strip())
    return _dedupe_strings(models), "app-server-model-list", None


def _discover_codex_models(command_argv: list[str], *, timeout_ms: int) -> tuple[list[str], str | None, str | None]:
    app_server_models, app_server_source, app_server_note = _discover_codex_app_server_models(command_argv, timeout_ms=timeout_ms)
    if app_server_source is not None:
        return app_server_models, app_server_source, app_server_note

    cached_models, cached_source, cached_note = _discover_codex_cached_models()
    if cached_source is not None:
        fallback_note = app_server_note
        if cached_note:
            fallback_note = f"{fallback_note} Falling back to local cache. {cached_note}" if fallback_note else cached_note
        elif fallback_note:
            fallback_note = f"{fallback_note} Falling back to local cache."
        return cached_models, cached_source, fallback_note
    return [], None, app_server_note or cached_note


def _discover_kimi_configured_models() -> tuple[list[str], str | None, str | None]:
    config_path = Path.home() / ".kimi" / "config.toml"
    if not config_path.exists():
        return [], None, f"Kimi config file not found at {config_path}."
    try:
        payload = tomllib.loads(config_path.read_text(encoding="utf-8"))
    except (OSError, tomllib.TOMLDecodeError) as exc:
        return [], None, f"Failed to parse Kimi config at {config_path}: {exc}"

    models_section = payload.get("models")
    if not isinstance(models_section, dict):
        return [], None, f"Kimi config at {config_path} does not contain a models table."

    models: list[str] = []
    for alias, entry in models_section.items():
        if isinstance(alias, str) and alias.strip() and isinstance(entry, dict):
            model_value = entry.get("model")
            if isinstance(model_value, str) and model_value.strip():
                models.append(alias.strip())
    return _dedupe_strings(models), "config-file", None


def _discover_local_models(adapter: CLIAdapter) -> tuple[list[str], str | None, str | None]:
    if adapter.id == "codex":
        return _discover_codex_cached_models()
    if adapter.id == "kimi":
        return _discover_kimi_configured_models()
    return [], None, None


def probe_adapter(adapter: CLIAdapter, *, timeout_ms: int) -> dict[str, object]:
    command_argv = resolve_command_argv(adapter.command)
    resolved_path = command_argv[0] if command_argv else None
    notes: list[str] = []
    entry: dict[str, object] = {
        "id": adapter.id,
        "available": False,
        "builtin": adapter.builtin,
        "command": _command_display(adapter.command),
        "resolved_path": resolved_path,
        "version": None,
        "models": [],
        "model_source": "unknown",
        "transport": adapter.transport,
        "notes": notes,
    }
    if resolved_path is None:
        notes.append("Executable not found on PATH or at the configured absolute path.")
        return entry

    try:
        probe_result = _run_command([*command_argv, *adapter.probe_args], timeout_ms=timeout_ms)
    except subprocess.TimeoutExpired:
        notes.append(f"Probe command timed out after {timeout_ms}ms.")
        return entry

    if probe_result.returncode != 0:
        message = (probe_result.stderr or probe_result.stdout).strip() or f"Probe command exited with code {probe_result.returncode}."
        notes.append(message)
        return entry

    entry["available"] = True
    entry["version"] = _normalize_version(probe_result.stdout, probe_result.stderr)

    if adapter.id == "codex" and adapter.transport == "app-server" and adapter.model_list_template is None:
        models, model_source, note = _discover_codex_models(command_argv, timeout_ms=timeout_ms)
        if model_source is not None:
            entry["models"] = models
            entry["model_source"] = model_source
            if note:
                notes.append(note)
            return entry
        if note:
            notes.append(note)

    if adapter.model_list_template:
        try:
            models_result = _run_command([*command_argv, *adapter.model_list_template], timeout_ms=timeout_ms)
        except subprocess.TimeoutExpired:
            entry["model_source"] = "failed"
            notes.append(f"Model-list command timed out after {timeout_ms}ms.")
            return entry

        if models_result.returncode != 0:
            entry["model_source"] = "failed"
            message = (models_result.stderr or models_result.stdout).strip() or f"Model-list command exited with code {models_result.returncode}."
            notes.append(message)
            return entry

        entry["models"] = _parse_models(models_result.stdout)
        entry["model_source"] = "cli-list"
        return entry

    if adapter.default_models:
        entry["models"] = list(adapter.default_models)
        entry["model_source"] = "adapter-defaults"
        return entry

    local_models, local_source, local_note = _discover_local_models(adapter)
    if local_source is not None:
        entry["models"] = local_models
        entry["model_source"] = local_source
        if local_note:
            notes.append(local_note)
    elif local_note:
        entry["model_source"] = "unknown"
        notes.append(local_note)
    else:
        entry["model_source"] = "unsupported"
        notes.append("Model discovery is not supported for this CLI adapter.")
    return entry


def probe_inventory(
    repo_root: Path,
    *,
    timeout_ms: int | None = None,
    probe_tool: str,
    write_discovery: bool = True,
    policy: dict[str, object] | None = None,
) -> dict[str, object]:
    effective_policy = policy
    if effective_policy is None:
        try:
            effective_policy = load_policy(repo_root)
        except RouterConfigError:
            effective_policy = None

    if effective_policy is not None and timeout_ms is None:
        timeout_ms = int(_as_dict(effective_policy["defaults"], "defaults")["probe_timeout_ms"])
    timeout_ms = 2500 if timeout_ms is None else timeout_ms

    clis = [probe_adapter(adapter, timeout_ms=timeout_ms) for adapter in adapters_from_policy(effective_policy)]
    if not clis:
        probe_status = "failed"
    elif all(entry["available"] for entry in clis):
        probe_status = "ok"
    elif any(entry["available"] for entry in clis):
        probe_status = "partial"
    else:
        probe_status = "failed"
    inventory = empty_discovery_inventory(probe_tool=probe_tool, probe_status=probe_status, clis=clis)
    if write_discovery:
        discovery_path = router_discovery_path(repo_root)
        discovery_path.parent.mkdir(parents=True, exist_ok=True)
        write_json(discovery_path, inventory)
    return inventory


def _available_cli_entries(inventory: dict[str, object]) -> list[dict[str, object]]:
    return [entry for entry in inventory["clis"] if entry["available"]]


def _cli_entry_by_id(inventory: dict[str, object], cli_id: str) -> dict[str, object] | None:
    for entry in inventory["clis"]:
        if entry["id"] == cli_id:
            return entry
    return None


def _probe_timeout_ms_from_policy(policy: dict[str, object]) -> int:
    return int(_as_dict(policy["defaults"], "defaults")["probe_timeout_ms"])


def _invoke_timeout_ms_from_policy(policy: dict[str, object]) -> int:
    defaults = _as_dict(policy["defaults"], "defaults")
    return int(defaults.get("invoke_timeout_ms", _as_dict(default_router_policy()["defaults"], "default defaults")["invoke_timeout_ms"]))


def adapter_by_id(policy: dict[str, object] | None, cli_id: str) -> CLIAdapter | None:
    for adapter in adapters_from_policy(policy):
        if adapter.id == cli_id:
            return adapter
    return None


def _verification_prompt(token: str) -> str:
    return f"Reply with exactly this token and no extra text: {token}"


def _token_found(token: str, *streams: str | None) -> bool:
    return any(token in stream for stream in streams if stream)


def _run_template_invocation(
    *,
    command_argv: list[str],
    adapter: CLIAdapter,
    repo_root: Path,
    model: str,
    prompt: str,
    timeout_ms: int,
) -> subprocess.CompletedProcess[str]:
    with tempfile.TemporaryDirectory(prefix="recursive-router-verify-") as temp_dir:
        prompt_path = Path(temp_dir) / "prompt.txt"
        prompt_path.write_text(prompt, encoding="utf-8")
        command_path = command_argv[0]
        if (
            os.name == "nt"
            and "\n" in prompt
            and any("{prompt}" in piece for piece in adapter.invoke_template)
            and command_path.lower().endswith((".cmd", ".bat", ".ps1"))
        ):
            shell_path = resolve_command_path("pwsh") or resolve_command_path("powershell")
            if shell_path is not None:
                powershell_command_argv = list(command_argv)
                if command_path.lower().endswith((".cmd", ".bat")):
                    companion_ps1 = Path(command_path).with_suffix(".ps1")
                    if companion_ps1.exists():
                        powershell_command_argv = [str(companion_ps1), *command_argv[1:]]
                return _run_template_invocation_via_powershell(
                    shell_path=shell_path,
                    command_argv=powershell_command_argv,
                    adapter=adapter,
                    repo_root=repo_root,
                    model=model,
                    prompt_path=prompt_path,
                    timeout_ms=timeout_ms,
                )
        args = [
            piece.format(model=model, prompt_file=str(prompt_path), prompt=prompt, repo_root=str(repo_root))
            for piece in adapter.invoke_template
        ]
        return _run_command([*command_argv, *args], timeout_ms=timeout_ms, cwd=repo_root)


def _strip_ansi(text: str | None) -> str:
    if text is None:
        return ""
    return re.sub(r"\x1b\[[0-9;]*[A-Za-z]", "", text)


def _collect_text_content(value: object) -> list[str]:
    if isinstance(value, str):
        return [value] if value.strip() else []
    if isinstance(value, list):
        fragments: list[str] = []
        for item in value:
            fragments.extend(_collect_text_content(item))
        return fragments
    if isinstance(value, dict):
        fragments = []
        for key in ("text", "content"):
            if key in value:
                fragments.extend(_collect_text_content(value[key]))
        return fragments
    return []


def _assistant_text_from_payload(value: object) -> list[str]:
    if isinstance(value, list):
        fragments: list[str] = []
        for item in value:
            fragments.extend(_assistant_text_from_payload(item))
        return fragments
    if not isinstance(value, dict):
        return []

    role = str(value.get("role", "")).lower()
    payload_type = str(value.get("type", "")).lower()
    assistant_like = role == "assistant" or payload_type in {
        "assistant",
        "assistant_message",
        "agentmessage",
        "agent_message",
    }
    if assistant_like:
        fragments = _collect_text_content(value)
        if fragments:
            return fragments

    fragments: list[str] = []
    for key in ("message", "delta", "part", "content", "data"):
        child = value.get(key)
        if isinstance(child, (dict, list)):
            fragments.extend(_assistant_text_from_payload(child))
    return fragments


def _normalize_kimi_output(text: str) -> str:
    fragments: list[str] = []
    plain_lines: list[str] = []
    for raw_line in text.splitlines():
        line = raw_line.strip()
        if not line or line == "<choice>STOP</choice>":
            continue
        if line.startswith("{"):
            try:
                payload = json.loads(line)
            except json.JSONDecodeError:
                plain_lines.append(raw_line)
                continue
            fragments.extend(_assistant_text_from_payload(payload))
        else:
            plain_lines.append(raw_line)
    if fragments:
        return "\n".join(fragment.strip() for fragment in fragments if fragment.strip()).strip()
    return "\n".join(line for line in plain_lines if line.strip()).strip()


def _normalize_opencode_output(text: str) -> str:
    stripped = text.strip()
    if not stripped:
        return ""
    fragments: list[str] = []
    for raw_line in stripped.splitlines():
        line = raw_line.strip()
        if not line or not line.startswith("{"):
            continue
        try:
            payload = json.loads(line)
        except json.JSONDecodeError:
            continue
        if not isinstance(payload, dict) or payload.get("type") != "text":
            continue
        part = payload.get("part")
        if not isinstance(part, dict):
            continue
        message = part.get("text")
        if isinstance(message, str) and message.strip():
            fragments.append(message.strip())
    if fragments:
        return "\n".join(fragments).strip()
    return stripped


def _single_quote_for_powershell(value: str) -> str:
    return value.replace("'", "''")


def _run_template_invocation_via_powershell(
    *,
    shell_path: str,
    command_argv: list[str],
    adapter: CLIAdapter,
    repo_root: Path,
    model: str,
    prompt_path: Path,
    timeout_ms: int,
) -> subprocess.CompletedProcess[str]:
    script_path = prompt_path.with_name("invoke-router-template.ps1")
    command_lines = [f"    '{_single_quote_for_powershell(part)}'" for part in command_argv]
    args_lines: list[str] = []
    prompt_expression = f"(Get-Content -Raw -LiteralPath '{_single_quote_for_powershell(str(prompt_path))}')"
    for piece in adapter.invoke_template:
        if "{prompt}" in piece:
            before, after = piece.split("{prompt}", 1)
            expression_parts: list[str] = []
            if before:
                formatted_before = before.format(model=model, prompt_file=str(prompt_path), prompt="", repo_root=str(repo_root))
                expression_parts.append(f"'{_single_quote_for_powershell(formatted_before)}'")
            expression_parts.append(prompt_expression)
            if after:
                formatted_after = after.format(model=model, prompt_file=str(prompt_path), prompt="", repo_root=str(repo_root))
                expression_parts.append(f"'{_single_quote_for_powershell(formatted_after)}'")
            if len(expression_parts) == 1:
                args_lines.append(f"    {expression_parts[0]}")
            else:
                args_lines.append(f"    ({' + '.join(expression_parts)})")
            continue
        formatted = piece.format(model=model, prompt_file=str(prompt_path), prompt="", repo_root=str(repo_root))
        args_lines.append(f"    '{_single_quote_for_powershell(formatted)}'")
    script = "\n".join(
        [
            '$ErrorActionPreference = "Stop"',
            "$command = @(",
            *command_lines,
            ")",
            "if ($command.Length -gt 1) {",
            "    $commandPrefix = $command[1..($command.Length - 1)]",
            "} else {",
            "    $commandPrefix = @()",
            "}",
            "$argsList = @(",
            *args_lines,
            ")",
            "& $command[0] @commandPrefix @argsList",
            "exit $LASTEXITCODE",
        ]
    )
    script_path.write_text(script, encoding="utf-8", newline="\n")
    return _run_command([shell_path, "-NoProfile", "-File", str(script_path)], timeout_ms=timeout_ms, cwd=repo_root)


def _invoke_codex_app_server(
    *,
    command_argv: list[str],
    repo_root: Path,
    model: str,
    prompt: str,
    timeout_ms: int,
) -> dict[str, object]:
    process = subprocess.Popen(
        [*command_argv, "app-server", "--listen", "stdio://"],
        cwd=str(repo_root),
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.STDOUT,
        text=True,
        bufsize=1,
    )
    if process.stdin is None or process.stdout is None:
        try:
            process.terminate()
        except OSError:
            pass
        return {
            "success": False,
            "transport": "app-server",
            "exit_code": None,
            "stdout": "",
            "stderr": "",
            "reason": "Failed to open Codex app-server stdio streams.",
            "transcript": "",
        }

    events: "queue.Queue[str | None]" = queue.Queue()
    transcript_lines: list[str] = []

    def reader() -> None:
        try:
            for raw_line in process.stdout:
                events.put(raw_line.rstrip("\r\n"))
        finally:
            events.put(None)

    reader_thread = threading.Thread(target=reader, daemon=True)
    reader_thread.start()

    def send(message: dict[str, object]) -> None:
        process.stdin.write(json.dumps(message) + "\n")
        process.stdin.flush()

    def read_until(predicate) -> dict[str, object]:
        deadline = time.monotonic() + max(0.5, timeout_ms / 1000.0)
        while time.monotonic() < deadline:
            remaining = max(0.1, deadline - time.monotonic())
            try:
                raw = events.get(timeout=remaining)
            except queue.Empty as exc:
                raise TimeoutError from exc
            if raw is None:
                break
            transcript_lines.append(raw)
            try:
                payload = json.loads(raw)
            except json.JSONDecodeError:
                continue
            if predicate(payload):
                return payload
        raise TimeoutError

    final_message = ""
    try:
        send(
            {
                "id": "initialize",
                "method": "initialize",
                "params": {
                    "clientInfo": {
                        "name": ROUTER_NAME,
                        "title": ROUTER_NAME,
                        "version": "1.0",
                    },
                    "capabilities": {"experimentalApi": True},
                },
            }
        )
        read_until(lambda payload: payload.get("id") == "initialize")
        send({"method": "initialized"})
        send(
            {
                "id": "thread-start",
                "method": "thread/start",
                "params": {
                    "model": model,
                    "approvalPolicy": "never",
                    "sandbox": "read-only",
                    "cwd": str(repo_root),
                },
            }
        )
        thread_start = read_until(lambda payload: payload.get("id") == "thread-start")
        if isinstance(thread_start.get("error"), dict):
            message = thread_start["error"].get("message") or repr(thread_start["error"])
            return {
                "success": False,
                "transport": "app-server",
                "exit_code": None,
                "stdout": "",
                "stderr": "",
                "reason": f"Codex thread/start failed: {message}",
                "transcript": "\n".join(transcript_lines),
            }
        thread_id = str(_as_dict(thread_start["result"], "thread/start result")["thread"]["id"])

        send(
            {
                "id": "turn-start",
                "method": "turn/start",
                "params": {
                    "threadId": thread_id,
                    "model": model,
                    "input": [{"type": "text", "text": prompt, "text_elements": []}],
                },
            }
        )
        turn_start = read_until(lambda payload: payload.get("id") == "turn-start")
        if isinstance(turn_start.get("error"), dict):
            message = turn_start["error"].get("message") or repr(turn_start["error"])
            return {
                "success": False,
                "transport": "app-server",
                "exit_code": None,
                "stdout": "",
                "stderr": "",
                "reason": f"Codex turn/start failed: {message}",
                "transcript": "\n".join(transcript_lines),
            }
        turn_id = str(_as_dict(turn_start["result"], "turn/start result")["turn"]["id"])

        deadline = time.monotonic() + max(0.5, timeout_ms / 1000.0)
        while time.monotonic() < deadline:
            remaining = max(0.1, deadline - time.monotonic())
            try:
                raw = events.get(timeout=remaining)
            except queue.Empty as exc:
                raise TimeoutError from exc
            if raw is None:
                break
            transcript_lines.append(raw)
            try:
                payload = json.loads(raw)
            except json.JSONDecodeError:
                continue
            if payload.get("method") == "item/completed":
                params = payload.get("params", {})
                item = params.get("item", {})
                if (
                    params.get("threadId") == thread_id
                    and params.get("turnId") == turn_id
                    and item.get("type") == "agentMessage"
                    and item.get("phase") == "final_answer"
                ):
                    final_message = str(item.get("text", ""))
            if payload.get("method") == "turn/completed":
                params = payload.get("params", {})
                turn = params.get("turn", {})
                if params.get("threadId") == thread_id and turn.get("id") == turn_id:
                    return {
                        "success": bool(final_message.strip()),
                        "transport": "app-server",
                        "exit_code": 0,
                        "stdout": final_message,
                        "stderr": "",
                        "reason": "Prompt completed via Codex app-server." if final_message.strip() else "Codex returned no final answer text.",
                        "transcript": "\n".join(transcript_lines),
                    }
        raise TimeoutError
    except TimeoutError:
        return {
            "success": False,
            "transport": "app-server",
            "exit_code": None,
            "stdout": "",
            "stderr": "",
            "reason": f"Codex app-server invocation timed out after {timeout_ms}ms.",
            "transcript": "\n".join(transcript_lines),
        }
    finally:
        try:
            process.terminate()
        except OSError:
            pass
        try:
            process.wait(timeout=5)
        except subprocess.TimeoutExpired:
            process.kill()
            process.wait(timeout=5)


def _verify_codex_app_server(
    *,
    command_argv: list[str],
    repo_root: Path,
    model: str,
    prompt: str,
    timeout_ms: int,
) -> dict[str, object]:
    process = subprocess.Popen(
        [*command_argv, "app-server", "--listen", "stdio://"],
        cwd=str(repo_root),
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.STDOUT,
        text=True,
        bufsize=1,
    )
    if process.stdin is None or process.stdout is None:
        try:
            process.terminate()
        except OSError:
            pass
        return {
            "verified": False,
            "transport": "app-server",
            "exit_code": None,
            "token_found": False,
            "stdout": "",
            "stderr": "",
            "reason": "Failed to open Codex app-server stdio streams.",
        }

    events: "queue.Queue[str | None]" = queue.Queue()
    transcript_lines: list[str] = []

    def reader() -> None:
        try:
            for raw_line in process.stdout:
                events.put(raw_line.rstrip("\r\n"))
        finally:
            events.put(None)

    reader_thread = threading.Thread(target=reader, daemon=True)
    reader_thread.start()

    def send(message: dict[str, object]) -> None:
        process.stdin.write(json.dumps(message) + "\n")
        process.stdin.flush()

    def read_until(predicate) -> dict[str, object]:
        deadline = time.monotonic() + max(0.5, timeout_ms / 1000.0)
        while time.monotonic() < deadline:
            remaining = max(0.1, deadline - time.monotonic())
            try:
                raw = events.get(timeout=remaining)
            except queue.Empty as exc:
                raise TimeoutError from exc
            if raw is None:
                break
            transcript_lines.append(raw)
            try:
                payload = json.loads(raw)
            except json.JSONDecodeError:
                continue
            if predicate(payload):
                return payload
        raise TimeoutError

    final_message = ""
    try:
        send(
            {
                "id": "initialize",
                "method": "initialize",
                "params": {
                    "clientInfo": {
                        "name": ROUTER_NAME,
                        "title": ROUTER_NAME,
                        "version": "1.0",
                    },
                    "capabilities": {"experimentalApi": True},
                },
            }
        )
        read_until(lambda payload: payload.get("id") == "initialize")
        send({"method": "initialized"})
        send(
            {
                "id": "thread-start",
                "method": "thread/start",
                "params": {
                    "model": model,
                    "approvalPolicy": "never",
                    "sandbox": "read-only",
                    "cwd": str(repo_root),
                },
            }
        )
        thread_start = read_until(lambda payload: payload.get("id") == "thread-start")
        if isinstance(thread_start.get("error"), dict):
            message = thread_start["error"].get("message") or repr(thread_start["error"])
            return {
                "verified": False,
                "transport": "app-server",
                "exit_code": None,
                "token_found": False,
                "stdout": "\n".join(transcript_lines),
                "stderr": "",
                "reason": f"Codex thread/start failed: {message}",
            }
        thread_id = str(_as_dict(thread_start["result"], "thread/start result")["thread"]["id"])

        send(
            {
                "id": "turn-start",
                "method": "turn/start",
                "params": {
                    "threadId": thread_id,
                    "model": model,
                    "input": [{"type": "text", "text": prompt, "text_elements": []}],
                },
            }
        )
        turn_start = read_until(lambda payload: payload.get("id") == "turn-start")
        if isinstance(turn_start.get("error"), dict):
            message = turn_start["error"].get("message") or repr(turn_start["error"])
            return {
                "verified": False,
                "transport": "app-server",
                "exit_code": None,
                "token_found": False,
                "stdout": "\n".join(transcript_lines),
                "stderr": "",
                "reason": f"Codex turn/start failed: {message}",
            }
        turn_id = str(_as_dict(turn_start["result"], "turn/start result")["turn"]["id"])

        deadline = time.monotonic() + max(0.5, timeout_ms / 1000.0)
        while time.monotonic() < deadline:
            remaining = max(0.1, deadline - time.monotonic())
            try:
                raw = events.get(timeout=remaining)
            except queue.Empty as exc:
                raise TimeoutError from exc
            if raw is None:
                break
            transcript_lines.append(raw)
            try:
                payload = json.loads(raw)
            except json.JSONDecodeError:
                continue
            if payload.get("method") == "item/completed":
                params = payload.get("params", {})
                item = params.get("item", {})
                if (
                    params.get("threadId") == thread_id
                    and params.get("turnId") == turn_id
                    and item.get("type") == "agentMessage"
                    and item.get("phase") == "final_answer"
                ):
                    final_message = str(item.get("text", ""))
            if payload.get("method") == "turn/completed":
                params = payload.get("params", {})
                turn = params.get("turn", {})
                if params.get("threadId") == thread_id and turn.get("id") == turn_id:
                    transcript = "\n".join(transcript_lines)
                    token = prompt.rsplit(":", 1)[-1].strip()
                    token_found = _token_found(token, final_message, transcript)
                    return {
                        "verified": token_found,
                        "transport": "app-server",
                        "exit_code": 0,
                        "token_found": token_found,
                        "stdout": final_message,
                        "stderr": "",
                        "reason": "Verification prompt completed via Codex app-server." if token_found else "Verification token not found in Codex response.",
                        "transcript": transcript,
                    }
        raise TimeoutError
    except TimeoutError:
        transcript = "\n".join(transcript_lines)
        return {
            "verified": False,
            "transport": "app-server",
            "exit_code": None,
            "token_found": False,
            "stdout": transcript,
            "stderr": "",
            "reason": f"Codex app-server verification timed out after {timeout_ms}ms.",
        }
    finally:
        try:
            process.terminate()
        except OSError:
            pass
        try:
            exit_code = process.wait(timeout=5)
        except subprocess.TimeoutExpired:
            process.kill()
            exit_code = process.wait(timeout=5)
        # Preserve a best-effort process exit code in the transcript for callers that need it.
        transcript_lines.append(f"[process-exit:{exit_code}]")


def verify_route_binding(
    repo_root: Path,
    *,
    role: str,
    cli_id: str,
    model: str,
    timeout_ms: int | None = None,
    policy: dict[str, object] | None = None,
) -> dict[str, object]:
    effective_policy = load_policy(repo_root) if policy is None else policy
    resolved_role = canonicalize_router_role(role)
    if not model.strip():
        raise RouterConfigError("Configured model must be a non-empty string.")

    adapter = adapter_by_id(effective_policy, cli_id)
    if adapter is None:
        raise RouterConfigError(f"Unknown CLI id: {cli_id}")

    effective_timeout_ms = _probe_timeout_ms_from_policy(effective_policy) if timeout_ms is None else timeout_ms
    command_argv = resolve_command_argv(adapter.command)
    command_path = command_argv[0] if command_argv else None
    token = f"ROUTER_VERIFY_{uuid.uuid4().hex[:12].upper()}"
    prompt = _verification_prompt(token)
    result: dict[str, object] = {
        "role": resolved_role,
        "cli": cli_id,
        "model": model,
        "transport": adapter.transport,
        "verified": False,
        "token": token,
        "token_found": False,
        "exit_code": None,
        "stdout": "",
        "stderr": "",
        "reason": "",
    }

    if command_path is None:
        result["reason"] = f"Executable for CLI {cli_id!r} was not found."
        return result

    builtin_adapter = BUILTIN_ADAPTER_BY_ID.get(adapter.id)
    template_overridden = builtin_adapter is not None and adapter.invoke_template != builtin_adapter.invoke_template
    transport_overridden = builtin_adapter is not None and adapter.transport != builtin_adapter.transport

    if adapter.id == "codex" and adapter.transport == "app-server":
        completed = _run_command(
            [
                *command_argv,
                "exec",
                "--model",
                model,
                "--json",
                "--skip-git-repo-check",
                "--ephemeral",
                "-c",
                "mcp_servers.playwright.enabled=false",
                "-c",
                "mcp_servers.subframe.enabled=false",
                "-c",
                'mcp_servers["subframe-docs"].enabled=false',
                "-c",
                "mcp_servers.pencil.enabled=false",
                "-C",
                str(repo_root),
                prompt,
            ],
            timeout_ms=effective_timeout_ms,
            cwd=repo_root,
        )
        token_found = _token_found(token, completed.stdout, completed.stderr)
        verification = {
            "verified": token_found and completed.returncode == 0,
            "transport": adapter.transport,
            "exit_code": completed.returncode,
            "token_found": token_found,
            "stdout": completed.stdout,
            "stderr": completed.stderr,
            "reason": (
                "Verification token observed in Codex exec output."
                if token_found and completed.returncode == 0
                else f"Codex verification failed with exit code {completed.returncode}."
            ),
        }
    elif adapter.id == "kimi" and not template_overridden and not transport_overridden:
        completed = _run_command(
            [
                *command_argv,
                "--model",
                model,
                "--work-dir",
                str(repo_root),
                "--print",
                "--output-format",
                "stream-json",
                "--max-ralph-iterations",
                "0",
                "--prompt",
                prompt,
            ],
            timeout_ms=effective_timeout_ms,
            cwd=repo_root,
        )
        combined = (completed.stdout or "") + "\n" + (completed.stderr or "")
        token_found = _token_found(token, completed.stdout, completed.stderr)
        verification = {
            "verified": token_found,
            "transport": adapter.transport,
            "exit_code": completed.returncode,
            "token_found": token_found,
            "stdout": completed.stdout,
            "stderr": completed.stderr,
            "reason": (
                "Verification token observed in Kimi output."
                if token_found
                else f"Kimi verification failed with exit code {completed.returncode}."
            ),
            "combined_output": combined,
        }
    elif adapter.id == "opencode" and not template_overridden and not transport_overridden:
        completed = _run_command(
            [
                *command_argv,
                "run",
                "--model",
                model,
                "--format",
                "json",
                "--dir",
                str(repo_root),
                prompt,
            ],
            timeout_ms=effective_timeout_ms,
            cwd=repo_root,
        )
        token_found = _token_found(token, completed.stdout, completed.stderr)
        verification = {
            "verified": token_found and completed.returncode == 0,
            "transport": adapter.transport,
            "exit_code": completed.returncode,
            "token_found": token_found,
            "stdout": completed.stdout,
            "stderr": completed.stderr,
            "reason": (
                "Verification token observed in Opencode output."
                if token_found and completed.returncode == 0
                else f"Opencode verification failed with exit code {completed.returncode}."
            ),
        }
    else:
        completed = _run_template_invocation(
            command_argv=command_argv,
            adapter=adapter,
            repo_root=repo_root,
            model=model,
            prompt=prompt,
            timeout_ms=effective_timeout_ms,
        )
        token_found = _token_found(token, completed.stdout, completed.stderr)
        verification = {
            "verified": token_found and completed.returncode == 0,
            "transport": adapter.transport,
            "exit_code": completed.returncode,
            "token_found": token_found,
            "stdout": completed.stdout,
            "stderr": completed.stderr,
            "reason": (
                f"Verification token observed in {cli_id} output."
                if token_found and completed.returncode == 0
                else f"{cli_id} verification failed with exit code {completed.returncode}."
            ),
        }

    result.update(verification)
    return result


def invoke_route_binding(
    repo_root: Path,
    *,
    role: str,
    prompt: str,
    timeout_ms: int | None = None,
    policy: dict[str, object] | None = None,
    write_discovery: bool = True,
) -> dict[str, object]:
    effective_policy = load_policy(repo_root) if policy is None else policy
    resolved_role = canonicalize_router_role(role)
    decision = resolve_route(repo_root, role=resolved_role, timeout_ms=timeout_ms, write_discovery=write_discovery)
    effective_timeout_ms = _invoke_timeout_ms_from_policy(effective_policy) if timeout_ms is None else timeout_ms
    payload: dict[str, object] = {
        "role": resolved_role,
        "decision": decision,
        "cli": decision.get("cli"),
        "model": decision.get("model"),
        "transport": decision.get("transport"),
        "resolved_command": None,
        "output_text": "",
        "raw_stdout": "",
        "raw_stderr": "",
        "exit_code": None,
        "success": False,
        "reason": "",
        "transcript": "",
    }

    if decision.get("decision") != "external-cli":
        payload["reason"] = f"Route did not resolve to external-cli: {decision.get('decision')}"
        return payload

    cli_id = str(decision["cli"])
    model = str(decision["model"])
    adapter = adapter_by_id(effective_policy, cli_id)
    if adapter is None:
        raise RouterConfigError(f"Unknown CLI id: {cli_id}")
    command_argv = resolve_command_argv(adapter.command)
    command_path = command_argv[0] if command_argv else None
    payload["resolved_command"] = _command_display(tuple(command_argv)) if command_argv and len(command_argv) > 1 else command_path
    if command_path is None:
        payload["reason"] = f"Executable for CLI {cli_id!r} was not found."
        return payload

    builtin_adapter = BUILTIN_ADAPTER_BY_ID.get(adapter.id)
    template_overridden = builtin_adapter is not None and adapter.invoke_template != builtin_adapter.invoke_template
    transport_overridden = builtin_adapter is not None and adapter.transport != builtin_adapter.transport

    if adapter.id == "codex" and adapter.transport == "app-server":
        invocation = _invoke_codex_app_server(
            command_argv=command_argv,
            repo_root=repo_root,
            model=model,
            prompt=prompt,
            timeout_ms=effective_timeout_ms,
        )
        payload.update(
            {
                "transport": invocation["transport"],
                "output_text": str(invocation["stdout"]).strip(),
                "raw_stdout": str(invocation["stdout"]),
                "raw_stderr": str(invocation["stderr"]),
                "exit_code": invocation["exit_code"],
                "success": invocation["success"],
                "reason": invocation["reason"],
                "transcript": invocation["transcript"],
            }
        )
        return payload

    if adapter.id == "kimi" and not template_overridden and not transport_overridden:
        completed = _run_command(
            [
                *command_argv,
                "--model",
                model,
                "--work-dir",
                str(repo_root),
                "--print",
                "--output-format",
                "stream-json",
                "--max-ralph-iterations",
                "0",
                "--prompt",
                prompt,
            ],
            timeout_ms=effective_timeout_ms,
            cwd=repo_root,
        )
        output_text = _normalize_kimi_output(completed.stdout)
        payload.update(
            {
                "output_text": output_text,
                "raw_stdout": completed.stdout,
                "raw_stderr": _strip_ansi(completed.stderr),
                "exit_code": completed.returncode,
                "success": bool(output_text) and completed.returncode == 0,
                "reason": (
                    "Prompt completed through Kimi."
                    if output_text and completed.returncode == 0
                    else f"Kimi returned output with exit code {completed.returncode}."
                    if output_text
                    else f"Kimi invocation failed with exit code {completed.returncode}."
                ),
            }
        )
        return payload

    if adapter.id == "opencode" and not template_overridden and not transport_overridden:
        completed = _run_command(
            [
                *command_argv,
                "run",
                "--model",
                model,
                "--format",
                "json",
                "--dir",
                str(repo_root),
                prompt,
            ],
            timeout_ms=effective_timeout_ms,
            cwd=repo_root,
        )
        output_text = _normalize_opencode_output(completed.stdout)
        payload.update(
            {
                "output_text": output_text,
                "raw_stdout": completed.stdout,
                "raw_stderr": _strip_ansi(completed.stderr),
                "exit_code": completed.returncode,
                "success": bool(output_text) and completed.returncode == 0,
                "reason": (
                    "Prompt completed through opencode."
                    if output_text and completed.returncode == 0
                    else f"opencode returned output with exit code {completed.returncode}."
                    if output_text
                    else f"opencode invocation failed with exit code {completed.returncode}."
                ),
            }
        )
        return payload

    completed = _run_template_invocation(
        command_argv=command_argv,
        adapter=adapter,
        repo_root=repo_root,
        model=model,
        prompt=prompt,
        timeout_ms=effective_timeout_ms,
    )
    output_text = completed.stdout.strip()
    payload.update(
        {
            "output_text": output_text,
            "raw_stdout": completed.stdout,
            "raw_stderr": _strip_ansi(completed.stderr),
            "exit_code": completed.returncode,
            "success": bool(output_text),
            "reason": (
                f"Prompt completed through {cli_id}."
                if output_text and completed.returncode == 0
                else f"{cli_id} returned output with exit code {completed.returncode}."
                if output_text
                else f"{cli_id} invocation failed with exit code {completed.returncode}."
            ),
        }
    )
    return payload


def configure_verified_routes(
    repo_root: Path,
    *,
    assignments: dict[str, dict[str, str]],
    timeout_ms: int | None = None,
) -> dict[str, object]:
    policy = load_policy(repo_root)
    normalized_assignments: dict[str, dict[str, str]] = {}
    for role, binding in assignments.items():
        canonical_role = canonicalize_router_role(role)
        if canonical_role in normalized_assignments:
            raise RouterConfigError(f"Duplicate role assignment provided for {canonical_role}.")
        normalized_assignments[canonical_role] = binding
    verification_results: dict[str, dict[str, object]] = {}
    verification_cache: dict[tuple[str, str], dict[str, object]] = {}
    for role, binding in normalized_assignments.items():
        cli_id = binding["cli"]
        model = binding["model"]
        cache_key = (cli_id, model)
        cached_result = verification_cache.get(cache_key)
        if cached_result is None:
            cached_result = verify_route_binding(
                repo_root,
                role=role,
                cli_id=cli_id,
                model=model,
                timeout_ms=timeout_ms,
                policy=policy,
            )
            verification_cache[cache_key] = cached_result
        role_result = deepcopy(cached_result)
        role_result["role"] = role
        verification_results[role] = role_result

    all_verified = all(result["verified"] for result in verification_results.values())
    if all_verified:
        updated_policy = deepcopy(policy)
        for role, binding in normalized_assignments.items():
            route = _as_dict(updated_policy["role_routes"][role], f"role_routes.{role}")
            route["cli"] = binding["cli"]
            route["model"] = binding["model"]
        write_json(router_policy_path(repo_root), validate_policy(updated_policy))

    return {
        "saved": all_verified,
        "policy_path": normalize_repo_path(str(router_policy_path(repo_root).relative_to(repo_root))),
        "verification_results": verification_results,
    }


def build_unresolved_prompt(*, roles: list[str], inventory: dict[str, object], reason: str, config_path: str, discovery_path: str) -> str:
    lines = ["I found these CLIs in this environment:"]
    for entry in inventory["clis"]:
        version = entry["version"] or "unknown version"
        models = entry["models"]
        model_suffix = f"; models: {', '.join(models)}" if models else ""
        lines.append(f"- {entry['id']} ({'available' if entry['available'] else 'unavailable'}, version {version}{model_suffix})")
    if len(lines) == 1:
        lines.append("- none discovered")
    lines.extend(
        [
            "",
            reason,
            f"Please choose a CLI and model for these roles in {config_path}.",
            f"For valid CLI ids and model ids, check {discovery_path}.",
            "",
            "Unresolved roles:",
        ]
    )
    lines.extend(f"- {role}" for role in roles)
    lines.extend(
        [
            "",
            "You can answer in a compact mapping like:",
            "analyst=codex:gpt-5",
            "code-reviewer=kimi:kimi-code/kimi-for-coding",
        ]
    )
    return "\n".join(lines)


def resolve_route(
    repo_root: Path,
    *,
    role: str,
    timeout_ms: int | None = None,
    write_discovery: bool = True,
) -> dict[str, object]:
    resolved_role = canonicalize_router_role(role)
    config_path = normalize_repo_path(str(router_policy_path(repo_root).relative_to(repo_root)))
    discovery_path = normalize_repo_path(str(router_discovery_path(repo_root).relative_to(repo_root)))
    policy_error = ""
    try:
        policy = load_policy(repo_root)
    except RouterConfigError as exc:
        policy = None
        policy_error = str(exc)

    inventory = probe_inventory(
        repo_root,
        timeout_ms=timeout_ms,
        probe_tool="recursive-router-probe",
        write_discovery=write_discovery,
        policy=policy,
    )

    if policy is None:
        reason = policy_error or f"Missing routing policy file at {config_path}."
        return {
            "role": resolved_role,
            "decision": "ask-user",
            "cli": None,
            "model": None,
            "available": False,
            "fallback_used": False,
            "fallback": "ask",
            "reason": reason,
            "config_path": config_path,
            "discovery_path": discovery_path,
            "prompt": build_unresolved_prompt(
                roles=[resolved_role],
                inventory=inventory,
                reason=reason,
                config_path=config_path,
                discovery_path=discovery_path,
            ),
        }

    if resolved_role not in policy["role_routes"]:
        raise RouterConfigError(f"Unknown router role: {role}")

    defaults = policy["defaults"]
    route = policy["role_routes"][resolved_role]
    if not route["enabled"] or route["mode"] == "local-only":
        return {
            "role": resolved_role,
            "decision": "local-only",
            "cli": None,
            "model": None,
            "available": True,
            "fallback_used": False,
            "fallback": route["fallback"],
            "reason": f"role_routes.{resolved_role} is configured for local-only execution.",
            "config_path": config_path,
            "discovery_path": discovery_path,
        }

    selected_cli = route["cli"]
    selected_model = route["model"]
    reason_parts: list[str] = [f"resolved from role_routes.{resolved_role}"]
    available_entries = _available_cli_entries(inventory)

    if selected_cli is None:
        if defaults["allow_auto_assign_if_single_cli"] and len(available_entries) == 1:
            selected_cli = available_entries[0]["id"]
            reason_parts = ["auto-assigned the only discovered CLI for the unresolved role route"]
        else:
            policy_choice = defaults["when_role_unconfigured"]
            if policy_choice == "fallback-local":
                return {
                    "role": resolved_role,
                    "decision": "fallback-local",
                    "cli": None,
                    "model": None,
                    "available": False,
                    "fallback_used": True,
                    "fallback": route["fallback"],
                    "reason": f"role_routes.{resolved_role}.cli is unconfigured and defaults.when_role_unconfigured=fallback-local.",
                    "config_path": config_path,
                    "discovery_path": discovery_path,
                }
            if policy_choice == "block":
                return {
                    "role": resolved_role,
                    "decision": "blocked",
                    "cli": None,
                    "model": None,
                    "available": False,
                    "fallback_used": False,
                    "fallback": route["fallback"],
                    "reason": f"role_routes.{resolved_role}.cli is unconfigured and defaults.when_role_unconfigured=block.",
                    "config_path": config_path,
                    "discovery_path": discovery_path,
                }
            prompt_reason = f"role_routes.{resolved_role}.cli is unresolved."
            return {
                "role": resolved_role,
                "decision": "ask-user",
                "cli": None,
                "model": None,
                "available": False,
                "fallback_used": False,
                "fallback": "ask",
                "reason": prompt_reason,
                "config_path": config_path,
                "discovery_path": discovery_path,
                "prompt": build_unresolved_prompt(
                    roles=[resolved_role],
                    inventory=inventory,
                    reason=prompt_reason,
                    config_path=config_path,
                    discovery_path=discovery_path,
                ),
            }

    cli_entry = _cli_entry_by_id(inventory, selected_cli)
    if cli_entry is None or not cli_entry["available"]:
        policy_choice = defaults["when_cli_unavailable"]
        reason = f"Configured CLI {selected_cli!r} is unavailable in the current environment."
        if policy_choice == "ask":
            return {
                "role": resolved_role,
                "decision": "ask-user",
                "cli": selected_cli,
                "model": selected_model,
                "available": False,
                "fallback_used": False,
                "fallback": "ask",
                "reason": reason,
                "config_path": config_path,
                "discovery_path": discovery_path,
                "prompt": build_unresolved_prompt(
                    roles=[resolved_role],
                    inventory=inventory,
                    reason=reason,
                    config_path=config_path,
                    discovery_path=discovery_path,
                ),
            }
        if policy_choice == "block":
            return {
                "role": resolved_role,
                "decision": "blocked",
                "cli": selected_cli,
                "model": selected_model,
                "available": False,
                "fallback_used": False,
                "fallback": route["fallback"],
                "reason": reason,
                "config_path": config_path,
                "discovery_path": discovery_path,
            }
        return {
            "role": resolved_role,
            "decision": "fallback-local",
            "cli": selected_cli,
            "model": selected_model,
            "available": False,
            "fallback_used": True,
            "fallback": route["fallback"],
            "reason": reason,
            "config_path": config_path,
            "discovery_path": discovery_path,
        }

    models = list(cli_entry["models"])
    if selected_model is None:
        policy_choice = defaults["when_model_unknown"]
        reason = f"{'; '.join(reason_parts)}; model is unresolved for role {resolved_role}."
        if policy_choice == "fallback-local":
            return {
                "role": resolved_role,
                "decision": "fallback-local",
                "cli": selected_cli,
                "model": None,
                "available": True,
                "fallback_used": True,
                "fallback": route["fallback"],
                "reason": reason,
                "config_path": config_path,
                "discovery_path": discovery_path,
            }
        return {
            "role": resolved_role,
            "decision": "ask-user" if policy_choice in {"ask", "use-as-literal"} else "blocked",
            "cli": selected_cli,
            "model": None,
            "available": True,
            "fallback_used": False,
            "fallback": "ask" if policy_choice in {"ask", "use-as-literal"} else route["fallback"],
            "reason": reason,
            "config_path": config_path,
            "discovery_path": discovery_path,
            "prompt": build_unresolved_prompt(
                roles=[resolved_role],
                inventory=inventory,
                reason=reason,
                config_path=config_path,
                discovery_path=discovery_path,
            ),
        }

    if models and selected_model not in models:
        policy_choice = defaults["when_model_unknown"]
        reason = f"{'; '.join(reason_parts)}; configured model {selected_model!r} was not listed by CLI {selected_cli!r}."
        if policy_choice == "use-as-literal":
            return {
                "role": resolved_role,
                "decision": "external-cli",
                "cli": selected_cli,
                "model": selected_model,
                "transport": cli_entry.get("transport"),
                "available": True,
                "fallback_used": False,
                "fallback": route["fallback"],
                "reason": reason + " Using the configured model string literally per policy.",
                "config_path": config_path,
                "discovery_path": discovery_path,
            }
        if policy_choice == "fallback-local":
            return {
                "role": resolved_role,
                "decision": "fallback-local",
                "cli": selected_cli,
                "model": selected_model,
                "available": True,
                "fallback_used": True,
                "fallback": route["fallback"],
                "reason": reason,
                "config_path": config_path,
                "discovery_path": discovery_path,
            }
        return {
            "role": resolved_role,
            "decision": "ask-user",
            "cli": selected_cli,
            "model": selected_model,
            "available": True,
            "fallback_used": False,
            "fallback": "ask",
            "reason": reason,
            "config_path": config_path,
            "discovery_path": discovery_path,
            "prompt": build_unresolved_prompt(
                roles=[resolved_role],
                inventory=inventory,
                reason=reason,
                config_path=config_path,
                discovery_path=discovery_path,
            ),
        }

    if not models and defaults["when_model_unknown"] == "ask":
        reason = f"{'; '.join(reason_parts)}; model {selected_model!r} could not be verified because CLI {selected_cli!r} does not advertise models."
        return {
            "role": resolved_role,
            "decision": "ask-user",
            "cli": selected_cli,
            "model": selected_model,
            "available": True,
            "fallback_used": False,
            "fallback": "ask",
            "reason": reason,
            "config_path": config_path,
            "discovery_path": discovery_path,
            "prompt": build_unresolved_prompt(
                roles=[resolved_role],
                inventory=inventory,
                reason=reason,
                config_path=config_path,
                discovery_path=discovery_path,
            ),
        }

    return {
        "role": resolved_role,
        "decision": "external-cli",
        "cli": selected_cli,
        "model": selected_model,
        "transport": cli_entry.get("transport"),
        "available": True,
        "fallback_used": False,
        "fallback": route["fallback"],
        "reason": "; ".join(reason_parts),
        "config_path": config_path,
        "discovery_path": discovery_path,
    }
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall