Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

620 KB
Raw Blame
import asyncio
import base64
import contextlib
import hashlib
import json
import logging
import os
import platform
import re
import shutil
import shlex
import socket
import ssl
import stat
import subprocess
import sys
import threading
import time
import urllib.parse
import urllib.request
import uuid
from datetime import datetime, timedelta, timezone
from http.client import HTTPSConnection
from pathlib import Path
from typing import Any, Callable, List, Optional

import yaml
from sqlalchemy import select
from sqlalchemy.dialects.sqlite import insert as sqlite_insert

from config import paths
from config.v2_config import (
    CONFIG_LOCK,
    V2Config,
    config_file_lock,
    AGENT_CREDENTIAL_SECTIONS,
    config_recovery_refusal,
    hub_supply_block,
)
from config.v2_settings import (
    SettingsStore,
    ChannelSettings,
    GuildSettings,
    UserSettings,
    RoutingSettings,
    _UNSET_AGENT_BINDING,
    LEGACY_ROUTING_ALIASES,
    normalize_show_message_types,
    _parse_routing,
    routing_to_dict,
)
from config.v2_sessions import SessionsStore
from config.platform_registry import get_platform_descriptor
from core import latest_version_cache
from core.backend_restart import NativeCredentialLease, NativeMigrationBlockedError, finish_native_operation
from core.install_integrity import verify_python_environment
from core.services import scope_settings
from vibe.opencode_config import (
    get_opencode_config_paths,
    load_first_opencode_user_config,
    set_jsonc_top_level_string_property,
)
from vibe.build_identity import get_build_identity
from vibe.desktop_backends import (
    DESKTOP_BACKEND_INSTALL_TIMEOUT_SECONDS,
    DESKTOP_BACKEND_LOCK_TIMEOUT_SECONDS,
    DESKTOP_BACKEND_PROBE_TIMEOUT_SECONDS,
    DESKTOP_BACKEND_PROCESS_DRAIN_TIMEOUT_SECONDS,
    DesktopBackendError,
    desktop_backend_toolchain,
    install_desktop_backend,
    is_desktop_backend_path,
)
from vibe.desktop_runtime import is_private_desktop_runtime_path
from vibe.desktop_update_status import read_desktop_update_status
from vibe.cli_health import CliHealth, probe_cli, probe_cli_sync
from vibe.cli_repair import REPAIR_PATH_CONFLICT, identify_repair_source, native_bootstrap_env
from vibe.cli_paths import (
    _candidate_cli_paths,
    _command_env_for,
    _is_executable_file,
    _ordered_cli_candidates,
    _npm_binary_candidates_for_prefix,
    _npm_global_binary_candidates,
    _npm_global_prefixes,
    _npm_prefix_for,
    _windows_executable_candidates,
    resolve_cli_path as _resolve_cli_path,
)
from vibe.upgrade import (
    _candidate_python,
    activation_block_reason,
    activate_upgrade_candidate,
    atomic_upgrade_lock,
    build_upgrade_plan,
    defer_upgrade_activation,
    discard_atomic_uv_install_generation,
    execute_upgrade_plan,
    format_deferred_activation_log,
    get_latest_version_info,
    get_running_vibe_path,
    get_safe_cwd,
    format_activation_failures,
    get_deferred_activation_log_path,
    is_desktop_managed_runtime,
    launcher_is_current_process,
    restart_is_pending,
    should_skip_show_runtime_prepare,
    UPGRADE_INSTALL_TIMEOUT_SECONDS,
    verify_upgrade_candidate,
)
from vibe.restart_supervisor import schedule_restart
from vibe import avault_authorization, backend_model_catalog
from vibe.i18n import t as backend_t
from modules.agents.catalog import (
    AGENT_BACKENDS,
    NATIVE_CLI_BACKENDS,
    agent_backend_catalog_payload,
    agent_backend_descriptors,
    display_name_for_backend,
    is_agent_backend,
    is_builtin_backend,
    is_native_cli_backend,
    latest_probe_for_backend,
    supports_runtime_refresh,
    supports_install,
    supports_web_oauth,
)
from modules.agents.subagent_router import list_codex_subagents
from core.vibe_agents import (
    AgentAlwaysEnabledError,
    AgentBotLockedError,
    AgentArchivedEditError,
    AgentArchiveError,
    AgentNameValidationError,
    AgentReferenceRewriteError,
    VibeAgentAccessError,
    VibeAgentStore,
    iter_global_agent_files,
    parse_agent_file,
    resolve_resource_access_context,
    validate_agent_backend,
)
from core.process_isolation import isolated_subprocess_kwargs, signal_process_tree, KILL_SIGNAL
from storage.lock import MigrationFileLock, MigrationLockTimeout
from core.dependency_network import DependencyNetworkError, dependency_error_message, fetch_to_path


logger = logging.getLogger(__name__)

_CURL_INSTALL_RETRY_FLAGS = "--retry 2 --retry-delay 1 --connect-timeout 10 --max-time 120"

# Cache per cwd: { cwd: { "data": ..., "updated_at": ... } }
_OPENCODE_OPTIONS_CACHE: dict[str, dict] = {}
_OPENCODE_OPTIONS_TTL_SECONDS = 30.0


_PLATFORM_SECRET_FIELDS: dict[str, tuple[str, ...]] = {
    "slack": ("bot_token", "app_token", "signing_secret"),
    "discord": ("bot_token",),
    "telegram": ("bot_token", "webhook_secret_token"),
    "lark": ("app_secret",),
    "wechat": ("bot_token",),
}
_GATEWAY_SECRET_FIELDS = ("workspace_token", "client_secret")


def _native_write_blocked(error: NativeMigrationBlockedError) -> dict:
    result = {"ok": False, "error": error.reason}
    if error.backends:
        result["backends"] = list(error.backends)
    if error.reason == "native_auth_hub_owned":
        result["reauth_channel"] = "hub"
    return result


def _native_auth_write(
    backend: str | None = None, *, pass_lease: bool = False, authentication: bool = True
):
    """Own the whole native RMW and its cancellation tail across instances.

    Model/permission-only edits need the same lease: rewriting a stale document
    can resurrect credentials after takeover. Only auth writers require native
    custody; non-auth edits remain usable with Hub routing.
    """
    from functools import wraps

    def decorate(function):
        def acquire(args, kwargs):
            target = str(backend or kwargs.get("backend") or (args[0] if args else "")).strip().lower()
            if target not in NATIVE_CLI_BACKENDS:
                raise NativeMigrationBlockedError("unsupported_backend", ())
            lease = NativeCredentialLease((target,)).acquire()
            try:
                if authentication:
                    lease.assert_auth_custody(target)
                return lease
            except BaseException:
                lease.release()
                raise

        if asyncio.iscoroutinefunction(function):
            @wraps(function)
            async def asynchronous(*args, **kwargs):
                try:
                    lease = acquire(args, kwargs)
                except NativeMigrationBlockedError as error:
                    return _native_write_blocked(error)
                try:
                    if pass_lease:
                        kwargs["_native_lease"] = lease
                    return await finish_native_operation(function(*args, **kwargs))
                finally:
                    lease.release()
            return asynchronous

        @wraps(function)
        def synchronous(*args, **kwargs):
            try:
                lease = acquire(args, kwargs)
            except NativeMigrationBlockedError as error:
                return _native_write_blocked(error)
            try:
                if pass_lease:
                    kwargs["_native_lease"] = lease
                return function(*args, **kwargs)
            finally:
                lease.release()
        return synchronous
    return decorate


def _parse_agent_import_file(path: Path, *, backend: str):
    try:
        return parse_agent_file(path, backend=backend)
    except (OSError, ValueError, TypeError, AttributeError, yaml.YAMLError) as exc:
        raise ValueError(f"Unable to read or parse agent import file: {exc}") from exc


def _validate_direct_agent_import_path(path: Path) -> Path:
    try:
        resolved = path.resolve(strict=False)
    except OSError as exc:
        raise ValueError(f"Unable to validate agent import file: {exc}") from exc
    if resolved.suffix.lower() != ".md":
        raise ValueError("Agent import file must be a Markdown (.md) file")
    try:
        raw = resolved.read_text(encoding="utf-8")
    except (OSError, UnicodeError) as exc:
        raise ValueError(f"Unable to read or parse agent import file: {exc}") from exc
    lines = raw.splitlines()
    if not lines or lines[0].strip() != "---":
        raise ValueError("Agent import file must include YAML frontmatter with a name field")
    end_idx = next((idx for idx, line in enumerate(lines[1:], start=1) if line.strip() == "---"), -1)
    if end_idx < 0:
        raise ValueError("Agent import file must include YAML frontmatter with a name field")
    try:
        header = yaml.safe_load("\n".join(lines[1:end_idx])) or {}
    except yaml.YAMLError as exc:
        raise ValueError(f"Unable to read or parse agent import file: {exc}") from exc
    if not isinstance(header, dict) or not str(header.get("name") or "").strip():
        raise ValueError("Agent import file must include YAML frontmatter with a name field")
    return resolved


def _enabled_agent_backends_from_config(config: Optional[V2Config] = None) -> list[str]:
    try:
        cfg = config or load_config()
    except FileNotFoundError:
        return [descriptor.id for descriptor in agent_backend_descriptors() if descriptor.default_enabled]
    result: list[str] = []
    agents = getattr(cfg, "agents", None)
    if agents is not None:
        for backend in AGENT_BACKENDS:
            backend_cfg = getattr(agents, backend, None)
            if backend_cfg is not None and bool(getattr(backend_cfg, "enabled", True)):
                result.append(backend)
    return result


def _ensure_builtin_default_agents(config: Optional[V2Config] = None) -> None:
    backends = _enabled_agent_backends_from_config(config)
    store = VibeAgentStore()
    try:
        store.ensure_builtin_default_agents(backends)
    finally:
        store.close()


def resolve_cli_path(binary: str, *, include_npm_global: bool = True) -> str | None:
    return _resolve_cli_path(
        binary,
        include_npm_global=include_npm_global,
        candidate_paths=_candidate_cli_paths,
        is_executable_file=_is_executable_file,
        include_desktop=include_npm_global,
    )


def resolve_cli_paths(
    binaries: list[str],
    *,
    include_npm_global: bool = True,
) -> dict[str, str | None]:
    """Resolve a CLI batch while querying each npm installation only once."""

    resolved: dict[str, str | None] = {}
    for binary in binaries:
        try:
            resolved[binary] = resolve_cli_path(
                binary,
                include_npm_global=False,
            )
        except Exception:
            logger.warning("CLI path probe failed for %s", binary, exc_info=True)
            resolved[binary] = None
    if not include_npm_global or all(path is not None for path in resolved.values()):
        return resolved

    try:
        prefixes = _npm_global_prefixes()
    except Exception:
        logger.warning("npm global prefix probe failed", exc_info=True)
        return resolved
    for binary, path in resolved.items():
        if path is not None or not binary:
            continue
        expanded = Path(os.path.expanduser(binary))
        has_path_separator = os.sep in binary or (
            os.altsep is not None and os.altsep in binary
        )
        lookup_name = (
            expanded.name if expanded.is_absolute() or has_path_separator else binary
        )
        for prefix in prefixes:
            npm_path = next(
                (
                    str(candidate)
                    for candidate in _npm_binary_candidates_for_prefix(prefix, lookup_name)
                    if _is_executable_file(candidate)
                ),
                None,
            )
            if npm_path is None:
                continue
            resolved[binary] = npm_path
            if lookup_name != binary:
                logger.info(
                    "resolve_cli_paths: stored path %s missing; falling back to %s",
                    binary,
                    npm_path,
                )
            break
    from vibe.desktop_backends import resolve_published_desktop_backend

    for binary, path in resolved.items():
        if path is None:
            name = Path(os.path.expanduser(binary)).name
            if name in NATIVE_CLI_BACKENDS:
                resolved[binary] = resolve_published_desktop_backend(name)
    return resolved



def _codex_npm_install_env(npm_path: str, *, prefix: str | Path | None = None) -> dict[str, str] | None:
    env = _command_env_for(npm_path)
    if prefix is None:
        if os.name == "nt":
            # Windows npm's active global prefix is the install command's
            # destination. Do not let post-install PATH discovery stand in for
            # an explicit target when this query cannot be completed.
            prefix = _npm_prefix_for(npm_path)
            if prefix is None:
                return None
        else:
            prefix = Path.home() / ".local"

    install_prefix = Path(os.path.expanduser(str(prefix)))
    prefix_text = str(install_prefix)
    env["NPM_CONFIG_PREFIX"] = prefix_text
    if os.name == "nt":
        path_entries = [entry for entry in env.get("PATH", "").split(os.pathsep) if entry and entry != prefix_text]
        env["PATH"] = os.pathsep.join([prefix_text, *path_entries])
        return env

    prefix_bin = str(install_prefix / "bin")
    path_entries = [entry for entry in env.get("PATH", "").split(os.pathsep) if entry and entry != prefix_bin]
    env["PATH"] = os.pathsep.join([prefix_bin, *path_entries])
    return env


def _declared_codex_npm_target(env: dict[str, str] | None) -> str | None:
    """The destination the existing npm command policy explicitly declares."""
    prefix = (env or {}).get("NPM_CONFIG_PREFIX")
    if not prefix:
        return None
    root = Path(prefix).expanduser().absolute()
    return str(root / ("codex.cmd" if os.name == "nt" else "bin/codex"))


def _npm_prefix_from_node_modules_path(codex_path: str) -> Path | None:
    try:
        paths = [Path(codex_path).expanduser(), Path(codex_path).expanduser().resolve()]
    except OSError:
        return None

    for path in paths:
        parts = path.parts
        for index in range(len(parts) - 2):
            if parts[index : index + 3] != ("node_modules", "@openai", "codex"):
                continue
            if index == 0 or parts[index - 1] != "lib":
                continue
            prefix_parts = parts[: index - 1]
            if prefix_parts:
                return Path(*prefix_parts)
    return None


def _npm_prefix_for_existing_codex_install(npm_path: str, codex_path: str) -> Path | None:
    try:
        original = Path(codex_path).expanduser()
        resolved = original.resolve()
    except OSError:
        resolved = None

    npm_prefix = _npm_prefix_for(npm_path)
    if npm_prefix is None:
        return None

    inferred_prefix = _npm_prefix_from_node_modules_path(codex_path)
    if inferred_prefix is not None:
        try:
            if inferred_prefix.resolve() == npm_prefix.resolve():
                return npm_prefix
        except OSError:
            if inferred_prefix == npm_prefix:
                return npm_prefix

    for candidate in _npm_binary_candidates_for_prefix(npm_prefix, "codex"):
        try:
            candidate_resolved = candidate.resolve()
        except OSError:
            candidate_resolved = None
        if original == candidate or (resolved is not None and candidate_resolved == resolved):
            return npm_prefix

    return None


def _path_is_relative_to(path: Path, parent: Path) -> bool:
    try:
        path.resolve().relative_to(parent.resolve())
        return True
    except (OSError, ValueError):
        return False


def _is_npm_codex_install(codex_path: str) -> bool:
    try:
        resolved = Path(codex_path).expanduser().resolve()
    except OSError:
        return False
    parts = resolved.parts
    if "node_modules" in parts and "@openai" in parts and "codex" in parts:
        return True

    try:
        original = Path(codex_path).expanduser()
    except OSError:
        return False
    for candidate in _npm_global_binary_candidates("codex"):
        if original == candidate or resolved == candidate.resolve():
            return True
    return False


def _homebrew_prefix(brew_path: str) -> Path | None:
    """Return the active Homebrew prefix reported by the selected brew binary."""
    try:
        result = subprocess.run(
            [brew_path, "--prefix"],
            capture_output=True,
            text=True,
            timeout=10,
            env=_command_env_for(brew_path),
        )
    except Exception:
        return None
    if result.returncode != 0:
        return None
    lines = [line.strip() for line in (result.stdout or "").splitlines() if line.strip()]
    if len(lines) != 1:
        return None
    try:
        prefix = Path(os.path.expanduser(lines[0])).absolute()
        brew = Path(brew_path).expanduser().absolute()
    except OSError:
        return None
    if brew != prefix / "bin" / "brew":
        return None
    return prefix


def _homebrew_codex_probe(brew_path: str) -> tuple[str, Path | None, Path | None]:
    """Inspect the active installed Codex cask without guessing from paths.

    Returns ``(state, prefix, payload)`` where state is ``installed``,
    ``not_installed``, or ``unknown``.  The JSON ``--installed`` query is
    supported by Homebrew and distinguishes an absent cask from a failed or
    malformed metadata query without using the unsupported ``--prefix --cask``
    command shape.
    """
    prefix = _homebrew_prefix(brew_path)
    if prefix is None:
        return "unknown", None, None
    try:
        result = subprocess.run(
            [brew_path, "info", "--cask", "--json=v2", "--installed", "codex"],
            capture_output=True,
            text=True,
            timeout=10,
            env=_command_env_for(brew_path),
        )
    except Exception:
        return "unknown", prefix, None
    if result.returncode != 0:
        return "unknown", prefix, None
    try:
        payload = json.loads(result.stdout or "")
        if not isinstance(payload, dict):
            return "unknown", prefix, None
        casks = payload.get("casks")
        if not isinstance(casks, list):
            return "unknown", prefix, None
        codex_casks = [cask for cask in casks if isinstance(cask, dict) and cask.get("token") == "codex"]
        if not codex_casks:
            return "not_installed", prefix, None
        if len(codex_casks) != 1:
            return "unknown", prefix, None
        installed = codex_casks[0].get("installed")
        if not isinstance(installed, str):
            return "unknown", prefix, None
        version = installed
        version_path = Path(version)
        if version_path.is_absolute() or len(version_path.parts) != 1 or version_path.name != version:
            return "unknown", prefix, None
    except (TypeError, ValueError, json.JSONDecodeError):
        return "unknown", prefix, None
    return "installed", prefix, prefix / "Caskroom" / "codex" / version


def _homebrew_codex_target(brew_path: str, selected_path: str) -> str | None:
    """Return a selected Codex launcher attributable to the active cask payload."""
    selected = Path(selected_path).expanduser()
    if selected.name not in {"codex", "codex.exe"}:
        return None
    state, prefix, payload = _homebrew_codex_probe(brew_path)
    if state != "installed" or prefix is None or payload is None:
        return None
    try:
        selected_absolute = selected.absolute()
        expected = (prefix / "bin" / selected.name).absolute()
        if selected_absolute != expected or not selected.is_symlink():
            return None
        resolved = selected.resolve(strict=True)
    except OSError:
        return None
    if not _path_is_relative_to(resolved, payload):
        return None
    return str(selected)


def _homebrew_codex_path_is_plausible(
    codex_path: str,
    *,
    brew_path: str | None = None,
    prefix: Path | None = None,
) -> bool:
    """Recognize paths that could belong to a Homebrew Codex cask.

    The selected path must stay attributable before a Homebrew upgrade is
    allowed, but an unrelated custom executable must not be rejected merely
    because another Homebrew installation exists. Stable Homebrew locations
    and resolved ``Caskroom/codex`` payloads are the narrow ownership evidence
    available without running the selected executable.
    """
    selected = Path(codex_path).expanduser()
    if selected.name not in {"codex", "codex.exe"}:
        return False
    try:
        selected_absolute = selected.absolute()
        resolved = selected.resolve(strict=False)
    except OSError:
        return False

    prefixes: list[Path] = []
    if prefix is not None:
        prefixes.append(prefix.expanduser().absolute())
    if brew_path:
        brew_absolute = Path(brew_path).expanduser().absolute()
        if brew_absolute.name in {"brew", "brew.exe"} and brew_absolute.parent.name == "bin":
            prefixes.append(brew_absolute.parent.parent)

    for candidate in prefixes:
        for parent in (candidate / "bin", candidate / "Caskroom" / "codex"):
            try:
                selected_absolute.relative_to(parent.absolute())
                return True
            except (OSError, ValueError):
                continue

    parts = resolved.parts
    return any(
        parts[index : index + 2] == ("Caskroom", "codex")
        for index in range(len(parts) - 1)
    )


def _is_homebrew_codex_install(codex_path: str) -> bool:
    brew_path = resolve_cli_path("brew")
    return bool(brew_path and _homebrew_codex_target(brew_path, codex_path))


def _codex_path_is_ambiguous_homebrew_target(
    codex_path: str,
    state: str,
    *,
    brew_path: str | None = None,
    prefix: Path | None = None,
) -> bool:
    return (
        state in {"installed", "unknown"}
        and _homebrew_codex_path_is_plausible(codex_path, brew_path=brew_path, prefix=prefix)
    )


def _codex_cli_supports_update(codex_path: str) -> bool:
    try:
        result = subprocess.run(
            [codex_path, "--help"],
            capture_output=True,
            text=True,
            timeout=10,
            env=_command_env_for(codex_path),
        )
    except Exception:
        return False
    if result.returncode != 0:
        return False
    output = f"{result.stdout}\n{result.stderr}"
    return re.search(r"(?m)^\s*update\s+", output) is not None


def _codex_upgrade_command(
    existing_path: str, *, version: str | None = None
) -> tuple[list[str], dict[str, str] | None] | dict:
    brew_path = resolve_cli_path("brew")
    npm_install = _is_npm_codex_install(existing_path)
    if brew_path:
        brew_state, brew_prefix, _ = _homebrew_codex_probe(brew_path)
        homebrew_target = _homebrew_codex_target(brew_path, existing_path)
        if homebrew_target is not None:
            return [brew_path, "upgrade", "--cask", "codex"], None
        if not npm_install and _codex_path_is_ambiguous_homebrew_target(
            existing_path,
            brew_state,
            brew_path=brew_path,
            prefix=brew_prefix,
        ):
            return {
                "ok": False,
                "code": "cli_target_unknown",
                "message": "Codex Homebrew installation target could not be attributed to the selected executable; no upgrade was started.",
                "output": None,
            }

    if npm_install:
        npm_path = resolve_cli_path("npm")
        if not npm_path:
            return {
                "ok": False,
                "message": "Codex appears to be installed via npm, but npm was not found. Please install Node.js or upgrade Codex manually.",
                "output": None,
            }
        prefix = _npm_prefix_for_existing_codex_install(npm_path, existing_path)
        command_env = _codex_npm_install_env(npm_path, prefix=prefix)
        if command_env is None:
            return {
                "ok": False,
                "code": "cli_target_unknown",
                "message": "Codex npm global prefix could not be determined; no upgrade was started.",
                "output": None,
            }
        # Unversioned, npm installs whatever is ``latest`` now, which may be newer
        # than the release the caller approved.
        return [npm_path, "install", "-g", f"@openai/codex@{version}" if version else "@openai/codex"], command_env

    if _codex_cli_supports_update(existing_path):
        return [existing_path, "update"], None

    return {
        "ok": False,
        "message": "Could not determine how Codex was installed, and this Codex CLI does not expose an update command. Please upgrade Codex with the installer you originally used.",
        "output": None,
    }


def browse_directory(path: str, show_hidden: bool = False) -> dict:
    """List sub-directories of *path* for the directory browser UI.

    Symlinks are not followed when scanning entries.

    Returns ``{"ok": True, "path": <abs>, "parent": <abs|None>, "dirs": [...]}``
    where each entry in *dirs* is ``{"name": ..., "path": ...}``.
    """
    try:
        target = Path(os.path.expanduser(path or "~")).resolve()

        if not target.is_dir():
            return {"ok": False, "error": f"Not a directory: {target}"}

        abs_path = str(target)
        parent = str(target.parent) if target.parent != target else None

        entries: list[dict[str, str]] = []
        try:
            for entry in sorted(os.scandir(abs_path), key=lambda e: e.name.lower()):
                if not show_hidden and entry.name.startswith("."):
                    continue
                if entry.is_dir(follow_symlinks=False):
                    entries.append({"name": entry.name, "path": str(target / entry.name)})
        except PermissionError:
            return {"ok": False, "error": "permission_denied"}

        return {"ok": True, "path": abs_path, "parent": parent, "dirs": entries}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


def browse_favorites() -> dict:
    """Return OS-appropriate quick-access directories for the directory picker.

    Each entry is ``{"key": <stable id>, "path": <abs>}``; only directories that
    actually exist are returned, so the UI never renders a dead shortcut. The
    ``key`` lets the UI localize the well-known shortcuts (home/desktop/...),
    while OS-specific roots (``/tmp``, ``/data``, Windows drive letters) are
    shown by their path. Home is always first. Mirrors how Finder/Explorer/most
    Linux file managers seed their sidebar per platform.
    """
    import platform

    home = Path(os.path.expanduser("~"))
    system = platform.system().lower()  # 'darwin' | 'linux' | 'windows'

    # (key, path) candidates in display order. Existence is verified below, so
    # OS-specific entries absent on this machine simply drop out of the list.
    candidates: list[tuple[str, Path]] = [("home", home)]
    if system == "darwin":
        candidates += [
            ("desktop", home / "Desktop"),
            ("documents", home / "Documents"),
            ("downloads", home / "Downloads"),
            ("applications", Path("/Applications")),
            ("tmp", Path("/tmp")),
        ]
    elif system == "windows":
        candidates += [
            ("desktop", home / "Desktop"),
            ("documents", home / "Documents"),
            ("downloads", home / "Downloads"),
        ]
        # Drive roots (C:\, D:\, …) as quick jumps to a volume's top level.
        candidates += [(f"drive_{letter.lower()}", Path(f"{letter}:\\")) for letter in "CDEFG"]
    else:  # linux / other unix
        candidates += [
            ("desktop", home / "Desktop"),
            ("documents", home / "Documents"),
            ("downloads", home / "Downloads"),
            ("root", Path("/")),
            ("tmp", Path("/tmp")),
            ("data", Path("/data")),
            ("mnt", Path("/mnt")),
            ("media", Path("/media")),
        ]

    seen: set[str] = set()
    favorites: list[dict] = []
    for key, candidate in candidates:
        try:
            abs_path = str(candidate)
            if abs_path in seen or not candidate.is_dir():
                continue
        except OSError:
            continue
        seen.add(abs_path)
        favorites.append({"key": key, "path": abs_path})

    return {"ok": True, "system": system, "favorites": favorites}


def load_config() -> V2Config:
    return V2Config.load()


def config_recovery_notice(config: V2Config) -> Optional[str]:
    """Return the localized, non-diagnostic message for a recovered config."""

    if not getattr(config, "load_warnings", ()):
        return None
    return backend_t(
        "error.configRecovery.beforeAuth",
        getattr(config, "language", "en") or "en",
    )


def _config_recovery_message() -> Optional[str]:
    """Return a localized guard message before mutating backend-owned auth files.

    Credential custody is decided by ``model_hub`` and the Agent backend
    settings; recovery of any other section leaves both readable.
    """

    with CONFIG_LOCK:
        try:
            config = load_config()
        except FileNotFoundError:
            return None
    if config_recovery_refusal(config, *AGENT_CREDENTIAL_SECTIONS) is None:
        return None
    return config_recovery_notice(config)


_LIST_OPS_PAYLOAD_KEY = "__avibe_list_ops"


_LIST_OPS_ALLOWED_PATHS = frozenset({"platforms.enabled"})


def _apply_list_ops(base: dict, list_ops: dict) -> dict:
    """Apply add/remove operations to list-valued config paths.

    ``{"platforms.enabled": {"add": ["wechat"], "remove": ["discord"]}}``
    mutates the lock-fresh base's list instead of replacing it wholesale,
    so a stale browser snapshot of the list cannot drop entries another
    process added (#1458 stage ③: lists are replace-on-merge otherwise).
    Only whitelisted paths are accepted: resolving arbitrary dotted paths
    would let a client mutate lists whose owners need service-mediated
    synchronization (e.g. ``model_hub.sources`` must go through
    ModelHubService) — anything outside the whitelist raises.
    """
    import copy as _copy

    merged = _copy.deepcopy(base)

    def _resolve(container: dict, dotted: str):
        current = container
        for part in dotted.split("."):
            if not isinstance(current, dict):
                return None
            current = current.get(part)
        return current

    if not isinstance(list_ops, dict):
        raise ValueError("Config list operations must be an object")

    def _validated_operands(ops: dict, name: str) -> list[str]:
        if name not in ops:
            return []
        values = ops[name]
        if not isinstance(values, list) or any(
            not isinstance(value, str) or not value.strip() for value in values
        ):
            raise ValueError(
                f"Config list operation '{name}' must be an array of non-empty strings"
            )
        return values

    for dotted, ops in list_ops.items():
        if not isinstance(dotted, str) or dotted not in _LIST_OPS_ALLOWED_PATHS:
            raise ValueError(
                f"Config list operation path '{dotted}' is not supported"
            )
        if not isinstance(ops, dict):
            raise ValueError(f"Config list operation '{dotted}' must be an object")
        unknown = set(ops) - {"add", "remove"}
        if unknown:
            names = ", ".join(sorted(str(name) for name in unknown))
            raise ValueError(f"Config list operation '{dotted}' has unknown keys: {names}")
        target = _resolve(merged, dotted)
        if not isinstance(target, list):
            raise ValueError(f"Config list operation target '{dotted}' is not a list")
        additions = _validated_operands(ops, "add")
        removals = _validated_operands(ops, "remove")
        next_list = [item for item in target if item not in removals]
        for item in additions:
            if item not in next_list:
                next_list.append(item)
        # Write back through the dotted path.
        parts = dotted.split(".")
        node = merged
        for part in parts[:-1]:
            node = node[part]
        node[parts[-1]] = next_list
    return merged


def _deep_merge_dicts(base: dict, patch: dict) -> dict:
    list_ops = None
    if isinstance(patch, dict):
        raw_ops = patch.get(_LIST_OPS_PAYLOAD_KEY)
        if isinstance(raw_ops, dict):
            list_ops = raw_ops
            patch = {k: v for k, v in patch.items() if k != _LIST_OPS_PAYLOAD_KEY}
    merged = dict(base)
    for key, value in patch.items():
        if isinstance(value, dict) and isinstance(merged.get(key), dict):
            merged[key] = _deep_merge_dicts(merged[key], value)
        else:
            merged[key] = value
    if list_ops is not None:
        merged = _apply_list_ops(merged, list_ops)
    return merged


_AGENT_AUTH_FIELDS = ("auth_mode", "api_key", "base_url", "oauth_relay_marker")


def _strip_agent_auth_fields(payload: dict) -> dict:
    """Drop auth fields from a generic settings patch.

    The UI's Settings → Backends page round-trips the masked agent config
    on save (api_key arrives as ``None`` after masking), and naive
    deep-merge would clobber the real key. Auth state changes must go
    through ``/backend/<name>/auth`` exclusively; this helper enforces
    that contract on the generic settings POST.
    """
    if not isinstance(payload, dict):
        return payload
    agents = payload.get("agents")
    if not isinstance(agents, dict):
        return payload
    cleaned_agents = dict(agents)
    for backend in ("claude", "codex"):
        backend_payload = cleaned_agents.get(backend)
        if isinstance(backend_payload, dict):
            cleaned_backend = {
                k: v for k, v in backend_payload.items() if k not in _AGENT_AUTH_FIELDS
            }
            cleaned_agents[backend] = cleaned_backend
    return {**payload, "agents": cleaned_agents}


def _strip_preserved_config_secrets(payload: dict) -> dict:
    """Drop redacted secret placeholders from generic config saves.

    ``GET /api/config`` now returns ``has_<field>`` metadata instead of
    plaintext platform and gateway secrets. Older UI paths may still round-trip
    an empty string for such a field; when the metadata says the secret is
    already configured, an empty submitted value means "unchanged", not "clear".
    """
    if not isinstance(payload, dict):
        return payload
    cleaned = dict(payload)
    for config_key, fields in _PLATFORM_SECRET_FIELDS.items():
        section = cleaned.get(config_key)
        if not isinstance(section, dict):
            continue
        next_section = dict(section)
        for field in fields:
            if next_section.get(f"has_{field}") is True and not next_section.get(field):
                next_section.pop(field, None)
        cleaned[config_key] = next_section
    gateway = cleaned.get("gateway")
    if isinstance(gateway, dict):
        next_gateway = dict(gateway)
        for field in _GATEWAY_SECRET_FIELDS:
            if next_gateway.get(f"has_{field}") is True and not next_gateway.get(field):
                next_gateway.pop(field, None)
        cleaned["gateway"] = next_gateway
    return cleaned


def _mark_explicit_audio_asr_enabled(payload: dict) -> dict:
    """Record explicit ASR enablement changes from config API payloads.

    Persisted configs from older versions may contain ``enabled: false`` only
    because that was the old default. A current API request that includes the
    same field is different: it is the user's requested value and must survive
    the migration default.
    """
    if not isinstance(payload, dict):
        return payload
    audio_asr = payload.get("audio_asr")
    if not isinstance(audio_asr, dict) or "enabled" not in audio_asr or "enabled_configured" in audio_asr:
        return payload
    return {**payload, "audio_asr": {**audio_asr, "enabled_configured": True}}


def _runtime_credential_fields_for_platform(platform: str) -> tuple[str, ...]:
    if platform == "wechat":
        return ()
    return get_platform_descriptor(platform).credential_fields


def _payload_edits_runtime_credential(section: dict, field: str, base_value: object) -> bool:
    if field not in section:
        return False
    value = section.get(field)
    if value == base_value:
        return False
    if not value and section.get(f"has_{field}") is True:
        return False
    return True


def _platforms_requiring_runtime_credential_validation(
    config: V2Config,
    payload: dict,
    base_config: Optional[V2Config],
) -> set[str]:
    enabled = set(config.platforms.enabled)
    previous_enabled = set(base_config.platforms.enabled) if base_config is not None else set()
    platforms = enabled - previous_enabled if "platforms" in payload or "platform" in payload else set()

    # If a save edits credential fields for an already-enabled platform, reject
    # partial clears or mismatched edits before they are persisted.
    for platform in enabled:
        required_fields = _runtime_credential_fields_for_platform(platform)
        if not required_fields:
            continue
        descriptor = get_platform_descriptor(platform)
        section = payload.get(descriptor.config_key)
        base_platform_config = descriptor.get_config(base_config) if base_config is not None else None
        if isinstance(section, dict) and any(
            _payload_edits_runtime_credential(
                section,
                field,
                getattr(base_platform_config, field, None),
            )
            for field in required_fields
        ):
            platforms.add(platform)
    return platforms


def _validate_enabled_platform_runtime_credentials(
    config: V2Config,
    payload: dict,
    base_config: Optional[V2Config],
) -> None:
    """Reject enabled IM transports that cannot start after config save.

    ``V2Config.from_payload`` intentionally allows empty credential fields so
    users can save setup drafts for disabled platforms. Once a platform enters
    ``platforms.enabled``, however, the running adapter must be able to boot.
    WeChat is the existing exception: its runtime idles without a token while
    the QR-login flow completes.
    """
    for platform in _platforms_requiring_runtime_credential_validation(config, payload, base_config):
        required_fields = _runtime_credential_fields_for_platform(platform)
        if not required_fields:
            continue
        descriptor = get_platform_descriptor(platform)
        platform_config = descriptor.get_config(config)
        missing = [field for field in required_fields if not getattr(platform_config, field, None)]
        if missing:
            fields_text = "', '".join(f"{descriptor.config_key}.{field}" for field in missing)
            raise ValueError(f"Config '{fields_text}' must be provided when {platform} is enabled")


def _remote_access_network_signature(config: V2Config | None) -> tuple[str, str]:
    if config is None:
        return ("4", "")
    cloud = config.remote_access.vibe_cloud
    return (
        str(cloud.edge_ip_version or "4").strip().lower(),
        str(cloud.edge_bind_address or "").strip(),
    )


_REMOTE_ACCESS_CONNECTOR_CONTROL_FIELDS = (
    "transport_protocol",
    "edge_ip_version",
    "edge_bind_address",
)


def _remote_access_connector_control_signature(config: V2Config | None) -> tuple[str, str, str]:
    if config is None:
        return ("auto", "4", "")
    cloud = config.remote_access.vibe_cloud
    return (
        str(cloud.transport_protocol or "auto").strip().lower(),
        str(cloud.edge_ip_version or "4").strip().lower(),
        str(cloud.edge_bind_address or "").strip(),
    )


def remote_access_runtime_changed(previous: V2Config | None, current: V2Config) -> bool:
    """Return whether a generic config save must reconcile the Connector runtime."""

    if previous is None:
        return bool(current.remote_access.vibe_cloud.enabled)

    def signature(config: V2Config) -> tuple[object, ...]:
        cloud = config.remote_access.vibe_cloud
        return (
            config.remote_access.provider,
            bool(cloud.enabled),
            str(cloud.public_url or ""),
            str(cloud.tunnel_token or ""),
            str(cloud.cloudflared_path or ""),
            *_remote_access_connector_control_signature(config),
        )

    return signature(previous) != signature(current)


def _validate_remote_access_network_change(
    config: V2Config,
    base_config: V2Config | None,
    *,
    require_current_binding: bool = False,
) -> None:
    if (
        not require_current_binding
        and _remote_access_network_signature(config) == _remote_access_network_signature(base_config)
    ):
        return
    from vibe import remote_access

    error = remote_access.edge_binding_error(config)
    if error == "edge_bind_address_unavailable":
        raise ValueError(
            "Config 'remote_access.vibe_cloud.edge_bind_address' must be assigned "
            "to an active network interface"
        )
    if error == "edge_bind_address_family_mismatch":
        raise ValueError(
            "Config 'remote_access.vibe_cloud.edge_bind_address' must match "
            "'remote_access.vibe_cloud.edge_ip_version'"
        )


def save_config(
    payload: dict,
    *,
    validate_remote_access_network: bool = True,
    generic_remote_access: bool = False,
    user_context: Any = None,
) -> V2Config:
    """Save general settings while discarding removed optional-feature sections."""
    if not isinstance(payload, dict):
        raise ValueError("Config payload must be an object")
    from vibe.authorization import require_instance_role

    context = require_instance_role(user_context, "editor")
    payload = {key: value for key, value in payload.items() if key != "memory"}
    if not context.can_manage_instance:
        payload = editor_config_write_payload(payload)

    # This read-only projection is returned by GET /api/config so the browser
    # can explain a recovered load; it must never become persisted config data.
    payload = {key: value for key, value in payload.items() if key != "config_recovery"}
    # Model Hub mutations must pass through ModelHubService so runtime source
    # bindings and credential lifecycle stay in sync with the persisted config.
    # Generic settings pages round-trip GET /api/config, so treat this section
    # as a read-only projection here rather than accepting a potentially stale
    # client snapshot.
    payload = {key: value for key, value in payload.items() if key != "model_hub"}
    payload = _strip_agent_auth_fields(payload)
    payload = _strip_preserved_config_secrets(payload)
    payload = _mark_explicit_audio_asr_enabled(payload)
    # The list-operations verb is a merge instruction, never config
    # state: pull it out before anything treats the payload as data —
    # but remember whether it touched the enabled list: credential
    # validation and runtime reconciliation gate on a ``platforms``
    # marker in the payload, and a bare operation payload must not
    # bypass them.
    raw_list_ops = payload.pop(_LIST_OPS_PAYLOAD_KEY, None)
    if raw_list_ops is not None and not isinstance(raw_list_ops, dict):
        raise ValueError("Config list operations must be an object")
    list_ops_touches_platforms = isinstance(raw_list_ops, dict) and any(
        str(key) in ("platforms.enabled", "platforms.primary") for key in raw_list_ops
    )

    pairing_revocation_operation_id: str | None = None
    # Serialize the WHOLE read-merge-write cycle across processes
    # (#1458 stage ③): the base load, merge, validation, and write all
    # happen under the config file lock, so a controller commit between
    # our load and our write can no longer be overwritten. The in-lock
    # A lock-fresh base prevents overlapping read-modify-write cycles from
    # losing one another. It cannot identify stale fields a client explicitly
    # resubmits, so UI callers still declare field mutations instead of sending
    # config snapshots.
    with config_file_lock():
        base_payload: dict = {}
        base_config: Optional[V2Config] = None
        try:
            base_config = load_config()
            base_payload = config_to_payload(base_config, include_secrets=True, include_internal=True)
        except FileNotFoundError:
            # Fresh install: seed the same workbench-only default served by the read side.
            from core.services.settings import default_config

            base_payload = config_to_payload(default_config(), include_secrets=True, include_internal=True)
            # Don't let the seed's workbench-only ``platforms`` shadow
            # from_payload's legacy ``platform`` -> ``platforms`` migration: when
            # the request is a legacy single-platform update (``platform`` set,
            # ``platforms`` absent), drop the seed's platform fields so the
            # request's own platform still derives ``platforms.enabled``. The
            # wizard always sends ``platforms`` and is unaffected; a bare partial
            # save (neither key) keeps the workbench-only seed.
            if "platform" in payload and "platforms" not in payload:
                base_payload.pop("platforms", None)
                base_payload.pop("platform", None)

        if base_payload:
            merged_payload = _deep_merge_dicts(base_payload, payload)
            if isinstance(raw_list_ops, dict) and raw_list_ops:
                merged_payload = _apply_list_ops(merged_payload, raw_list_ops)
        else:
            merged_payload = payload
        if list_ops_touches_platforms and isinstance(merged_payload.get("platforms"), dict):
            # Credential validation and runtime reconciliation gate on a
            # ``platforms`` marker in the payload; surface the FINAL
            # post-operation enabled list so a bare list-op payload is
            # validated and reconciled exactly like an explicit list save.
            final_platforms = dict(merged_payload["platforms"])
            if "enabled" in final_platforms or "primary" in final_platforms:
                payload["platforms"] = final_platforms
        merged_payload = _merge_legacy_discord_guild_scope_fields(merged_payload, payload, base_config)
        sanitized_payload, guild_scope_update = _extract_settings_scopes_from_config_payload(merged_payload)
        config = V2Config.from_payload(sanitized_payload)
        if base_config is not None:
            # A recovered base section must reach the file as stored, never as
            # the defaults merged in above. Refuse before any side effect below.
            config.inherit_load_diagnostics(base_config)
            recovery_refusal = config.pending_write_refusal()
            if recovery_refusal is not None:
                raise ValueError(recovery_refusal)
        if not context.can_manage_access_members:
            from core.services.settings import default_config

            _require_preserved_config_access(base_config or default_config(), config)
        connector_controls_changed = (
            base_config is not None
            and _remote_access_connector_control_signature(config)
            != _remote_access_connector_control_signature(base_config)
        )
        if generic_remote_access and connector_controls_changed:
            fields = "', '".join(
                f"remote_access.vibe_cloud.{field}"
                for field in _REMOTE_ACCESS_CONNECTOR_CONTROL_FIELDS
            )
            raise ValueError(
                f"Config '{fields}' must be changed through "
                "'/api/remote-access/settings'"
            )
        if validate_remote_access_network:
            _validate_remote_access_network_change(
                config,
                base_config,
                require_current_binding=(
                    generic_remote_access
                    and config.remote_access.vibe_cloud.enabled
                    and remote_access_runtime_changed(base_config, config)
                ),
            )
        _validate_enabled_platform_runtime_credentials(config, payload, base_config)
        from vibe import remote_access

        # Admit the pairing clear before publishing the separate settings
        # store: an unreadable journal or failed fence must reject this
        # request without already changing its Discord guild scope.
        pairing_revocation_operation_id = remote_access.prepare_pairing_revocation(
            base_config,
            config,
        )
        if guild_scope_update is not None:
            _save_discord_guild_scope_update(*guild_scope_update, user_context=context)
        elif base_config is not None:
            store = SettingsStore.get_instance()
            if not store.has_guild_scope_for_platform("discord"):
                existing_update = _discord_guild_scope_from_config(base_config)
                if existing_update is not None:
                    _save_discord_guild_scope_update(*existing_update, store=store, user_context=context)
        config.save()
        if not remote_access.complete_pairing_revocation(pairing_revocation_operation_id):
            logger.error(
                "Pairing revocation committed but its pending record could not be retired; "
                "the safety fence remains for operation %s",
                pairing_revocation_operation_id,
            )
        try:
            from core.message_mirror import reset_activity_flag_cache

            reset_activity_flag_cache()
        except Exception:
            pass
        persisted = load_config()
        _ensure_builtin_default_agents(persisted)
    return persisted


def _require_preserved_config_access(current: V2Config, candidate: V2Config) -> None:
    """Generic manager saves cannot change admission or pairing, even via aliases."""
    from vibe.authorization import InstanceAuthorizationError

    def policy(config):
        return (
            config.remote_access,
            config.ui.trusted_public_origins,
            tuple(
                bool(getattr(getattr(config, p), "require_bind", False))
                for p in ("slack", "discord", "telegram", "lark", "wechat")
            ),
            getattr(config.telegram, "allowed_user_ids", None) or [],
            getattr(config.telegram, "allowed_chat_ids", None) or [],
        )

    if policy(current) != policy(candidate):
        raise InstanceAuthorizationError("owner")


def _vibe_cloud_payload(config: V2Config, include_secrets: bool) -> dict:
    """Project remote-access pairing state while redacting credentials."""
    vibe_cloud = config.remote_access.vibe_cloud
    payload = vibe_cloud.__dict__.copy()
    payload["paired"] = vibe_cloud.is_runtime_paired()
    if not include_secrets:
        for key in ("tunnel_token", "instance_secret", "session_secret"):
            payload.pop(key, None)
    return payload


def _agent_payload(raw: dict, *, include_secrets: bool) -> dict:
    """Project a Claude/Codex config dict for the UI, masking the api_key.

    The UI surfaces *whether* a key is configured (and its length, so the
    user can see ``****6c1f``-style hints), never the plaintext. Only the
    secrets-included path (used by the setup wizard's "load existing
    config" flow) sees the raw value.
    """
    payload = dict(raw)
    api_key = payload.get("api_key")
    if isinstance(api_key, str):
        payload["api_key_length"] = len(api_key)
        payload["has_api_key"] = bool(api_key)
    else:
        payload["api_key_length"] = 0
        payload["has_api_key"] = False
    if not include_secrets:
        payload["api_key"] = None
    return payload


def _project_secret_fields(payload: dict | None, fields: tuple[str, ...], *, include_secrets: bool) -> dict | None:
    if payload is None:
        return None
    projected = dict(payload)
    for field in fields:
        value = projected.get(field)
        if isinstance(value, str):
            projected[f"has_{field}"] = bool(value)
            projected[f"{field}_length"] = len(value)
        else:
            projected[f"has_{field}"] = False
            projected[f"{field}_length"] = 0
        if not include_secrets:
            projected.pop(field, None)
    return projected


def _system_hostname() -> str:
    """Best-effort system hostname for the browser-title fallback."""
    try:
        return socket.gethostname() or ""
    except OSError:
        return ""


def _remote_access_instance_name(config: V2Config) -> str:
    cloud = getattr(getattr(config, "remote_access", None), "vibe_cloud", None)
    if not cloud or not getattr(cloud, "enabled", False):
        return ""
    public_url = (getattr(cloud, "public_url", "") or "").strip()
    if not public_url:
        return ""
    try:
        parsed = urllib.parse.urlsplit(public_url)
    except ValueError:
        return ""
    if parsed.scheme.lower() != "https" or parsed.username or parsed.password:
        return ""
    hostname = (parsed.hostname or "").strip().lower().rstrip(".")
    labels = hostname.split(".")
    if len(labels) < 3 or labels[-2:] != ["avibe", "bot"]:
        return ""
    slug = labels[0]
    if slug.endswith("-app"):
        slug = slug[:-4]
    return slug.strip("-")


def _default_instance_name(config: V2Config, *, system_hostname: str) -> str:
    return _remote_access_instance_name(config) or system_hostname


def config_to_payload(
    config: V2Config,
    *,
    include_secrets: bool = False,
    include_internal: bool = False,
) -> dict:
    from config.platform_registry import platform_descriptors
    from modules.agents.catalog import agent_backend_catalog_payload

    system_hostname = _system_hostname()
    platform_payload = {}
    for descriptor in platform_descriptors():
        descriptor_config = descriptor.get_config(config)
        raw = descriptor_config.__dict__.copy() if descriptor_config else None
        platform_payload[descriptor.config_key] = _project_secret_fields(
            raw,
            _PLATFORM_SECRET_FIELDS.get(descriptor.config_key, ()),
            include_secrets=include_secrets,
        )
    if isinstance(platform_payload.get("discord"), dict):
        platform_payload["discord"].pop("guild_allowlist", None)
        platform_payload["discord"].pop("guild_denylist", None)
    payload = {
        "platform": config.platform,
        "platforms": {
            "enabled": config.platforms.enabled,
            "primary": config.platforms.primary,
        },
        "platform_catalog": config.platform_catalog(),
        "agent_backend_catalog": agent_backend_catalog_payload(),
        "setup_state": config.setup_state(),
        "mode": config.mode,
        "version": config.version,
        **platform_payload,
        "runtime": {
            "default_cwd": config.runtime.default_cwd,
            "log_level": config.runtime.log_level,
            "show_page_api_timeout_seconds": config.runtime.show_page_api_timeout_seconds,
            "resource_governance": config.runtime.resource_governance,
            # The config-only Harness knobs have no UI, but this payload IS the
            # deep-merge base every ``/api/config`` save builds on: a key omitted here
            # is absent from the merged payload, so ``from_payload`` rebuilds
            # ``RuntimeConfig`` with the dataclass default and silently reverts the
            # on-disk value (a ``harness_prompt_echo: false`` opt-out would come back
            # enabled after any unrelated settings save — Codex P1).
            "harness_prompt_echo": config.runtime.harness_prompt_echo,
            "harness_run_sweep_interval_seconds": config.runtime.harness_run_sweep_interval_seconds,
            "harness_run_orphan_grace_seconds": config.runtime.harness_run_orphan_grace_seconds,
            "harness_run_queued_ttl_seconds": config.runtime.harness_run_queued_ttl_seconds,
            "harness_run_hold_ttl_seconds": config.runtime.harness_run_hold_ttl_seconds,
            # Same round-trip contract as the Harness knobs above: omitting these
            # here would revert a user's retention opt-out on unrelated saves.
            "agent_events_trace_retention_enabled": config.runtime.agent_events_trace_retention_enabled,
            "agent_events_trace_retention_days": config.runtime.agent_events_trace_retention_days,
            "skill_observability_enabled": config.runtime.skill_observability_enabled,
        },
        "agents": {
            "opencode": config.agents.opencode.__dict__,
            "claude": _agent_payload(config.agents.claude.__dict__, include_secrets=include_secrets),
            "codex": _agent_payload(config.agents.codex.__dict__, include_secrets=include_secrets),
            # Mirror ``V2Config.save`` — avault must be emitted here too, or every
            # UI save (which uses this payload as the deep-merge base) silently
            # resets ``agents.avault.cli_path`` to the dataclass default.
            "avault": config.agents.avault.__dict__,
        },
        "model_hub": config.model_hub.to_payload(),
        "gateway": _project_secret_fields(
            config.gateway.__dict__ if config.gateway else None,
            _GATEWAY_SECRET_FIELDS,
            include_secrets=include_secrets,
        ),
        # ``system_hostname`` and ``default_instance_name`` are read-only,
        # computed hints (not stored config fields): the UI uses the default as
        # the browser-title fallback when ``ui.instance_name`` is blank. They
        # are dropped on save via ``_filter_dataclass_fields`` so they never
        # persist.
        "ui": {
            **config.ui.__dict__,
            "system_hostname": system_hostname,
            "default_instance_name": _default_instance_name(config, system_hostname=system_hostname),
        },
        "remote_access": {
            "provider": config.remote_access.provider,
            "vibe_cloud": _vibe_cloud_payload(config, include_secrets),
        },
        "audio_asr": config.audio_asr.__dict__,
        "update": config.update.__dict__,
        "ack_mode": config.ack_mode,
        "language": config.language,
        "show_duration": config.show_duration,
        "include_time_info": config.include_time_info,
        "include_user_info": config.include_user_info,
        "reply_enhancements": config.reply_enhancements,
        "agent_progress_style": config.agent_progress_style,
        "agent_status_heartbeat_ms": config.agent_status_heartbeat_ms,
        "agent_status_no_output_ms": config.agent_status_no_output_ms,
        "setup_completed": config.setup_completed,
    }
    return payload


def client_config_payload(config: V2Config) -> dict:
    """Project config for an HTTP response rather than for a save.

    The generic projection excludes the removed optional-feature section from
    both saved and returned configuration. Legacy clients may still submit that
    section; it is ignored before persistence and never appears in this payload.
    """

    payload = config_to_payload(config)
    payload.pop("memory", None)
    recovery_notice = config_recovery_notice(config)
    recovery_warnings = [recovery_notice] if recovery_notice else []
    payload["config_recovery"] = {
        "required": bool(config.load_warnings),
        "warnings": recovery_warnings,
    }
    return payload


_NON_OWNER_CONFIG_UI_FIELDS = (
    "instance_name",
    "default_instance_name",
    "chat_message_font_size",
    "show_agent_activity",
    "show_tool_calls",
)


_NON_OWNER_AUDIO_ASR_FIELDS = (
    "enabled",
    "echo_transcript",
    "enabled_configured",
)

_EDITOR_CONFIG_WRITE_FIELDS = frozenset(
    {
        "ack_mode",
        "show_duration",
        "include_time_info",
        "include_user_info",
        "reply_enhancements",
        "agent_progress_style",
        "audio_asr",
        "ui",
    }
)

_EDITOR_CONFIG_UI_WRITE_FIELDS = frozenset(
    {
        "chat_message_font_size",
        "show_agent_activity",
        "show_tool_calls",
    }
)
_EDITOR_AUDIO_ASR_WRITE_FIELDS = frozenset(_NON_OWNER_AUDIO_ASR_FIELDS)

# Read-only context the shared Settings pages need in order to render the
# writable fields above the way an Owner sees them: platform capabilities
# decide which acknowledgement modes are offered, and cloud pairing decides
# whether the transcription control is live. Without them a non-owner client
# falls back to guesses (``getEnabledPlatforms`` assumes Slack) and offers
# settings the instance does not support.
#
# Together with ``_EDITOR_CONFIG_WRITE_FIELDS`` this is the complete set of
# keys a non-owner may see; ``test_non_owner_config_projects_exactly_the_declared_surface``
# holds the projection to it, so a field added to either half fails a test
# rather than leaking or going missing.
_NON_OWNER_CONFIG_CONTEXT_FIELDS = frozenset(
    {
        "mode",
        "version",
        "setup_state",
        "language",
        "platforms",
        "platform_catalog",
        "remote_access",
    }
)

_EDITOR_CONFIG_WRITE_ERROR_CODES = frozenset(
    {
        "editor_config_write_forbidden",
        "editor_config_write_invalid",
    }
)


def _remote_access_pairing_projection(payload: dict) -> dict:
    """Project cloud pairing for a non-owner as the readiness boolean alone.

    Below the Owner role no pairing identifier or endpoint is exposed at all —
    only whether cloud-backed controls can work, which ``_vibe_cloud_payload``
    already decided from the stored config.
    """
    remote_access = payload.get("remote_access")
    vibe_cloud = remote_access.get("vibe_cloud") if isinstance(remote_access, dict) else None
    paired = bool(vibe_cloud.get("paired")) if isinstance(vibe_cloud, dict) else False
    return {"vibe_cloud": {"paired": paired}}


# ``strip_pairing_identity_from_config_write`` used to sit here: a non-owner
# config write had ``remote_access`` removed and everything else was persisted.
# It is gone rather than kept beside the allowlist, because a subtractive filter
# and a closed allowlist cannot both be the non-owner write schema — the
# subtractive one is only ever as complete as the last section somebody
# remembered, and that is precisely how credential-bearing sections stayed
# writable for a member. ``editor_config_write_payload`` is now the single
# schema for every writer below Owner, and pairing identity is covered by it the
# same way every other Owner-only section is: ``remote_access`` is not on the
# allowlist, so the write is refused.


def _audio_asr_preference_projection(payload: dict) -> dict:
    audio_asr = payload.get("audio_asr")
    if not isinstance(audio_asr, dict):
        return {}
    return {
        key: audio_asr[key]
        for key in _NON_OWNER_AUDIO_ASR_FIELDS
        if key in audio_asr
    }


def editor_config_write_payload(payload: dict) -> dict:
    """Keep only the messaging preferences an Editor may persist."""

    if not isinstance(payload, dict):
        raise ValueError("editor_config_write_invalid")
    payload = {key: value for key, value in payload.items() if key != "memory"}
    unknown = set(payload) - _EDITOR_CONFIG_WRITE_FIELDS
    if unknown:
        raise ValueError("editor_config_write_forbidden")

    projected: dict = {}
    for key in payload:
        if key == "audio_asr":
            audio_asr = payload.get("audio_asr")
            if not isinstance(audio_asr, dict):
                raise ValueError("editor_config_write_invalid")
            extra = set(audio_asr) - _EDITOR_AUDIO_ASR_WRITE_FIELDS
            if extra:
                raise ValueError("editor_config_write_forbidden")
            projected["audio_asr"] = {
                field: audio_asr[field]
                for field in _EDITOR_AUDIO_ASR_WRITE_FIELDS
                if field in audio_asr
            }
            continue
        if key == "ui":
            ui_payload = payload.get("ui")
            if not isinstance(ui_payload, dict):
                raise ValueError("editor_config_write_invalid")
            extra = set(ui_payload) - _EDITOR_CONFIG_UI_WRITE_FIELDS
            if extra:
                raise ValueError("editor_config_write_forbidden")
            projected["ui"] = {
                field: ui_payload[field]
                for field in _EDITOR_CONFIG_UI_WRITE_FIELDS
                if field in ui_payload
            }
            continue
        projected[key] = payload[key]
    return projected


def editor_config_write_error_code(exc: Exception) -> str:
    """Return the stable client code for any failure on an Editor config write.

    Stated as a property rather than as a list of recognised messages: every
    validation failure reached while applying an Editor write is an Editor
    write error, whichever layer raised it. Only the codes this module raises
    survive; anything else — including value validation raised much later by
    ``V2Config.from_payload`` — collapses to the generic invalid code, so a
    non-English client never renders a raw English sentence.
    """
    message = str(exc)
    if message in _EDITOR_CONFIG_WRITE_ERROR_CODES:
        return message
    return "editor_config_write_invalid"


def non_owner_config_payload(config: V2Config) -> dict:
    """Return the configuration projection available below the Owner role.

    This projection is role-based rather than origin-based. It keeps sensitive
    runtime and control-plane fields out of Viewer and Editor responses while
    leaving ordinary messaging and UI preferences available to both local and
    remote callers.

    Its key set is exactly ``_EDITOR_CONFIG_WRITE_FIELDS`` (what an Editor may
    change) plus ``_NON_OWNER_CONFIG_CONTEXT_FIELDS`` (the read-only context
    needed to render those controls correctly). Keeping the two halves in step
    is the invariant: a writable field that is not projected leaves the client
    guessing, and an unprojected context field makes the shared Settings pages
    fall back to defaults that do not match the instance.
    """

    payload = client_config_payload(config)
    ui_payload = payload.get("ui")
    return {
        "mode": payload.get("mode"),
        "version": payload.get("version"),
        "setup_state": payload.get("setup_state"),
        "language": payload.get("language"),
        "ack_mode": payload.get("ack_mode"),
        "show_duration": payload.get("show_duration"),
        "include_time_info": payload.get("include_time_info"),
        "include_user_info": payload.get("include_user_info"),
        "reply_enhancements": payload.get("reply_enhancements"),
        "agent_progress_style": payload.get("agent_progress_style"),
        "audio_asr": _audio_asr_preference_projection(payload),
        "remote_access": _remote_access_pairing_projection(payload),
        "platforms": payload.get("platforms"),
        "platform_catalog": payload.get("platform_catalog"),
        "ui": {
            key: ui_payload[key]
            for key in _NON_OWNER_CONFIG_UI_FIELDS
            if isinstance(ui_payload, dict) and key in ui_payload
        },
    }
def _merge_legacy_discord_guild_scope_fields(
    merged_payload: dict,
    request_payload: dict,
    base_config: Optional[V2Config],
) -> dict:
    """Complete partial legacy Discord guild updates before migration."""
    request_discord = request_payload.get("discord")
    if not isinstance(request_discord, dict):
        return merged_payload
    if "guild_allowlist" not in request_discord and "guild_denylist" not in request_discord:
        return merged_payload

    next_payload = dict(merged_payload)
    merged_discord = dict(next_payload.get("discord") or {})
    base_discord = getattr(base_config, "discord", None) if base_config is not None else None

    if "guild_allowlist" not in request_discord and base_discord is not None:
        merged_discord["guild_allowlist"] = getattr(base_discord, "guild_allowlist", None) or []
    if "guild_denylist" not in request_discord and base_discord is not None:
        merged_discord["guild_denylist"] = getattr(base_discord, "guild_denylist", None) or []

    next_payload["discord"] = merged_discord
    return next_payload


def get_platform_catalog() -> dict:
    from config.platform_registry import platform_catalog_payload

    return {"platforms": platform_catalog_payload()}


def get_agent_backend_catalog() -> dict:
    return {"backends": agent_backend_catalog_payload()}


def _apply_session_meta(payloads: list[dict]) -> list[dict]:
    """Attach title / platform / agent to each Show Page payload from agent_sessions."""
    from storage.sessions_service import read_session_display_meta

    meta = read_session_display_meta([payload["session_id"] for payload in payloads])
    for payload in payloads:
        info = meta.get(payload["session_id"], {})
        payload["title"] = info.get("title")
        payload["platform"] = info.get("platform")
        payload["agent"] = info.get("agent")
    return payloads


def list_show_pages(*, user_context: Any = None) -> dict:
    """All Show Pages, newest-first, each enriched with the session title.

    Reuses ``ShowPageStore.list_page`` (already ordered by ``updated_at`` desc)
    and joins ``agent_sessions.title`` so the UI can label rows by title and
    fall back to the session id when no title is set.
    """
    from core.avibe_cloud import avibe_cloud_connect_guidance, avibe_cloud_url_available
    from core.show_pages import ShowPageStore, show_page_payload
    from storage import resource_access_service

    config = V2Config.load()
    context = resource_access_service.resolve_resource_access_context(user_context)
    store = ShowPageStore()
    try:
        result = store.list_page(page_request=None, user_context=user_context)
        pages = [show_page_payload(page, config=config) for page in result.items]
        # §3.2: management and sharing control follow the Instance Editor role
        # alone — show_page no longer has a Resource ACL row to consult.
        can_manage = context.has_role("editor")
        for payload in pages:
            payload["can_manage"] = can_manage
            payload["can_publish_public"] = can_manage
    finally:
        store.close()
    _apply_session_meta(pages)
    return {
        "ok": True,
        "count": len(pages),
        "pages": pages,
        "url_available": avibe_cloud_url_available(config),
        "url_guidance": avibe_cloud_connect_guidance(config),
    }


def _show_page_mutation_response(
    store,
    page,
    *,
    config: V2Config,
    additional_payload: dict | None = None,
    user_context: Any = None,
) -> dict:
    """Return mutation details only when the caller can use the page."""
    from storage import resource_access_service

    context = resource_access_service.resolve_resource_access_context(user_context)
    can_use = context.has_role("viewer")
    if not can_use:
        # Access managers may take a page offline without page-use access. Do
        # not return page paths, URLs, share IDs, audience, or session metadata.
        return {"ok": True}
    from core.show_pages import show_page_payload

    payload = show_page_payload(page, config=config)
    return {
        "ok": True,
        **(additional_payload or {}),
        **_apply_session_meta([payload])[0],
    }


def set_show_page_availability(
    session_id: str,
    offline: bool,
    *,
    user_context: Any = None,
) -> dict:
    """Change Show Page availability without mutating its configured audience."""

    from core.show_pages import ShowPageStore

    config = V2Config.load()
    store = ShowPageStore()
    try:
        updated = store.set_offline(
            session_id,
            offline,
            user_context=user_context,
        )
        return _show_page_mutation_response(
            store,
            updated,
            config=config,
            user_context=user_context,
        )
    finally:
        store.close()


def ensure_show_page(session_id: str, *, user_context: Any = None) -> dict:
    """Create the session's Show Page if it doesn't exist yet; report which.

    ``existed`` tells the caller whether the page was already initialized, so the
    workbench can ALSO send the "visualize this session" prompt only on first
    creation. Mirrors the CLI ``vibe show path`` (ensure + return).
    """
    from core.show_pages import ShowPageStore, show_page_payload

    config = V2Config.load()
    store = ShowPageStore()
    try:
        # Atomic: refuses to create a page for an archived session and reports
        # whether IT created the row (so the UI only prompts the agent on a real
        # first creation, not a concurrent ensure). Raises ShowPageError for an
        # archived session — the route maps it to a 4xx.
        page, created = store.ensure_active(session_id, user_context=user_context)
        payload = show_page_payload(page, config=config)
    finally:
        store.close()
    return {"ok": True, "existed": not created, **_apply_session_meta([payload])[0]}


def get_show_page(session_id: str, *, user_context: Any = None) -> dict:
    """Read one session's Show Page without creating it.

    The read-only counterpart of ``ensure_show_page``: same payload and the same
    access enforcement for a page that exists, and ``show_page_not_found`` where
    ensure would have created one. A caller that only needs to DISPLAY the page
    uses this, so ``ensure_show_page``'s one-shot ``existed`` edge stays with the
    single caller that owns the "visualize this session" prompt. The response
    deliberately carries no ``existed`` key: there is no creation fact to report,
    and none to accidentally consume.
    """
    from core.show_pages import ShowPageStore, show_page_payload

    config = V2Config.load()
    store = ShowPageStore()
    try:
        page = store.get_for_use(session_id, user_context=user_context)
        payload = show_page_payload(page, config=config)
    finally:
        store.close()
    return {"ok": True, **_apply_session_meta([payload])[0]}


def get_show_page_access(session_id: str, *, user_context: Any = None) -> dict:
    """Return the applied authenticated audience and sharing authority.

    §3.2 removed show_page from the Resource ACL, so there is no policy row:
    the ownership fence drives ``mode``/``ownership_status`` and the Instance
    role alone drives ``can_use``/``can_manage``/``can_publish_public``.
    """

    from core.show_pages import ShowPageError, ShowPageStore
    from storage import resource_access_service

    context = resource_access_service.resolve_resource_access_context(user_context)
    store = ShowPageStore()
    try:
        page = store.get(session_id)
        if page is None:
            raise ShowPageError("This session has no Show Page.", code="show_page_not_found")
        reconciliation = store.reconcile_resource_policy(page.session_id)
        can_use = context.has_role("viewer")
        can_manage = context.has_role("editor")
        can_publish_public = context.has_role("editor")
        if not (can_use or can_manage):
            raise ShowPageError("Show Page access is not permitted.", code="resource_access_forbidden")
    finally:
        store.close()

    ownership = reconciliation["ownership"]
    organization_id = ownership.get("organization_id")
    return {
        "ok": True,
        "mode": ownership["mode"],
        "ownership_status": reconciliation["status"],
        "instance_id": ownership.get("instance_id"),
        "organization_id": organization_id,
        "policy_organization_id": None,
        "access_level": "private",
        "group_ids": [],
        "policy_revision": None,
        "last_applied_control_plane_revision": None,
        "can_use": can_use,
        "can_manage": can_manage,
        "can_publish_public": can_publish_public,
    }


def require_show_access_settings_control(
    session_id: str,
    *,
    user_context: Any = None,
) -> None:
    from core.show_pages import ShowPageError, ShowPageStore
    from storage import resource_access_service

    context = resource_access_service.resolve_resource_access_context(user_context)
    store = ShowPageStore()
    try:
        page = store.get(session_id)
        if page is None:
            raise ShowPageError("This session has no Show Page.", code="show_page_not_found")
        if not context.has_role("editor"):
            raise ShowPageError(
                "Show Page access is not permitted.",
                code="resource_access_forbidden",
            )
    finally:
        store.close()


def upload_show_page_icon(
    session_id: str,
    data: bytes,
    *,
    filename: str | None,
    content_type: str | None,
    user_context: Any = None,
) -> dict:
    """Write an uploaded image as the page's workspace-root favicon; return the
    refreshed page payload so the Web UI merges it like any other show-page mutation
    (the fresh ``icon_version`` flows through ``show_page_payload``) — §7.1j.

    404 (``show_page_not_found``) when the session has no Show Page; ``session_archived``
    when the session is archived (mirrors the other Show Page mutators — an archived,
    terminal session's page cannot be changed); the write itself raises ``ShowPageError``
    (→ 4xx) for a malformed id / bad type / empty / oversized payload. Never edits
    ``index.html``.
    """
    from core.show_pages import ShowPageError, ShowPageStore, show_page_payload, write_show_page_icon

    config = V2Config.load()
    store = ShowPageStore()
    try:
        page = store.require_management(session_id, user_context=user_context)
        if store.is_archived(session_id):
            # Archiving leaves the page offline and terminal; the other mutators guard it
            # with session_archived, so a direct icon upload must not slip past that.
            raise ShowPageError(
                "This session is archived, so its Show Page can't be changed.",
                code="session_archived",
            )
        write_show_page_icon(session_id, data, filename=filename, content_type=content_type)
        payload = show_page_payload(page, config=config)
    finally:
        store.close()
    return {"ok": True, **_apply_session_meta([payload])[0]}


def get_dock(*, user_context: Any = None) -> dict:
    """The workbench Dock document — resident-tile order + pinned Show Pages."""
    from core.dock_store import load_dock

    return {"ok": True, "dock": load_dock(user_context=user_context)}


def pin_dock_show_page(session_id: str, *, user_context: Any = None) -> dict:
    """Pin a session's Show Page to the Dock (idempotent).

    Raises ``ShowPageError`` (malformed id → 400) or ``DockError`` (no Show Page
    → 404), which the route layer maps to a 4xx response.
    """
    from core.dock_store import pin_show_page

    return {"ok": True, "dock": pin_show_page(session_id, user_context=user_context)}


def unpin_dock_show_page(session_id: str, *, user_context: Any = None) -> dict:
    """Unpin a Show Page from the Dock (idempotent; leaves the page untouched)."""
    from core.dock_store import unpin_show_page

    return {"ok": True, "dock": unpin_show_page(session_id, user_context=user_context)}


def set_dock_order(
    order: list,
    known: list | None = None,
    *,
    user_context: Any = None,
) -> dict:
    """Persist a new resident-tile (docked-subset) order. ``known`` is the
    client's optimistic-concurrency baseline id set; when it no longer matches the
    server's, the write is rejected as stale so a stale tab can't silently undock a
    newer pin. Raises ``DockError`` for an invalid/stale order, mapped to a 400."""
    from core.dock_store import set_dock_order as _set_dock_order

    return {"ok": True, "dock": _set_dock_order(order, known=known, user_context=user_context)}


def get_workbench_prefs() -> dict:
    """Global workbench toggles the UI reads (state_meta-backed)."""
    from core.workbench_prefs import get_background_work_banner_enabled, get_fast_mode_default

    return {
        "ok": True,
        "background_work_banner_enabled": get_background_work_banner_enabled(),
        "fast_mode_default": get_fast_mode_default(),
    }


def set_workbench_prefs(
    *,
    background_work_banner_enabled: Optional[bool] = None,
    fast_mode_default: Optional[bool] = None,
) -> dict:
    """Persist provided workbench toggles; omitted fields are left untouched."""
    from core.workbench_prefs import set_background_work_banner_enabled, set_fast_mode_default

    if background_work_banner_enabled is not None:
        set_background_work_banner_enabled(bool(background_work_banner_enabled))
    if fast_mode_default is not None:
        set_fast_mode_default(bool(fast_mode_default))
    return get_workbench_prefs()


def _vibe_agent_payload(agent, *, brief: bool = False, remote_safe: bool = False) -> dict:
    payload = agent.to_dict()
    if brief or remote_safe:
        projected = {
            "id": payload["id"],
            "name": payload["name"],
            "display_name": payload["display_name"],
            "description": payload["description"],
            "backend": payload["backend"],
            "model": payload["model"],
            "reasoning_effort": payload["reasoning_effort"],
            "enabled": payload["enabled"],
            "archived": payload["archived"],
            "archived_at": payload["archived_at"],
            "source": payload["source"],
            "updated_at": payload["updated_at"],
            # The Bot this Agent is, if any (``docs/plans/bots.md`` D1): handle and display name.
            "bot": payload["bot"],
        }
        if remote_safe:
            projected.update(
                {
                    "system_prompt": payload["system_prompt"],
                    "metadata": {},
                    "created_at": payload["created_at"],
                }
            )
        return projected
    return payload


def _parse_agent_enabled_field(payload: dict, *, default: Optional[bool] = None) -> Optional[bool]:
    if "enabled" not in payload:
        return default
    value = payload.get("enabled")
    if isinstance(value, bool):
        return value
    raise ValueError("Agent enabled must be a JSON boolean")


def get_vibe_agents(
    *,
    backend: Optional[str] = None,
    include_disabled: bool = False,
    include_archived: bool = False,
    user_context: Any = None,
) -> dict:
    _ensure_builtin_default_agents()
    user_context = resolve_resource_access_context(user_context)
    store = VibeAgentStore()
    try:
        normalized_backend = validate_agent_backend(backend) if backend else None
        agents = store.list_agents(
            include_disabled=include_disabled,
            include_archived=include_archived,
            user_context=user_context,
        )
        if normalized_backend:
            agents = [agent for agent in agents if agent.backend == normalized_backend]
        default_agent = store.get_default_agent()
        if default_agent is not None:
            try:
                default_agent = store.require_accessible(default_agent.name, user_context=user_context)
            except VibeAgentAccessError:
                default_agent = None
        return {
            "ok": True,
            "agents": [_vibe_agent_payload(agent, brief=True) for agent in agents],
            "default_agent_name": default_agent.name if default_agent else None,
        }
    finally:
        store.close()


def _organization_resource_console_url(config: V2Config, organization_id: str) -> str:
    backend_url = str(config.remote_access.vibe_cloud.backend_url or "https://avibe.bot").rstrip("/")
    organization = urllib.parse.quote(organization_id, safe="")
    return f"{backend_url}/app/organizations/{organization}/resources"


def _agent_onboarding_resource_descriptors(
    organization_id: str,
    inventory: list[dict],
) -> list[dict]:
    """Enrich the full ACL snapshot with safe Agent names for first publication."""

    from vibe import remote_access

    display_names: dict[str, str] = {}
    for agent in inventory:
        resource_id = str(agent.get("id") or "")
        try:
            display_names[resource_id] = remote_access._safe_resource_acl_identifier(
                agent.get("name"),
                limit=240,
            )
        except ValueError:
            display_names[resource_id] = resource_id

    # A resource-index update is a full snapshot. Preserve non-Agent resources
    # while enriching newly onboarded Agent rows with their safe names.
    descriptors = remote_access._local_policy_resource_descriptors(organization_id)
    for descriptor in descriptors:
        if descriptor.get("resource_kind") != "agent":
            continue
        display_name = display_names.get(str(descriptor.get("resource_id") or ""))
        if display_name:
            descriptor["display_name"] = display_name
    return descriptors


def get_vibe_agent_onboarding(*, user_context: Any = None) -> dict:
    """Return the safe owner inventory for Organization Agent onboarding."""

    config = V2Config.load()
    _ensure_builtin_default_agents(config)
    store = VibeAgentStore()
    try:
        result = store.organization_onboarding_inventory(
            user_context=resolve_resource_access_context(user_context),
        )
    finally:
        store.close()
    result["ok"] = True
    if result.get("available") and result.get("organization_id"):
        result["console_url"] = _organization_resource_console_url(
            config,
            str(result["organization_id"]),
        )
    return result


def onboard_vibe_agents(*, user_context: Any = None) -> dict:
    """Register all existing Agents privately, then publish the safe index."""

    from vibe import remote_access

    config = V2Config.load()
    _ensure_builtin_default_agents(config)
    context = resolve_resource_access_context(user_context)
    store = VibeAgentStore()
    try:
        result = store.onboard_organization_agents(user_context=context)
    finally:
        store.close()

    organization_id = str(result["organization_id"])
    resources = _agent_onboarding_resource_descriptors(
        organization_id,
        list(result.get("agents") or []),
    )
    result.update(
        {
            "ok": True,
            "console_url": _organization_resource_console_url(config, organization_id),
            "sync": remote_access.sync_resource_acl_once(
                config,
                organization_id=organization_id,
                resources=resources,
            ),
        }
    )
    return result


def get_vibe_agent(name: str, *, user_context: Any = None) -> dict:
    user_context = resolve_resource_access_context(user_context)
    store = VibeAgentStore()
    try:
        agent = store.require_accessible(name, user_context=user_context)
        default_agent = store.get_default_agent()
        if default_agent is not None:
            try:
                default_agent = store.require_accessible(default_agent.name, user_context=user_context)
            except VibeAgentAccessError:
                default_agent = None
        return {
            "ok": True,
            "agent": _vibe_agent_payload(
                agent,
                remote_safe=False,
            ),
            "default_agent_name": default_agent.name if default_agent else None,
        }
    finally:
        store.close()


def create_vibe_agent(payload: dict, *, user_context: Any = None) -> dict:
    if not isinstance(payload, dict):
        raise ValueError("Agent payload must be an object")
    metadata = payload.get("metadata") or payload.get("metadata_json") or {}
    if not isinstance(metadata, dict):
        raise ValueError("Agent metadata must be an object")
    store = VibeAgentStore()
    try:
        try:
            agent = store.create(
                name=str(payload.get("name") or "").strip(),
                backend=validate_agent_backend(str(payload.get("backend") or "")),
                description=payload.get("description"),
                model=payload.get("model"),
                reasoning_effort=payload.get("reasoning_effort") or payload.get("effort"),
                system_prompt=payload.get("system_prompt"),
                metadata=metadata,
                enabled=_parse_agent_enabled_field(payload, default=True),
                user_context=resolve_resource_access_context(user_context),
            )
        except AgentNameValidationError as exc:
            return _agent_name_validation_error(exc)
        return {"ok": True, "agent": _vibe_agent_payload(agent)}
    finally:
        store.close()


def update_vibe_agent(name: str, payload: dict, *, user_context: Any = None) -> dict:
    if not isinstance(payload, dict):
        raise ValueError("Agent payload must be an object")
    if "backend" in payload:
        raise ValueError("Agent backend is immutable")

    allowed_fields = {
        "description",
        "model",
        "reasoning_effort",
        "effort",
        "system_prompt",
        "metadata",
        "metadata_json",
        "enabled",
    }
    kwargs: dict[str, object] = {}
    if "description" in payload:
        kwargs["description"] = payload.get("description")
    if "model" in payload:
        kwargs["model"] = payload.get("model")
    if "reasoning_effort" in payload or "effort" in payload:
        kwargs["reasoning_effort"] = payload.get("reasoning_effort") or payload.get("effort")
    if "system_prompt" in payload:
        kwargs["system_prompt"] = payload.get("system_prompt")
    if "metadata" in payload or "metadata_json" in payload:
        metadata = payload.get("metadata") if "metadata" in payload else payload.get("metadata_json")
        if metadata is None:
            metadata = {}
        if not isinstance(metadata, dict):
            raise ValueError("Agent metadata must be an object")
        kwargs["metadata"] = metadata
    if "enabled" in payload:
        kwargs["enabled"] = _parse_agent_enabled_field(payload)
    unknown = sorted(set(payload) - allowed_fields - {"name"})
    if unknown:
        raise ValueError(f"Unsupported Agent fields: {', '.join(unknown)}")
    new_name = str(payload.get("name") or "").strip() if "name" in payload else ""
    renaming = bool(new_name and new_name != name)
    if renaming and kwargs:
        raise ValueError("Agent rename cannot be combined with other field updates")
    if not kwargs and not renaming:
        raise ValueError("No editable Agent fields were provided")

    store = VibeAgentStore()
    try:
        context = resolve_resource_access_context(user_context)
        try:
            agent = (
                store.rename(name, new_name, user_context=context)
                if renaming
                else store.update(name, user_context=context, **kwargs)
            )
        except AgentNameValidationError as exc:
            return _agent_name_validation_error(exc)
        except (AgentArchivedEditError, AgentAlwaysEnabledError, AgentBotLockedError) as exc:
            return _agent_lifecycle_error(exc)
        except AgentReferenceRewriteError as exc:
            return _agent_reference_rewrite_error(exc)
        return {"ok": True, "agent": _vibe_agent_payload(agent)}
    finally:
        store.close()


def _agent_name_validation_error(exc: AgentNameValidationError) -> dict:
    try:
        lang = V2Config.load().language
    except Exception:
        lang = "en"
    key = f"error.agentNameValidation.{exc.code}"
    return {
        "ok": False,
        "code": exc.code,
        "message": backend_t(f"{key}.message", lang, agent=exc.agent_name),
        "hint": backend_t(f"{key}.hint", lang, agent=exc.agent_name),
    }


def _agent_lifecycle_error(exc: AgentArchivedEditError | AgentAlwaysEnabledError | AgentBotLockedError) -> dict:
    try:
        lang = V2Config.load().language
    except Exception:
        lang = "en"
    key = f"error.agentLifecycle.{exc.code}"
    return {
        "ok": False,
        "code": exc.code,
        "message": backend_t(f"{key}.message", lang, agent=exc.agent_name),
        "hint": backend_t(f"{key}.hint", lang, agent=exc.agent_name),
    }


def _agent_reference_rewrite_error(exc: AgentReferenceRewriteError) -> dict:
    try:
        lang = V2Config.load().language
    except Exception:
        lang = "en"
    key = f"error.agentLifecycle.{exc.code}"
    return {
        "ok": False,
        "code": exc.code,
        "message": backend_t(f"{key}.message", lang),
        "hint": backend_t(f"{key}.hint", lang),
    }


def remove_vibe_agent(name: str, *, user_context: Any = None) -> dict:
    store = VibeAgentStore()
    try:
        context = resolve_resource_access_context(user_context)
        store.require_manageable(name, user_context=context)
        try:
            archived = store.archive(name, user_context=context)
        except AgentArchiveError as exc:
            try:
                lang = V2Config.load().language
            except Exception:
                lang = "en"
            return {
                "ok": False,
                "code": exc.code,
                "message": backend_t(
                    f"error.agentArchive.{exc.code}.message",
                    lang,
                    agent=exc.agent_name,
                ),
            }
        except AgentReferenceRewriteError as exc:
            return _agent_reference_rewrite_error(exc)
        if archived is None:
            return {"ok": False, "code": "agent_not_found", "message": f"agent '{name}' not found"}
        return {
            "ok": True,
            "removed_agent": archived.original_name,
            "archived_agent": _vibe_agent_payload(archived.agent, brief=True),
            "references": archived.references,
            "default_agent_name": archived.default_agent_name,
        }
    finally:
        store.close()


def set_default_vibe_agent(name: str, *, user_context: Any = None) -> dict:
    store = VibeAgentStore()
    try:
        context = resolve_resource_access_context(user_context)
        agent = store.require_manageable(name, user_context=context)
        if not agent.enabled:
            raise ValueError(f"agent '{agent.name}' is disabled")
        try:
            store.set_default_agent_name(name, user_context=context)
        except AgentBotLockedError as exc:
            return _agent_lifecycle_error(exc)
        return {"ok": True, "default_agent_name": agent.name, "agent": _vibe_agent_payload(agent, brief=True)}
    finally:
        store.close()


# ----- Vaults (secret management; design: docs/plans/vaults.md) -----
# Thin web-facing wrappers over storage.vault_service. Reads are masked (no values);
# values are only ever delivered to agents via the CLI (vibe vault run/fetch/...).


class VaultApiError(ValueError):
    """A vault REST error carrying a stable code + HTTP status for the route layer."""

    def __init__(self, message: str, *, code: str = "vault_error", status: int = 400):
        super().__init__(message)
        self.code = code
        self.status = status


def _vault_secret_access_forbidden(exc: Exception) -> VaultApiError:
    """Translate the storage-layer Vault ACL denial into the REST contract."""

    return VaultApiError(str(exc), code="resource_access_forbidden", status=403)


def _publish_vaults_updated(
    *,
    scope: str,
    request_id: str | None = None,
    request_status: str | None = None,
    grant_id: str | None = None,
    grant_status: str | None = None,
    secret_name: str | None = None,
) -> None:
    """Publish a UI-server-local vault update event for refetch-on-event pages."""

    try:
        from uuid import uuid4

        from core.inbox_events import VAULTS_UPDATED_EVENT, vaults_updated_payload
        from vibe.inbox_bridge import remember_local_event
        from vibe.sse_broker import broker

        payload = vaults_updated_payload(
            scope=scope,
            request_id=request_id,
            request_status=request_status,
            grant_id=grant_id,
            grant_status=grant_status,
            secret_name=secret_name,
        )
        event_id = uuid4().hex
    except Exception:
        logger.debug("vaults.updated event construction failed", exc_info=True)
        return
    try:
        broker.publish(VAULTS_UPDATED_EVENT, payload)
        remember_local_event(event_id)
    except Exception:
        logger.debug("vaults.updated local publish failed", exc_info=True)
    try:
        from vibe import internal_client

        internal_client.publish_event_sync(
            VAULTS_UPDATED_EVENT,
            {**payload, "_event_id": event_id},
            timeout=1.5,
        )
    except Exception:
        logger.debug("vaults.updated bridge publish failed", exc_info=True)


def _notify_vault_request_created(request: dict | None) -> None:
    """Best-effort bridge to the daemon-owned IM dispatcher for Vault request notices."""

    if not isinstance(request, dict):
        return
    try:
        from vibe import internal_client

        internal_client.notify_vault_request_created_sync(request, timeout=2.0)
    except Exception:
        logger.debug("vault request notification bridge failed", exc_info=True)


def _vault_api_error_from_avault(exc: "AvaultError", *, prefix: str) -> VaultApiError:
    if isinstance(exc, AvaultStaleLoginSessionError):
        return VaultApiError(
            backend_t("errors.staleLoginSession"),
            code=exc.code,
            status=409,
        )
    message = str(exc)
    if isinstance(exc, AvaultAuthorizationRequiredError):
        return VaultApiError(f"{prefix}: {message}", code=exc.code, status=409)
    if "requires avault >=" in message:
        return VaultApiError(f"{prefix}: {message}", code="avault_upgrade_required", status=409)
    return VaultApiError(f"{prefix}: {message}", code="avault_failed")


_VAULT_MAX_FIELDS = 32


def _vault_validate_field_name(value: Any, *, field: str = "field") -> str:
    from storage import vault_service

    return vault_service.validate_field_name(value, field=field)


def _vault_secret_record_names(meta: dict[str, Any]) -> list[str]:
    """Expand one value-free secret meta into its encrypted record names."""

    from storage import vault_service

    return [str(name) for name in vault_service.secret_record_names(meta)]


def _vault_record_meta(
    conn: Any,
    ref: str,
    *,
    user_context: Any = None,
) -> dict[str, Any]:
    """Resolve a record ref through the storage public contract."""

    from storage import vault_service

    return dict(vault_service.get_secret_record_meta(conn, ref, user_context=user_context))


def _vault_secret_management_meta(
    conn: Any,
    secret_name: str,
    *,
    user_context: Any = None,
) -> dict[str, Any]:
    """Authorize management before a field is sealed, then return masked meta."""

    from storage import vault_service

    vault_service.require_secret_management(conn, secret_name, user_context=user_context)
    return dict(vault_service.get_secret_meta(conn, secret_name, user_context=user_context))


# Stable Web field errors: ApiContext/vaultErrorMessage resolve errors.<code>.
# The catalog contract test also probes all service exception mappings so adding
# a mapped code without declaring and translating it fails validation.
_VAULT_FIELD_ERROR_CODES = (
    "invalid_field_name",
    "field_exists",
    "field_not_found",
    "too_many_fields",
    "fields_corrupt",
    "fields_not_supported",
    "record_mismatch",
    "secret_conflict",
)


def _vault_field_service_error(exc: Exception) -> VaultApiError:
    from storage import vault_service

    mappings: tuple[tuple[type[Exception], str, int], ...] = (
        (vault_service.InvalidFieldNameError, "invalid_field_name", 400),
        (vault_service.FieldExistsError, "field_exists", 409),
        (vault_service.FieldNotFoundError, "field_not_found", 404),
        (vault_service.TooManyFieldsError, "too_many_fields", 409),
        (vault_service.FieldsCorruptError, "fields_corrupt", 409),
        (vault_service.FieldsNotSupportedError, "fields_not_supported", 409),
        (vault_service.RecordMismatchError, "record_mismatch", 409),
        (vault_service.SecretConflictError, "secret_conflict", 409),
    )
    for error_type, code, status in mappings:
        if isinstance(exc, error_type):
            return VaultApiError(str(exc), code=code, status=status)
    if isinstance(exc, vault_service.InvalidRequestError):
        return VaultApiError(str(exc), code="invalid_request", status=409)
    if isinstance(exc, vault_service.SecretNotFoundError):
        return VaultApiError(str(exc), code="secret_not_found", status=404)
    if isinstance(exc, vault_service.VaultSecretAccessError):
        return _vault_secret_access_forbidden(exc)
    return VaultApiError(str(exc), code="vault_error")


def _vault_create_field_specs(
    payload: dict[str, Any],
    *,
    secret_name: str,
    kind: str,
    default_field: str,
) -> list[dict[str, Any]]:
    from storage import vault_service

    if "fields" not in payload:
        return []
    raw_fields = payload.get("fields")
    if not isinstance(raw_fields, list):
        raise VaultApiError("fields must be an array", code="invalid_request", status=409)
    if kind == "keypair" and "fields" in payload:
        raise VaultApiError(
            "keypair secrets do not support fields",
            code="fields_not_supported",
            status=409,
        )
    if len(raw_fields) + 1 > _VAULT_MAX_FIELDS:
        raise VaultApiError(
            f"a vault secret can have at most {_VAULT_MAX_FIELDS} fields",
            code="too_many_fields",
            status=409,
        )
    names: set[str] = {default_field}
    specs: list[dict[str, Any]] = []
    envelope_key = "blind_box" if str(payload.get("protection") or "standard").strip().lower() == "standard" else "sealed"
    for index, item in enumerate(raw_fields):
        if not isinstance(item, dict):
            raise VaultApiError(
                f"fields[{index}] must be an object",
                code="invalid_request",
                status=409,
            )
        try:
            field_name = _vault_validate_field_name(item.get("name"), field=f"fields[{index}].name")
        except vault_service.InvalidFieldNameError as exc:
            raise VaultApiError(str(exc), code="invalid_field_name", status=400) from exc
        if field_name in names:
            raise VaultApiError(
                f"field {field_name!r} already exists",
                code="field_exists",
                status=409,
            )
        if "record" not in item:
            raise VaultApiError(
                f"fields[{index}].record is required",
                code="invalid_request",
                status=409,
            )
        record = item["record"]
        if not isinstance(record, str):
            raise VaultApiError(
                f"fields[{index}].record must be a string",
                code="record_mismatch",
                status=409,
            )
        expected_record = f"{secret_name}.{field_name}"
        if record != expected_record:
            raise VaultApiError(
                f"fields[{index}].record must be {expected_record!r}",
                code="record_mismatch",
                status=409,
            )
        envelope = item.get(envelope_key)
        if not isinstance(envelope, dict):
            raise VaultApiError(
                f"fields[{index}].{envelope_key} is required",
                code="invalid_envelope" if envelope_key == "sealed" else "blind_box_required",
                status=400,
            )
        names.add(field_name)
        specs.append({"name": field_name, "record": record, envelope_key: envelope})
    return specs


def _vault_engine():
    from storage.db import create_sqlite_engine
    from storage.importer import ensure_sqlite_state, resolve_primary_platform_from_config

    # Resolve the platform from config like the other CLI/data paths — if the Vaults
    # route is the first to initialize SQLite on an upgraded install with legacy
    # sessions, ``ensure_sqlite_state`` requires a platform and would otherwise raise.
    ensure_sqlite_state(primary_platform=resolve_primary_platform_from_config(paths.get_state_dir()))
    return create_sqlite_engine(paths.get_sqlite_state_path())


def get_vault_secrets(
    *,
    tag: Optional[str] = None,
    tags: Optional[List[str]] = None,
    query: Optional[str] = None,
    kind: Optional[str] = None,
    protection: Optional[str] = None,
) -> dict:
    from storage import vault_service

    engine = _vault_engine()
    try:
        with engine.connect() as conn:
            secrets = vault_service.list_secrets(
                conn,
                tag=tag,
                tags=tags,
                query=query,
                kind=kind,
                protection=protection,
            )
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    return {"ok": True, "secrets": secrets}


def get_vault_tags(*, query: Optional[str] = None, tag_type: Optional[str] = None) -> dict:
    from storage import vault_service

    engine = _vault_engine()
    try:
        with engine.connect() as conn:
            tags = vault_service.list_secret_tags(conn, query=query, tag_type=tag_type)
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    return {"ok": True, "tags": tags}


def get_vault_pubkey() -> dict:
    try:
        return {"ok": True, **avault_pubkey()}
    except AvaultError as exc:
        raise _vault_api_error_from_avault(exc, prefix="avault pubkey failed") from exc


def get_vault_agent_pubkey() -> dict:
    try:
        return {"ok": True, **avault_agent_pubkey()}
    except AvaultError as exc:
        raise _vault_api_error_from_avault(exc, prefix="avault agent pubkey failed") from exc


def derive_vault_signing_addresses(public_key: str) -> dict:
    """Derive the receive addresses for a compressed secp256k1 public key.

    Value-free: uses only the public key, so it needs no vault/avault access. Lets the
    create form preview a signing key's addresses before the secret is saved.
    """
    from storage.vault_addresses import derive_addresses

    if not isinstance(public_key, str) or not public_key.strip():
        raise VaultApiError("public_key is required", code="invalid_request")
    try:
        return {"ok": True, "addresses": derive_addresses(public_key)}
    except VaultApiError:
        raise
    except Exception as exc:
        raise VaultApiError("invalid secp256k1 public key", code="invalid_public_key") from exc


def get_vault_vmk() -> dict:
    from storage import vault_service

    engine = _vault_engine()
    with engine.connect() as conn:
        wrap_meta = vault_service.latest_protected_vmk_wrap_meta(conn)
    return {"ok": True, "exists": wrap_meta is not None, "wrap_meta": wrap_meta}


_VAULT_DAEMON_AGENT_BINDING_KEY = "vault.daemon_agent_binding_key.v1"


def _b64(data: bytes) -> str:
    return base64.b64encode(data).decode("ascii")


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


def _parse_vault_daemon_binding_key(raw: object) -> dict[str, str] | None:
    if not isinstance(raw, str):
        return None
    with contextlib.suppress(Exception):
        payload = json.loads(raw)
        if (
            isinstance(payload, dict)
            and isinstance(payload.get("keyId"), str)
            and isinstance(payload.get("privateKey"), str)
            and isinstance(payload.get("publicKey"), str)
        ):
            return payload
    return None


def _new_vault_daemon_binding_key() -> dict[str, str]:
    from cryptography.hazmat.primitives import serialization
    from cryptography.hazmat.primitives.asymmetric import ed25519

    private_key = ed25519.Ed25519PrivateKey.generate()
    private_raw = private_key.private_bytes(
        encoding=serialization.Encoding.Raw,
        format=serialization.PrivateFormat.Raw,
        encryption_algorithm=serialization.NoEncryption(),
    )
    public_raw = private_key.public_key().public_bytes(
        encoding=serialization.Encoding.Raw,
        format=serialization.PublicFormat.Raw,
    )
    key_id = "vault-daemon-ed25519-v1"
    return {"keyId": key_id, "privateKey": _b64(private_raw), "publicKey": _b64(public_raw)}


def _load_or_create_vault_daemon_binding_key(conn) -> dict[str, str]:
    from storage.models import state_meta

    raw = conn.execute(
        select(state_meta.c.value_json).where(state_meta.c.key == _VAULT_DAEMON_AGENT_BINDING_KEY)
    ).scalar_one_or_none()
    existing = _parse_vault_daemon_binding_key(raw)
    if existing is not None:
        return existing

    payload = _new_vault_daemon_binding_key()
    stmt = sqlite_insert(state_meta).values(
        key=_VAULT_DAEMON_AGENT_BINDING_KEY,
        value_json=json.dumps(payload, sort_keys=True),
        updated_at=_utc_now_iso(),
    )
    conn.execute(stmt.on_conflict_do_nothing(index_elements=[state_meta.c.key]))
    raw = conn.execute(
        select(state_meta.c.value_json).where(state_meta.c.key == _VAULT_DAEMON_AGENT_BINDING_KEY)
    ).scalar_one_or_none()
    existing = _parse_vault_daemon_binding_key(raw)
    if existing is not None:
        return existing

    conn.execute(
        state_meta.update()
        .where(state_meta.c.key == _VAULT_DAEMON_AGENT_BINDING_KEY)
        .values(value_json=json.dumps(payload, sort_keys=True), updated_at=_utc_now_iso())
    )
    return payload


def get_vault_sandbox_root_metadata() -> dict:
    engine = _vault_engine()
    with engine.begin() as conn:
        key = _load_or_create_vault_daemon_binding_key(conn)
    return {
        "ok": True,
        "root_metadata": {
            "daemon": {
                "verificationKeys": [
                    {
                        "alg": "ed25519",
                        "keyId": key["keyId"],
                        "publicKey": key["publicKey"],
                    }
                ]
            }
        },
    }


def _u64_be(value: int) -> bytes:
    if value < 0 or value > 0xFFFF_FFFF_FFFF_FFFF:
        raise VaultApiError("ttl_seconds out of bounds", code="invalid_grant")
    return value.to_bytes(8, "big")


def _length_prefixed(fields: list[str | bytes]) -> bytes:
    out = bytearray()
    for field in fields:
        data = field.encode("utf-8") if isinstance(field, str) else field
        if len(data) > 0xFFFF_FFFF:
            raise VaultApiError("blind-box AAD field is too large", code="invalid_grant")
        out.extend(len(data).to_bytes(4, "big"))
        out.extend(data)
    return bytes(out)


def _agent_deliver_operation_hash(name: str, ttl_seconds: int) -> str:
    return hashlib.sha256(
        _length_prefixed(["agent-deliver", name, _u64_be(ttl_seconds)])
    ).hexdigest()


def _jsonify_surrogates_like_js(canonical: str) -> str:
    chars: list[str] = []
    index = 0
    while index < len(canonical):
        codepoint = ord(canonical[index])
        if 0xD800 <= codepoint <= 0xDBFF and index + 1 < len(canonical):
            next_codepoint = ord(canonical[index + 1])
            if 0xDC00 <= next_codepoint <= 0xDFFF:
                chars.append(chr(0x10000 + ((codepoint - 0xD800) << 10) + (next_codepoint - 0xDC00)))
                index += 2
                continue
        if 0xD800 <= codepoint <= 0xDFFF:
            chars.append(f"\\u{codepoint:04x}")
        else:
            chars.append(canonical[index])
        index += 1
    return "".join(chars)


def _vault_sandbox_canonical_json(payload: Any) -> str:
    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
    return _jsonify_surrogates_like_js(canonical)


def _envelope_hash(envelope_payload: dict[str, Any]) -> dict[str, str]:
    canonical = _vault_sandbox_canonical_json(envelope_payload)
    return {
        "alg": "sha256",
        "digest": hashlib.sha256(canonical.encode("utf-8")).hexdigest(),
    }


def _signed_agent_binding(binding: dict[str, Any], key: dict[str, str]) -> dict[str, Any]:
    from cryptography.hazmat.primitives.asymmetric import ed25519

    private_key = ed25519.Ed25519PrivateKey.from_private_bytes(base64.b64decode(key["privateKey"]))
    canonical = _vault_sandbox_canonical_json(binding)
    signature = _b64(private_key.sign(canonical.encode("utf-8")))
    return {
        **binding,
        "signature": {
            "alg": "ed25519",
            "keyId": key["keyId"],
            "value": signature,
        },
    }


def _isoformat_z(value: datetime) -> str:
    return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")


def _display_text(value: Any, *, max_len: int) -> str | None:
    if value is None:
        return None
    text = re.sub(r"[\x00-\x1f\x7f]+", " ", str(value))
    text = re.sub(r"\s+", " ", text).strip()
    if not text:
        return None
    if len(text) > max_len:
        return f"{text[: max_len - 3].rstrip()}..."
    return text


def _display_list(values: Any, *, max_items: int = 20, max_len: int = 80) -> list[str]:
    if not isinstance(values, list):
        return []
    out: list[str] = []
    for item in values:
        cleaned = _display_text(item, max_len=max_len)
        if cleaned:
            out.append(cleaned)
        if len(out) >= max_items:
            break
    return out


def _display_source(selector: Any) -> dict[str, list[str]]:
    from storage import vault_service

    if not isinstance(selector, dict):
        return {}
    source: dict[str, list[str]] = {}
    env = _display_list(selector.get("env"))
    if env:
        source["env"] = env
    raw_tags = selector.get("tags")
    plain_tags: list[str] = []
    skills: list[str] = []
    if isinstance(raw_tags, list):
        for tag in raw_tags:
            cleaned = _display_text(tag, max_len=80)
            if not cleaned:
                continue
            if cleaned.startswith(vault_service.SKILL_TAG_PREFIX):
                skill = _display_text(cleaned[len(vault_service.SKILL_TAG_PREFIX) :], max_len=80)
                if skill:
                    skills.append(skill)
            else:
                plain_tags.append(cleaned)
    raw_skills = selector.get("skills")
    if isinstance(raw_skills, list):
        skills.extend(_display_list(raw_skills))
    if plain_tags:
        source["tags"] = list(dict.fromkeys(plain_tags))[:20]
    if skills:
        source["skills"] = list(dict.fromkeys(skills))[:20]
    return source


def _operation_context_display(
    request_payload: dict[str, Any] | None,
    secret_metas: list[dict[str, Any]],
    *,
    grant_ttl_seconds: int | None = None,
) -> dict[str, Any]:
    request_payload = request_payload if isinstance(request_payload, dict) else {}
    card = request_payload.get("card") if isinstance(request_payload.get("card"), dict) else {}
    display: dict[str, Any] = {
        "secrets": [
            {
                "name": str(meta["name"]),
                "kind": str(meta.get("kind") or "static") if meta.get("kind") in {"static", "keypair"} else "static",
            }
            for meta in secret_metas
        ]
    }
    session = request_payload.get("session") if isinstance(request_payload.get("session"), dict) else {}
    session_label = _display_text(session.get("label") or card.get("session_id"), max_len=120)
    if session_label:
        display["sessionLabel"] = session_label
    command = _display_text(card.get("command"), max_len=240)
    if command:
        display["command"] = command
    egress = _display_text(card.get("egress"), max_len=160)
    if egress:
        display["egress"] = egress
    delivery = request_payload.get("delivery") if isinstance(request_payload.get("delivery"), dict) else {}
    source = _display_source(card.get("source_selector") or delivery.get("source_selector"))
    if source:
        display["source"] = source
    if grant_ttl_seconds is not None:
        display["grantTtlSeconds"] = int(grant_ttl_seconds)
    return display


def _grant_duration_value_from_payload(payload: dict[str, Any]) -> Any | None:
    from storage import vault_service

    grant_duration_keys = ("grant_duration", "grantDuration", "last_grant_ttl", "lastGrantTtl")
    ttl_keys = ("ttl_seconds", "ttlSecs")
    has_grant_duration = any(key in payload for key in grant_duration_keys)
    has_one_shot = payload.get("one_shot") is True or payload.get("oneShot") is True
    has_legacy_ttl = any(key in payload for key in ttl_keys)
    if (has_grant_duration or has_one_shot) and has_legacy_ttl:
        raise VaultApiError("use grant_duration or ttl_seconds, not both", code="invalid_request", status=409)

    for key in grant_duration_keys:
        if key in payload:
            return payload[key]
    if has_one_shot:
        return vault_service.GRANT_DURATION_ONE_TIME
    for key in ttl_keys:
        if key in payload:
            value = payload[key]
            try:
                if int(value) == vault_service.ONE_TIME_GRANT_TTL_SECONDS:
                    return vault_service.GRANT_DURATION_ONE_TIME
            except (TypeError, ValueError):
                pass
            return value
    return None


def _signed_operation_context(context: dict[str, Any], key: dict[str, str]) -> dict[str, Any]:
    return _signed_agent_binding(context, key)


def create_vault_agent_bindings_batch(payload: dict) -> dict:
    from storage import vault_crypto, vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    request_id = str(payload.get("request_id") or payload.get("requestId") or "").strip()
    if not request_id:
        raise VaultApiError("request_id is required", code="missing_request_id")

    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            request_payload = vault_service.get_request(conn, request_id, audience=vault_service.REQUEST_AUDIENCE_UI)
            option = _grant_option_from_request(conn, request_id)
            # The approval card issues these contexts while it is open, before the approver
            # decides, so issuing them never changes the remembered duration; an approval does.
            duration = vault_service.normalize_grant_duration(
                _grant_duration_value_from_payload(payload),
                default=option.get("default_grant_duration") or vault_service.get_vault_settings(conn)["last_grant_ttl"],
            )
            grantable_members = vault_service.request_grantable_member_metas(conn, request_id)
            protected_metas = [member for member in grantable_members if member.get("protection") == "protected"]
            member_order = {name: index for index, name in enumerate(option["member_names"])}
            grantable_members.sort(key=lambda item: member_order.get(str(item.get("name")), 10_000))
            protected_metas.sort(key=lambda item: member_order.get(str(item.get("name")), 10_000))
    except vault_service.RequestNotFoundError as exc:
        raise VaultApiError(f"request '{request_id}' not found", code="request_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.InvalidRequestError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    except vault_service.InvalidGrantError as exc:
        raise VaultApiError(str(exc), code="invalid_grant") from exc
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="vault_error") from exc

    if not protected_metas:
        return {
            "ok": True,
            "request_id": request_id,
            "grant_id": option["grant_id"],
            "grant_duration": duration["last_grant_ttl"],
            "ttl_seconds": duration["ttl_seconds"],
            "items": [],
        }

    with engine.begin() as conn:
        key = _load_or_create_vault_daemon_binding_key(conn)

    for meta in protected_metas:
        name = str(meta.get("name") or "")
        try:
            valid_name = vault_crypto.is_valid_secret_name(name)
        except Exception:
            valid_name = False
        if not valid_name:
            raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
        if meta.get("protection") != "protected":
            raise VaultApiError("agent binding is only valid for protected secrets", code="not_protected", status=409)

    try:
        _require_avault_grant_delivery_surface("resident agent grant")
        agent_pubkey = avault_agent_pubkey()
    except AvaultError as exc:
        raise _vault_api_error_from_avault(exc, prefix="avault agent binding failed") from exc

    now = datetime.now(timezone.utc)
    ttl_seconds = int(duration["ttl_seconds"])
    expires_at = now + timedelta(seconds=ttl_seconds)
    expires_at_unix = int(expires_at.timestamp())
    display_members: list[dict[str, Any]] = []
    for meta in grantable_members:
        for record_name in _vault_secret_record_names(meta):
            display_members.append({**meta, "name": record_name})
    display = _operation_context_display(request_payload, display_members, grant_ttl_seconds=ttl_seconds)
    agent = {
        "publicKey": {
            "public_key": str(agent_pubkey["public_key"]),
            "fingerprint": str(agent_pubkey["fingerprint"]),
        },
        "fingerprint": str(agent_pubkey["fingerprint"]),
    }
    items: list[dict[str, Any]] = []
    issued_items: list[dict[str, Any]] = []
    for meta in protected_metas:
        for name in _vault_secret_record_names(meta):
            approval_nonce = os.urandom(16)
            context_request_id = f"vab_{uuid.uuid4().hex}"
            release = {
                "name": name,
                "ttlSecs": ttl_seconds,
                "approvalNonce": list(approval_nonce),
                "approvalExpiresAtUnix": expires_at_unix,
                "operationHash": _agent_deliver_operation_hash(name, ttl_seconds),
            }
            context = {
                "v": 2,
                "purpose": "agent-deliver",
                "requestId": context_request_id,
                "grantId": option["grant_id"],
                "display": display,
                "release": release,
                "agent": agent,
                "expiresAt": _isoformat_z(expires_at),
            }
            signed_context = _signed_operation_context(context, key)
            approval = {
                "nonce": _b64(approval_nonce),
                "expires_at_unix": expires_at_unix,
            }
            items.append(
                {
                    "name": name,
                    "context": signed_context,
                    "approval": approval,
                }
            )
            issued_items.append(
                {
                    "name": name,
                    "request_id": context_request_id,
                    "approval": approval,
                }
            )
    with engine.begin() as conn:
        vault_service.record_request_agent_binding_approvals(
            conn,
            request_id,
            {
                "grant_id": option["grant_id"],
                "grant_duration": duration["last_grant_ttl"],
                "ttl_seconds": ttl_seconds,
                "agent": agent,
                "issued_at": _isoformat_z(now),
                "expires_at": _isoformat_z(expires_at),
                "items": issued_items,
            },
        )
    return {
        "ok": True,
        "request_id": request_id,
        "grant_id": option["grant_id"],
        "grant_duration": duration["last_grant_ttl"],
        "ttl_seconds": ttl_seconds,
        "agent": {
            "publicKey": agent["publicKey"],
            "fingerprint": str(agent_pubkey["fingerprint"]),
        },
        "agent_pubkey": {
            "public_key": str(agent_pubkey["public_key"]),
            "fingerprint": str(agent_pubkey["fingerprint"]),
        },
        "items": items,
    }


def create_vault_agent_binding(payload: dict) -> dict:
    from storage import vault_crypto, vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    request_id = str(payload.get("request_id") or payload.get("requestId") or "").strip()
    grant_id = str(payload.get("grant_id") or payload.get("grantId") or "").strip()
    raw_name = payload.get("name")
    requested_name = raw_name if isinstance(raw_name, str) else ""
    if "." not in requested_name:
        requested_name = requested_name.strip()
    if not request_id or not grant_id:
        raise VaultApiError("request_id and grant_id are required", code="invalid_request", status=409)
    if not requested_name or not vault_crypto.is_valid_secret_name(requested_name.split(".", 1)[0]):
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
    if "." in requested_name:
        try:
            _vault_validate_field_name(requested_name.split(".", 1)[1], field="field")
        except vault_service.InvalidFieldNameError as exc:
            raise _vault_field_service_error(exc) from exc

    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            option = _grant_option_from_request(conn, request_id)
            if grant_id != option["grant_id"]:
                raise vault_service.InvalidRequestError("grant id does not match the approval request")
            base_name = requested_name.split(".", 1)[0]
            if base_name not in set(option["member_names"]):
                raise vault_service.InvalidRequestError("secret is not part of the approval request")
            grant_duration_value = _grant_duration_value_from_payload(payload)
            remember_duration = grant_duration_value is not None
            duration = vault_service.normalize_grant_duration(
                grant_duration_value,
                default=option.get("default_grant_duration") or vault_service.get_vault_settings(conn)["last_grant_ttl"],
            )
            record_meta = _vault_record_meta(conn, requested_name)
            name = str(record_meta.get("record_name") or requested_name)
            meta = record_meta
            if meta.get("protection") != "protected":
                raise VaultApiError("agent binding is only valid for protected secrets", code="not_protected", status=409)
            key = _load_or_create_vault_daemon_binding_key(conn)
            if remember_duration:
                vault_service.save_vault_settings(conn, {"last_grant_ttl": duration["last_grant_ttl"]})
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(
            f"secret '{requested_name}' not found",
            code="secret_not_found",
            status=404,
        ) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.RequestNotFoundError as exc:
        raise VaultApiError(f"request '{request_id}' not found", code="request_not_found", status=404) from exc
    except vault_service.InvalidRequestError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    except vault_service.InvalidGrantError as exc:
        raise VaultApiError(str(exc), code="invalid_grant") from exc
    except (
        vault_service.InvalidFieldNameError,
        vault_service.FieldNotFoundError,
        vault_service.FieldsNotSupportedError,
        vault_service.FieldsCorruptError,
    ) as exc:
        raise _vault_field_service_error(exc) from exc
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="vault_error") from exc

    try:
        _require_avault_grant_delivery_surface("resident agent grant")
        agent_pubkey = avault_agent_pubkey()
    except AvaultError as exc:
        raise _vault_api_error_from_avault(exc, prefix="avault agent binding failed") from exc

    ttl_seconds = int(duration["ttl_seconds"])
    now = datetime.now(timezone.utc)
    expires_at = now + timedelta(seconds=ttl_seconds)
    expires_at_unix = int(expires_at.timestamp())
    approval_nonce = os.urandom(16)
    approval = {"nonce": _b64(approval_nonce), "expires_at_unix": expires_at_unix}
    agent = {
        "publicKey": {
            "public_key": str(agent_pubkey["public_key"]),
            "fingerprint": str(agent_pubkey["fingerprint"]),
        },
        "fingerprint": str(agent_pubkey["fingerprint"]),
    }
    binding = {
        "challengeId": f"vab_{uuid.uuid4().hex}",
        "requestId": request_id,
        "grantId": grant_id,
        "agent": agent,
        "context": {
            "purpose": "agent-deliver",
            "name": name,
            "grantId": grant_id,
            "ttlSecs": ttl_seconds,
            "approvalNonce": list(approval_nonce),
            "approvalExpiresAtUnix": expires_at_unix,
            "operationHash": _agent_deliver_operation_hash(name, ttl_seconds),
        },
        "expiresAt": _isoformat_z(expires_at),
    }
    signed_binding = _signed_agent_binding(binding, key)
    with engine.begin() as conn:
        vault_service.record_request_agent_binding_approvals(
            conn,
            request_id,
            {
                "grant_id": grant_id,
                "grant_duration": duration["last_grant_ttl"],
                "ttl_seconds": ttl_seconds,
                "agent": agent,
                "issued_at": _isoformat_z(now),
                "expires_at": _isoformat_z(expires_at),
                "items": [{"name": name, "request_id": binding["challengeId"], "approval": approval}],
            },
        )
    return {
        "ok": True,
        "request_id": request_id,
        "grant_id": grant_id,
        "grant_duration": duration["last_grant_ttl"],
        "ttl_seconds": ttl_seconds,
        "agent_pubkey": {
            "public_key": str(agent_pubkey["public_key"]),
            "fingerprint": str(agent_pubkey["fingerprint"]),
        },
        "binding": signed_binding,
        "approval": approval,
    }


def create_vault_reveal_context(
    name: str,
    payload: dict | None = None,
    *,
    user_context: Any = None,
) -> dict:
    from storage import vault_crypto, vault_service

    secret_name = str(name or "").strip()
    if not vault_crypto.is_valid_secret_name(secret_name):
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
    body = payload if isinstance(payload, dict) else {}
    _reject_plaintext_value_fields(body)
    field = body.get("field")
    if field is not None and not isinstance(field, str):
        raise VaultApiError("field must be a string", code="invalid_field_name", status=400)
    field_name = None
    if field is not None:
        try:
            field_name = _vault_validate_field_name(field, field="field")
        except vault_service.InvalidFieldNameError as exc:
            raise VaultApiError(str(exc), code="invalid_field_name", status=400) from exc
    try:
        ttl_seconds = int(body.get("ttl_seconds") or body.get("ttlSecs") or 120)
    except (TypeError, ValueError) as exc:
        raise VaultApiError("ttl_seconds must be an integer", code="invalid_request") from exc
    ttl_seconds = max(1, min(ttl_seconds, 10 * 60))
    engine = _vault_engine()
    context_request_id = f"vrl_{uuid.uuid4().hex}"
    expires_at = datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds)
    try:
        with engine.begin() as conn:
            record_ref = secret_name if field_name is None else f"{secret_name}.{field_name}"
            record_meta = _vault_record_meta(conn, record_ref, user_context=user_context)
            meta = dict(record_meta)
            if meta.get("protection") != "protected":
                raise VaultApiError("reveal context is only valid for protected secrets", code="not_protected", status=409)
            record_name = str(record_meta.get("record_name") or record_ref)
            envelope = vault_service.get_protected_record_envelope(
                conn,
                record_name,
                user_context=user_context,
            )
            key = _load_or_create_vault_daemon_binding_key(conn)
            envelope_payload = _envelope_payload(envelope)
            display_meta = {**meta, "name": record_name}
            context = {
                "v": 2,
                "purpose": "reveal",
                "requestId": context_request_id,
                "display": _operation_context_display(
                    {
                        "card": {
                            "command": body.get("command"),
                            "egress": body.get("egress"),
                            "session_id": body.get("session_label") or body.get("sessionLabel"),
                            "source_selector": body.get("source") if isinstance(body.get("source"), dict) else {},
                        }
                    },
                    [display_meta],
                ),
                "release": {
                    "name": record_name,
                    "envelopeHash": _envelope_hash(envelope_payload),
                },
                "expiresAt": _isoformat_z(expires_at),
            }
            signed_context = _signed_operation_context(context, key)
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{secret_name}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.KeypairNotValueDeliverableError as exc:
        raise VaultApiError(str(exc), code="keypair_not_value_deliverable", status=409) from exc
    except (
        vault_service.InvalidFieldNameError,
        vault_service.FieldNotFoundError,
        vault_service.FieldsNotSupportedError,
    ) as exc:
        raise _vault_field_service_error(exc) from exc
    except vault_service.VaultServiceError as exc:
        raise _vault_field_service_error(exc) from exc
    return {"ok": True, "context": signed_context, "envelope": envelope_payload}


def get_vault_settings() -> dict:
    from storage import vault_service

    engine = _vault_engine()
    with engine.begin() as conn:
        settings = vault_service.get_vault_settings(conn)
    return {"ok": True, "settings": settings, "policy": vault_service.vault_session_policy(settings)}


def save_vault_settings(payload: dict, *, user_context: Any = None) -> dict:
    from storage import vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    allowed = {"unlock_window_seconds", "strict_approvals", "last_grant_ttl"}
    extra = set(payload) - allowed
    if extra:
        raise VaultApiError(f"unsupported vault settings fields: {', '.join(sorted(extra))}", code="invalid_request", status=409)
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            settings = vault_service.save_vault_settings(conn, payload, user_context=user_context)
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.InvalidGrantError as exc:
        raise VaultApiError(str(exc), code="invalid_grant") from exc
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    return {"ok": True, "settings": settings, "policy": vault_service.vault_session_policy(settings)}


def _request_context_expires_at(request_payload: dict[str, Any]) -> str:
    expires_at = _parse_iso_utc(request_payload.get("expires_at"))
    if expires_at is None:
        expires_at = datetime.now(timezone.utc) + timedelta(seconds=30 * 60)
    return _isoformat_z(expires_at)


def _attach_signed_sign_operation_context(
    request_id: str,
    *,
    audience: str | None = None,
) -> dict:
    from storage import vault_service

    response_audience = audience or vault_service.REQUEST_AUDIENCE_AGENT
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            request_payload = vault_service.get_request(conn, request_id, audience=vault_service.REQUEST_AUDIENCE_UI)
            if request_payload.get("request_type") != "sign":
                raise vault_service.InvalidRequestError("operation context can only be attached to sign requests")
            meta = vault_service.get_secret_meta(conn, str(request_payload.get("secret_name") or ""))
            key = _load_or_create_vault_daemon_binding_key(conn)
            context = {
                "v": 2,
                "purpose": "sign",
                "requestId": request_id,
                "display": _operation_context_display(request_payload, [meta]),
                "expiresAt": _request_context_expires_at(request_payload),
            }
            signed = _signed_operation_context(context, key)
            return vault_service.set_request_operation_context(
                conn,
                request_id,
                signed,
                audience=response_audience,
            )
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{exc}' not found", code="secret_not_found", status=404) from exc
    except vault_service.RequestNotFoundError as exc:
        raise VaultApiError(f"request '{request_id}' not found", code="request_not_found", status=404) from exc
    except vault_service.InvalidRequestError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc


def _sign_request_response_audience(request: dict[str, Any]) -> str:
    from storage import vault_service

    card = request.get("card") if isinstance(request.get("card"), dict) else {}
    if "secret_unlock_material" in card or "unlock_material" in card:
        return vault_service.REQUEST_AUDIENCE_UI
    return vault_service.REQUEST_AUDIENCE_AGENT


def _vault_webauthn_context(origin: str | None):
    from storage import vault_webauthn

    try:
        return vault_webauthn.rp_context_from_origin(origin or "")
    except vault_webauthn.WebAuthnVerificationError as exc:
        raise VaultApiError(str(exc), code="webauthn_origin_unsupported", status=409) from exc


def create_vault_authz_webauthn_options(*, origin: str | None = None) -> dict:
    from storage import vault_service

    context = _vault_webauthn_context(origin)
    engine = _vault_engine()
    with engine.begin() as conn:
        return vault_service.create_webauthn_registration_options(
            conn,
            rp_id=context.rp_id,
            origin=context.origin,
        )


def register_vault_authz_webauthn_factor(payload: dict, *, origin: str | None = None) -> dict:
    from storage import vault_service

    context = _vault_webauthn_context(origin)
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            result = vault_service.register_webauthn_factor(
                conn,
                payload,
                rp_id=context.rp_id,
                origin=context.origin,
            )
    except vault_service.InvalidProtectedAuthzError as exc:
        raise VaultApiError(str(exc), code="invalid_protected_authz", status=409) from exc
    except vault_service.ProtectedAuthRequiredError as exc:
        raise VaultApiError(str(exc), code="protected_auth_required", status=409) from exc
    except vault_service.ProtectedAuthzSetupRequiredError as exc:
        raise VaultApiError(str(exc), code="protected_authz_setup_required", status=409) from exc
    return result


def _reject_plaintext_value_fields(payload: object) -> None:
    if isinstance(payload, dict):
        if "value" in payload:
            raise VaultApiError(
                "vault create does not accept plaintext value fields",
                code="plaintext_value_rejected",
            )
        for item in payload.values():
            _reject_plaintext_value_fields(item)
    elif isinstance(payload, list):
        for item in payload:
            _reject_plaintext_value_fields(item)


_VAULT_METADATA_ALLOWED_FIELDS = {"description", "tags", "policy", "default_field"}
_VAULT_METADATA_SECRET_FIELDS = {
    "value",
    "sealed",
    "envelope",
    "blind_box",
    "ciphertext",
    "nonce",
    "wrap_meta",
    "private_key",
    "secret",
}


def _reject_vault_metadata_secret_fields(payload: object, *, path: str = "payload") -> None:
    if isinstance(payload, dict):
        for key, item in payload.items():
            if str(key) in _VAULT_METADATA_SECRET_FIELDS:
                raise VaultApiError(
                    f"{path}.{key} is not allowed in vault metadata updates",
                    code="secret_material_rejected",
                )
            _reject_vault_metadata_secret_fields(item, path=f"{path}.{key}")
    elif isinstance(payload, list):
        for index, item in enumerate(payload):
            _reject_vault_metadata_secret_fields(item, path=f"{path}[{index}]")


def _sealed_from_payload(payload: dict):
    from storage.vault_crypto import Sealed

    if not isinstance(payload, dict):
        raise VaultApiError("sealed envelope must be an object", code="invalid_envelope")
    try:
        ciphertext = payload["ciphertext"]
        nonce = payload["nonce"]
        wrap_meta = payload["wrap_meta"]
    except KeyError as exc:
        raise VaultApiError("sealed envelope requires ciphertext, nonce, and wrap_meta", code="invalid_envelope") from exc
    if not isinstance(ciphertext, str) or not ciphertext.strip():
        raise VaultApiError("sealed envelope fields must be non-empty strings", code="invalid_envelope")
    if not isinstance(nonce, str) or not nonce.strip():
        raise VaultApiError("sealed envelope fields must be non-empty strings", code="invalid_envelope")
    if isinstance(wrap_meta, dict):
        wrap_meta = json.dumps(wrap_meta)
    if not isinstance(wrap_meta, str) or not wrap_meta.strip():
        raise VaultApiError("sealed envelope fields must be non-empty strings", code="invalid_envelope")
    return Sealed(ciphertext=ciphertext, nonce=nonce, wrap_meta=wrap_meta)


def create_vault_secret(
    payload: dict,
    *,
    origin: str | None = None,
    user_context: Any = None,
) -> dict:
    from storage import vault_crypto, vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    _reject_plaintext_value_fields(payload)
    name = str(payload.get("name") or "").strip()
    if not vault_crypto.is_valid_secret_name(name):
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
    tags = [str(tag) for tag in payload.get("tags", []) if isinstance(tag, str)] if isinstance(payload.get("tags"), list) else []
    policy = payload.get("policy") if isinstance(payload.get("policy"), dict) else None
    public_meta = payload.get("public_meta") if isinstance(payload.get("public_meta"), dict) else None
    links = payload.get("links") if isinstance(payload.get("links"), dict) else None
    authz_factor_registration = payload.get("authz_factor_registration")
    try:
        if links and isinstance(links.get("skills"), list):
            tags.extend(vault_service.skill_tag(str(skill)) for skill in links["skills"] if isinstance(skill, str))
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    protection = str(payload.get("protection") or "standard").strip().lower()
    establishing_vmk = bool(payload.get("establishing_vmk"))
    kind = str(payload.get("kind") or "static").strip().lower()
    signer_kind = payload.get("signer_kind")
    if signer_kind is not None:
        signer_kind = str(signer_kind)
    provision_request_id = str(payload.get("provision_request_id") or "") or None
    if kind == "keypair" and ("fields" in payload or "default_field" in payload or "default_field" in (public_meta or {})):
        raise VaultApiError(
            "keypair secrets do not support fields or default_field",
            code="fields_not_supported",
            status=409,
        )
    if "default_field" in payload:
        try:
            default_field = _vault_validate_field_name(payload.get("default_field"), field="default_field")
        except vault_service.InvalidFieldNameError as exc:
            raise VaultApiError(str(exc), code="invalid_field_name", status=400) from exc
    else:
        default_field = "value"
    field_specs = _vault_create_field_specs(
        payload,
        secret_name=name,
        kind=kind,
        default_field=default_field,
    )
    atomic_protected_establishment = establishing_vmk and protection == "protected"
    try:
        user_context = vault_service.require_secret_create_access(user_context=user_context)
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    engine = _vault_engine()
    try:
        # Establishment defers preflight to create_secret's write-serialized
        # transaction so a same-name loser receives vault_already_initialized.
        if not atomic_protected_establishment:
            with engine.begin() as conn:
                vault_service.preflight_secret_create(
                    conn,
                    name=name,
                    provision_request_id=provision_request_id,
                )
    except vault_service.InvalidSecretNameError as exc:
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name") from exc
    except (
        vault_service.InvalidFieldNameError,
        vault_service.FieldExistsError,
        vault_service.TooManyFieldsError,
        vault_service.FieldsNotSupportedError,
        vault_service.RecordMismatchError,
    ) as exc:
        raise _vault_field_service_error(exc) from exc
    except vault_service.SecretNameCaseConflictError as exc:
        raise VaultApiError(
            f"secret name '{name}' conflicts with existing secret '{exc.existing_name}'",
            code="secret_name_case_conflict",
            status=409,
        ) from exc
    except vault_service.SecretExistsError as exc:
        fulfilled_count = 0
        try:
            with engine.begin() as conn:
                fulfilled_count = vault_service.fulfill_pending_provision_requests_for_secret(conn, name)
        except Exception:
            logger.warning("failed to settle pending provision requests for existing secret %s", name, exc_info=True)
        if fulfilled_count > 0:
            _publish_vaults_updated(scope="secret", secret_name=name, request_status="fulfilled")
        raise VaultApiError(f"secret '{name}' already exists", code="secret_exists", status=409) from exc
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="vault_error") from exc

    if protection == "standard":
        blind_box = payload.get("blind_box")
        if isinstance(blind_box, dict):
            try:
                sealed = avault_seal_blind_box(name, blind_box)
            except AvaultError as exc:
                raise _vault_api_error_from_avault(exc, prefix="avault blind-box seal failed") from exc
        else:
            raise VaultApiError(
                "standard create requires a browser blind_box",
                code="blind_box_required",
            )
    elif protection == "protected":
        # Protected-tier encryption is browser-side. Python stores the opaque envelope
        # and wrap_meta only; no avault open/decrypt happens in this process.
        sealed = _sealed_from_payload(payload.get("sealed") or payload.get("envelope") or payload)
    else:
        raise VaultApiError("invalid protection tier", code="invalid_protection")
    sealed_fields: list[dict[str, Any]] = []
    for spec in field_specs:
        field_name = str(spec["name"])
        record_name = str(spec["record"])
        if protection == "standard":
            try:
                field_sealed = avault_seal_blind_box(record_name, spec["blind_box"])
            except AvaultError as exc:
                raise _vault_api_error_from_avault(exc, prefix="avault blind-box seal failed") from exc
        else:
            field_sealed = _sealed_from_payload(spec["sealed"])
        sealed_fields.append({"name": field_name, "record": record_name, "sealed": field_sealed})
    try:
        with engine.begin() as conn:
            meta = vault_service.create_secret(
                conn,
                name=name,
                sealed=sealed,
                fields=sealed_fields,
                default_field=default_field if kind != "keypair" else None,
                tags=tags or None,
                protection=protection,
                kind=kind,
                signer_kind=signer_kind,
                description=payload.get("description"),
                policy=policy,
                public_meta=public_meta,
                establishing_vmk=establishing_vmk,
                authz_factor_registration=authz_factor_registration if isinstance(authz_factor_registration, dict) else None,
                authz_factor_origin=origin,
                provision_request_id=provision_request_id,
                user_context=user_context,
            )
    except vault_service.InvalidSecretNameError as exc:
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name") from exc
    except (
        vault_service.InvalidFieldNameError,
        vault_service.FieldExistsError,
        vault_service.TooManyFieldsError,
        vault_service.FieldsNotSupportedError,
        vault_service.RecordMismatchError,
    ) as exc:
        raise _vault_field_service_error(exc) from exc
    except vault_service.SecretNameCaseConflictError as exc:
        raise VaultApiError(
            f"secret name '{name}' conflicts with existing secret '{exc.existing_name}'",
            code="secret_name_case_conflict",
            status=409,
        ) from exc
    except vault_service.SecretExistsError as exc:
        fulfilled_count = 0
        try:
            with engine.begin() as conn:
                fulfilled_count = vault_service.fulfill_pending_provision_requests_for_secret(conn, name)
        except Exception:
            logger.warning("failed to settle pending provision requests for existing secret %s", name, exc_info=True)
        if fulfilled_count > 0:
            _publish_vaults_updated(scope="secret", secret_name=name, request_status="fulfilled")
        raise VaultApiError(f"secret '{name}' already exists", code="secret_exists", status=409) from exc
    except vault_service.VaultAlreadyInitializedError as exc:
        raise VaultApiError(str(exc), code="vault_already_initialized", status=409) from exc
    except vault_service.ProtectedAuthzSetupRequiredError as exc:
        raise VaultApiError(str(exc), code="protected_authz_setup_required", status=409) from exc
    except vault_service.InvalidProtectedAuthzError as exc:
        raise VaultApiError(str(exc), code="invalid_protected_authz", status=409) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="vault_error") from exc
    _publish_vaults_updated(
        scope="secret",
        secret_name=meta.get("name") or name,
        request_id=str(payload.get("provision_request_id") or "") or None,
        request_status="fulfilled" if payload.get("provision_request_id") else None,
    )
    return {"ok": True, "secret": meta}


def update_vault_secret(name: str, payload: dict, *, user_context: Any = None) -> dict:
    from storage import vault_crypto, vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    _reject_vault_metadata_secret_fields(payload)
    secret_name = str(name or "").strip()
    if not vault_crypto.is_valid_secret_name(secret_name):
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
    extra_fields = set(payload) - _VAULT_METADATA_ALLOWED_FIELDS
    if extra_fields:
        raise VaultApiError(
            f"unsupported vault metadata fields: {', '.join(sorted(extra_fields))}",
            code="invalid_metadata",
            status=409,
        )
    kwargs = {field: payload[field] for field in _VAULT_METADATA_ALLOWED_FIELDS if field in payload}
    if not kwargs:
        raise VaultApiError("no metadata fields were provided", code="missing_metadata", status=409)
    engine = _vault_engine()
    release_scopes: list[dict[str, str]] = []
    try:
        with engine.begin() as conn:
            meta = vault_service.update_secret_metadata(
                conn,
                secret_name,
                release_scopes=release_scopes,
                user_context=user_context,
                **kwargs,
            )
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{secret_name}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except (
        vault_service.InvalidFieldNameError,
        vault_service.FieldExistsError,
        vault_service.TooManyFieldsError,
        vault_service.FieldsNotSupportedError,
        vault_service.FieldsCorruptError,
        vault_service.SecretConflictError,
    ) as exc:
        raise _vault_field_service_error(exc) from exc
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="invalid_metadata", status=409) from exc
    release_vault_agent_scopes(release_scopes, reason="update_vault_secret")
    _publish_vaults_updated(scope="secret", secret_name=meta.get("name") or secret_name)
    return {"ok": True, "secret": meta}


def update_vault_secret_field(
    name: str,
    field: str,
    payload: dict,
    *,
    user_context: Any = None,
) -> dict:
    from storage import vault_crypto, vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    _reject_plaintext_value_fields(payload)
    secret_name = str(name or "").strip()
    if not vault_crypto.is_valid_secret_name(secret_name):
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
    try:
        field_name = _vault_validate_field_name(field)
    except vault_service.InvalidFieldNameError as exc:
        raise VaultApiError(str(exc), code="invalid_field_name", status=400) from exc
    allowed = {"record", "blind_box", "sealed", "expected_updated_at"}
    extra = set(payload) - allowed
    if extra:
        raise VaultApiError(
            f"unsupported vault field payload fields: {', '.join(sorted(extra))}",
            code="invalid_request",
            status=409,
        )
    if "record" not in payload:
        raise VaultApiError("record is required", code="invalid_request", status=409)
    record = payload["record"]
    if not isinstance(record, str):
        raise VaultApiError("record must be a string", code="record_mismatch", status=409)
    expected_supplied = "expected_updated_at" in payload
    expected_updated_at = payload.get("expected_updated_at")
    if expected_supplied and expected_updated_at is not None and not isinstance(expected_updated_at, str):
        raise VaultApiError("expected_updated_at must be a string", code="invalid_request", status=409)

    engine = _vault_engine()
    try:
        with engine.connect() as conn:
            meta = _vault_secret_management_meta(
                conn,
                secret_name,
                user_context=user_context,
            )
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{secret_name}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultServiceError as exc:
        raise _vault_field_service_error(exc) from exc

    if meta.get("kind") == "keypair":
        raise VaultApiError(
            f"{secret_name} does not support fields",
            code="fields_not_supported",
            status=409,
        )
    default_field = str(meta.get("default_field") or "value")
    record_name = secret_name if field_name == default_field else f"{secret_name}.{field_name}"
    if record != record_name:
        raise VaultApiError(
            f"record does not match field {field_name!r} on {secret_name}",
            code="record_mismatch",
            status=409,
        )
    snapshot_updated_at = meta.get("updated_at")
    if expected_supplied and expected_updated_at != snapshot_updated_at:
        raise VaultApiError(
            f"secret '{secret_name}' changed while the field was being updated",
            code="secret_conflict",
            status=409,
        )

    protection = str(meta.get("protection") or "standard")
    if protection == "standard":
        if "sealed" in payload:
            raise VaultApiError("standard field updates require blind_box", code="invalid_request", status=409)
        blind_box = payload.get("blind_box")
        if not isinstance(blind_box, dict):
            raise VaultApiError("standard field update requires a browser blind_box", code="blind_box_required")
        try:
            sealed = avault_seal_blind_box(record_name, blind_box)
        except AvaultError as exc:
            raise _vault_api_error_from_avault(exc, prefix="avault blind-box seal failed") from exc
    elif protection == "protected":
        if "blind_box" in payload:
            raise VaultApiError("protected field updates require sealed", code="invalid_request", status=409)
        sealed = _sealed_from_payload(payload.get("sealed") or payload)
    else:
        raise VaultApiError("invalid protection tier", code="invalid_protection")

    release_scopes: list[dict[str, str]] = []
    try:
        with engine.begin() as conn:
            meta = vault_service.update_secret_field(
                conn,
                secret_name,
                field_name,
                sealed,
                record=record,
                expected_updated_at=snapshot_updated_at,
                release_scopes=release_scopes,
                user_context=user_context,
            )
    except vault_service.VaultServiceError as exc:
        raise _vault_field_service_error(exc) from exc
    release_vault_agent_scopes(release_scopes, reason="update_vault_secret_field")
    _publish_vaults_updated(scope="secret", secret_name=meta.get("name") or secret_name)
    return {"ok": True, "secret": meta}


def delete_vault_secret_field(
    name: str,
    field: str,
    payload: dict | None = None,
    *,
    user_context: Any = None,
) -> dict:
    from storage import vault_crypto, vault_service

    body = {} if payload is None else payload
    if not isinstance(body, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    _reject_plaintext_value_fields(body)
    if set(body) - {"expected_updated_at"}:
        raise VaultApiError("unsupported field delete payload", code="invalid_request", status=409)
    expected_supplied = "expected_updated_at" in body
    expected_updated_at = body.get("expected_updated_at")
    if expected_supplied and not isinstance(expected_updated_at, str):
        raise VaultApiError("expected_updated_at must be a string", code="invalid_request", status=409)
    secret_name = str(name or "").strip()
    if not vault_crypto.is_valid_secret_name(secret_name):
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
    try:
        field_name = _vault_validate_field_name(field)
    except vault_service.InvalidFieldNameError as exc:
        raise VaultApiError(str(exc), code="invalid_field_name", status=400) from exc
    engine = _vault_engine()
    try:
        with engine.connect() as conn:
            meta = _vault_secret_management_meta(
                conn,
                secret_name,
                user_context=user_context,
            )
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{secret_name}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultServiceError as exc:
        raise _vault_field_service_error(exc) from exc
    if meta.get("kind") == "keypair":
        raise VaultApiError(
            f"{secret_name} does not support fields",
            code="fields_not_supported",
            status=409,
        )
    snapshot_updated_at = meta.get("updated_at")
    if expected_supplied and expected_updated_at != snapshot_updated_at:
        raise _vault_field_service_error(vault_service.SecretConflictError(f"secret '{secret_name}' changed before field removal"))
    release_scopes: list[dict[str, str]] = []
    try:
        with engine.begin() as conn:
            updated = vault_service.remove_secret_field(
                conn,
                secret_name,
                field_name,
                expected_updated_at=expected_updated_at if expected_supplied else snapshot_updated_at,
                release_scopes=release_scopes,
                user_context=user_context,
            )
    except vault_service.VaultServiceError as exc:
        raise _vault_field_service_error(exc) from exc
    release_vault_agent_scopes(release_scopes, reason="delete_vault_secret_field")
    _publish_vaults_updated(scope="secret", secret_name=updated.get("name") or secret_name)
    return {"ok": True, "secret": updated}


def delete_vault_secret(name: str) -> dict:
    from storage import vault_service

    engine = _vault_engine()
    release_scopes: list[dict[str, str]] = []
    try:
        with engine.begin() as conn:
            grant_rows = vault_service.active_grant_rows_for_secret(conn, name)
            vault_service.delete_secret(conn, name)
            release_scopes = vault_service.agent_release_scopes_after_rows(conn, grant_rows)
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{name}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    release_vault_agent_scopes(release_scopes, reason="delete_vault_secret")
    _publish_vaults_updated(scope="secret", secret_name=name)
    return {"ok": True, "removed": True, "name": name}


def get_vault_audit(*, secret_name: Optional[str] = None, limit: int = 100) -> dict:
    from storage import vault_service

    engine = _vault_engine()
    with engine.connect() as conn:
        events = vault_service.list_audit(
            conn,
            secret_name=secret_name,
            limit=limit,
            user_context=resolve_resource_access_context(),
        )
    return {"ok": True, "events": events}


def get_vault_requests(
    *,
    status: Optional[str] = "pending",
    request_type: Optional[str] = None,
    limit: int = 100,
    session: Optional[str] = None,
    user_context: Any = None,
) -> dict:
    from storage import vault_service

    engine = _vault_engine()
    with engine.begin() as conn:
        requests = vault_service.list_requests(conn, status=status, request_type=request_type, limit=limit, session=session)
    return {"ok": True, "requests": requests}


def get_vault_provision_request_by_name(name: str) -> dict:
    from storage import vault_crypto, vault_service

    requested_name = str(name or "").strip()
    if not vault_crypto.is_valid_secret_name(requested_name):
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            request, ambiguous = vault_service.resolve_pending_provision_request_by_name(
                conn,
                requested_name,
                user_context=resolve_resource_access_context(),
            )
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    return {"ok": True, "request": request, "ambiguous": ambiguous}


def get_vault_provision_request(request_id: str) -> dict:
    from storage import vault_service

    requested_id = str(request_id or "").strip()
    if not requested_id:
        raise VaultApiError("request_id is required", code="missing_request_id")
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            request = vault_service.get_pending_provision_request(
                conn,
                requested_id,
                user_context=resolve_resource_access_context(),
            )
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    return {"ok": True, "request": request}


def _vault_request_grant_members_and_purpose(request: dict) -> tuple[list[str], str]:
    card = request.get("card") if isinstance(request.get("card"), dict) else {}
    purpose = str(card.get("purpose") or "run")
    options = card.get("grant_options") if isinstance(card, dict) else None
    if isinstance(options, list) and options and isinstance(options[0], dict):
        option = options[0]
        purpose = str(option.get("purpose") or purpose)
        snapshot = option.get("member_snapshot")
        if isinstance(snapshot, list):
            members = [str(name) for name in snapshot if isinstance(name, str) and name]
            return sorted(set(members)), purpose
    secret_name = str(request.get("secret_name") or "").strip()
    return ([secret_name] if secret_name else []), purpose


def _vault_request_result(conn, request: dict) -> dict | None:
    from storage import vault_service

    request_type = request.get("request_type")
    if request.get("status") != "approved":
        return None
    if request_type == "access":
        grant = vault_service.get_grant_created_by_request(conn, str(request["id"]))
        if grant is None:
            requester = request.get("requester") if isinstance(request.get("requester"), dict) else {}
            delivery = request.get("delivery") if isinstance(request.get("delivery"), dict) else {}
            session_id = str(requester.get("session_id") or delivery.get("session_id") or "").strip() or None
            secret_name = str(request.get("secret_name") or "").strip()
            member_names, purpose = _vault_request_grant_members_and_purpose(request)
            if secret_name:
                grant = vault_service.find_active_grant_for_secret(
                    conn,
                    secret_name,
                    session_id=session_id,
                    purpose=purpose,
                )
            elif member_names:
                grant = vault_service.find_active_grant_for_secrets(
                    conn,
                    member_names,
                    session_id=session_id,
                    purpose=purpose,
                )
        if grant is None:
            return None
        return {"type": "grant", "grant": grant}
    if request_type == "sign":
        delivery = request.get("delivery") if isinstance(request.get("delivery"), dict) else {}
        signature = delivery.get("signature") if isinstance(delivery, dict) else None
        if isinstance(signature, dict):
            return {"type": "signature", "signature": signature}
    return None


def get_vault_request(
    request_id: str,
    *,
    audience: str | None = None,
    user_context: Any = None,
) -> dict:
    from storage import vault_service

    request_audience = audience or vault_service.REQUEST_AUDIENCE_AGENT
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            request = vault_service.get_request(
                conn,
                request_id,
                audience=request_audience,
                user_context=user_context,
            )
            result = _vault_request_result(conn, request)
    except vault_service.RequestNotFoundError as exc:
        raise VaultApiError(f"request '{request_id}' not found", code="request_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    payload = {"ok": True, "request": request}
    if result is not None:
        payload["result"] = result
    return payload


def _vault_requester_payload(payload: dict) -> dict:
    requester = payload.get("requester") if isinstance(payload.get("requester"), dict) else {}
    session_id = str(payload.get("session_id") or requester.get("session_id") or "").strip()
    out = {"source": "agent-cli"}
    if session_id:
        out["session_id"] = session_id
    if payload.get("run_id"):
        out["run_id"] = str(payload["run_id"])
    if payload.get("skill"):
        out["skill"] = str(payload["skill"])
    if isinstance(requester, dict):
        for key in ("backend", "native_session_id"):
            if requester.get(key):
                out[key] = str(requester[key])
    return out


def _vault_ui_requester_payload(payload: dict) -> dict:
    requester = payload.get("requester") if isinstance(payload.get("requester"), dict) else {}
    session_id = str(payload.get("session_id") or requester.get("session_id") or "").strip()
    out = dict(requester)
    if session_id:
        out["session_id"] = session_id
    if payload.get("run_id"):
        out["run_id"] = str(payload["run_id"])
    if payload.get("skill"):
        out["skill"] = str(payload["skill"])
    return out


def _vault_delivery_payload(payload: dict) -> dict:
    delivery = dict(payload.get("delivery") if isinstance(payload.get("delivery"), dict) else {})
    for key in ("session_id", "skill", "command", "egress", "mode"):
        if payload.get(key) is not None:
            delivery[key] = payload[key]
    return delivery


def _expires_at_from_ttl(payload: dict) -> str | None:
    ttl = payload.get("request_ttl_seconds")
    if ttl is None:
        return None
    try:
        ttl_seconds = int(ttl)
    except (TypeError, ValueError) as exc:
        raise VaultApiError("request_ttl_seconds must be an integer", code="invalid_request") from exc
    if ttl_seconds <= 0:
        raise VaultApiError("request_ttl_seconds must be positive", code="invalid_request")
    return (datetime.now(timezone.utc) + timedelta(seconds=ttl_seconds)).isoformat()


def request_vault_access(payload: dict, *, user_context: Any = None) -> dict:
    from storage import vault_crypto, vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    raw_name = payload.get("name")
    name = raw_name if isinstance(raw_name, str) else ""
    if "." not in name:
        name = name.strip()
    raw_selector = payload.get("source_selector")
    source_selector = dict(raw_selector) if isinstance(raw_selector, dict) else None
    if not name and source_selector is None:
        raise VaultApiError("name or source_selector is required", code="invalid_request", status=409)
    if name and not vault_crypto.is_valid_secret_name(name.split(".", 1)[0]):
        raise VaultApiError("invalid secret reference", code="invalid_name")
    purpose = str(payload.get("purpose") or "run")
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            if name:
                if "." in name:
                    vault_service.validate_field_name(name.split(".", 1)[1])
                vault_service.get_secret_record_meta(conn, name, user_context=user_context)
            request = vault_service.create_access_request(
                conn,
                name or None,
                source_selector=source_selector,
                purpose=purpose,
                requester=_vault_requester_payload(payload),
                delivery=_vault_delivery_payload(payload),
                expires_at=_expires_at_from_ttl(payload),
                audience=vault_service.REQUEST_AUDIENCE_AGENT,
                user_context=user_context,
            )
    except vault_service.SecretNotFoundError as exc:
        missing_name = name or str(exc)
        raise VaultApiError(f"secret '{missing_name}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.NotGrantableError as exc:
        raise VaultApiError(str(exc), code="not_grantable", status=409) from exc
    except vault_service.KeypairNotValueDeliverableError as exc:
        raise VaultApiError(str(exc), code="keypair_not_value_deliverable", status=409) from exc
    except (
        vault_service.FieldNotFoundError,
        vault_service.FieldsCorruptError,
        vault_service.InvalidFieldNameError,
        vault_service.FieldsNotSupportedError,
    ) as exc:
        raise _vault_field_service_error(exc) from exc
    except vault_service.InvalidRequestError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    _publish_vaults_updated(
        scope="request",
        request_id=request.get("id"),
        request_status=request.get("status"),
        secret_name=request.get("secret_name"),
    )
    _notify_vault_request_created(request)
    return {"ok": True, "request": request}


def request_vault_sign(payload: dict, *, user_context: Any = None) -> dict:
    from storage import vault_crypto, vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    name = str(payload.get("name") or "").strip()
    digest = _sign_digest_from_payload(payload.get("digest"))
    scheme = str(payload.get("scheme") or "ecdsa-secp256k1-recoverable").strip()
    if scheme not in vault_service.SUPPORTED_SIGNATURE_SCHEMES:
        raise VaultApiError(f"unsupported signature scheme: {scheme}", code="invalid_request", status=409)
    if not vault_crypto.is_valid_secret_name(name):
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            meta = vault_service.get_secret_meta(conn, name, user_context=user_context)
            if meta.get("kind") != "keypair":
                raise VaultApiError(f"secret '{name}' is not a signing key", code="not_signing_key", status=409)
            if (meta.get("signer_kind") or "local") != "local":
                raise VaultApiError(
                    f"secret '{name}' uses signer_kind '{meta.get('signer_kind')}', which is not locally signable",
                    code="unsupported_signer_kind",
                    status=409,
                )
            signing_context = _verifiable_signing_context_from_payload(
                payload,
                digest=digest,
                required=meta.get("protection") == "protected",
            )
            request = vault_service.create_sign_request(
                conn,
                name,
                digest=digest,
                scheme=scheme,
                signing_context=signing_context,
                requester=_vault_ui_requester_payload(payload),
                delivery=_vault_delivery_payload(payload),
                expires_at=_expires_at_from_ttl(payload),
                user_context=user_context,
            )
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{name}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.InvalidRequestError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="vault_error") from exc
    request = _attach_signed_sign_operation_context(
        str(request["id"]),
        audience=_sign_request_response_audience(request),
    )
    _publish_vaults_updated(
        scope="request",
        request_id=request.get("id"),
        request_status=request.get("status"),
        secret_name=request.get("secret_name"),
    )
    _notify_vault_request_created(request)
    return {"ok": True, "request": request}


def deny_vault_request(request_id: str, payload: dict | None = None) -> dict:
    from storage import vault_service

    body = payload if isinstance(payload, dict) else {}
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            request = vault_service.deny_request(
                conn,
                str(request_id),
                requester=body.get("requester") if isinstance(body.get("requester"), dict) else None,
                reason=str(body.get("reason") or "").strip() or None,
            )
    except vault_service.RequestNotFoundError as exc:
        raise VaultApiError(f"request '{request_id}' not found", code="request_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.InvalidRequestError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    _publish_vaults_updated(
        scope="request",
        request_id=request.get("id") or str(request_id),
        request_status=request.get("status"),
        secret_name=request.get("secret_name"),
    )
    return {"ok": True, "request": request}


def approve_vault_delete_request(request_id: str, *, user_context: Any = None) -> dict:
    from storage import vault_service

    release_scopes: list[dict[str, str]] = []
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            request = vault_service.approve_delete_request(
                conn,
                str(request_id),
                release_scopes=release_scopes,
                user_context=user_context,
            )
    except vault_service.RequestNotFoundError as exc:
        raise VaultApiError(f"request '{request_id}' not found", code="request_not_found", status=404) from exc
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{exc}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.InvalidRequestError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    release_vault_agent_scopes(release_scopes, reason="approve_vault_delete_request")
    _publish_vaults_updated(
        scope="secret",
        request_id=request.get("id") or str(request_id),
        request_status=request.get("status"),
        secret_name=request.get("secret_name"),
    )
    return {"ok": True, "request": request, "removed": True, "name": request.get("secret_name")}


def get_vault_grants(*, status: Optional[str] = "active", session_id: Optional[str] = None) -> dict:
    from storage import vault_service

    engine = _vault_engine()
    with engine.begin() as conn:
        grants = vault_service.list_grants(
            conn,
            status=status,
            session_id=session_id,
            user_context=resolve_resource_access_context(),
        )
    return {"ok": True, "grants": grants}


def _parse_iso_utc(value: object) -> datetime | None:
    if not isinstance(value, str):
        return None
    try:
        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    except ValueError:
        return None
    if parsed.tzinfo is None:
        return parsed.replace(tzinfo=timezone.utc)
    return parsed.astimezone(timezone.utc)


def _remaining_ttl_seconds(expires_at: datetime) -> int:
    remaining = (expires_at - datetime.now(timezone.utc)).total_seconds()
    return max(1, int(round(remaining)))


def _grant_ttl_seconds(grant: dict) -> int:
    expires_at = _parse_iso_utc(grant.get("expires_at"))
    if expires_at is None:
        return 1
    return _remaining_ttl_seconds(expires_at)


def _release_one_shot_agent_grant(grant: dict | None, *, reason: str) -> None:
    if not isinstance(grant, dict) or grant.get("one_shot") is not True:
        return
    release_vault_agent_scopes(_grant_release_payload(grant), reason=reason)


def consume_one_shot_grants(grants: list[dict] | tuple[dict, ...] | None, *, reason: str) -> None:
    """Expire one-shot grants after the caller has committed value delivery."""
    from storage import vault_service

    if not grants:
        return
    seen: set[str] = set()
    release_scopes: list[dict[str, str]] = []
    consumed_grants: list[dict[str, str | None]] = []
    engine = _vault_engine()
    with engine.begin() as conn:
        for grant in grants:
            if not isinstance(grant, dict) or grant.get("one_shot") is not True:
                continue
            grant_id = str(grant.get("id") or "")
            if not grant_id or grant_id in seen:
                continue
            seen.add(grant_id)
            with contextlib.suppress(vault_service.GrantNotActiveError, vault_service.GrantNotFoundError):
                release_scopes.extend(vault_service.consume_one_shot_grant(conn, grant_id))
                consumed_grants.append({"id": grant_id, "request_id": str(grant.get("request_id") or "") or None})
    release_vault_agent_scopes(release_scopes, reason=reason)
    for grant in consumed_grants:
        _publish_vaults_updated(
            scope="grant",
            grant_id=grant["id"],
            grant_status="expired",
            request_id=grant.get("request_id"),
        )


def _agent_grant_cached_all(result: dict, expected_count: int) -> bool:
    granted = result.get("granted")
    try:
        return int(granted) == expected_count
    except (TypeError, ValueError):
        return False


def _restore_access_request_after_failed_agent_grant(
    *,
    engine: Any,
    request_id: str,
    member_names: list[str] | set[str] | tuple[str, ...] | None,
    session_id: str | None,
) -> None:
    from storage import vault_service

    with contextlib.suppress(Exception), engine.begin() as conn:
        vault_service.restore_access_request_after_failed_grant(
            conn,
            request_id=str(request_id),
            member_names=list(member_names or []),
            session_id=session_id,
        )


def _grant_dek_entries_from_payload(payload: dict) -> object:
    deks = payload.get("deks")
    if deks is None:
        deks = payload.get("agent_deks")
    if deks is None and isinstance(payload.get("deks_by_secret"), dict):
        deks = []
        for name, dek in payload["deks_by_secret"].items():
            if isinstance(dek, dict):
                deks.append({"name": name, **dek})
            else:
                deks.append({"name": name, "dek_blindbox": dek, "approval": None})
    return deks


def _validate_resident_agent_dek_blindbox(blindbox: dict[str, Any]) -> dict[str, str]:
    allowed_keys = {"scheme", "enc", "ct"}
    if set(blindbox) != allowed_keys:
        raise VaultApiError("resident agent grant DEKs must contain only opaque blind-box metadata", code="invalid_grant")
    normalized: dict[str, str] = {}
    for key in allowed_keys:
        value = blindbox.get(key)
        if not isinstance(value, str) or not value:
            raise VaultApiError("resident agent grant DEK blind boxes require non-empty scheme, enc, and ct", code="invalid_grant")
        normalized[key] = value
    return normalized


def _validate_resident_agent_dek_approval(approval: dict[str, Any]) -> dict[str, Any]:
    allowed_keys = {"nonce", "expires_at_unix"}
    if set(approval) != allowed_keys:
        raise VaultApiError("resident agent grant DEKs must contain only opaque blind-box metadata", code="invalid_grant")
    nonce = approval.get("nonce")
    expires_at_unix = approval.get("expires_at_unix")
    if not isinstance(nonce, str) or not nonce:
        raise VaultApiError("resident agent grant DEK approvals require a non-empty nonce", code="invalid_grant")
    if type(expires_at_unix) is not int:
        raise VaultApiError("resident agent grant DEK approvals require expires_at_unix", code="invalid_grant")
    return {"nonce": nonce, "expires_at_unix": expires_at_unix}


def _resident_agent_deks_from_payload(payload: dict, *, needs_agent_deks: bool) -> list[dict[str, Any]]:
    deks = _grant_dek_entries_from_payload(payload)
    if deks is None and not needs_agent_deks:
        return []
    if not isinstance(deks, list) or (needs_agent_deks and not deks):
        raise VaultApiError("resident agent grant requires sealed DEKs", code="invalid_grant")
    agent_deks: list[dict[str, Any]] = []
    allowed_keys = {"name", "dek_blindbox", "approval"}
    seen_names: set[str] = set()
    for item in deks:
        if not isinstance(item, dict):
            raise VaultApiError("resident agent grant DEKs must be objects", code="invalid_grant")
        extra_keys = set(item) - allowed_keys
        if extra_keys:
            raise VaultApiError("resident agent grant DEKs must contain only opaque blind-box metadata", code="invalid_grant")
        name = item.get("name")
        dek_blindbox = item.get("dek_blindbox")
        approval = item.get("approval")
        if not isinstance(name, str) or not name or not isinstance(dek_blindbox, dict) or not isinstance(approval, dict):
            raise VaultApiError("resident agent grant DEKs require name, dek_blindbox, and approval", code="invalid_grant")
        if name in seen_names:
            raise VaultApiError("resident agent grant DEKs must contain unique record names", code="invalid_grant")
        seen_names.add(name)
        agent_deks.append(
            {
                "name": name,
                "dek_blindbox": _validate_resident_agent_dek_blindbox(dek_blindbox),
                "approval": _validate_resident_agent_dek_approval(approval),
            }
        )
    return agent_deks


def _agent_binding_record_items(record: dict[str, Any]) -> list[dict[str, Any]]:
    items = record.get("items")
    return items if isinstance(items, list) else []


def _agent_binding_record_matches_agent(record: dict[str, Any], expected_pubkey: dict[str, Any] | None) -> bool:
    if expected_pubkey is None:
        return False
    agent = record.get("agent") if isinstance(record.get("agent"), dict) else {}
    public_key = agent.get("publicKey") if isinstance(agent.get("publicKey"), dict) else {}
    expected_public_key = str(expected_pubkey.get("public_key") or "")
    expected_fingerprint = str(expected_pubkey.get("fingerprint") or "")
    if not expected_public_key and not expected_fingerprint:
        return False
    record_public_key = str(public_key.get("public_key") or "")
    record_fingerprint = str(public_key.get("fingerprint") or agent.get("fingerprint") or "")
    if expected_public_key and record_public_key != expected_public_key:
        return False
    if expected_fingerprint and record_fingerprint != expected_fingerprint:
        return False
    return True


def _request_agent_binding_records(request: dict[str, Any]) -> list[dict[str, Any]]:
    delivery = request.get("delivery") if isinstance(request.get("delivery"), dict) else {}
    records = delivery.get("agent_binding_approvals")
    return [record for record in records if isinstance(record, dict)] if isinstance(records, list) else []


def _validate_agent_binding_approvals(
    request: dict[str, Any],
    *,
    grant_id: str,
    agent_deks: list[dict[str, Any]],
    expected_pubkey: dict[str, Any] | None,
    grant_duration: Any | None,
) -> Any | None:
    from storage import vault_service

    records = _request_agent_binding_records(request)
    if not records:
        raise VaultApiError("resident agent DEKs do not match an issued binding context", code="invalid_grant")
    expected_duration = (
        vault_service.normalize_grant_duration(grant_duration)["last_grant_ttl"] if grant_duration is not None else None
    )
    now = datetime.now(timezone.utc)
    matched_durations: set[Any] = set()
    matched_ttl_seconds: set[int] = set()
    matched_expires_at: list[datetime] = []
    for dek in agent_deks:
        dek_name = str(dek.get("name") or "")
        dek_approval = dek.get("approval")
        matched_record: dict[str, Any] | None = None
        for record in records:
            if str(record.get("grant_id") or "") != grant_id:
                continue
            if not _agent_binding_record_matches_agent(record, expected_pubkey):
                continue
            record_expires_at = _parse_iso_utc(record.get("expires_at"))
            if record_expires_at is None or record_expires_at <= now:
                continue
            duration = record.get("grant_duration")
            if expected_duration is not None and vault_service.normalize_grant_duration(duration)["last_grant_ttl"] != expected_duration:
                continue
            for item in _agent_binding_record_items(record):
                if item.get("name") == dek_name and item.get("approval") == dek_approval:
                    matched_record = record
                    break
            if matched_record is not None:
                break
        if matched_record is None:
            raise VaultApiError("resident agent DEKs do not match issued binding contexts", code="invalid_grant")
        normalized_duration = vault_service.normalize_grant_duration(matched_record.get("grant_duration"))
        matched_durations.add(normalized_duration["last_grant_ttl"])
        try:
            issued_ttl_seconds = int(matched_record.get("ttl_seconds", normalized_duration["ttl_seconds"]))
        except (TypeError, ValueError) as exc:
            raise VaultApiError("resident agent DEK binding context has invalid TTL", code="invalid_grant") from exc
        if issued_ttl_seconds < 1:
            raise VaultApiError("resident agent DEK binding context has invalid TTL", code="invalid_grant")
        matched_ttl_seconds.add(issued_ttl_seconds)
        record_expires_at = _parse_iso_utc(matched_record.get("expires_at"))
        if record_expires_at is None:
            raise VaultApiError("resident agent DEK binding context has invalid expiry", code="invalid_grant")
        matched_expires_at.append(record_expires_at)
    if len(matched_durations) != 1:
        raise VaultApiError("resident agent DEK binding contexts disagree on grant duration", code="invalid_grant")
    if len(matched_ttl_seconds) != 1:
        raise VaultApiError("resident agent DEK binding contexts disagree on grant TTL", code="invalid_grant")
    return {
        "grant_duration": next(iter(matched_durations)),
        "ttl_seconds": next(iter(matched_ttl_seconds)),
        "expires_at": _isoformat_z(min(matched_expires_at)),
    }


def _access_request_secret_name(request_id: str) -> str:
    from storage import vault_service

    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            request = vault_service.get_request(conn, request_id, audience=vault_service.REQUEST_AUDIENCE_AGENT)
    except vault_service.RequestNotFoundError as exc:
        raise VaultApiError(f"request '{request_id}' not found", code="request_not_found", status=404) from exc
    if request.get("request_type") != "access":
        raise VaultApiError("access fulfillment must target an access request", code="invalid_request", status=409)
    name = str(request.get("secret_name") or "").strip()
    if not name:
        raise VaultApiError("access request is missing a secret name", code="invalid_request", status=409)
    return name


def _grant_release_payload(grant: dict) -> list[dict[str, str]]:
    grant_id = str(grant.get("id") or grant.get("grant_id") or "")
    if not grant_id:
        return []
    return [{"grant_id": grant_id}]


def _grant_option_from_request(conn, request_id: str) -> dict[str, Any]:
    from storage import vault_service

    request = vault_service.get_request(conn, request_id, audience=vault_service.REQUEST_AUDIENCE_AGENT)
    if request.get("request_type") != "access":
        raise VaultApiError("grant approval must complete an access request", code="invalid_request", status=409)
    card = request.get("card") if isinstance(request.get("card"), dict) else {}
    options = card.get("grant_options") if isinstance(card, dict) else None
    if not isinstance(options, list) or len(options) != 1 or not isinstance(options[0], dict):
        raise VaultApiError("access request is missing a grant option", code="invalid_request", status=409)
    option = options[0]
    grant_id = str(option.get("grant_id") or "").strip()
    if not grant_id:
        raise VaultApiError("access request is missing a grant id", code="invalid_request", status=409)
    members = option.get("member_snapshot")
    if not isinstance(members, list) or not all(isinstance(name, str) and name for name in members):
        raise VaultApiError("access request has an invalid grant member snapshot", code="invalid_request", status=409)
    source_selector = option.get("source_selector")
    if not isinstance(source_selector, dict):
        raise VaultApiError("access request has an invalid source selector", code="invalid_request", status=409)
    purpose = str(option.get("purpose") or "run")
    return {
        "grant_id": grant_id,
        "member_names": list(members),
        "source_selector": source_selector,
        "purpose": purpose,
        "one_shot": bool(option.get("one_shot")),
        "default_grant_duration": option.get("default_grant_duration"),
    }


def _cleanup_failed_agent_grant(
    *,
    engine: Any,
    grant: dict,
    reason: str,
    force_release_on_cleanup_failure: bool = False,
    force_release_scope: bool = False,
) -> None:
    from storage import vault_service

    release_scopes: list[dict[str, str]] = []
    try:
        with engine.begin() as conn:
            grant_rows = [
                dict(row)
                for row in conn.execute(
                    select(vault_service.vault_grants).where(
                        vault_service.vault_grants.c.id == str(grant["id"])
                    )
                ).mappings()
            ]
            with contextlib.suppress(Exception):
                vault_service.expire_grant(conn, str(grant["id"]), reason="grant-expired-agent-relay-failed")
            release_scopes = (
                vault_service.agent_release_scopes_after_rows(conn, grant_rows)
                if grant_rows
                else _grant_release_payload(grant)
            )
            if force_release_scope:
                forced_scopes = _grant_release_payload(grant)
                for scope in forced_scopes:
                    raw_scope_members = grant.get("member_snapshot") or []
                    scope_members = set(raw_scope_members if isinstance(raw_scope_members, list) else [])
                    active_scope_members: set[str] = set()
                    for active in conn.execute(
                        select(vault_service.vault_grants).where(
                            vault_service.vault_grants.c.status.in_(vault_service.ACTIVE_GRANT_STATES),
                            vault_service.vault_grants.c.id == scope["grant_id"],
                        )
                    ).mappings():
                        active_row = dict(active)
                        if vault_service.grant_row_has_resident_agent_ready(active_row):
                            active_members = json.loads(active_row.get("member_snapshot") or "[]")
                            if isinstance(active_members, list):
                                active_scope_members.update(str(member) for member in active_members if isinstance(member, str))
                    if not scope_members.issubset(active_scope_members) and scope not in release_scopes:
                        release_scopes.append(scope)
    except Exception:
        if not force_release_on_cleanup_failure:
            raise
        logger.warning("%s: failed to update grant DB state; releasing resident scope", reason, exc_info=True)
        release_scopes = _grant_release_payload(grant)
    release_vault_agent_scopes(release_scopes, reason=reason)


def create_vault_grant(payload: dict) -> dict:
    from storage import vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    grant_duration = _grant_duration_value_from_payload(payload)
    if grant_duration is not None:
        try:
            vault_service.normalize_grant_duration(grant_duration)
        except vault_service.InvalidGrantError as exc:
            raise VaultApiError(str(exc), code="invalid_grant") from exc
    request_id = payload.get("request_id")
    if not request_id:
        raise VaultApiError("request_id is required to create a grant", code="missing_request_id")
    request_id = str(request_id)
    engine = _vault_engine()
    preflight_error: Exception | None = None
    request_for_grant: dict[str, Any] | None = None
    with engine.begin() as conn:
        try:
            option = _grant_option_from_request(conn, request_id)
            request_for_grant = vault_service.get_request(conn, request_id, audience=vault_service.REQUEST_AUDIENCE_AGENT)
            member_names = payload.get("member_names") if isinstance(payload.get("member_names"), list) else option["member_names"]
            member_names = [str(name) for name in member_names if isinstance(name, str) and name]
            source_selector = payload.get("source_selector") if isinstance(payload.get("source_selector"), dict) else option["source_selector"]
            purpose = str(payload.get("purpose") or option["purpose"])
            grant_id = str(payload.get("grant_id") or "").strip()
            if grant_id and grant_id != option["grant_id"]:
                raise vault_service.InvalidRequestError("grant id does not match the approval request")
            if set(member_names) != set(option["member_names"]):
                raise vault_service.InvalidRequestError("grant members do not match the approval request")
            if source_selector != option["source_selector"]:
                raise vault_service.InvalidRequestError("grant source selector does not match the approval request")
            if purpose != option["purpose"]:
                raise vault_service.InvalidRequestError("grant purpose does not match the approval request")
            grantable_members = vault_service.request_grantable_member_metas(conn, request_id)
        except (
            vault_service.SecretNotFoundError,
            vault_service.VaultSecretAccessError,
            vault_service.RequestNotFoundError,
            vault_service.InvalidRequestError,
            vault_service.InvalidGrantError,
        ) as exc:
            preflight_error = exc
            grantable_members = []
    if isinstance(preflight_error, vault_service.SecretNotFoundError):
        raise VaultApiError(f"secret '{preflight_error}' not found", code="secret_not_found", status=404) from preflight_error
    if isinstance(preflight_error, vault_service.VaultSecretAccessError):
        raise _vault_secret_access_forbidden(preflight_error) from preflight_error
    if isinstance(preflight_error, vault_service.RequestNotFoundError):
        raise VaultApiError(f"request '{preflight_error}' not found", code="request_not_found", status=404) from preflight_error
    if isinstance(preflight_error, vault_service.InvalidRequestError):
        raise VaultApiError(str(preflight_error), code="invalid_request", status=409) from preflight_error
    if isinstance(preflight_error, vault_service.InvalidGrantError):
        raise VaultApiError(str(preflight_error), code="invalid_grant") from preflight_error
    if not grantable_members:
        raise VaultApiError("grant has no grantable static secrets", code="not_grantable", status=409)
    protected_member_names = {str(member["name"]) for member in grantable_members if member.get("protection") == "protected"}
    protected_record_names = {
        record_name
        for member in grantable_members
        if member.get("protection") == "protected"
        for record_name in _vault_secret_record_names(member)
    }
    needs_agent_deks = bool(protected_record_names)
    binding_grant_expires_at: str | None = None
    binding_operation_ttl_seconds: int | None = None

    agent_deks = _resident_agent_deks_from_payload(payload, needs_agent_deks=needs_agent_deks)
    provided_names = {item["name"] for item in agent_deks}
    if needs_agent_deks and provided_names != protected_record_names:
        raise VaultApiError("resident agent DEKs must match the protected grant records", code="invalid_grant")
    expected_member_names = {str(member["name"]) for member in grantable_members} if needs_agent_deks else None
    expected_pubkey = payload.get("agent_pubkey") if isinstance(payload.get("agent_pubkey"), dict) else None
    if needs_agent_deks:
        try:
            _require_avault_grant_delivery_surface("resident agent grant")
            validate_avault_agent_pubkey(expected_pubkey)
        except AvaultError as exc:
            raise _vault_api_error_from_avault(exc, prefix="avault agent grant failed") from exc
        binding = _validate_agent_binding_approvals(
            request_for_grant or {},
            grant_id=option["grant_id"],
            agent_deks=agent_deks,
            expected_pubkey=expected_pubkey,
            grant_duration=grant_duration,
        )
        if grant_duration is None:
            grant_duration = binding["grant_duration"]
        binding_grant_expires_at = binding["expires_at"]
        try:
            binding_requested_ttl_seconds = int(binding["ttl_seconds"])
        except (KeyError, TypeError, ValueError) as exc:
            raise VaultApiError("resident agent DEK binding context has invalid ttl", code="invalid_grant") from exc
        if binding_requested_ttl_seconds < 1:
            raise VaultApiError("resident agent DEK binding context has invalid ttl", code="invalid_grant")
        binding_expires_at = _parse_iso_utc(binding_grant_expires_at)
        if binding_expires_at is None:
            raise VaultApiError("resident agent DEK binding context has invalid expiry", code="invalid_grant")
        if binding_expires_at <= datetime.now(timezone.utc):
            raise VaultApiError("resident agent DEK binding context has expired", code="invalid_grant")
        binding_operation_ttl_seconds = binding_requested_ttl_seconds
    session_id = payload.get("session_id")
    inherit_request_session = payload.get("this_session_only") is not False
    if not inherit_request_session:
        session_id = None
    try:
        with engine.begin() as conn:
            grant = vault_service.create_grant(
                conn,
                member_names=member_names,
                source_selector=source_selector,
                purpose=purpose,
                session_id=str(session_id) if session_id else None,
                grant_duration=grant_duration,
                expires_at=binding_grant_expires_at,
                request_id=request_id,
                inherit_request_session=inherit_request_session,
                expected_member_names=expected_member_names,
                cache_ready=False,
            )
    except vault_service.NotGrantableError as exc:
        raise VaultApiError(str(exc), code="not_grantable", status=409) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{exc}' not found", code="secret_not_found", status=404) from exc
    except vault_service.RequestNotFoundError as exc:
        raise VaultApiError(f"request '{exc}' not found", code="request_not_found", status=404) from exc
    except vault_service.InvalidRequestError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    except vault_service.InvalidGrantError as exc:
        raise VaultApiError(str(exc), code="invalid_grant") from exc
    if not needs_agent_deks:
        _publish_vaults_updated(
            scope="grant",
            request_id=request_id,
            request_status="approved",
            grant_id=grant.get("id"),
            grant_status=grant.get("status"),
        )
        return {"ok": True, "grant": grant}
    agent_relayed = False
    try:
        operation_ttl = (
            binding_operation_ttl_seconds
            if binding_operation_ttl_seconds is not None
            else _grant_ttl_seconds(grant)
        )
        agent_result = avault_agent_grant(
            grant_id=str(grant["id"]),
            purpose=str(grant.get("purpose") or purpose),
            ttl_secs=operation_ttl,
            deks=agent_deks,
            expected_pubkey=expected_pubkey,
        )
        if not _agent_grant_cached_all(agent_result, len(agent_deks)):
            raise AvaultError("avault agent grant cached fewer DEKs than requested")
        agent_relayed = True
        with engine.begin() as conn:
            grant = vault_service.mark_grant_agent_ready(conn, str(grant["id"]), expires_at=str(grant.get("expires_at") or ""))
    except (vault_service.InvalidGrantError, vault_service.GrantNotActiveError) as exc:
        if agent_relayed:
            _cleanup_failed_agent_grant(
                engine=engine,
                grant=grant,
                reason=f"create_vault_grant:{grant['id']}:mark-ready-failed",
                force_release_on_cleanup_failure=True,
                force_release_scope=True,
            )
            _restore_access_request_after_failed_agent_grant(
                engine=engine,
                request_id=str(request_id),
                member_names=expected_member_names,
                session_id=str(grant.get("session_id") or "") or None,
            )
        raise VaultApiError(str(exc), code="invalid_grant") from exc
    except AvaultError as exc:
        _cleanup_failed_agent_grant(
            engine=engine,
            grant=grant,
            reason=f"create_vault_grant:{grant['id']}",
            force_release_on_cleanup_failure=True,
            force_release_scope=True,
        )
        _restore_access_request_after_failed_agent_grant(
            engine=engine,
            request_id=str(request_id),
            member_names=expected_member_names,
            session_id=str(grant.get("session_id") or "") or None,
        )
        raise _vault_api_error_from_avault(exc, prefix="avault agent grant failed") from exc
    except Exception:
        if agent_relayed:
            _cleanup_failed_agent_grant(
                engine=engine,
                grant=grant,
                reason=f"create_vault_grant:{grant['id']}:mark-ready-failed",
                force_release_on_cleanup_failure=True,
                force_release_scope=True,
            )
        raise
    _publish_vaults_updated(
        scope="grant",
        request_id=request_id,
        request_status="approved",
        grant_id=grant.get("id"),
        grant_status=grant.get("status"),
    )
    return {"ok": True, "grant": grant}


def fulfill_vault_access_request(request_id: str, payload: dict | None = None) -> dict:
    """Approve an access request by relaying browser blind-boxed DEKs to avault.

    The submitted DEKs are HPKE blind boxes addressed to the resident avault
    agent. Python validates only metadata and forwards the opaque boxes; it never
    opens a protected DEK or protected plaintext.
    """

    body = dict(payload) if isinstance(payload, dict) else {}
    request_id = str(request_id or "").strip()
    if not request_id:
        raise VaultApiError("request_id is required to fulfill protected access", code="missing_request_id")
    body["request_id"] = request_id
    created = create_vault_grant(body)
    return {
        "ok": True,
        "request_id": request_id,
        "grant": created["grant"],
        "result": {"type": "grant", "grant": created["grant"]},
    }


def _sign_digest_from_payload(value: object) -> str:
    if not isinstance(value, str):
        raise VaultApiError("digest must be a 32-byte hex string", code="invalid_digest")
    digest = value.strip()
    try:
        decoded = bytes.fromhex(digest)
    except ValueError as exc:
        raise VaultApiError("digest must be a 32-byte hex string", code="invalid_digest") from exc
    if len(digest) != 64 or len(decoded) != 32:
        raise VaultApiError("digest must be a 32-byte hex string", code="invalid_digest")
    return digest.lower()


def _verifiable_signing_context_from_payload(payload: dict, *, digest: str, required: bool = False) -> dict[str, Any] | None:
    context = payload.get("signing_context")
    if context is None:
        context = payload.get("signingContext")
    if context is None:
        delivery = payload.get("delivery")
        if isinstance(delivery, dict):
            context = delivery.get("signing_context") if delivery.get("signing_context") is not None else delivery.get("signingContext")
    if context is None:
        if required:
            raise VaultApiError("protected signing requires a verifiable signing_context", code="missing_signing_context", status=409)
        return None
    if not isinstance(context, dict):
        raise VaultApiError("signing_context must be an object", code="invalid_request", status=409)
    kind = context.get("kind")
    if kind not in {"evm-transaction", "eip-712-typed-data", "avault-agent-operation"}:
        raise VaultApiError("unsupported signing_context kind", code="invalid_request", status=409)
    context_digest = context.get("digest")
    if not isinstance(context_digest, str) or context_digest.lower() != digest:
        raise VaultApiError("signing_context digest must match the sign request digest", code="invalid_request", status=409)
    if kind == "evm-transaction":
        if context.get("digestAlgorithm") != "keccak256" or not isinstance(context.get("chainId"), str):
            raise VaultApiError("invalid evm signing_context", code="invalid_request", status=409)
        if "unsignedTransaction" not in context:
            raise VaultApiError("invalid evm signing_context", code="invalid_request", status=409)
    elif kind == "eip-712-typed-data":
        if context.get("digestAlgorithm") != "eip712" or "typedData" not in context:
            raise VaultApiError("invalid EIP-712 signing_context", code="invalid_request", status=409)
    else:
        if context.get("digestAlgorithm") != "avault-operation-hash-v1" or not isinstance(context.get("canonicalPreimage"), str):
            raise VaultApiError("invalid avault operation signing_context", code="invalid_request", status=409)
    return dict(context)


def _protected_sign_invalid(message: str) -> VaultApiError:
    return VaultApiError(message, code="invalid_request", status=409)


def _protected_signing_public_key_bytes(meta: dict) -> bytes:
    signing_key = meta.get("signing_public_key")
    if not isinstance(signing_key, dict):
        raise _protected_sign_invalid("protected signing key is missing signing_public_key")
    if signing_key.get("curve") != "secp256k1":
        raise _protected_sign_invalid("protected signing key must use secp256k1")
    public_key = signing_key.get("public_key")
    if not isinstance(public_key, str) or not public_key:
        raise _protected_sign_invalid("protected signing key is missing a public key")
    try:
        public_key_bytes = bytes.fromhex(public_key)
    except ValueError as exc:
        raise _protected_sign_invalid("protected signing public key must be hex-encoded") from exc
    return public_key_bytes


def _signature_bytes_for_verification(signature: dict[str, Any]) -> bytes:
    raw_signature = signature.get("signature")
    if not isinstance(raw_signature, str) or not raw_signature:
        raise _protected_sign_invalid("signature payload requires a non-empty signature")
    try:
        return bytes.fromhex(raw_signature)
    except ValueError as exc:
        raise _protected_sign_invalid("signature must be hex-encoded bytes") from exc


def _normalized_protected_signature(signature: dict[str, Any]) -> dict[str, Any]:
    allowed_keys = {"signature", "recovery_id"}
    extra_keys = set(signature) - allowed_keys
    if extra_keys:
        raise _protected_sign_invalid(f"signature payload contains unsupported fields: {', '.join(sorted(extra_keys))}")
    normalized = {"signature": signature.get("signature")}
    if signature.get("recovery_id") is not None:
        normalized["recovery_id"] = signature.get("recovery_id")
    return normalized


def _verify_protected_ecdsa_signature(
    *,
    public_key_bytes: bytes,
    digest_bytes: bytes,
    scheme: str,
    signature: dict[str, Any],
) -> None:
    from cryptography.exceptions import InvalidSignature
    from cryptography.hazmat.primitives import hashes
    from cryptography.hazmat.primitives.asymmetric import ec, utils

    sig_bytes = _signature_bytes_for_verification(signature)
    recovery_id = signature.get("recovery_id")
    try:
        public_key = ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256K1(), public_key_bytes)
    except ValueError as exc:
        raise _protected_sign_invalid("protected signing public key is not a valid secp256k1 point") from exc
    if scheme == "ecdsa-secp256k1-recoverable":
        if len(sig_bytes) != 64:
            raise _protected_sign_invalid("recoverable secp256k1 signatures must be 64 bytes")
        if type(recovery_id) is not int or recovery_id not in {0, 1, 2, 3}:
            raise _protected_sign_invalid("recoverable secp256k1 signatures require recovery_id 0..3")
        r = int.from_bytes(sig_bytes[:32], "big")
        s = int.from_bytes(sig_bytes[32:], "big")
        sig_bytes = utils.encode_dss_signature(r, s)
    else:
        if len(sig_bytes) < 8 or sig_bytes[0] != 0x30:
            raise _protected_sign_invalid("DER secp256k1 signatures must be DER-encoded")
        if recovery_id is not None:
            raise _protected_sign_invalid("DER secp256k1 signatures must not include recovery_id")
    try:
        public_key.verify(sig_bytes, digest_bytes, ec.ECDSA(utils.Prehashed(hashes.SHA256())))
    except InvalidSignature as exc:
        raise _protected_sign_invalid("browser signature does not verify against signing_public_key") from exc
    if scheme == "ecdsa-secp256k1-recoverable":
        _verify_recoverable_signature_recovery_id(
            public_key_bytes=public_key_bytes,
            digest_bytes=digest_bytes,
            r=r,
            s=s,
            recovery_id=recovery_id,
        )


_SECP256K1_P = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFC2F
_SECP256K1_N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141
_SECP256K1_G = (
    0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798,
    0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8,
)
_Secp256k1Point = tuple[int, int] | None


def _secp256k1_mod_sqrt(value: int) -> int | None:
    root = pow(value, (_SECP256K1_P + 1) // 4, _SECP256K1_P)
    return root if pow(root, 2, _SECP256K1_P) == value % _SECP256K1_P else None


def _secp256k1_decompress_public_key(public_key_bytes: bytes) -> _Secp256k1Point:
    if len(public_key_bytes) == 33 and public_key_bytes[0] in {2, 3}:
        x = int.from_bytes(public_key_bytes[1:], "big")
        if x >= _SECP256K1_P:
            return None
        y = _secp256k1_mod_sqrt((pow(x, 3, _SECP256K1_P) + 7) % _SECP256K1_P)
        if y is None:
            return None
        if (y % 2) != (public_key_bytes[0] & 1):
            y = _SECP256K1_P - y
        return (x, y)
    if len(public_key_bytes) == 65 and public_key_bytes[0] == 4:
        x = int.from_bytes(public_key_bytes[1:33], "big")
        y = int.from_bytes(public_key_bytes[33:], "big")
        if x >= _SECP256K1_P or y >= _SECP256K1_P or (pow(y, 2, _SECP256K1_P) - pow(x, 3, _SECP256K1_P) - 7) % _SECP256K1_P:
            return None
        return (x, y)
    return None


def _secp256k1_lift_x(x: int) -> _Secp256k1Point:
    if x >= _SECP256K1_P:
        return None
    y_sq = (pow(x, 3, _SECP256K1_P) + 7) % _SECP256K1_P
    y = _secp256k1_mod_sqrt(y_sq)
    if y is None:
        return None
    return (x, y if y % 2 == 0 else _SECP256K1_P - y)


def _secp256k1_add(point_a: _Secp256k1Point, point_b: _Secp256k1Point) -> _Secp256k1Point:
    if point_a is None:
        return point_b
    if point_b is None:
        return point_a
    x1, y1 = point_a
    x2, y2 = point_b
    if x1 == x2 and (y1 + y2) % _SECP256K1_P == 0:
        return None
    if point_a == point_b:
        slope = (3 * x1 * x1 * pow(2 * y1, -1, _SECP256K1_P)) % _SECP256K1_P
    else:
        slope = ((y2 - y1) * pow(x2 - x1, -1, _SECP256K1_P)) % _SECP256K1_P
    x3 = (slope * slope - x1 - x2) % _SECP256K1_P
    y3 = (slope * (x1 - x3) - y1) % _SECP256K1_P
    return (x3, y3)


def _secp256k1_mul(scalar: int, point: _Secp256k1Point) -> _Secp256k1Point:
    result: _Secp256k1Point = None
    addend = point
    while scalar:
        if scalar & 1:
            result = _secp256k1_add(result, addend)
        addend = _secp256k1_add(addend, addend)
        scalar >>= 1
    return result


def _secp256k1_recover_ecdsa_public_key(r: int, s: int, digest_bytes: bytes, recovery_id: int) -> _Secp256k1Point:
    if not (1 <= r < _SECP256K1_N and 1 <= s < _SECP256K1_N):
        return None
    x = r + (recovery_id >> 1) * _SECP256K1_N
    if x >= _SECP256K1_P:
        return None
    y = _secp256k1_mod_sqrt((pow(x, 3, _SECP256K1_P) + 7) % _SECP256K1_P)
    if y is None:
        return None
    if (y % 2) != (recovery_id & 1):
        y = _SECP256K1_P - y
    point_r = (x, y)
    if _secp256k1_mul(_SECP256K1_N, point_r) is not None:
        return None
    z = int.from_bytes(digest_bytes, "big") % _SECP256K1_N
    r_inv = pow(r, -1, _SECP256K1_N)
    return _secp256k1_mul(
        r_inv,
        _secp256k1_add(
            _secp256k1_mul(s, point_r),
            _secp256k1_mul(z, (_SECP256K1_G[0], (-_SECP256K1_G[1]) % _SECP256K1_P)),
        ),
    )


def _verify_recoverable_signature_recovery_id(
    *,
    public_key_bytes: bytes,
    digest_bytes: bytes,
    r: int,
    s: int,
    recovery_id: int,
) -> None:
    expected = _secp256k1_decompress_public_key(public_key_bytes)
    if expected is None:
        raise _protected_sign_invalid("protected signing public key is not a valid secp256k1 point")
    recovered = _secp256k1_recover_ecdsa_public_key(r, s, digest_bytes, recovery_id)
    if recovered != expected:
        raise _protected_sign_invalid("recoverable signature recovery_id does not match signing_public_key")


def _bip340_tagged_hash(tag: str, payload: bytes) -> bytes:
    import hashlib

    tag_hash = hashlib.sha256(tag.encode("utf-8")).digest()
    return hashlib.sha256(tag_hash + tag_hash + payload).digest()


def _xonly_public_key(public_key_bytes: bytes) -> bytes:
    if len(public_key_bytes) == 32:
        x_only = public_key_bytes
    elif len(public_key_bytes) == 33 and public_key_bytes[0] in {2, 3}:
        x_only = public_key_bytes[1:]
    elif len(public_key_bytes) == 65 and public_key_bytes[0] == 4:
        x_only = public_key_bytes[1:33]
        x = int.from_bytes(x_only, "big")
        y = int.from_bytes(public_key_bytes[33:], "big")
        if x >= _SECP256K1_P or y >= _SECP256K1_P or (pow(y, 2, _SECP256K1_P) - pow(x, 3, _SECP256K1_P) - 7) % _SECP256K1_P:
            raise _protected_sign_invalid("protected signing public key is not a valid secp256k1 point")
    else:
        raise _protected_sign_invalid("protected signing public key must be compressed, uncompressed, or x-only secp256k1")
    if _secp256k1_lift_x(int.from_bytes(x_only, "big")) is None:
        raise _protected_sign_invalid("protected signing public key is not a valid secp256k1 point")
    return x_only


def _verify_protected_schnorr_signature(
    *,
    public_key_bytes: bytes,
    digest_bytes: bytes,
    signature: dict[str, Any],
) -> None:
    sig_bytes = _signature_bytes_for_verification(signature)
    if len(sig_bytes) != 64:
        raise _protected_sign_invalid("BIP340 Schnorr signatures must be 64 bytes")
    if signature.get("recovery_id") is not None:
        raise _protected_sign_invalid("BIP340 Schnorr signatures must not include recovery_id")
    public_key_xonly = _xonly_public_key(public_key_bytes)
    r = int.from_bytes(sig_bytes[:32], "big")
    s = int.from_bytes(sig_bytes[32:], "big")
    if r >= _SECP256K1_P or s >= _SECP256K1_N:
        raise _protected_sign_invalid("browser signature does not verify against signing_public_key")
    point_p = _secp256k1_lift_x(int.from_bytes(public_key_xonly, "big"))
    if point_p is None:
        raise _protected_sign_invalid("protected signing public key is not a valid secp256k1 point")
    challenge = int.from_bytes(_bip340_tagged_hash("BIP0340/challenge", sig_bytes[:32] + public_key_xonly + digest_bytes), "big") % _SECP256K1_N
    point_r = _secp256k1_add(
        _secp256k1_mul(s, _SECP256K1_G),
        _secp256k1_mul(challenge, (point_p[0], (-point_p[1]) % _SECP256K1_P)),
    )
    if point_r is None or point_r[1] % 2 != 0 or point_r[0] != r:
        raise _protected_sign_invalid("browser signature does not verify against signing_public_key")


def _verify_protected_browser_signature(meta: dict, *, digest: str, scheme: str, signature: dict[str, Any]) -> None:
    public_key_bytes = _protected_signing_public_key_bytes(meta)
    digest_bytes = bytes.fromhex(digest)
    if scheme in {"ecdsa-secp256k1-recoverable", "ecdsa-secp256k1-der"}:
        _verify_protected_ecdsa_signature(
            public_key_bytes=public_key_bytes,
            digest_bytes=digest_bytes,
            scheme=scheme,
            signature=signature,
        )
        return
    if scheme == "schnorr-secp256k1-bip340":
        _verify_protected_schnorr_signature(public_key_bytes=public_key_bytes, digest_bytes=digest_bytes, signature=signature)
        return
    raise _protected_sign_invalid(f"unsupported signature scheme: {scheme}")


def revoke_vault_grant(grant_id: str) -> dict:
    from storage import vault_service

    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            grant_row = conn.execute(select(vault_service.vault_grants).where(vault_service.vault_grants.c.id == grant_id)).mappings().first()
            grant_rows = [dict(grant_row)] if grant_row is not None else []
            grant = vault_service.revoke_grant(
                conn,
                grant_id,
                user_context=resolve_resource_access_context(),
            )
            release_scopes = vault_service.agent_release_scopes_after_rows(conn, grant_rows)
    except vault_service.GrantNotFoundError as exc:
        raise VaultApiError(f"grant '{grant_id}' not found", code="grant_not_found", status=404) from exc
    except vault_service.GrantNotActiveError as exc:
        raise VaultApiError(f"grant '{grant_id}' is not active", code="grant_not_active", status=409) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    release_vault_agent_scopes(release_scopes, reason=f"revoke_vault_grant:{grant_id}")
    _publish_vaults_updated(
        scope="grant",
        grant_id=grant.get("id") or grant_id,
        grant_status=grant.get("status"),
        request_id=grant.get("request_id"),
    )
    return {"ok": True, "grant": grant}


def vault_sign(payload: dict) -> dict:
    """Sign a digest without returning private key material to Python.

    Standard-tier local keypairs are relayed to ``avault sign``. Protected-tier keypairs
    are browser-signed; the daemon accepts and audits the public signature object only.
    """
    from storage import vault_crypto, vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    name = str(payload.get("name") or "").strip()
    digest = _sign_digest_from_payload(payload.get("digest"))
    scheme = str(payload.get("scheme") or "ecdsa-secp256k1-recoverable").strip()
    if scheme not in vault_service.SUPPORTED_SIGNATURE_SCHEMES:
        raise VaultApiError(f"unsupported signature scheme: {scheme}", code="invalid_request", status=409)
    if not vault_crypto.is_valid_secret_name(name):
        raise VaultApiError("invalid secret name (use ^[A-Za-z_][A-Za-z0-9_]*$)", code="invalid_name")
    engine = _vault_engine()
    protected_response: dict | None = None
    protected_event: dict | None = None
    approval_required_request: dict | None = None
    try:
        with engine.begin() as conn:
            meta = vault_service.get_secret_meta(conn, name)
            if meta.get("kind") != "keypair":
                raise VaultApiError(f"secret '{name}' is not a signing key", code="not_signing_key", status=409)
            signer_kind = meta.get("signer_kind") or "local"
            if signer_kind != "local":
                raise VaultApiError(
                    f"secret '{name}' uses signer_kind '{signer_kind}', which is not locally signable",
                    code="unsupported_signer_kind",
                    status=409,
                )
            if meta.get("protection") == "protected":
                signature = payload.get("signature")
                if not isinstance(signature, dict):
                    signing_context = _verifiable_signing_context_from_payload(payload, digest=digest, required=True)
                    request = vault_service.create_sign_request(
                        conn,
                        name,
                        digest=digest,
                        scheme=scheme,
                        signing_context=signing_context,
                        requester=payload.get("requester") if isinstance(payload.get("requester"), dict) else None,
                        delivery=payload.get("delivery") if isinstance(payload.get("delivery"), dict) else None,
                    )
                    protected_event = {
                        "scope": "request",
                        "request_id": request.get("id"),
                        "request_status": request.get("status"),
                        "secret_name": request.get("secret_name"),
                    }
                    protected_response = {"ok": False, "code": "browser_signature_required", "request": request}
                else:
                    request_id = str(payload.get("request_id") or "")
                    if not request_id:
                        raise VaultApiError("request_id is required to complete protected signing", code="missing_request_id")
                    sign_request = vault_service.validate_sign_request(conn, request_id, name=name, digest=digest, scheme=scheme)
                    delivery = sign_request.get("delivery") if isinstance(sign_request.get("delivery"), dict) else {}
                    if not isinstance(delivery.get("signing_context"), dict):
                        raise VaultApiError(
                            "protected signing request is missing a verifiable signing_context",
                            code="missing_signing_context",
                            status=409,
                        )
                    signature = _normalized_protected_signature(signature)
                    # `meta` is the masked payload (derived addresses only, no raw key); source
                    # the pinned public key from storage for server-side verification.
                    verify_meta = {**meta, "signing_public_key": vault_service.get_signing_public_key(conn, name)}
                    _verify_protected_browser_signature(verify_meta, digest=digest, scheme=scheme, signature=signature)
                    request = vault_service.complete_sign_request(
                        conn,
                        request_id,
                        name=name,
                        digest=digest,
                        scheme=scheme,
                        signature=signature,
                        requester=payload.get("requester") if isinstance(payload.get("requester"), dict) else None,
                        browser_signed=True,
                    )
                    protected_event = {
                        "scope": "request",
                        "request_id": request.get("id") or request_id,
                        "request_status": request.get("status"),
                        "secret_name": request.get("secret_name"),
                    }
                    protected_response = {"ok": True, "signature": signature, "request": request}
            else:
                request_id = str(payload.get("request_id") or "")
                if request_id:
                    vault_service.claim_sign_request(conn, request_id, name=name, digest=digest, scheme=scheme)
                    key_envelope = vault_service.get_key_envelope(conn, name)
                elif vault_service.sign_needs_approval(conn, name):
                    request = vault_service.create_sign_request(
                        conn,
                        name,
                        digest=digest,
                        scheme=scheme,
                        requester=_vault_requester_payload(payload),
                        delivery=_vault_delivery_payload(payload),
                        expires_at=_expires_at_from_ttl(payload),
                    )
                    approval_required_request = request
                    protected_event = {
                        "scope": "request",
                        "request_id": request.get("id"),
                        "request_status": request.get("status"),
                        "secret_name": request.get("secret_name"),
                    }
                    protected_response = {"ok": False, "code": "approval_required", "request": request}
                else:
                    key_envelope = vault_service.get_key_envelope(conn, name)
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{name}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.RequestNotFoundError as exc:
        raise VaultApiError(f"request '{exc}' not found", code="request_not_found", status=404) from exc
    except vault_service.InvalidRequestError as exc:
        raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
    except vault_service.VaultServiceError as exc:
        raise VaultApiError(str(exc), code="vault_error") from exc

    if protected_response is not None and isinstance(protected_response.get("request"), dict):
        request_id_for_context = str(protected_response["request"].get("id") or "")
        if request_id_for_context and protected_response.get("code") in {"browser_signature_required", "approval_required"}:
            request_with_context = _attach_signed_sign_operation_context(
                request_id_for_context,
                audience=_sign_request_response_audience(protected_response["request"]),
            )
            protected_response["request"] = request_with_context
            if approval_required_request is not None and approval_required_request.get("id") == request_id_for_context:
                approval_required_request = request_with_context

    if protected_response is not None:
        if protected_event is not None:
            _publish_vaults_updated(**protected_event)
        if approval_required_request is not None:
            _notify_vault_request_created(approval_required_request)
        return protected_response

    def _settle_claimed_request(settle: Callable[[Any, str], dict]) -> None:
        request_id = str(payload.get("request_id") or "")
        if not request_id:
            return
        with contextlib.suppress(Exception):
            with engine.begin() as conn:
                request = settle(conn, request_id)
            _publish_vaults_updated(
                scope="request",
                request_id=request.get("id") or request_id,
                request_status=request.get("status"),
                secret_name=request.get("secret_name"),
            )

    def _fail_claimed_request(reason: str) -> None:
        _settle_claimed_request(lambda conn, request_id: vault_service.fail_sign_request(conn, request_id, reason=reason))

    try:
        signature = avault_sign(key_envelope, digest, scheme, name=name)
    except AvaultAuthorizationRequiredBeforeHandoffError as exc:
        # Nothing was signed, so the approval stays pending: the user authorizes
        # avault and approves the same request again instead of the Agent re-asking.
        _settle_claimed_request(vault_service.release_sign_request_claim)
        raise _vault_api_error_from_avault(exc, prefix="avault sign failed") from exc
    except AvaultError as exc:
        _fail_claimed_request("avault_failed")
        raise VaultApiError(f"avault sign failed: {exc}", code="avault_failed") from exc
    request_id = str(payload.get("request_id") or "")
    if request_id:
        try:
            with engine.begin() as conn:
                request = vault_service.complete_sign_request(
                    conn,
                    request_id,
                    name=name,
                    digest=digest,
                    scheme=scheme,
                    signature=signature,
                    requester=payload.get("requester") if isinstance(payload.get("requester"), dict) else None,
                )
        except vault_service.RequestNotFoundError as exc:
            raise VaultApiError(f"request '{exc}' not found", code="request_not_found", status=404) from exc
        except vault_service.InvalidRequestError as exc:
            _fail_claimed_request("signature_rejected")
            raise VaultApiError(str(exc), code="invalid_request", status=409) from exc
        _publish_vaults_updated(
            scope="request",
            request_id=request.get("id") or request_id,
            request_status=request.get("status"),
            secret_name=request.get("secret_name"),
        )
        return {"ok": True, "signature": signature, "request": request}
    try:
        with engine.begin() as conn:
            vault_service.record_signing_use(
                conn,
                name,
                requester=payload.get("requester") if isinstance(payload.get("requester"), dict) else None,
                delivery={"scheme": scheme, "digest": digest},
            )
    except Exception as exc:  # noqa: BLE001
        logger.warning("vault_sign: signature produced but usage audit failed for %s: %s", name, exc)
    return {"ok": True, "signature": signature}


def store_vault_pubkey_pin(payload: dict) -> dict:
    """Store value-free pubkey pin/attestation metadata on a vault secret."""
    from storage import vault_service

    if not isinstance(payload, dict):
        raise VaultApiError("payload must be an object", code="invalid_payload")
    name = str(payload.get("name") or "").strip()
    pin = payload.get("pin") if isinstance(payload.get("pin"), dict) else None
    if not name or not pin:
        raise VaultApiError("name and pin are required", code="invalid_pin")
    engine = _vault_engine()
    try:
        with engine.begin() as conn:
            meta = vault_service.store_pubkey_pin(conn, name, pin)
    except vault_service.SecretNotFoundError as exc:
        raise VaultApiError(f"secret '{name}' not found", code="secret_not_found", status=404) from exc
    except vault_service.VaultSecretAccessError as exc:
        raise _vault_secret_access_forbidden(exc) from exc
    except vault_service.SecretConflictError as exc:
        raise _vault_field_service_error(exc) from exc
    _publish_vaults_updated(scope="secret", secret_name=meta.get("name") or name)
    return {"ok": True, "secret": meta}


def import_vibe_agents(payload: dict, *, user_context: Any = None) -> dict:
    if not isinstance(payload, dict):
        raise ValueError("Import payload must be an object")
    candidates = []
    skipped = []
    file_path = payload.get("file")
    source = payload.get("from") or payload.get("from_source")
    name = str(payload.get("name") or "").strip()
    import_all = bool(payload.get("all"))

    if file_path:
        if source:
            raise ValueError("Use either file or from, not both")
        if name or import_all:
            raise ValueError("name and all are only valid with from")
        backend = validate_agent_backend(str(payload.get("backend") or ""))
        path = _validate_direct_agent_import_path(Path(file_path).expanduser())
        candidates.append(_parse_agent_import_file(path, backend=backend))
    else:
        if source not in NATIVE_CLI_BACKENDS:
            raise ValueError("from must be one of: claude, codex, opencode")
        if name and import_all:
            raise ValueError("Use either name or all, not both")
        for path, backend in iter_global_agent_files(str(source)):
            try:
                candidate = _parse_agent_import_file(path, backend=backend)
            except ValueError as exc:
                skipped.append({"source_ref": str(path), "reason": "invalid", "error": str(exc)})
                continue
            if name and candidate.name != name:
                continue
            candidates.append(candidate)
        if name and not candidates:
            return {
                "ok": False,
                "code": "agent_import_source_not_found",
                "message": f"agent '{name}' was not found in {source} global agents",
            }

    store = VibeAgentStore()
    try:
        result = store.import_candidates(
            candidates,
            user_context=resolve_resource_access_context(user_context),
        )
        return {
            "ok": True,
            "imported": [_vibe_agent_payload(agent, brief=True) for agent in result.imported],
            "skipped": skipped + result.skipped,
        }
    finally:
        store.close()


def get_settings(platform: Optional[str] = None, *, user_context: Any = None) -> dict:
    store = SettingsStore.get_instance()
    target_platform = platform or _current_platform()
    if target_platform == "discord":
        _migrate_discord_guild_scope_from_config(store)
    payload = _settings_to_payload(store, platform=target_platform)
    payload["agent_catalog"] = get_vibe_agents(
        include_archived=True,
        user_context=user_context,
    )
    return payload


def save_settings(payload: dict, *, user_context: Any = None) -> dict:
    from vibe.authorization import require_instance_role

    require_instance_role(user_context, "member")
    # Keep unvalidated request candidates out of the process-wide cache.
    with contextlib.closing(SettingsStore()) as store:
        platform = payload.get("platform") or _current_platform()

        if "channels" in payload:
            channels = {}
            for channel_id, channel_payload in (payload.get("channels") or {}).items():
                existing = store.find_channel(channel_id, platform=platform)
                channels[channel_id] = ChannelSettings(
                    enabled=channel_payload.get("enabled", True),
                    show_message_types=scope_settings.normalize_scope_message_types(
                        channel_payload.get("show_message_types"), platform
                    ),
                    custom_cwd=channel_payload.get("custom_cwd"),
                    routing=_parse_routing(scope_settings.normalize_scope_routing(channel_payload.get("routing") or {})),
                    require_mention=channel_payload.get("require_mention"),
                    require_bind=channel_payload.get("require_bind", existing.require_bind if existing else None),
                    _agent_name_at_load=channel_payload.get(
                        "expected_agent_name", _UNSET_AGENT_BINDING
                    ),
                )
            store.set_channels_for_platform(platform, channels)
        if "guilds" in payload or "guild_allowlist" in payload:
            guilds, default_enabled = _guild_scope_update_from_settings_payload(store, platform, payload)
            store.set_guilds_for_platform(platform, guilds, default_enabled=default_enabled)
        store.save(user_context=user_context)
        return _settings_to_payload(store, platform=platform)


def save_thread_settings(payload: dict, *, user_context: Any = None) -> dict:
    """Create or replace one child-thread settings override."""
    from vibe.authorization import require_instance_role

    require_instance_role(user_context, "member")
    # Keep unvalidated request candidates out of the process-wide cache.
    with contextlib.closing(SettingsStore()) as store:
        platform = str(payload.get("platform") or _current_platform())
        channel_id = str(payload.get("channel_id") or "").strip()
        thread_id = str(payload.get("thread_id") or "").strip()
        settings_payload = payload.get("settings")
        if platform != "telegram":
            return {"ok": False, "error": "thread settings currently support Telegram only"}
        if not channel_id or not thread_id or not isinstance(settings_payload, dict):
            return {"ok": False, "error": "channel_id, thread_id, and settings are required"}

        existing = store.find_thread(channel_id, thread_id, platform=platform)
        base = existing
        if base is None:
            base = store.find_channel(channel_id, platform=platform) or ChannelSettings()
        routing_payload = settings_payload.get("routing")
        routing = (
            _parse_routing(scope_settings.normalize_scope_routing(routing_payload))
            if isinstance(routing_payload, dict)
            else base.routing
        )
        require_mention = settings_payload.get("require_mention", base.require_mention)
        if existing is None and require_mention is None:
            platform_config = _stored_platform_config(platform)
            require_mention = bool(getattr(platform_config, "require_mention", True))
        settings = ChannelSettings(
            enabled=bool(settings_payload.get("enabled", base.enabled)),
            show_message_types=scope_settings.normalize_scope_message_types(
                settings_payload.get("show_message_types", base.show_message_types),
                platform,
            ),
            custom_cwd=settings_payload.get("custom_cwd", base.custom_cwd),
            routing=routing,
            require_mention=require_mention,
            require_bind=settings_payload.get("require_bind", base.require_bind),
            _agent_name_at_load=settings_payload.get(
                "expected_agent_name", _UNSET_AGENT_BINDING
            ),
        )
        store.update_thread(channel_id, thread_id, settings, platform=platform, user_context=user_context)
        return {
            "ok": True,
            "channel_id": channel_id,
            "thread_id": thread_id,
            "settings": _scope_settings_payload(settings, platform),
        }


class ScopeSettingsRequestError(ValueError):
    """A scope settings change the API cannot apply as asked."""

    def __init__(self, code: str, message: str, *, status: int = 400) -> None:
        super().__init__(message)
        self.code = code
        self.message = message
        self.status = status


def _scope_patch_value_error(name: str, value: Any) -> Optional[str]:
    if name == "enabled":
        return None if isinstance(value, bool) else "must be a boolean"
    if name in {"require_mention", "require_bind"}:
        return None if value is None or isinstance(value, bool) else "must be a boolean or null"
    if name == "custom_cwd":
        return None if value is None or isinstance(value, str) else "must be a string or null"
    if name == "display_name":
        return None if isinstance(value, str) else "must be a string"
    if name == "show_message_types":
        valid = isinstance(value, list) and all(isinstance(item, str) for item in value)
        return None if valid else "must be a list of strings"
    if name == "routing":
        if not isinstance(value, dict):
            return "must be an object"
        # Retired per-backend aliases are still accepted from older browser tabs.
        unknown = sorted(set(value) - scope_settings.ROUTING_FIELDS - LEGACY_ROUTING_ALIASES)
        if unknown:
            return f"has unknown fields: {', '.join(unknown)}"
        if any(item is not None and not isinstance(item, str) for item in value.values()):
            return "values must be strings or null"
    return None


def patch_scope_settings(payload: dict, *, user_context: Any = None) -> dict:
    """Change only the named fields of one channel, Telegram topic, or bound DM user.

    The request contract of ``core.services.scope_settings.apply_scope_change``,
    which every settings surface writes through. A routing change must name the
    Agent its view of the route was based on (``expected_agent_name``).
    """
    from vibe.authorization import require_instance_role

    require_instance_role(user_context, "member")
    platform = str(payload.get("platform") or _current_platform())
    kind = payload.get("scope")
    native_id = str(payload.get("id") or "").strip()
    thread_id = str(payload.get("thread_id") or "").strip()
    changes = payload.get("changes")
    if kind not in scope_settings.SCOPE_KINDS:
        raise ScopeSettingsRequestError("invalid_scope", "scope must be channel, thread, or user")
    if not native_id or (kind == "thread" and not thread_id):
        raise ScopeSettingsRequestError("invalid_scope", "id (and thread_id for a thread) is required")
    if kind == "thread" and platform != "telegram":
        raise ScopeSettingsRequestError("invalid_scope", "thread settings currently support Telegram only")
    if not isinstance(changes, dict):
        raise ScopeSettingsRequestError("invalid_changes", "changes must be an object")
    unknown = sorted(set(changes) - scope_settings.SCOPE_FIELDS[kind])
    if unknown:
        raise ScopeSettingsRequestError("invalid_changes", f"unknown {kind} fields: {', '.join(unknown)}")
    for name, value in changes.items():
        problem = _scope_patch_value_error(name, value)
        if problem:
            raise ScopeSettingsRequestError("invalid_changes", f"{name} {problem}")
    expected_agent_name = payload.get("expected_agent_name", scope_settings.MISSING)
    if "routing" in changes and (
        expected_agent_name is scope_settings.MISSING
        or (expected_agent_name is not None and not isinstance(expected_agent_name, str))
    ):
        raise ScopeSettingsRequestError(
            "invalid_changes", "a routing change requires expected_agent_name (a string or null)"
        )

    # A new topic override keeps the mention gate it showed while inheriting.
    new_topic_require_mention = None
    if kind == "thread":
        platform_config = _stored_platform_config(platform)
        new_topic_require_mention = bool(getattr(platform_config, "require_mention", True))
    # Keep unvalidated request candidates out of the process-wide cache.
    with contextlib.closing(SettingsStore()) as store:
        try:
            saved = scope_settings.apply_scope_change(
                store,
                platform=platform,
                kind=kind,
                native_id=native_id,
                thread_id=thread_id,
                changes=changes,
                expected_agent_name=expected_agent_name,
                new_topic_require_mention=new_topic_require_mention,
                user_context=user_context,
            )
        except scope_settings.ScopeNotFoundError as exc:
            raise ScopeSettingsRequestError("user_not_found", "User not found", status=404) from exc
        if kind == "user":
            settings_payload = _user_settings_payload(saved, platform)
        else:
            settings_payload = _scope_settings_payload(saved, platform)
    result = {"ok": True, "platform": platform, "scope": kind, "id": native_id, "settings": settings_payload}
    if kind == "thread":
        result["thread_id"] = thread_id
    return result


def delete_thread_settings(platform: str, channel_id: str, thread_id: str, *, user_context: Any = None) -> dict:
    """Remove one child-thread override so it inherits its parent channel again."""
    from vibe.authorization import require_instance_role

    require_instance_role(user_context, "member")
    platform = str(platform or "").strip()
    channel_id = str(channel_id or "").strip()
    thread_id = str(thread_id or "").strip()
    if platform != "telegram":
        return {"ok": False, "error": "thread settings currently support Telegram only"}
    if not channel_id or not thread_id:
        return {"ok": False, "error": "channel_id and thread_id are required"}
    # Keep unvalidated request candidates out of the process-wide cache.
    with contextlib.closing(SettingsStore()) as store:
        removed = store.delete_thread(channel_id, thread_id, platform=platform, user_context=user_context)
        return {"ok": True, "removed": removed, "channel_id": channel_id, "thread_id": thread_id}


def _guild_scope_update_from_settings_payload(
    store: SettingsStore,
    platform: str,
    payload: dict,
) -> tuple[dict[str, GuildSettings], bool]:
    next_guilds = _guild_settings_from_payload(payload)
    if "guild_default_enabled" in payload:
        return next_guilds, bool(payload.get("guild_default_enabled", False))

    default_enabled = store.get_guild_default_enabled_for_platform(platform)
    if default_enabled:
        for guild_id, settings in store.get_guilds_for_platform(platform).items():
            if not settings.enabled and guild_id not in next_guilds:
                next_guilds[guild_id] = settings
    return next_guilds, default_enabled


def _guild_settings_from_payload(payload: dict) -> dict[str, GuildSettings]:
    if "guilds" in payload:
        guild_payload = payload.get("guilds") or {}
        if not isinstance(guild_payload, dict):
            return {}
        return {
            str(guild_id): GuildSettings(enabled=(settings or {}).get("enabled", True))
            for guild_id, settings in guild_payload.items()
            if isinstance(settings, dict)
        }

    allowlist = payload.get("guild_allowlist") or []
    if not isinstance(allowlist, list):
        return {}
    return {str(guild_id): GuildSettings(enabled=True) for guild_id in allowlist if str(guild_id)}


def _migrate_discord_guild_scope_from_config(store: SettingsStore, config: Optional[V2Config] = None) -> None:
    if store.has_guild_scope_for_platform("discord"):
        return
    try:
        cfg = config or load_config()
    except FileNotFoundError:
        return
    discord_config = getattr(cfg, "discord", None)
    if not discord_config:
        return
    allowlist = getattr(discord_config, "guild_allowlist", None) or []
    denylist = getattr(discord_config, "guild_denylist", None) or []
    if not allowlist and not denylist:
        return
    _save_discord_guild_scope_update(*_discord_guild_scope_from_legacy_payload(allowlist, denylist), store=store)


def _discord_guild_scope_from_legacy_payload(
    allowlist: list | None,
    denylist: list | None,
) -> tuple[dict[str, GuildSettings], bool]:
    default_enabled = not bool(allowlist)
    guilds = {
        str(guild_id): GuildSettings(enabled=True)
        for guild_id in (allowlist or [])
        if str(guild_id)
    }
    for guild_id in denylist or []:
        guilds[str(guild_id)] = GuildSettings(enabled=False)
    return guilds, default_enabled


def _discord_guild_scope_from_config(config: V2Config) -> Optional[tuple[dict[str, GuildSettings], bool]]:
    discord_config = getattr(config, "discord", None)
    if not discord_config:
        return None
    allowlist = getattr(discord_config, "guild_allowlist", None) or []
    denylist = getattr(discord_config, "guild_denylist", None) or []
    if not allowlist and not denylist:
        return None
    return _discord_guild_scope_from_legacy_payload(allowlist, denylist)


def _save_discord_guild_scope_update(
    guilds: dict[str, GuildSettings],
    default_enabled: bool,
    store: Optional[SettingsStore] = None,
    *,
    user_context: Any = None,
) -> None:
    # Config writes and legacy migrations need the same private candidate as
    # channel/DM writes; another Owner request must never commit this draft.
    with contextlib.closing(SettingsStore(store.settings_path if store else None)) as candidate:
        candidate.set_guilds_for_platform("discord", guilds, default_enabled=default_enabled)
        candidate.save(user_context=user_context)
    if store is not None:
        store.maybe_reload()


def _extract_settings_scopes_from_config_payload(
    payload: dict,
) -> tuple[dict, Optional[tuple[dict[str, GuildSettings], bool]]]:
    """Move legacy Discord server access fields from config updates to settings."""
    if not isinstance(payload, dict):
        return payload, None
    next_payload = dict(payload)
    discord_payload = next_payload.get("discord")
    if not isinstance(discord_payload, dict):
        return next_payload, None

    discord_next = dict(discord_payload)
    has_guild_scope = "guild_allowlist" in discord_next or "guild_denylist" in discord_next
    allowlist = discord_next.pop("guild_allowlist", None)
    denylist = discord_next.pop("guild_denylist", None)
    next_payload["discord"] = discord_next

    if has_guild_scope:
        return next_payload, _discord_guild_scope_from_legacy_payload(allowlist, denylist)

    return next_payload, None


def init_sessions() -> None:
    store = SessionsStore()
    if store.sessions_path.exists():
        return
    store.save()


def _cli_detection_target(binary: str, backend: str | None) -> tuple[str | None, str | None]:
    if backend is None and binary in NATIVE_CLI_BACKENDS:
        backend = binary
    if backend is not None and not is_native_cli_backend(backend):
        raise ValueError("Unknown native CLI backend")
    # An explicit existing file that lacks execute permission is broken, not
    # missing. Do not let discovery silently test a different installation.
    expanded = Path(binary).expanduser() if binary else None
    explicit = bool(binary) and (os.path.isabs(binary) or os.sep in binary or (os.altsep and os.altsep in binary))
    if explicit and expanded is not None:
        if expanded.is_file():
            return backend, str(expanded.absolute())
        if backend is not None:
            return backend, None
    path = resolve_cli_path(binary)
    if path is None and backend is not None and not explicit:
        # Discovery normally skips non-executable files. If no runnable candidate
        # resolved, retain a present candidate so its failed launch is 'broken'.
        candidates = _ordered_cli_candidates(
            binary,
            include_npm_global=True,
            candidate_paths=_candidate_cli_paths,
        )
        path = next((str(p.absolute()) for p in candidates if p.is_file()), None)
    return backend, path


def detect_cli(binary: str, backend: str | None = None) -> dict:
    """Synchronous CLI/installer entry; HTTP uses detect_cli_async directly."""
    backend, path = _cli_detection_target(binary, backend)
    if path is None:
        return CliHealth(False, None, "missing", reason="not_found").payload()
    if backend is None:
        return CliHealth(True, path, "unknown").payload()
    return probe_cli_sync(backend, path, env=_command_env_for(path)).payload()


async def detect_cli_async(binary: str, backend: str | None = None) -> dict:
    backend, path = await asyncio.to_thread(_cli_detection_target, binary, backend)
    if path is None:
        return CliHealth(False, None, "missing", reason="not_found").payload()
    if backend is None:
        return CliHealth(True, path, "unknown").payload()
    return (await probe_cli(backend, path, env=_command_env_for(path))).payload()


def check_cli_exec(path: str) -> dict:
    if not path:
        return {"ok": False, "error": "path is empty"}
    if not os.path.exists(path):
        return {"ok": False, "error": "path does not exist"}
    if not os.access(path, os.X_OK):
        return {"ok": False, "error": "path is not executable"}
    return {"ok": True}


def _stored_platform_config(platform: str) -> Any | None:
    try:
        config = load_config()
    except FileNotFoundError:
        return None
    return getattr(config, platform, None)


def _stored_platform_secret(platform: str, field: str) -> str:
    platform_config = _stored_platform_config(platform)
    value = getattr(platform_config, field, "") if platform_config else ""
    return value if isinstance(value, str) else ""


def _stored_platform_field(platform: str, field: str, default: str = "") -> str:
    platform_config = _stored_platform_config(platform)
    value = getattr(platform_config, field, default) if platform_config else default
    return value if isinstance(value, str) else default


def slack_auth_test(bot_token: str, proxy_url: str | None = None) -> dict:
    bot_token = bot_token or _stored_platform_secret("slack", "bot_token")
    try:
        from slack_sdk.web import WebClient
        from vibe.proxy import resolve_proxy

        proxy = resolve_proxy(proxy_url)
        client = WebClient(token=bot_token, proxy=proxy)
        response = client.auth_test()
        return {"ok": True, "response": response.data}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


def list_channels(
    bot_token: str,
    browse_all: bool = False,
    force: bool = False,
    include_not_returned: bool = False,
) -> dict:
    from core import chat_discovery

    bot_token = bot_token or _stored_platform_secret("slack", "bot_token")
    return chat_discovery.channels_response(
        "slack",
        bot_token=bot_token,
        browse_all=browse_all,
        require_member=not browse_all,
        force=force,
        include_not_returned=include_not_returned,
    )


def list_channels_live(bot_token: str, browse_all: bool = False) -> dict:
    """List Slack channels.

    When *browse_all* is False (default), only channels the bot has joined are
    returned via ``users_conversations``.  This is very fast and avoids hitting
    Slack rate-limits even in large workspaces.

    When *browse_all* is True, all visible channels in the workspace are
    returned via ``conversations_list``.  Rate-limit retries with exponential
    back-off are applied automatically.
    """
    import time

    from slack_sdk.errors import SlackApiError
    from slack_sdk.web import WebClient

    client = WebClient(token=bot_token)
    channels: list[dict] = []
    cursor = None

    try:
        while True:
            for attempt in range(5):
                try:
                    if browse_all:
                        response = client.conversations_list(
                            types="public_channel,private_channel",
                            exclude_archived=True,
                            limit=200,
                            cursor=cursor,
                        )
                    else:
                        response = client.users_conversations(
                            types="public_channel,private_channel",
                            exclude_archived=True,
                            limit=200,
                            cursor=cursor,
                        )
                    break  # success
                except SlackApiError as e:
                    if e.response.status_code == 429:
                        retry_after = int(e.response.headers.get("Retry-After", 1))
                        wait = max(retry_after, 2**attempt)
                        logger.warning(
                            "Slack rate-limited (429), retrying after %ds (attempt %d/5)",
                            wait,
                            attempt + 1,
                        )
                        time.sleep(wait)
                    else:
                        raise
            else:
                # Exhausted retries
                return {
                    "ok": False,
                    "error": "Slack rate-limit exceeded after 5 retries",
                }

            for channel in response.get("channels", []):
                channels.append(
                    {
                        "id": channel.get("id"),
                        "name": channel.get("name"),
                        "is_private": channel.get("is_private", False),
                        "is_member": channel.get("is_member"),
                    }
                )
            cursor = response.get("response_metadata", {}).get("next_cursor")
            if not cursor:
                break

        return {"ok": True, "channels": channels, "is_member_only": not browse_all}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


def discord_auth_test(bot_token: str, proxy_url: str | None = None) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(discord_auth_test_async(bot_token, proxy_url=proxy_url))


async def discord_auth_test_async(bot_token: str, proxy_url: str | None = None) -> dict:
    bot_token = bot_token or _stored_platform_secret("discord", "bot_token")
    try:
        data = await _discord_api_get_async(bot_token, "users/@me", proxy_url=proxy_url)
        return {"ok": True, "response": data}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


def telegram_auth_test(bot_token: str, proxy_url: str | None = None) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(telegram_auth_test_async(bot_token, proxy_url=proxy_url))


async def telegram_auth_test_async(bot_token: str, proxy_url: str | None = None) -> dict:
    bot_token = bot_token or _stored_platform_secret("telegram", "bot_token")
    try:
        from vibe.proxy import resolve_proxy

        proxy = resolve_proxy(proxy_url)
        return {"ok": True, "response": await _telegram_get_me(bot_token, proxy)}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


def delete_channel_scope(
    platform: str, native_id: str, scope_type: str = "channel", *, user_context: Any = None,
) -> dict:
    """Permanently remove a discovered channel/chat scope and its settings.

    Restricted to ``channel`` scopes: this endpoint exists only to clear stale
    discovered chats. Deleting other scope types (e.g. ``project``) would bypass
    their dedicated lifecycle (project archival preserves the scope for sessions),
    so any non-channel scope type is rejected.
    """
    from core import chat_discovery
    from vibe.authorization import InstanceAuthorizationError

    platform = str(platform or "").strip()
    native_id = str(native_id or "").strip()
    scope_type = str(scope_type or "channel").strip()
    if not platform or not native_id:
        return {"ok": False, "error": "platform and id are required"}
    if scope_type != "channel":
        return {"ok": False, "error": "only channel scopes can be removed here"}
    try:
        outcome = chat_discovery.delete_scope(platform, native_id, scope_type="channel", user_context=user_context)
    except InstanceAuthorizationError:
        raise
    except Exception as exc:
        logger.warning("Failed to delete %s scope %s: %s", platform, native_id, exc, exc_info=True)
        return {"ok": False, "error": str(exc)}
    # ``dismissed`` means history was preserved and the entry was hidden instead
    # of physically deleted; ``removed`` means the scope row was deleted outright.
    return {"ok": True, **outcome}


def telegram_list_chats(include_private: bool = False, include_not_returned: bool = False) -> dict:
    from core import chat_discovery

    result = chat_discovery.channels_response(
        "telegram",
        include_private=include_private,
        include_not_returned=include_not_returned,
    )
    for channel in result.get("channels") or []:
        supports_topics = bool(channel.get("supports_topics") or channel.get("supports_threads"))
        channel["supports_topics"] = supports_topics
        if supports_topics:
            channel["topics"] = chat_discovery.list_thread_payloads("telegram", str(channel.get("id") or ""))
    result["chats"] = result.get("channels") or []
    return result


def discord_list_guilds(bot_token: str) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(discord_list_guilds_async(bot_token))


async def discord_list_guilds_async(bot_token: str) -> dict:
    bot_token = bot_token or _stored_platform_secret("discord", "bot_token")
    try:
        data = await _discord_api_get_async(bot_token, "users/@me/guilds")
        return {"ok": True, "guilds": data}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


def discord_list_channels(
    bot_token: str, guild_id: str, force: bool = False, include_not_returned: bool = False
) -> dict:
    guild_id = str(guild_id or "").strip()
    if not guild_id:
        return {
            "ok": False,
            "channels": [],
            "chats": [],
            "refreshing": False,
            "last_attempt_at": None,
            "last_success_at": None,
            "error": "Discord guild_id is required",
            "summary": {"discovered_count": 0, "visible_count": 0, "hidden_private_count": 0, "forum_count": 0},
        }

    from core import chat_discovery

    from storage.settings_service import make_scope_id

    bot_token = bot_token or _stored_platform_secret("discord", "bot_token")
    parent_scope_id = make_scope_id("discord", "guild", guild_id)
    return chat_discovery.channels_response(
        "discord",
        bot_token=bot_token,
        guild_id=guild_id,
        parent_scope_id=parent_scope_id,
        force=force,
        include_not_returned=include_not_returned,
    )


def discord_list_channels_live(bot_token: str, guild_id: str) -> dict:
    try:
        data = _discord_api_get(bot_token, f"guilds/{guild_id}/channels")
        channels = []
        for channel in data:
            channels.append(
                {
                    "id": channel.get("id"),
                    "name": channel.get("name"),
                    "type": channel.get("type"),
                    "position": channel.get("position"),
                    "parent_id": channel.get("parent_id"),
                }
            )
        return {"ok": True, "channels": channels}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


def opencode_options(cwd: str) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    try:
        return run_coroutine_blocking(opencode_options_async(cwd))
    except Exception as exc:
        logger.warning("OpenCode options fetch failed: %s", exc, exc_info=True)
        return {"ok": False, "error": str(exc)}


def _discord_retry_wait(exc: "urllib.error.HTTPError", attempt: int) -> float:
    retry_after = exc.headers.get("Retry-After") if exc.headers else None
    try:
        return max(float(retry_after), float(2**attempt)) if retry_after else float(2**attempt)
    except (TypeError, ValueError):
        return float(2**attempt)


def _discord_api_get(bot_token: str, path: str, proxy_url: str | None = None) -> dict:
    import urllib.error
    import urllib.request

    from vibe.proxy import is_socks_proxy, resolve_proxy

    if not bot_token:
        raise ValueError("bot_token is required")
    url = f"https://discord.com/api/v10/{path.lstrip('/')}"
    headers = {"Authorization": f"Bot {bot_token}", "User-Agent": "avibe"}

    proxy = resolve_proxy(proxy_url)

    def _request() -> dict:
        if proxy and is_socks_proxy(proxy):
            return _https_json_request_via_socks(proxy, url, headers=headers)
        if proxy:
            opener = urllib.request.build_opener(
                urllib.request.ProxyHandler({"http": proxy, "https": proxy})
            )
        else:
            opener = urllib.request.build_opener()
        req = urllib.request.Request(url, headers=headers)
        with opener.open(req, timeout=10) as resp:
            payload = resp.read().decode("utf-8")
            return json.loads(payload)

    attempts = 5
    for attempt in range(attempts):
        try:
            return _request()
        except urllib.error.HTTPError as http_exc:
            if http_exc.code in (429, 500, 502, 503, 504) and attempt < attempts - 1:
                wait = _discord_retry_wait(http_exc, attempt)
                logger.warning(
                    "Discord rate-limited/transient (%d), retrying after %ss (attempt %d/%d)",
                    http_exc.code,
                    wait,
                    attempt + 1,
                    attempts,
                )
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Discord request exhausted retries")  # pragma: no cover


async def _discord_api_get_async(bot_token: str, path: str, proxy_url: str | None = None) -> dict:
    import urllib.error
    import urllib.request

    from vibe.proxy import is_socks_proxy, resolve_proxy

    if not bot_token:
        raise ValueError("bot_token is required")
    url = f"https://discord.com/api/v10/{path.lstrip('/')}"
    headers = {"Authorization": f"Bot {bot_token}", "User-Agent": "avibe"}

    proxy = resolve_proxy(proxy_url)
    use_socks = bool(proxy and is_socks_proxy(proxy))

    if proxy and not use_socks:
        opener = urllib.request.build_opener(
            urllib.request.ProxyHandler({"http": proxy, "https": proxy})
        )
    else:
        opener = urllib.request.build_opener()

    def _request() -> dict:
        req = urllib.request.Request(url, headers=headers)
        with opener.open(req, timeout=10) as resp:
            payload = resp.read().decode("utf-8")
            return json.loads(payload)

    attempts = 5
    for attempt in range(attempts):
        try:
            if use_socks:
                # urllib has no native SOCKS support; route via aiohttp + aiohttp_socks.
                return await _discord_api_get_via_aiohttp(url, headers, proxy)
            return await asyncio.to_thread(_request)
        except urllib.error.HTTPError as http_exc:
            if http_exc.code in (429, 500, 502, 503, 504) and attempt < attempts - 1:
                wait = _discord_retry_wait(http_exc, attempt)
                logger.warning(
                    "Discord rate-limited/transient (%d), retrying after %ss (attempt %d/%d)",
                    http_exc.code,
                    wait,
                    attempt + 1,
                    attempts,
                )
                await asyncio.sleep(wait)
                continue
            raise
        except Exception as exc:
            # aiohttp (SOCKS path) raises ClientResponseError with a `.status`.
            status = getattr(exc, "status", None)
            if status in (429, 500, 502, 503, 504) and attempt < attempts - 1:
                wait = float(2**attempt)
                logger.warning(
                    "Discord rate-limited/transient (%s) via proxy, retrying after %ss (attempt %d/%d)",
                    status,
                    wait,
                    attempt + 1,
                    attempts,
                )
                await asyncio.sleep(wait)
                continue
            raise
    raise RuntimeError("Discord request exhausted retries")  # pragma: no cover


def _https_json_request_via_socks(
    proxy_url: str,
    url: str,
    *,
    method: str = "GET",
    body: bytes | None = None,
    headers: dict[str, str] | None = None,
    timeout: float = 10,
) -> dict:
    from python_socks.sync import Proxy

    parsed = urllib.parse.urlparse(url)
    if parsed.scheme != "https" or not parsed.hostname:
        raise ValueError("Only HTTPS URLs are supported")
    port = parsed.port or 443
    path = parsed.path or "/"
    if parsed.query:
        path = f"{path}?{parsed.query}"

    sock = Proxy.from_url(proxy_url).connect(parsed.hostname, port, timeout=timeout)
    try:
        tls_sock = ssl.create_default_context().wrap_socket(sock, server_hostname=parsed.hostname)
    except Exception:
        sock.close()
        raise
    conn = HTTPSConnection(parsed.hostname, port, timeout=timeout)
    conn.sock = tls_sock
    try:
        conn.request(method, path, body=body, headers=headers or {})
        resp = conn.getresponse()
        payload = resp.read().decode("utf-8")
        if resp.status < 200 or resp.status >= 300:
            raise urllib.error.HTTPError(url, resp.status, resp.reason, resp.headers, None)
        return json.loads(payload)
    finally:
        conn.close()


async def _discord_api_get_via_aiohttp(url: str, headers: dict, proxy: str) -> dict:
    import aiohttp
    from aiohttp_socks import ProxyConnector

    connector = ProxyConnector.from_url(proxy, rdns=True)
    timeout = aiohttp.ClientTimeout(total=10)
    async with aiohttp.ClientSession(connector=connector, timeout=timeout) as session:
        async with session.get(url, headers=headers) as resp:
            # urllib.urlopen raises HTTPError on non-2xx; mirror that here so
            # callers like discord_auth_test correctly treat 401 as a failure
            # instead of returning Discord's error JSON as a successful payload.
            resp.raise_for_status()
            return await resp.json()


async def _telegram_get_me(bot_token: str, proxy_url: str | None = None) -> dict:
    from modules.im import telegram_api

    result = await telegram_api.get_me(bot_token, proxy_url=proxy_url)
    return result.get("result") or {}


async def opencode_options_async(
    cwd: str,
    *,
    model_hub_models: dict[str, Any] | None = None,
) -> dict:
    # Expand ~ to user home directory
    expanded_cwd = os.path.expanduser(cwd)
    cache_entry = _OPENCODE_OPTIONS_CACHE.get(expanded_cwd, {})
    cache_data = cache_entry.get("data")
    updated_at = cache_entry.get("updated_at", 0.0)
    cache_age = time.monotonic() - updated_at
    model_hub_models_were_supplied = model_hub_models is not None
    projection_key = ""
    cache_projection_matches = False
    cache_mode_matches = cache_entry.get("mode") == "direct"
    model_hub_mode = None
    lease = None
    try:
        from config.v2_compat import to_app_config
        from config.v2_config import is_model_hub_enabled
        from core.handlers.model_hub import load_opencode_public_models
        from modules.agents.opencode import (
            build_reasoning_effort_options,
            project_opencode_model_hub_models,
        )
        from modules.agents.opencode.client_manager import lease_opencode_server
        from modules.agents.opencode.utils import opencode_model_picker_value

        v2_config = V2Config.load()
        if model_hub_models is None:
            model_hub_config = getattr(v2_config, "model_hub", None)
            model_hub_models = (
                load_opencode_public_models(model_hub_config)
                if model_hub_config is not None
                else {}
            )
        projection_key = json.dumps(
            model_hub_models,
            ensure_ascii=True,
            sort_keys=True,
            separators=(",", ":"),
        )
        cache_projection_matches = (
            cache_entry.get("model_hub_projection") == projection_key
        )
        model_hub_agents = getattr(getattr(v2_config, "model_hub", None), "agents", {})
        model_hub_agent = (
            model_hub_agents.get("opencode")
            if isinstance(model_hub_agents, dict)
            else None
        )
        model_hub_mode = (
            getattr(model_hub_agent, "mode", "direct")
            if is_model_hub_enabled()
            else "direct"
        )
        if (
            model_hub_mode != "hub"
            and cache_data
            and cache_age < _OPENCODE_OPTIONS_TTL_SECONDS
            and cache_projection_matches
            and cache_mode_matches
        ):
            return {"ok": True, "data": cache_data, "cached": True}
        config = to_app_config(v2_config)
        if not config.opencode:
            return {"ok": False, "error": "opencode disabled"}
        opencode_config = config.opencode
        timeout_seconds = min(10.0, float(opencode_config.request_timeout_seconds or 10))

        def _build_reasoning_options(
            models: dict,
            builder,
        ) -> dict:
            options: dict = {}
            for provider in models.get("providers", []):
                provider_id = provider.get("id") or provider.get("provider_id") or provider.get("name")
                if not provider_id:
                    continue
                model_items = []
                provider_models = provider.get("models", {})
                if isinstance(provider_models, dict):
                    model_items = list(provider_models.items())
                elif isinstance(provider_models, list):
                    model_items = [
                        (model.get("id"), model)
                        for model in provider_models
                        if isinstance(model, dict) and model.get("id")
                    ]
                for model_id, model_info in model_items:
                    model_key = opencode_model_picker_value(
                        provider_id,
                        model_id,
                        model_info,
                    )
                    options[model_key] = builder(models, model_key)
            return options

        if model_hub_mode == "hub":
            models = {
                "providers": project_opencode_model_hub_models(
                    [],
                    model_hub_models or {},
                ),
                "default": {},
            }
            data = {
                "agents": [],
                "models": models,
                "defaults": {},
                "reasoning_options": _build_reasoning_options(
                    models,
                    build_reasoning_effort_options,
                ),
                "source": "model hub projection (persisted)",
                "live": False,
            }
            return {"ok": True, "data": data}

        # The controller owns every OpenCode process; this process only leases one.
        lease = await asyncio.wait_for(
            lease_opencode_server("model options", ttl_seconds=60.0),
            timeout=timeout_seconds,
        )
        server = lease.server
        agents = await asyncio.wait_for(server.get_available_agents(expanded_cwd), timeout=timeout_seconds)
        model_request = (
            server.get_available_models(expanded_cwd)
            if not model_hub_models_were_supplied
            else server.get_available_models(
                expanded_cwd,
                model_hub_models=model_hub_models,
            )
        )
        models = await asyncio.wait_for(model_request, timeout=timeout_seconds)
        if model_hub_mode != "hub":
            provider_catalog_available = True
            try:
                providers_raw = await asyncio.wait_for(server.get_providers(), timeout=timeout_seconds)
            except Exception as exc:
                logger.debug("OpenCode provider auth filter skipped: provider list failed: %s", exc)
                providers_raw = {}
                provider_catalog_available = False
            try:
                from vibe.opencode_config import read_opencode_provider_auth_entries

                auth_entries = await asyncio.to_thread(
                    read_opencode_provider_auth_entries, logger_instance=logger
                )
            except Exception as exc:
                logger.debug("OpenCode provider auth filter skipped: auth read failed: %s", exc)
                auth_entries = {}
            allowed_provider_ids: set[str] | None = None
            if provider_catalog_available:
                config_api_key_provider_ids = await _read_opencode_config_api_key_provider_ids()
                custom_config_provider_ids = await _read_opencode_custom_provider_ids()
                allowed_provider_ids = _configured_opencode_provider_ids(
                    providers_raw=providers_raw,
                    auth_entries=auth_entries,
                    config_api_key_provider_ids=config_api_key_provider_ids,
                    custom_config_provider_ids=custom_config_provider_ids,
                )
                models = _filter_opencode_models_to_configured_providers(
                    models,
                    providers_raw=providers_raw,
                    auth_entries=auth_entries,
                    config_api_key_provider_ids=config_api_key_provider_ids,
                    custom_config_provider_ids=custom_config_provider_ids,
                )
            user_model_index = await _read_opencode_user_model_index()
            models = _merge_opencode_user_models(
                models,
                user_model_index,
                allowed_provider_ids=allowed_provider_ids,
            )
        defaults = await asyncio.wait_for(server.get_default_config(expanded_cwd), timeout=timeout_seconds)
        reasoning_options = _build_reasoning_options(models, build_reasoning_effort_options)
        data = {
            "agents": agents,
            "models": models,
            "defaults": defaults,
            "reasoning_options": reasoning_options,
            "source": "opencode server (live) + user config overlay",
            "live": True,
        }
        _OPENCODE_OPTIONS_CACHE[expanded_cwd] = {
            "data": data,
            "updated_at": time.monotonic(),
            "model_hub_projection": projection_key,
            "mode": "direct",
        }
        return {"ok": True, "data": data}
    except Exception as exc:
        logger.warning("OpenCode options fetch failed: %s", exc, exc_info=True)
        if (
            model_hub_mode != "hub"
            and cache_data
            and cache_projection_matches
            and cache_mode_matches
        ):
            return {"ok": True, "data": cache_data, "cached": True, "warning": str(exc)}
        return {"ok": False, "error": str(exc)}
    finally:
        if lease is not None:
            await lease.release()


def _current_platform() -> str:
    return load_config().platform


def _scope_settings_payload(settings: ChannelSettings, platform: str) -> dict:
    return {
        "enabled": settings.enabled,
        "show_message_types": scope_settings.normalize_scope_message_types(settings.show_message_types, platform),
        "custom_cwd": settings.custom_cwd,
        "require_mention": settings.require_mention,
        "require_bind": settings.require_bind,
        "routing": routing_to_dict(settings.routing),
        "expected_agent_name": _agent_binding_expectation(settings),
    }


def _user_settings_payload(settings: UserSettings, platform: str) -> dict:
    return {
        "display_name": settings.display_name,
        "is_admin": settings.is_admin,
        "bound_at": settings.bound_at,
        "enabled": settings.enabled,
        "show_message_types": scope_settings.normalize_scope_message_types(settings.show_message_types, platform),
        "custom_cwd": settings.custom_cwd,
        "routing": routing_to_dict(settings.routing),
        "expected_agent_name": _agent_binding_expectation(settings),
    }


def _agent_binding_expectation(settings: ChannelSettings | UserSettings) -> Optional[str]:
    expected_agent_name = settings._agent_name_at_load
    if expected_agent_name is _UNSET_AGENT_BINDING:
        return settings.routing.agent_name
    return expected_agent_name


def _settings_to_payload(store: SettingsStore, platform: str) -> dict:
    payload: dict = {
        "channels": {},
        "threads": {},
        "guilds": {},
        "guild_allowlist": [],
        "guild_scope_configured": False,
        "guild_default_enabled": False,
        "users": {},
        "bind_codes": [],
    }
    for channel_id, settings in store.get_channels_for_platform(platform).items():
        payload["channels"][channel_id] = _scope_settings_payload(settings, platform)
    for channel_id, threads in store.get_threads_for_platform(platform).items():
        payload["threads"][channel_id] = {
            thread_id: _scope_settings_payload(settings, platform)
            for thread_id, settings in threads.items()
        }
    payload["guild_scope_configured"] = store.has_guild_scope_for_platform(platform)
    payload["guild_default_enabled"] = store.get_guild_default_enabled_for_platform(platform)
    for guild_id, settings in store.get_guilds_for_platform(platform).items():
        payload["guilds"][guild_id] = {
            "enabled": settings.enabled,
        }
    payload["guild_allowlist"] = [
        guild_id for guild_id, settings in payload["guilds"].items() if settings.get("enabled")
    ]
    for user_id, u in store.get_users_for_platform(platform).items():
        payload["users"][user_id] = _user_settings_payload(u, platform)
    for bc in store.settings.bind_codes:
        payload["bind_codes"].append(
            {
                "code": bc.code,
                "type": bc.type,
                "created_at": bc.created_at,
                "expires_at": bc.expires_at,
                "is_active": bc.is_active,
                "used_by": bc.used_by,
            }
        )
    return payload


def get_slack_manifest() -> dict:
    """Get Slack App Manifest template for self-host mode.

    Loads manifest from vibe/templates/slack_manifest.json.

    Returns:
        {"ok": True, "manifest": str, "manifest_compact": str} on success
        {"ok": False, "error": str} on failure
    """
    import json
    import importlib.resources

    try:
        manifest = None

        # Try to load from package resources (installed via pip/uv)
        try:
            if hasattr(importlib.resources, "files"):
                package_files = importlib.resources.files("vibe")
                template_path = package_files / "templates" / "slack_manifest.json"
                if hasattr(template_path, "read_text"):
                    manifest = json.loads(template_path.read_text(encoding="utf-8"))
        except (TypeError, FileNotFoundError, AttributeError, json.JSONDecodeError):
            pass

        # Fallback: load from file system (development mode)
        if manifest is None:
            this_dir = Path(__file__).parent
            template_file = this_dir / "templates" / "slack_manifest.json"
            if template_file.exists():
                manifest = json.loads(template_file.read_text(encoding="utf-8"))

        if manifest is None:
            return {"ok": False, "error": "Manifest template file not found"}

        # Pretty JSON for display, compact JSON for URL
        manifest_pretty = json.dumps(manifest, indent=2)
        manifest_compact = json.dumps(manifest, separators=(",", ":"))
        return {
            "ok": True,
            "manifest": manifest_pretty,
            "manifest_compact": manifest_compact,
        }
    except Exception as exc:
        logger.error("Failed to load Slack manifest: %s", exc)
        return {"ok": False, "error": str(exc)}


def _pid_file_points_to_live_process(pid_path: Path) -> bool:
    from vibe import runtime

    if pid_path == paths.get_runtime_pid_path():
        return runtime.service_process_running()
    if pid_path == paths.get_runtime_ui_pid_path():
        return runtime.ui_pid_file_points_to_running_ui(pid_path)
    return False


def _runtime_process_was_running() -> bool:
    return _pid_file_points_to_live_process(paths.get_runtime_pid_path()) or _pid_file_points_to_live_process(
        paths.get_runtime_ui_pid_path()
    )


def get_version_info() -> dict:
    """Get package version, deployed build identity, and available updates.

    Returns:
        {
            "current": str,
            "latest": str | None,
            "has_update": bool,
            "error": str | None,
            "build": {"kind": "package" | "source", ...},
            "managed_by": "desktop" | None
        }

    A desktop-managed Runtime reports the desktop app's last completed check
    (``vibe/desktop_update_status.py``) and never queries PyPI.
    """
    from vibe import __version__

    build = get_build_identity()
    managed_by = "desktop" if is_desktop_managed_runtime() else None
    if managed_by:
        # The desktop app alone decides what this computer can install; relay
        # its last conclusion, never PyPI's.
        status = read_desktop_update_status()
        result = {
            "current": __version__,
            "latest": status["latest"] if status else None,
            "has_update": status["has_update"] if status else False,
            "error": None,
            "remote_install_allowed": (
                status["remote_install_allowed"] if status else False
            ),
            "remote_request": status["remote_request"] if status else None,
        }
    elif build.kind == "source":
        result = {"current": __version__, "latest": None, "has_update": False, "error": None}
    else:
        result = get_latest_version_info(__version__)
    result["build"] = build.as_dict()
    if managed_by:
        result["managed_by"] = managed_by
    return result


def do_upgrade(auto_restart: bool = True) -> dict:
    """Perform upgrade to latest version.

    Args:
        auto_restart: If True, restart vibe after successful upgrade

    Returns:
        {
            "ok": bool,
            "message": str,
            "output": str | None,
            "activation_notice": str | None,
            "restarting": bool,
        }
    """
    if is_desktop_managed_runtime():
        return {
            "ok": False,
            "message": backend_t("desktopRuntime.apiUpgrade", V2Config.load().language),
            "output": None,
            "activation_notice": None,
            "restarting": False,
            "code": "desktop_managed_runtime",
        }

    current_vibe_path = get_running_vibe_path()
    try:
        plan = build_upgrade_plan(
            vibe_path=current_vibe_path,
            target_version=get_version_info().get("latest"),
        )
    except ValueError as exc:
        return {
            "ok": False,
            "message": "Upgrade failed.",
            "output": str(exc),
            "activation_notice": None,
            "restarting": False,
        }
    if plan.preflight_error:
        return {
            "ok": False,
            "message": "Upgrade cannot be activated safely",
            "output": plan.preflight_error,
            "activation_notice": None,
            "restarting": False,
        }
    runtime_was_running = _runtime_process_was_running()

    # Use a stable directory as cwd to avoid "Current directory does not exist"
    # errors.  The vibe service process cwd may be inside the uv tool venv
    # directory, which uv deletes and recreates during upgrade.
    safe_cwd = get_safe_cwd()
    restarting = False
    restart_failed = False
    runtime_output = None
    deferred_activation = False
    deferred_activation_log = None
    deferred_activation_log_error = None
    restart_python = None
    activation_outcome = None
    activation_notice = None
    activation_committed = False
    activation_postcommit_error = None

    try:
        with atomic_upgrade_lock():
            if restart_is_pending():
                return {
                    "ok": False,
                    "message": "Upgrade already has a restart in progress",
                    "output": "Wait for the pending restart to finish before starting another upgrade.",
                    "activation_notice": None,
                    "restarting": False,
                }
            if plan.activation is not None and activation_block_reason(plan.activation) == "superseded":
                return {
                    "ok": False,
                    "message": "Upgrade was superseded by another activation",
                    "output": "The active Avibe generation changed while waiting for the upgrade lock; retry the upgrade.",
                    "activation_notice": None,
                    "restarting": False,
                }
            result = execute_upgrade_plan(
                plan,
                run=subprocess.run,
                capture_output=True,
                text=True,
                # A wheel install copies the complete candidate environment before
                # it can be activated.  The old 120s bound interrupted that copy
                # in-place and left metadata claiming a package tree that no longer
                # existed.  The candidate is isolated now; this is only a bound for
                # a genuinely hung resolver/download.
                timeout=UPGRADE_INSTALL_TIMEOUT_SECONDS,
                cwd=safe_cwd,
            )
            if result.returncode == 0 and plan.activation is not None:
                try:
                    if os.name == "nt" and launcher_is_current_process(plan.activation.launcher):
                        candidate_result = verify_upgrade_candidate(plan.activation)
                        if not candidate_result.ok:
                            raise RuntimeError(candidate_result.detail)
                        deferred_process = defer_upgrade_activation(
                            plan.activation,
                            parent_pid=os.getpid(),
                            restart_required=auto_restart and runtime_was_running,
                            prepare_show_runtime=not should_skip_show_runtime_prepare(),
                        )
                        activation_committed = True
                        deferred_activation = True
                        try:
                            deferred_activation_log = get_deferred_activation_log_path(deferred_process)
                        except Exception as exc:  # noqa: BLE001
                            deferred_activation_log_error = str(exc)
                    else:
                        restart_python = _candidate_python(plan.activation.candidate_launcher)
                        activation_outcome = activate_upgrade_candidate(plan.activation)
                        activation_committed = True
                except Exception as exc:  # noqa: BLE001
                    activation_committed = activation_committed or plan.activation.committed
                    if not activation_committed:
                        discard_atomic_uv_install_generation(plan.activation.candidate_launcher)
                        return {
                            "ok": False,
                            "message": "Upgrade candidate failed integrity verification",
                            "output": str(exc),
                            "activation_notice": None,
                            "restarting": False,
                        }
                    deferred_activation = deferred_activation or (
                        os.name == "nt" and launcher_is_current_process(plan.activation.launcher)
                    )
                    activation_postcommit_error = str(exc)
                    logger.warning("Upgrade activation completed with a post-commit error", exc_info=True)
            elif result.returncode != 0 and plan.activation is not None:
                discard_atomic_uv_install_generation(plan.activation.candidate_launcher)
            if result.returncode == 0 and plan.activation is None and plan.method == "pip":
                integrity = verify_python_environment(sys.executable)
                if not integrity.ok:
                    return {
                        "ok": False,
                        "message": "Upgrade installed an incomplete Python environment",
                        "output": integrity.detail,
                        "activation_notice": None,
                        "restarting": False,
                    }
            if result.returncode == 0 and auto_restart and runtime_was_running and not deferred_activation:
                try:
                    schedule_restart(
                        delay_seconds=2.0,
                        vibe_path=current_vibe_path,
                        trigger="upgrade",
                        prepare_show_runtime=not should_skip_show_runtime_prepare(),
                        **({"python_executable": str(restart_python)} if restart_python else {}),
                    )
                    restarting = True
                except Exception as exc:
                    restart_failed = True
                    runtime_output = f"Restart scheduling failed; run `vibe restart` to use the new version.\n{exc}"
        if result.returncode == 0:
            if deferred_activation_log_error is not None:
                return {
                    "ok": True,
                    "message": "Upgrade successful. Activation will complete after this process exits.",
                    "output": _append_upgrade_output(result.stdout, deferred_activation_log_error),
                    "activation_notice": None,
                    "restarting": auto_restart and runtime_was_running,
                }
            if deferred_activation:
                try:
                    activation_notice = format_deferred_activation_log(
                        deferred_activation_log,
                        _configured_backend_language(),
                    )
                except Exception as exc:  # noqa: BLE001
                    logger.warning("Deferred activation notice could not be formatted", exc_info=True)
                    return {
                        "ok": True,
                        "message": "Upgrade successful. Activation will complete after this process exits.",
                        "output": _append_upgrade_output(result.stdout, str(exc)),
                        "activation_notice": None,
                        "restarting": auto_restart and runtime_was_running,
                    }
                return {
                    "ok": True,
                    "message": "Upgrade successful. Activation will complete after this process exits.",
                    "output": _append_upgrade_output(
                        result.stdout,
                        activation_notice,
                    ),
                    "activation_notice": activation_notice,
                    "restarting": auto_restart and runtime_was_running,
                }
            if not restarting and not restart_failed:
                runtime_output = _prepare_show_runtime_after_upgrade(current_vibe_path, safe_cwd)
            if restarting:
                message = "Upgrade successful. Restarting..."
            elif restart_failed:
                message = "Upgrade successful, but restart scheduling failed. Please restart vibe."
            else:
                message = "Upgrade successful. Please restart vibe."

            output = _append_upgrade_output(result.stdout, runtime_output)
            if activation_postcommit_error:
                output = _append_upgrade_output(
                    output,
                    f"Upgrade activation cleanup reported: {activation_postcommit_error}",
                )
            if activation_outcome is not None:
                try:
                    activation_notice = format_activation_failures(
                        activation_outcome,
                        _configured_backend_language(),
                    )
                except Exception as exc:  # noqa: BLE001
                    logger.warning("Activation notice could not be formatted", exc_info=True)
                    activation_notice = None
                    output = _append_upgrade_output(
                        output,
                        f"Stable launcher activation notice unavailable: {exc}",
                    )
                output = _append_upgrade_output(output, activation_notice)
            return {
                "ok": True,
                "message": message,
                "output": output,
                "activation_notice": activation_notice,
                "restarting": restarting,
            }
        else:
            return {
                "ok": False,
                "message": "Upgrade failed",
                "output": result.stderr or result.stdout,
                "activation_notice": None,
                "restarting": False,
            }
    except subprocess.TimeoutExpired:
        if plan.activation is not None:
            activation_committed = activation_committed or plan.activation.committed
        if plan.activation is not None and not activation_committed:
            discard_atomic_uv_install_generation(plan.activation.candidate_launcher)
        return {
            "ok": False,
            "message": "Upgrade timed out",
            "output": None,
            "activation_notice": None,
            "restarting": False,
        }
    except Exception as e:
        if plan.activation is not None:
            activation_committed = activation_committed or plan.activation.committed
        if plan.activation is not None and not activation_committed:
            discard_atomic_uv_install_generation(plan.activation.candidate_launcher)
        if activation_committed:
            return {
                "ok": True,
                "message": "Upgrade successful.",
                "output": str(e),
                "activation_notice": None,
                "restarting": restarting,
            }
        return {
            "ok": False,
            "message": str(e),
            "output": None,
            "activation_notice": None,
            "restarting": restarting,
        }


def _append_upgrade_output(output: str | None, runtime_output: str | None) -> str | None:
    parts = [part for part in ((output or "").strip(), (runtime_output or "").strip()) if part]
    if not parts:
        return None
    return "\n\n".join(parts)


def _prepare_show_runtime_after_upgrade(vibe_path: str | None, cwd: str) -> str | None:
    if should_skip_show_runtime_prepare():
        return "Show Runtime preparation skipped because VIBE_INSTALL_SKIP_SHOW_RUNTIME is set."
    if not vibe_path:
        return "Show Runtime was not prepared because the vibe executable path was not available."
    try:
        result = subprocess.run(
            [vibe_path, "runtime", "prepare", "--strict"],
            capture_output=True,
            text=True,
            # 600s (not 300s): prepare now refreshes both the Show Runtime AND
            # askill, so budget for two installers nested in this one call.
            timeout=600,
            cwd=cwd,
            check=False,
        )
    except Exception as exc:
        return f"Show Runtime preparation skipped: {exc}"
    output = (result.stdout or result.stderr or "").strip()
    if result.returncode == 0:
        return output or "Show Runtime prepared."
    return "Show Runtime preparation failed; avibe upgrade is still installed." + (f"\n{output}" if output else "")


def _opencode_permission_grants_all(node) -> bool:
    """Recursively decide whether an OpenCode permission node allows every call.

    OpenCode resolves the last matching rule, with ``"*"`` as the wildcard at
    each level and tool entries that are themselves either a string or a nested
    rule object (https://opencode.ai/docs/permissions). A node grants all tool
    calls iff it is the string ``"allow"``, or a dict whose ``"*"`` wildcard
    grants all AND every nested rule grants all — so a single ``"bash": "ask"``
    (or a nested ``ask``/``deny``) keeps it ungranted, while a fully-``allow``
    tree (e.g. ``{"*": "allow", "bash": {"*": "allow"}}``) passes. Conservative:
    a dict without a ``"*"`` can't guarantee otherwise-unmatched keys, so it is
    treated as not-granted — erring toward keeping the write-allow button rather
    than letting a tool call silently stall on a prompt avibe can't answer.
    """
    if node == "allow":
        return True
    if isinstance(node, dict):
        return _opencode_permission_grants_all(node.get("*")) and all(
            _opencode_permission_grants_all(value) for value in node.values()
        )
    return False


def opencode_permission_allowed(probe) -> bool:
    """Whether an OpenCode config probe already grants full tool-call permission.

    Single source of truth for the "Allow tool calls" state. Without a config
    that allows every call the OpenCode daemon prompts on tool calls and Vibe
    Remote can't answer the prompt, so both the Settings provider page and the
    setup wizard hide the write-allow affordance once this returns True.

    Accepts both forms OpenCode documents: the ``"permission": "allow"`` string
    shorthand and the granular object form — evaluated recursively via
    :func:`_opencode_permission_grants_all` so any config that already avoids all
    approval prompts (including nested ``allow`` rules) isn't gated or nagged to
    overwrite, while a partial config that can still prompt keeps the button.
    """
    config = getattr(probe, "config", None)
    if not isinstance(config, dict):
        return False
    return _opencode_permission_grants_all(config.get("permission"))


def opencode_permission_status() -> dict:
    """Cheaply report whether ``opencode.json`` already grants ``permission: "allow"``.

    Reads (and JSONC-parses) the user's OpenCode config only — it never starts
    the OpenCode server — so the setup wizard can decide whether to surface the
    write-allow affordance without paying for a full provider probe (which the
    Settings page already does via ``get_opencode_providers``).

    Returns ``{"ok": bool, "permission_allowed": bool, "config_path": str}``.
    """
    config_paths = get_opencode_config_paths(Path.home())
    probe = load_first_opencode_user_config(home=Path.home(), logger_instance=logger)
    # A malformed existing config can't be auto-fixed — ``setup_opencode_permission``
    # refuses to overwrite invalid files — so report unknown (``ok: False``) here.
    # The wizard gate keys off a successful status read, so this makes it FAIL
    # OPEN instead of trapping the user behind a Continue the only available
    # action can't satisfy. (A missing config — no existing paths — is the normal
    # first-run case and stays ``ok: True`` so setup can create it.)
    if probe.config is None and probe.existing_paths:
        error_path, error_message = (
            probe.errors[0] if probe.errors else (probe.existing_paths[0], "unknown parse error")
        )
        return {
            "ok": False,
            "permission_allowed": False,
            "config_path": str(error_path),
            "message": f"Existing OpenCode config could not be parsed: {error_message}",
        }
    config_path = probe.path if probe.path is not None else (config_paths[0] if config_paths else None)
    return {
        "ok": True,
        "permission_allowed": opencode_permission_allowed(probe),
        "config_path": str(config_path) if config_path is not None else "",
    }


@_native_auth_write("opencode", authentication=False)
def setup_opencode_permission() -> dict:
    """Set OpenCode permission to 'allow' in config file.

    Detection priority (aligned with _load_opencode_user_config):
    1. ~/.config/opencode/opencode.json - if exists and valid JSON/JSONC, update it
    2. ~/.opencode/opencode.json - if exists and valid JSON/JSONC, update it
    3. Create new file at ~/.config/opencode/opencode.json (XDG standard)

    Mirrors _load_opencode_user_config behavior: skips invalid files and tries next.
    If config files exist but none can be parsed, returns an error instead of
    overwriting the existing file contents.

    Returns:
        {"ok": bool, "message": str, "config_path": str}
    """
    config_paths = get_opencode_config_paths(Path.home())
    probe = load_first_opencode_user_config(home=Path.home(), logger_instance=logger)

    if probe.config is not None and probe.path is not None:
        if opencode_permission_allowed(probe):
            return {
                "ok": True,
                "message": "Permission already set",
                "config_path": str(probe.path),
            }

        try:
            original_content = probe.content
            if original_content is None:
                original_content = probe.path.read_text(encoding="utf-8")

            updated_content = set_jsonc_top_level_string_property(original_content, "permission", "allow")
            probe.path.write_text(updated_content, encoding="utf-8")
            return {
                "ok": True,
                "message": "Permission set to 'allow'",
                "config_path": str(probe.path),
            }
        except Exception as e:
            logger.error(f"Failed to update OpenCode config at {probe.path}: {e}")
            return {"ok": False, "message": str(e), "config_path": str(probe.path)}

    if probe.existing_paths:
        error_path, error_message = (
            probe.errors[0] if probe.errors else (probe.existing_paths[0], "unknown parse error")
        )
        logger.error(f"Refusing to overwrite invalid OpenCode config at {error_path}: {error_message}")
        return {
            "ok": False,
            "message": f"Existing OpenCode config could not be parsed: {error_message}. File left unchanged.",
            "config_path": str(error_path),
        }

    # No existing valid config found, create at XDG path (first in list)
    config_path = config_paths[0]
    try:
        config_path.parent.mkdir(parents=True, exist_ok=True)
        config_path.write_text(json.dumps({"permission": "allow"}, indent=2) + "\n", encoding="utf-8")
        return {
            "ok": True,
            "message": "Permission set to 'allow'",
            "config_path": str(config_path),
        }
    except Exception as e:
        logger.error(f"Failed to create OpenCode config: {e}")
        return {"ok": False, "message": str(e), "config_path": str(config_path)}


def parse_claude_agent_file(agent_path: str) -> Optional[dict]:
    """Parse a Claude agent markdown file and extract metadata.

    Agent files have YAML frontmatter and a markdown body:
    ---
    name: agent-name
    description: When to invoke this agent
    tools: Read, Bash, Edit  # Optional
    model: sonnet  # Optional: sonnet, opus, haiku, inherit
    ---
    System prompt content here...

    Returns:
        {
            "name": str,
            "description": str,
            "prompt": str,       # The markdown body (system prompt)
            "tools": list[str],  # Optional
            "model": str,        # Optional
        }
        or None on parse failure
    """
    try:
        content = Path(agent_path).read_text(encoding="utf-8")

        # Check for YAML frontmatter
        if not content.startswith("---"):
            # No frontmatter, use entire content as prompt
            return {
                "name": Path(agent_path).stem,
                "description": f"Agent from {Path(agent_path).name}",
                "prompt": content.strip(),
                "tools": None,
                "model": None,
            }

        # Find the closing ---
        lines = content.split("\n")
        end_idx = -1
        for i, line in enumerate(lines[1:], start=1):
            if line.strip() == "---":
                end_idx = i
                break

        if end_idx == -1:
            # Malformed frontmatter, use entire content
            return {
                "name": Path(agent_path).stem,
                "description": f"Agent from {Path(agent_path).name}",
                "prompt": content.strip(),
                "tools": None,
                "model": None,
            }

        # Parse YAML frontmatter
        frontmatter_lines = lines[1:end_idx]
        frontmatter_text = "\n".join(frontmatter_lines)

        # Use yaml.safe_load for proper YAML parsing (handles lists, etc.)
        metadata: dict = {}
        try:
            import yaml

            parsed = yaml.safe_load(frontmatter_text)
            if isinstance(parsed, dict):
                metadata = parsed
        except Exception as yaml_err:
            logger.debug(f"YAML parse failed, falling back to simple parsing: {yaml_err}")
            # Fallback to simple key: value parsing
            for line in frontmatter_lines:
                if ":" in line:
                    key, _, value = line.partition(":")
                    key = key.strip()
                    value = value.strip()
                    if key and value:
                        metadata[key] = value

        # Extract body (system prompt)
        body_lines = lines[end_idx + 1 :]
        body = "\n".join(body_lines).strip()

        # Parse tools if present
        tools = None
        if "tools" in metadata:
            tools_val = metadata["tools"]
            if isinstance(tools_val, list):
                # YAML list format: tools:\n  - Read\n  - Bash
                tools = [str(t).strip() for t in tools_val if t]
            elif isinstance(tools_val, str):
                # Inline format: tools: Read, Bash, Edit
                if "," in tools_val:
                    tools = [t.strip() for t in tools_val.split(",") if t.strip()]
                else:
                    tools = [t.strip() for t in tools_val.split() if t.strip()]

        return {
            "name": metadata.get("name", Path(agent_path).stem),
            "description": metadata.get("description", f"Agent from {Path(agent_path).name}"),
            "prompt": body,
            "tools": tools,
            "model": metadata.get("model"),
        }
    except Exception as e:
        logger.warning(f"Failed to parse agent file {agent_path}: {e}")
        return None


def claude_agents(cwd: Optional[str] = None) -> dict:
    """List available Claude Code agents (global + project).

    Claude supports both:
    - Global agents: ~/.claude/agents/*.md
    - Project agents: <cwd>/.claude/agents/*.md (if cwd provided)

    Returns:
        {
            "ok": True,
            "agents": [
                {"id": "reviewer", "name": "reviewer", "path": "/path/to/reviewer.md"},
                ...
            ]
        }
        or {"ok": False, "error": str} on failure
    """
    global_dir = Path.home() / ".claude" / "agents"
    project_dir: Optional[Path] = None
    if cwd:
        try:
            project_dir = Path(cwd).expanduser().resolve() / ".claude" / "agents"
        except Exception:
            project_dir = None

    def _scan_agents(directory: Path, source: str) -> dict[str, dict]:
        if not directory.exists():
            return {}
        if not directory.is_dir():
            return {}
        found: dict[str, dict] = {}
        for agent_file in sorted(directory.glob("*.md")):
            if not agent_file.is_file():
                continue
            agent_id = agent_file.stem
            found[agent_id] = {
                "id": agent_id,
                "name": agent_id,
                "path": str(agent_file),
                "source": source,
            }
        return found

    try:
        # Project overrides global on name collision.
        merged = _scan_agents(global_dir, "global")
        if project_dir is not None:
            merged.update(_scan_agents(project_dir, "project"))
        agents = list(merged.values())
        agents.sort(key=lambda x: (0 if x.get("source") == "project" else 1, x.get("id", "")))
        return {"ok": True, "agents": agents}
    except Exception as e:
        logger.error(f"Failed to scan Claude agents directory: {e}")
        return {"ok": False, "error": str(e)}


def codex_agents(cwd: Optional[str] = None) -> dict:
    """List available Codex custom agents (global + project)."""
    try:
        project_root: Optional[Path] = None
        if cwd:
            try:
                project_root = Path(cwd).expanduser().resolve()
            except Exception:
                project_root = None

        definitions = list_codex_subagents(project_root=project_root)
        agents = [
            {
                "id": definition.name,
                "name": definition.name,
                "path": str(definition.path) if definition.path else "",
                "source": definition.source,
                "description": definition.description,
            }
            for definition in definitions.values()
        ]
        agents.sort(key=lambda item: (0 if item.get("source") == "project" else 1, item.get("id", "")))
        return {"ok": True, "agents": agents}
    except Exception as e:
        logger.error("Failed to scan Codex agents directory: %s", e)
        return {"ok": False, "error": str(e)}


def claude_models(*, schedule_refresh: bool = True) -> dict:
    """Return the immediate shared Claude model-catalog snapshot."""
    return backend_model_catalog.backend_model_snapshot("claude", schedule_refresh=schedule_refresh)


def _effort_values(reasoning_entries: object) -> list[str]:
    """Extract settable reasoning-effort values, dropping the UI ``__default__`` sentinel."""
    out: list[str] = []
    if not isinstance(reasoning_entries, list):
        return out
    for entry in reasoning_entries:
        if not isinstance(entry, dict):
            continue
        value = entry.get("value")
        if isinstance(value, str) and value and value != "__default__" and value not in out:
            out.append(value)
    return out


def _flat_catalog_models(catalog: dict) -> list[dict]:
    """Shape claude_models()/codex_models() output into the unified models list."""
    reasoning_map = catalog.get("reasoning_options") or {}
    models: list[dict] = []
    for model_id in catalog.get("models") or []:
        if not isinstance(model_id, str) or not model_id:
            continue
        models.append(
            {
                "value": model_id,
                "label": (catalog.get("model_labels") or {}).get(model_id, model_id),
                "reasoning_efforts": _effort_values(reasoning_map.get(model_id)),
            }
        )
    return models


def _opencode_model_options(
    *,
    provider: Optional[str],
    cwd: Optional[str],
    config: Optional[V2Config],
) -> dict:
    """OpenCode model options, including custom providers and user-added models.

    Reuses ``opencode_options`` whose async path already overlays custom
    providers (``_read_opencode_custom_provider_ids``) and user models
    (``_merge_opencode_user_models``), so this only normalizes the shape and
    applies the optional ``provider`` filter.
    """

    resolved_cwd = cwd
    if not resolved_cwd:
        runtime_cfg = getattr(config, "runtime", None) if config is not None else None
        resolved_cwd = getattr(runtime_cfg, "default_cwd", None) if runtime_cfg is not None else None
    if not resolved_cwd:
        resolved_cwd = "."

    raw = opencode_options(resolved_cwd)
    if not raw.get("ok"):
        return {"ok": False, "backend": "opencode", "error": raw.get("error") or "opencode options unavailable"}

    data = raw.get("data") or {}
    models_block = data.get("models") if isinstance(data.get("models"), dict) else {}
    reasoning_map = data.get("reasoning_options") or {}
    providers_raw = models_block.get("providers") if isinstance(models_block.get("providers"), list) else []

    try:
        from vibe.opencode_config import _is_vibe_user_model as _oc_is_user_model
        from vibe.opencode_config import read_opencode_custom_providers

        custom_ids = set(read_opencode_custom_providers().keys())
    except Exception:
        _oc_is_user_model = None
        custom_ids = set()

    from modules.agents.opencode.utils import (
        opencode_model_is_hub_projected,
        opencode_model_picker_value,
    )

    provider_filter = (provider or "").strip().lower() or None
    matched_provider_filter = False
    providers_out: list[dict] = []
    models_out: list[dict] = []
    for prov in providers_raw:
        if not isinstance(prov, dict):
            continue
        pid = prov.get("id") or prov.get("provider_id") or prov.get("name")
        if not isinstance(pid, str) or not pid:
            continue
        if provider_filter and pid.lower() != provider_filter:
            continue
        matched_provider_filter = True
        prov_models = prov.get("models")
        if isinstance(prov_models, dict):
            model_items = list(prov_models.items())
        elif isinstance(prov_models, list):
            model_items = [(m.get("id"), m) for m in prov_models if isinstance(m, dict) and m.get("id")]
        else:
            model_items = []
        if not model_items or not all(
            opencode_model_is_hub_projected(model_info)
            for _model_id, model_info in model_items
        ):
            providers_out.append({"id": pid, "name": prov.get("name") or pid, "custom": pid in custom_ids})
        for model_id, model_info in model_items:
            if not isinstance(model_id, str) or not model_id:
                continue
            projected = opencode_model_is_hub_projected(model_info)
            value = opencode_model_picker_value(pid, model_id, model_info)
            source = "catalog"
            if _oc_is_user_model is not None and isinstance(model_info, dict) and _oc_is_user_model(model_id, model_info):
                source = "user"
            row = {
                "value": value,
                "source": source,
                "reasoning_efforts": _effort_values(reasoning_map.get(value)),
            }
            if not projected:
                row["provider"] = pid
            models_out.append(row)

    opencode_cfg = getattr(getattr(config, "agents", None), "opencode", None) if config is not None else None
    default_provider = getattr(opencode_cfg, "default_provider", None) if opencode_cfg is not None else None

    notes: list[str] = []
    if provider_filter and not matched_provider_filter:
        notes.append(f"no configured OpenCode provider matches '{provider}'")
    catalog_source = data.get("source")
    if not isinstance(catalog_source, str) or not catalog_source:
        catalog_source = "opencode server (live) + user config overlay"
    catalog_live = data.get("live")
    if not isinstance(catalog_live, bool):
        catalog_live = True
    return {
        "ok": True,
        "backend": "opencode",
        "default_provider": default_provider or None,
        "providers": providers_out,
        "models": models_out,
        "source": catalog_source,
        "live": catalog_live,
        "notes": notes or None,
    }


def agent_model_options(
    backend: str,
    *,
    provider: Optional[str] = None,
    cwd: Optional[str] = None,
) -> dict:
    """Backend-agnostic available models + per-model reasoning efforts.

    Single entry point wrapping ``claude_models`` / ``codex_models`` /
    ``opencode_options`` into one shape so the CLI and the Web UI can share it::

        {ok, backend, models: [{value, reasoning_efforts, provider?, source?}],
         providers?: [{id, name, custom}], source, live, notes}

    ``provider`` filters OpenCode results (ignored for other backends). Narrowing
    to a single model is a presentation concern left to the caller.
    """

    normalized_backend = (backend or "").strip().lower()
    if normalized_backend not in AGENT_BACKENDS:
        return {"ok": False, "error": f"unknown backend '{backend}'", "backend": normalized_backend}

    try:
        config: Optional[V2Config] = V2Config.load()
    except Exception:
        config = None

    if not is_native_cli_backend(normalized_backend):
        if config is None:
            return {"ok": False, "backend": normalized_backend, "error": "config_unavailable"}
        supply = config.model_hub.agents[normalized_backend]
        return {
            "ok": True,
            "backend": normalized_backend,
            "models": [
                {
                    "value": model.id,
                    "label": model.display_name or model.id,
                    "reasoning_efforts": (
                        [] if model.supports_reasoning is False else list(model.reasoning_efforts)
                    ),
                }
                for model in supply.models
            ],
            "source": "model_hub",
            "live": False,
        }
    if normalized_backend == "claude":
        data = claude_models()
        if not data.get("ok"):
            return {"ok": False, "backend": normalized_backend, "error": data.get("error") or "claude model lookup failed"}
        result = {
            "ok": True,
            "backend": "claude",
            "models": _flat_catalog_models(data),
            "source": data.get("source"),
            "live": bool(data.get("live")),
            "notes": data.get("notes"),
            "catalog_refresh_pending": bool(data.get("catalog_refresh_pending")),
        }
    elif normalized_backend == "codex":
        data = codex_models()
        if not data.get("ok"):
            return {"ok": False, "backend": normalized_backend, "error": data.get("error") or "codex model lookup failed"}
        result = {
            "ok": True,
            "backend": "codex",
            "models": _flat_catalog_models(data),
            "source": data.get("source"),
            "live": bool(data.get("live")),
            "notes": data.get("notes"),
            "catalog_refresh_pending": bool(data.get("catalog_refresh_pending")),
        }
    else:
        result = _opencode_model_options(provider=provider, cwd=cwd, config=config)

    return result


_AGENT_INSTALL_JOB_LOCK = threading.Lock()
_AGENT_INSTALL_JOBS: dict[str, dict] = {}
_AGENT_INSTALL_LATEST_BY_BACKEND: dict[str, str] = {}
_AGENT_INSTALL_JOB_TTL_SECONDS = 3600.0
_AGENT_INSTALL_POLL_TIMEOUT_SECONDS = (
    DESKTOP_BACKEND_LOCK_TIMEOUT_SECONDS
    + DESKTOP_BACKEND_INSTALL_TIMEOUT_SECONDS
    + DESKTOP_BACKEND_PROBE_TIMEOUT_SECONDS
    + DESKTOP_BACKEND_PROCESS_DRAIN_TIMEOUT_SECONDS
    + 4.0  # Controller refresh acknowledgement.
    + 30.0  # Filesystem publication, persistence, and polling margin.
)


def _prune_agent_install_jobs(now: float | None = None) -> None:
    timestamp = now or time.time()
    stale = [
        job_id
        for job_id, job in _AGENT_INSTALL_JOBS.items()
        if job.get("finished_at") and timestamp - float(job.get("finished_at") or 0) > _AGENT_INSTALL_JOB_TTL_SECONDS
    ]
    for job_id in stale:
        job = _AGENT_INSTALL_JOBS.pop(job_id, None)
        backend = job.get("backend") if isinstance(job, dict) else None
        if isinstance(backend, str) and _AGENT_INSTALL_LATEST_BY_BACKEND.get(backend) == job_id:
            _AGENT_INSTALL_LATEST_BY_BACKEND.pop(backend, None)


def _agent_install_job_succeeded(result: dict, name: str) -> bool:
    if not bool(result.get("ok")):
        return False
    if not supports_runtime_refresh(name):
        return True
    restart = result.get("restart")
    return isinstance(restart, dict) and bool(restart.get("ok"))


def _agent_runtime_fingerprint(name: str, detection: dict | None = None) -> tuple[str, str, str] | None:
    """Measure the configured CLI, not another installation found by name.

    Include the persisted launch path as well as its resolved target: changing
    an alias still requires the controller to load the new configuration.
    Unknown configuration, paths, or versions cannot prove a no-op.
    """
    try:
        config = V2Config.load()
        if config.load_warnings:
            return None
        configured_path = getattr(config.agents, name).cli_path or name
        if detection is None:
            detection = detect_cli(configured_path, name)
        if detection.get("status") != "ok" or not detection.get("version") or not detection.get("path"):
            return None
        resolved_path = resolve_cli_path(configured_path)
        if not resolved_path or os.path.abspath(resolved_path) != os.path.abspath(detection["path"]):
            return None
        return configured_path, os.path.realpath(resolved_path), detection["version"]
    except Exception as exc:  # noqa: BLE001
        logger.debug("Agent runtime fingerprint probe failed for %s: %s", name, exc)
        return None


def start_agent_install_job(name: str) -> dict:
    """Start backend CLI install/upgrade in a background job.

    The UI request path must not run package-manager subprocesses directly:
    npm/curl/brew can hang or take minutes, and backend CLI failures should
    not affect the avibe main service. The worker still uses the same
    install/upgrade implementation as the CLI card used before; only the
    execution boundary changes.
    """
    if not supports_install(name):
        return {"ok": False, "message": f"Unknown agent: {name}"}

    job_id = uuid.uuid4().hex
    now = time.time()
    job = {
        "ok": True,
        "job_id": job_id,
        "backend": name,
        "status": "running",
        "message": "Upgrade started",
        "output": "",
        "path": None,
        "poll_timeout_seconds": _AGENT_INSTALL_POLL_TIMEOUT_SECONDS,
        "started_at": now,
        "finished_at": None,
    }
    with _AGENT_INSTALL_JOB_LOCK:
        _prune_agent_install_jobs(now)
        latest_job_id = _AGENT_INSTALL_LATEST_BY_BACKEND.get(name)
        latest_job = _AGENT_INSTALL_JOBS.get(latest_job_id or "")
        if isinstance(latest_job, dict) and latest_job.get("status") == "running":
            return dict(latest_job)
        _AGENT_INSTALL_JOBS[job_id] = job
        _AGENT_INSTALL_LATEST_BY_BACKEND[name] = job_id

    def _worker() -> None:
        try:
            refresh_supported = supports_runtime_refresh(name)
            runtime_before = _agent_runtime_fingerprint(name) if refresh_supported else None
            result = install_agent(name)
            verified = result.get("detection")
            if result.get("ok") and (not isinstance(verified, dict) or verified.get("status") != "ok"
                                     or not verified.get("version") or verified.get("path") != result.get("path")):
                result = {**result, "ok": False, "code": "cli_readback_failed",
                          "message": backend_t("cliHealth.installReadbackFailed", _configured_backend_language())}
            if result.get("ok") and refresh_supported:
                try:
                    runtime_after = _agent_runtime_fingerprint(name, result.get("detection"))
                    if runtime_before is None or runtime_before != runtime_after:
                        result["restart"] = restart_backend(
                            name,
                            metadata={"reason": "agent_install_job", "source": "ui_api"},
                        )
                    else:
                        logger.info(
                            "Skipping %s backend refresh after install: effective CLI runtime unchanged",
                            name,
                        )
                        result["restart"] = {
                            "ok": True,
                            "skipped": True,
                        }
                except Exception as exc:  # noqa: BLE001
                    logger.warning(
                        "Backend refresh after %s install job failed: %s",
                        name,
                        exc,
                    )
                    result["restart"] = {"ok": False, "message": str(exc)}
            ok = _agent_install_job_succeeded(result, name)
            status = "succeeded" if ok else "failed"
            if not ok:
                restart = result.get("restart")
                if isinstance(restart, dict):
                    restart_message = restart.get("message")
                    if isinstance(restart_message, str) and restart_message.strip():
                        result["message"] = restart_message.strip()
            with _AGENT_INSTALL_JOB_LOCK:
                current = _AGENT_INSTALL_JOBS.get(job_id)
                if current is not None:
                    current.update(result)
                    current["ok"] = ok
                    current["status"] = status
                    current["finished_at"] = time.time()
        except Exception as exc:  # noqa: BLE001
            logger.warning("Agent install job failed for %s: %s", name, exc, exc_info=True)
            with _AGENT_INSTALL_JOB_LOCK:
                current = _AGENT_INSTALL_JOBS.get(job_id)
                if current is not None:
                    current.update(
                        {
                            "ok": False,
                            "status": "failed",
                            "message": str(exc),
                            "output": None,
                            "finished_at": time.time(),
                        }
                    )

    threading.Thread(
        target=_worker,
        daemon=True,
        name=f"vibe-agent-install-{name}-{job_id[:8]}",
    ).start()
    return dict(job)


def get_agent_install_job(job_id: str | None = None, *, backend: str | None = None) -> dict:
    """Return the latest state for a background backend install job."""
    with _AGENT_INSTALL_JOB_LOCK:
        _prune_agent_install_jobs()
        resolved_job_id = (job_id or "").strip()
        if not resolved_job_id and backend:
            resolved_job_id = _AGENT_INSTALL_LATEST_BY_BACKEND.get(backend.strip()) or ""
        job = _AGENT_INSTALL_JOBS.get(resolved_job_id)
        if not job:
            return {"ok": False, "error": "job_not_found"}
        return dict(job)


def _configured_agent_cli_path(name: str) -> str:
    try:
        config = load_config()
    except (FileNotFoundError, OSError, ValueError):
        return name
    backend = getattr(getattr(config, "agents", None), name, None)
    configured = getattr(backend, "cli_path", "") if backend is not None else ""
    return configured or name


def _persist_agent_cli_path(name: str, installed_path: str, *, required: bool = False) -> str | None:
    """Persist one backend path and return its previous configured value."""

    try:
        from config.v2_config import update_config_fields

        if not paths.get_config_path().exists():
            raise FileNotFoundError("Avibe config is not initialized")
        previous: str | None = None

        def persist(config) -> None:
            nonlocal previous
            target = getattr(getattr(config, "agents", None), name, None)
            if target is None:
                raise ValueError(f"Agent backend config is unavailable: {name}")
            previous = getattr(target, "cli_path", "") or name
            target.cli_path = installed_path

        update_config_fields(persist)
        return previous
    except FileNotFoundError:
        if required:
            raise
        logger.debug(
            "install_agent: config is not initialized; skipping cli_path persistence for %s",
            name,
        )
    except Exception:
        if required:
            raise
        logger.warning("install_agent: failed to persist cli_path for %s", name, exc_info=True)
    return None


_DESKTOP_BACKEND_LABELS = {
    backend: display_name_for_backend(backend) for backend in NATIVE_CLI_BACKENDS
}
_DESKTOP_BACKEND_ERROR_I18N_KEYS = {
    "unknown_backend": "desktopBackendInstall.unknownBackend",
    "desktop_toolchain_unavailable": "desktopBackendInstall.toolchainUnavailable",
    "install_locked": "desktopBackendInstall.installLocked",
    "npm_install_failed": "desktopBackendInstall.installFailed",
    "desktop_install_failed": "desktopBackendInstall.installFailed",
    "invalid_backend_root": "desktopBackendInstall.invalidInstall",
    "invalid_package": "desktopBackendInstall.invalidInstall",
    "native_executable_missing": "desktopBackendInstall.invalidInstall",
    "invalid_executable": "desktopBackendInstall.invalidInstall",
    "unsupported_platform": "desktopBackendInstall.unsupportedPlatform",
    "install_timeout": "desktopBackendInstall.timedOut",
    "executable_probe_failed": "desktopBackendInstall.probeFailed",
}


def _configured_backend_language() -> str:
    try:
        return str(getattr(load_config(), "language", "en") or "en")
    except (FileNotFoundError, OSError, ValueError):
        return "en"


def _desktop_backend_install_message(name: str, code: str) -> str:
    key = _DESKTOP_BACKEND_ERROR_I18N_KEYS.get(code, "desktopBackendInstall.installFailed")
    return backend_t(
        key,
        _configured_backend_language(),
        backend=_DESKTOP_BACKEND_LABELS.get(name, name),
    )


def _run_desktop_backend_install(name: str, truncate_output) -> dict:
    def _activate(installed_path: str) -> None:
        _persist_agent_cli_path(name, installed_path, required=True)

    try:
        result = install_desktop_backend(name, activate=_activate)
    except DesktopBackendError as exc:
        return {
            "ok": False,
            "code": exc.code,
            "message": _desktop_backend_install_message(name, exc.code),
            "output": truncate_output(exc.output) if exc.output else None,
        }
    health = detect_cli(result.path, name)
    if health["status"] != "ok":
        # Publication/activation already committed. Report failed verification,
        # but never remove the now-active generation as diagnostic cleanup.
        return {"ok": False, "code": "cli_readback_failed",
                "message": backend_t("cliHealth.installReadbackFailed", _configured_backend_language()),
                "path": result.path, "output": None, "detection": health}
    return {
        "ok": True,
        "message": backend_t(
            "desktopBackendInstall.success",
            _configured_backend_language(),
            backend=_DESKTOP_BACKEND_LABELS.get(name, name),
        ),
        "path": result.path,
        "version": health["version"],
        "detection": health,
        "managed_by": "desktop",
        "output": truncate_output(result.output) if result.output else None,
    }


def install_agent(name: str, *, version: str | None = None) -> dict:
    """Install (or upgrade) an agent CLI tool, one install per backend at a time.

    Settings runs this in the UI process and backend auto-update in the
    controller, so only a file lock keeps two installers off one CLI.
    ``version`` pins the release where the installation's source can: a Codex
    npm install or upgrade, and a repair of a broken npm installation. Backend
    auto-update passes the release it approved, or the one a failed upgrade
    replaced. Self-updaters and Homebrew install what their source publishes.
    """
    if not supports_install(name):
        return {"ok": False, "message": f"Unknown agent: {name}"}
    lock = MigrationFileLock(paths.get_state_dir() / "agent_install" / f"{name}.lock", timeout_seconds=0)
    try:
        lock.acquire()
    except MigrationLockTimeout:
        return {
            "ok": False,
            "code": "install_locked",
            "message": _desktop_backend_install_message(name, "install_locked"),
            "output": None,
            "path": None,
        }
    try:
        return _install_agent(name, version=version)
    finally:
        lock.release()


def _cli_repair_refusal(name: str, *, conflict: bool = False) -> dict:
    return {
        "ok": False,
        "code": "repair_path_conflict" if conflict else "repair_source_unknown",
        "message": backend_t("cliHealth.repairPathConflict" if conflict else "cliHealth.repairUnavailable", _configured_backend_language(), backend=display_name_for_backend(name)),
        "output": None,
        "path": None,
    }


def _repair_broken_cli(name: str, selected: str, truncate_output, *, version: str | None = None) -> dict:
    source = identify_repair_source(name, selected)
    if source is None:
        return _cli_repair_refusal(name)
    command_env = _command_env_for(selected)
    if source.kind == "npm":
        npm = resolve_cli_path("npm")
        if not npm:
            return _cli_repair_refusal(name)
        # A pinned release is the one npm already fetched whole for this
        # platform; its native package is in the npm cache.
        package = f"{source.package}@{version}" if version else source.package
        cmd = [npm, "install", "--global", "--prefix", str(source.prefix), package]
        command_env = _command_env_for(npm)
    elif source.kind == "brew":
        brew = source.prefix / "bin" / "brew"
        if not _is_executable_file(brew):
            return _cli_repair_refusal(name)
        cmd = [str(brew), "reinstall", *(["--cask"] if source.cask else []), source.package]
        command_env = _command_env_for(str(brew))
    elif name == "opencode":
        if os.name == "nt":
            return _cli_repair_refusal(name)
        bash, curl = resolve_cli_path("bash"), resolve_cli_path("curl")
        if not bash or not curl:
            return _cli_repair_refusal(name)
        command_env = native_bootstrap_env(command_env, hide_directory=Path(source.destination).parent)
        guard = f"if command -v opencode >/dev/null 2>&1; then printf '%s\\n' {shlex.quote(REPAIR_PATH_CONFLICT)} >&2; exit 73; fi; "
        # Check before network activity, then in the actual non-login bootstrap
        # shell. No startup hook/imported function can restore the old PATH.
        consumer = [bash, "--noprofile", "--norc", "-s", "--", "--no-modify-path"]
        download = shlex.join([curl, "-fsSL", *shlex.split(_CURL_INSTALL_RETRY_FLAGS), "https://opencode.ai/install"])
        # Prefix the guard to the streamed script rather than sourcing a pipe
        # through /dev/stdin (macOS bash may see an empty source before data arrives).
        script = "set -euo pipefail; " + guard + "{ printf '%s\\n' " + shlex.quote(guard) + "; " + download + "; } | " + shlex.join(consumer)
        cmd = [bash, "--noprofile", "--norc", "-c", script]
    elif name == "claude":
        command_env = native_bootstrap_env(command_env)
        if os.name == "nt":
            powershell = resolve_cli_path("powershell")
            if not powershell:
                return _cli_repair_refusal(name)
            cmd = [powershell, "-NoProfile", "-Command", "irm https://claude.ai/install.ps1 -ErrorAction Stop | iex"]
        else:
            bash, curl = resolve_cli_path("bash"), resolve_cli_path("curl")
            if not bash or not curl:
                return _cli_repair_refusal(name)
            cmd = [bash, "--noprofile", "--norc", "-c", "set -euo pipefail; " + shlex.join([curl, "-fsSL", *shlex.split(_CURL_INSTALL_RETRY_FLAGS), "https://claude.ai/install.sh"]) + " | " + shlex.join([bash, "--noprofile", "--norc"])]
    else:
        return _cli_repair_refusal(name)
    return _run_install_command(name, cmd, truncate_output, mode="repair", env=command_env, expected_path=source.destination)


def _native_vendor_install_target(name: str) -> str | None:
    home = Path.home()
    if name == "opencode":
        return str(home / ".opencode" / "bin" / ("opencode.exe" if os.name == "nt" else "opencode"))
    if name == "claude":
        return str(home / ".local" / "bin" / ("claude.exe" if os.name == "nt" else "claude"))
    return None


def _install_agent(name: str, *, version: str | None = None) -> dict:
    """Install (or upgrade) an agent CLI tool.

    Existing installations keep their install method and their selected
    executable. Post-upgrade verification is bound before invoking the updater;
    a missing launcher cannot be replaced by an unrelated same-name discovery.
    An unattributed relocation fails verification rather than silently changing
    the configured selection.

    Upgrade commands:
      - ``claude update``   — auto-detects npm-global vs native install
      - ``opencode upgrade`` — auto-detects curl/npm/pnpm/bun/brew/choco/scoop
      - Codex npm installs use ``npm install -g @openai/codex`` with a
        user-owned npm prefix.
      - Codex Homebrew installs use ``brew upgrade --cask codex``.
      - Unknown Codex installs fall back to ``codex update``.

    Fresh-install path (binary missing) keeps the bootstrap commands
    below — the user has no install yet, so we have no install method
    to defer to.

    Returns:
        {"ok": bool, "message": str, "output": str | None, "path": str | None}
    """
    import platform

    system = platform.system().lower()

    # Max output size to prevent UI slowdown (last N characters)
    MAX_OUTPUT_CHARS = 8192

    def _check_binary(binary: str) -> str | None:
        """Check if a binary exists in PATH. Returns error message if not found."""
        if resolve_cli_path(binary) is None:
            return f"{binary} is required but not found. Please install it first."
        return None

    def _truncate_output(output: str) -> str:
        """Truncate output to last MAX_OUTPUT_CHARS characters."""
        if len(output) <= MAX_OUTPUT_CHARS:
            return output
        return "...(truncated)\n" + output[-MAX_OUTPUT_CHARS:]

    # Upgrade branch: if the binary is already on disk, keep the install
    # source stable. Some CLIs own a reliable self-update command; Codex has
    # multiple install sources, so choose npm/brew/self-update by source.
    configured_path = _configured_agent_cli_path(name)
    existing_path = resolve_cli_path(configured_path)

    def _owned_path(under_app_root) -> str | None:
        """The app-private path this Runtime owns, configured or discovered.

        The configured path has to be judged too, and on its own. It names the
        backend this Runtime installed and it keeps naming it after the
        executable is deleted -- at which point ``resolve_cli_path`` falls back
        to finding the bare name on PATH and hands back the user's own
        ``claude``/``codex``/``opencode``. Judging only that result would run the
        external upgrade against a binary this Runtime does not own, mutating
        user or system state, and would never reach the fail-closed guard below,
        which is only entered when nothing resolved at all.
        """

        if under_app_root(configured_path):
            return configured_path
        if existing_path is not None and under_app_root(existing_path):
            return existing_path
        return None

    if _owned_path(is_desktop_backend_path) is not None:
        return _run_desktop_backend_install(name, _truncate_output)
    if name == "codex":
        private_runtime_path = _owned_path(is_private_desktop_runtime_path)
        if private_runtime_path is not None:
            if desktop_backend_toolchain() is not None:
                return _run_desktop_backend_install(name, _truncate_output)
            return {
                "ok": False,
                "code": "desktop_managed_backend",
                "message": backend_t("desktopRuntime.backendUpgrade", _configured_backend_language()),
                "output": None,
                # The path we refused to update, not whatever discovery found in
                # its place -- the message is about that backend.
                "path": private_runtime_path,
            }
    # Preserve the app-private ownership boundary before any global probe or
    # repair planner can discover a non-executable user installation.
    if existing_path is None and is_desktop_managed_runtime():
        return _run_desktop_backend_install(name, _truncate_output)
    health = detect_cli(configured_path, name)
    if health["status"] in {"broken", "unknown"} or (health["status"] == "missing" and configured_path != name):
        if health["status"] == "unknown":
            return _cli_repair_refusal(name)
        return _repair_broken_cli(name, health["path"] or configured_path, _truncate_output, version=version)
    existing_path = health["path"]
    if existing_path:
        readback_validator = None
        if name == "codex":
            brew_path = resolve_cli_path("brew")
            homebrew_target = _homebrew_codex_target(brew_path, existing_path) if brew_path else None
            if homebrew_target is not None:
                readback_validator = lambda path, brew=brew_path, expected=homebrew_target: (
                    path == expected and _homebrew_codex_target(brew, path) == expected
                )
        if name == "claude":
            cmd = [existing_path, "update"]
            command_env = None
        elif name == "opencode":
            # ``opencode upgrade`` auto-detects the install method; we
            # don't pass ``--method`` so the user's bootstrap choice
            # wins (curl on our Dockerfile, brew/npm/bun on user machines).
            cmd = [existing_path, "upgrade"]
            command_env = None
        elif name == "codex":
            upgrade = _codex_upgrade_command(existing_path, version=version)
            if isinstance(upgrade, dict):
                return upgrade
            cmd, command_env = upgrade
        else:
            cmd = None
        if cmd is not None:
            # Codex's existing npm policy may explicitly select a user prefix.
            # Only that command-declared destination can certify a relocation.
            declared_target = _declared_codex_npm_target(command_env) if name == "codex" else None
            return _run_install_command(
                name,
                cmd,
                _truncate_output,
                mode="upgrade",
                env=command_env,
                expected_path=declared_target or existing_path,
                preserve_selected_path=existing_path if declared_target else None,
                readback_validator=readback_validator,
            )

    # A damaged private toolchain must fail closed. Falling through here would
    # run the legacy global installers and mutate user/system state from a
    # desktop Runtime that promises app-private backend ownership.
    if is_desktop_managed_runtime():
        return _run_desktop_backend_install(name, _truncate_output)

    command_env: dict[str, str] | None = None
    expected_path: str | None = None

    if name == "opencode":
        # OpenCode: use curl installer (not supported on Windows)
        if system == "windows":
            return {
                "ok": False,
                "message": "OpenCode installer is not supported on Windows. Please use the manual installation method.",
                "output": None,
            }
        # Check prerequisites
        for binary in ["curl", "bash"]:
            error = _check_binary(binary)
            if error:
                return {"ok": False, "message": error, "output": None}
        # Use pipefail to ensure curl failures are detected
        cmd = _curl_installer_command("https://opencode.ai/install", "bash")
        expected_path = _native_vendor_install_target(name)
    elif name == "claude":
        # Claude Code: platform-specific installer
        if system == "windows":
            # Windows: use PowerShell with error handling
            error = _check_binary("powershell")
            if error:
                return {"ok": False, "message": error, "output": None}
            cmd = ["powershell", "-NoProfile", "-Command", "irm https://claude.ai/install.ps1 -ErrorAction Stop | iex"]
            expected_path = _native_vendor_install_target(name)
        else:
            # macOS/Linux: use bash with pipefail
            for binary in ["curl", "bash"]:
                error = _check_binary(binary)
                if error:
                    return {"ok": False, "message": error, "output": None}
            cmd = _curl_installer_command("https://claude.ai/install.sh", "bash")
            expected_path = _native_vendor_install_target(name)
    elif name == "codex":
        # Fresh installs use npm because it is the documented cross-platform
        # package source that does not require OS package-manager privileges.
        npm_path = resolve_cli_path("npm")
        if npm_path:
            cmd = [npm_path, "install", "-g", f"@openai/codex@{version}" if version else "@openai/codex"]
            command_env = _codex_npm_install_env(npm_path)
            if command_env is None:
                return {
                    "ok": False,
                    "code": "cli_target_unknown",
                    "message": "Codex npm global prefix could not be determined; no installation was started.",
                    "output": None,
                }
            expected_path = _declared_codex_npm_target(command_env)
        else:
            return {
                "ok": False,
                "message": "npm not found. Please install Node.js first.",
                "output": None,
            }
    else:
        return {"ok": False, "message": f"Unknown agent: {name}", "output": None}

    return _run_install_command(
        name, cmd, _truncate_output, mode="install", env=command_env,
        expected_path=expected_path,
    )


def _curl_installer_command(url: str, consumer: str) -> list[str]:
    """Build the shared bounded-retry command for trusted script installers."""
    return [
        "bash",
        "-c",
        f"set -euo pipefail; curl -fsSL {_CURL_INSTALL_RETRY_FLAGS} {url} | {consumer}",
    ]


_AGENT_INSTALL_TIMEOUT_SECONDS = 300

# Installer failures we can explain, recognized from what the installer printed.
# Each shape comes from real npm 9/11, curl, and ``opencode upgrade`` output;
# the fixtures in tests/test_agent_install_failures.py are those captures.
_NPM_ERROR_PREFIX = r"npm (?:error|ERR!)"
_NPM_ERROR_CODE_RE = re.compile(rf"^{_NPM_ERROR_PREFIX} code (?P<code>\S+)\s*$", re.MULTILINE)
_NPM_ERROR_PATH_RE = re.compile(rf"^{_NPM_ERROR_PREFIX} path (?P<path>.+?)\s*$", re.MULTILINE)
_NPM_ENOTEMPTY_RENAME_RE = re.compile(
    r"ENOTEMPTY: directory not empty, rename '(?P<source>[^']+)' -> '(?P<dest>[^']+)'"
)
# Before moving a new version in, npm renames the installed package to
# ``.<name>-<8 chars>`` beside it. The suffix is derived from the package path,
# so a folder left there by an interrupted update fails every retry the same way.
_NPM_RETIRED_PACKAGE_RE = re.compile(r"^\.(?P<package>.+)-[A-Za-z0-9_-]{8}$")
_NPM_PERMISSION_CODES = frozenset({"EACCES", "EPERM"})
_NPM_NETWORK_CODES = frozenset({"ENOTFOUND", "ECONNREFUSED", "ETIMEDOUT"})
_NPM_REQUEST_URL_RE = re.compile(r"request to (?P<url>\S+) failed")
_CURL_UNREACHABLE_RE = re.compile(
    r"^curl: \((?:6\) Could not resolve host: (?P<dns_host>\S+)|(?:7|28)\) Failed to connect to (?P<connect_host>\S+) port)",
    re.MULTILINE,
)
_GITHUB_API_FORBIDDEN_RE = re.compile(r"\b403\b.*\bapi\.github\.com\b|\bapi\.github\.com\b.*\b403\b")
_GITHUB_RATE_LIMIT_URL = "https://api.github.com/rate_limit"
_GITHUB_RATE_LIMIT_TIMEOUT_SECONDS = 3
_INSTALL_FAILURE_HINT_KEYS = {
    "npm_leftover_directory": "agentInstall.hint.npmLeftoverDirectory",
    "permission_denied": "agentInstall.hint.permissionDenied",
    "network_unreachable": "agentInstall.hint.networkUnreachable",
    "install_timeout": "agentInstall.hint.timedOut",
}


def _github_rate_limit_reset() -> int | None:
    """When this network's exhausted GitHub API quota resets, as epoch seconds.

    ``GET /rate_limit`` does not spend the quota it reports, so it still answers
    after the call that failed. Best effort: the hint is still useful without a
    time, so any failure here only drops the time.
    """
    req = urllib.request.Request(
        _GITHUB_RATE_LIMIT_URL,
        headers={"Accept": "application/vnd.github+json", "User-Agent": _BACKEND_RUNTIME_USER_AGENT},
    )
    try:
        with _http_opener_for_best_effort_probe().open(  # noqa: S310 - fixed GitHub API URL
            req, timeout=_GITHUB_RATE_LIMIT_TIMEOUT_SECONDS
        ) as resp:
            core = json.loads(resp.read().decode("utf-8"))["resources"]["core"]
        remaining, reset_at = int(core["remaining"]), int(core["reset"])
    except Exception as exc:
        logger.debug("GitHub rate limit lookup failed: %s", exc)
        return None
    if remaining > 0 or reset_at <= time.time():
        return None
    return reset_at


def _recognize_install_failure(output: str | None, *, timed_out: bool = False) -> tuple[str, dict[str, Any]]:
    """Map a failed agent CLI install/upgrade to a stable hint code and params.

    The code is always one of ``install_timeout``, ``npm_leftover_directory``,
    ``permission_denied``, ``github_rate_limited``, ``network_unreachable`` or
    ``install_failed`` (nothing recognized); the params are what its hint names.
    """
    if timed_out:
        return "install_timeout", {"minutes": _AGENT_INSTALL_TIMEOUT_SECONDS // 60}
    text = output or ""
    rename = _NPM_ENOTEMPTY_RENAME_RE.search(text)
    if rename and _NPM_RETIRED_PACKAGE_RE.match(re.split(r"[\\/]", rename.group("dest"))[-1]):
        return "npm_leftover_directory", {"path": rename.group("dest")}
    npm_code = _NPM_ERROR_CODE_RE.search(text)
    npm_code = npm_code.group("code") if npm_code else None
    if npm_code in _NPM_PERMISSION_CODES:
        path = _NPM_ERROR_PATH_RE.search(text)
        if path:
            return "permission_denied", {"path": path.group("path")}
    if _GITHUB_API_FORBIDDEN_RE.search(text):
        return "github_rate_limited", {"reset_at": _github_rate_limit_reset()}
    if npm_code in _NPM_NETWORK_CODES:
        request = _NPM_REQUEST_URL_RE.search(text)
        host = urllib.parse.urlsplit(request.group("url")).hostname if request else None
        if host:
            return "network_unreachable", {"host": host}
    curl = _CURL_UNREACHABLE_RE.search(text)
    if curl:
        return "network_unreachable", {"host": curl.group("dns_host") or curl.group("connect_host")}
    return "install_failed", {}


def _install_failure_hint(code: str, params: dict[str, Any], language: str) -> str | None:
    if code == "github_rate_limited":
        reset_at = params.get("reset_at")
        if reset_at is None:
            return backend_t("agentInstall.hint.githubRateLimitedNoReset", language)
        return backend_t(
            "agentInstall.hint.githubRateLimited",
            language,
            # The runtime's local time; the minutes keep it usable from a browser
            # in another time zone.
            time=datetime.fromtimestamp(reset_at).strftime("%H:%M"),
            minutes=max(1, (int(reset_at - time.time()) + 59) // 60),
        )
    key = _INSTALL_FAILURE_HINT_KEYS.get(code)
    return backend_t(key, language, **params) if key else None


def _install_failure_result(
    name: str,
    mode: str,
    output: str,
    truncate_output,
    *,
    timed_out: bool = False,
    **details: Any,
) -> dict:
    """The one shape every failed ``_run_install_command`` returns.

    The headline names what failed in the instance language; ``code``/``hint``
    say why when the output is recognized; ``output`` keeps the installer's own
    words for the details. Recognition reads the whole output rather than the
    truncated tail, so an explanation printed before a long tail still counts.
    """
    code, params = _recognize_install_failure(output, timed_out=timed_out)
    language = _configured_backend_language()
    backend = display_name_for_backend(name) if is_agent_backend(name) else name
    headline = "agentInstall.upgradeFailed" if mode == "upgrade" else "agentInstall.installFailed"
    return {
        "ok": False,
        "message": backend_t(headline, language, backend=backend),
        "code": code,
        "hint": _install_failure_hint(code, params, language),
        "hint_params": params,
        **details,
        "output": truncate_output(output) or None,
    }


def _run_install_command(
    name: str,
    cmd: list[str],
    truncate_output,
    *,
    mode: str = "install",
    env: dict[str, str] | None = None,
    resolve_from: str | None = None,
    expected_path: str | None = None,
    preserve_selected_path: str | None = None,
    readback_validator: Callable[[str], bool] | None = None,
) -> dict:
    """Shared subprocess + post-success bookkeeping for install / upgrade.

    Factored out so the self-update branch (existing binary) and the
    fresh-install branch (curl/npm bootstrap) share identical post-run
    handling: log the result, verify a fresh executable observation, capture
    its path, and persist it to V2Config only after verification.
    """
    label = "Upgrading" if mode == "upgrade" else "Installing"
    try:
        logger.info("%s agent %s with command: %s", label, name, cmd)
        command_env = env or _command_env_for(cmd[0] if cmd and os.path.isabs(cmd[0]) else None)
        process = subprocess.Popen(
            cmd,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True,
            env=command_env,
            **isolated_subprocess_kwargs(),
        )
        try:
            stdout, stderr = process.communicate(timeout=_AGENT_INSTALL_TIMEOUT_SECONDS)
        except subprocess.TimeoutExpired:
            logger.error("Agent %s %s timed out", name, mode)
            signal_process_tree(process, KILL_SIGNAL, logger, f"{name} {mode}")
            stdout, stderr = process.communicate(timeout=10)
            output = (stdout or "") + ("\n" + stderr if stderr else "")
            # A killed installer can leave the CLI half-replaced; the next
            # detection observes it afresh rather than using an old version.
            return _install_failure_result(
                name,
                mode,
                output.strip(),
                truncate_output,
                timed_out=True,
                reason=f"{name}_{mode}_timeout",
                timeout_seconds=_AGENT_INSTALL_TIMEOUT_SECONDS,
            )
        result = subprocess.CompletedProcess(cmd, process.returncode, stdout, stderr)
        raw_output = (result.stdout + ("\n" + result.stderr if result.stderr else "")).strip()
        output = truncate_output(raw_output)
        # Exit zero alone does not certify the executable it left behind.
        if result.returncode == 0:
            selected = expected_path if expected_path is not None else resolve_cli_path(resolve_from or name)
            if expected_path and preserve_selected_path and _is_executable_file(Path(expected_path)):
                try:
                    # Keep a configured alias only while it still names the
                    # exact artifact at this operation's declared destination.
                    if os.path.samefile(expected_path, preserve_selected_path):
                        selected = preserve_selected_path
                except OSError:
                    pass
            # An install must certify its exact destination, never a different
            # healthy installation found by missing-path fallback.
            health = None
            if is_native_cli_backend(name):
                health = detect_cli(selected, name) if selected else CliHealth(False, None, "missing", reason="not_found").payload()
            installed_path = health["path"] if health is not None else selected
            if health is not None and health["status"] != "ok":
                return {
                    "ok": False,
                    "code": "cli_readback_failed",
                    "message": backend_t("cliHealth.installReadbackFailed", _configured_backend_language()),
                    "path": installed_path,
                    "output": None,
                    "detection": health,
                }
            if readback_validator is not None:
                try:
                    identity_ok = bool(readback_validator(installed_path))
                except Exception:
                    identity_ok = False
                if not identity_ok:
                    return {
                        "ok": False,
                        "code": "cli_readback_failed",
                        "message": backend_t("cliHealth.installReadbackFailed", _configured_backend_language()),
                        "path": installed_path,
                        "output": None,
                        "detection": health,
                    }
            logger.info("Agent %s %s succeeded at %s", name, mode, installed_path)

            # Persist real Agent backend CLI paths to V2Config so the next
            # ``get_backend_runtime`` reads them directly instead of relying
            # on the resolver's stale-path fallback. Only Agent backends have
            # ``agents.<name>`` config entries to persist into.
            if installed_path and is_agent_backend(name):
                _persist_agent_cli_path(name, installed_path)

            return {
                "ok": True,
                "message": f"{name} {mode}d successfully" if mode == "install" else f"{name} upgraded successfully",
                "path": installed_path,
                "output": output,
                "detection": health,
            }
        if mode == "repair" and result.returncode == 73 and REPAIR_PATH_CONFLICT in raw_output:
            return _cli_repair_refusal(name, conflict=True)
        logger.warning("Agent %s %s failed: %s", name, mode, output)
        return _install_failure_result(
            name,
            mode,
            raw_output,
            truncate_output,
            reason=f"{name}_{mode}_failed",
            exit_code=result.returncode,
        )
    except Exception as e:
        logger.error("Agent %s %s error: %s", name, mode, e)
        # No installer output reached us; the error is the detail.
        return _install_failure_result(
            name,
            mode,
            str(e),
            truncate_output,
            reason=f"{name}_{mode}_error",
            error=str(e),
        )


# =============================================================================
# Local dependencies (askill / avault) — required tools avibe installs for the user
# =============================================================================


_ASKILL_INSTALL_LOCK = threading.Lock()
# The managed askill release. Avibe installs it and upgrades an older askill to
# it; only an explicit repair replaces a newer one.
ASKILL_VERSION = "0.1.15"
# (sha256, size) of each ASKILL_VERSION binary by askill's platform name, from
# the release's GitHub asset digests.
_ASKILL_BINARIES = {
    "darwin-arm64": ("09d333828577bca89c4c842f3a30fb5459f22a78a59db8287512b3653762acb1", 63759842),
    "darwin-x64": ("0f81766bcaf18c05148c403ebe561a3b7f2c0699cadca86fc498b5f812fc97a9", 69484624),
    "linux-arm64": ("e06830ba2170f70e8dc9c5efbe83568f615735c75cca8f6961e45f2fbaf2bc91", 93956240),
    "linux-x64": ("a5ac72faafc0f3f14c36a34c1a2e2beff777a483ad6ce71ee945297f0fa0aa24", 94894208),
    "win32-x64": ("00e1bd471f531bded8504f1c6d79edf900ff9cee7e313bf6528be927e508dfe1", 98781696),
}
_AVAULT_INSTALL_LOCK = threading.Lock()
_AVAULT_AGENT_MANAGER_LOCK = threading.Lock()
_AVAULT_AGENT_MANAGER = None
AVAULT_P2_MIN_VERSION = "0.1.3"
# The released 0.1.3 resident-agent protocol still used scope_type/scope_ref
# delivery frames. The grant_id delivery protocol is intentionally gated on the
# next avault release so upgraded Avibe installs fail closed instead of sending
# new frames to an incompatible resident agent.
AVAULT_GRANT_DELIVERY_MIN_VERSION = "0.1.4"
# Protected-record open requires avault's v2 canonical-JSON record AAD (v0.1.6).
# Older binaries cannot open browser-sealed protected values and fail with
# "open failed for <name>", so protected Vaults must not treat them as ready.
AVAULT_PROTECTED_RECORD_MIN_VERSION = "0.1.6"
# ``deliver fetch`` hands a credential to avault's own HTTPS client. avault 0.1.7
# refreshed that client's trust store (webpki-roots 1.0.10 / rustls-webpki
# 0.103.16) to reject the compromised eMudhra/emSign intermediates, so older
# binaries must not receive credentials for HTTPS egress.
AVAULT_FETCH_TLS_MIN_VERSION = "0.1.7"
# avault 0.1.8 is the first Developer ID signed release. From it on, no
# background Keychain read shows a dialog: one the item does not trust yet
# reports keychain_authorization_required (one-shot exit 77, agent frame
# ``code``), and ``avault key authorize`` is the only verb that may prompt.
# Older binaries have neither, and their background reads may still prompt.
AVAULT_KEYCHAIN_AUTHORIZATION_MIN_VERSION = "0.1.8"
# Installer pin must reference a published release. v0.1.8 is the first
# Developer ID signed release (identifier bot.avibe.avault, Team 68B2SQ6YK3): a
# master key an ad-hoc release created needs one "Authorize avault" after the
# upgrade, and later signed releases read it without asking again.
AVAULT_VERSION = "0.1.8"
# (sha256, size) of each AVAULT_VERSION archive by target, copied from that
# release's manifest.json so the download is verified whichever source served it.
_AVAULT_ARCHIVES = {
    "linux-arm64": ("b22d237b97ab2ed3143f498bebce4affbe6a2617c2d50abcb48c1c668351799f", 3273950),
    "linux-x64": ("6f64d8e089fa859889db53472616a065c9bb3e500b4ad04267bd1b2dd29366e1", 3596395),
    "macos-arm64": ("2dc4b81c4ab3995e519e86854011ee1c38ae9696310d94d1eeaa8d0fe25725bd", 1480823),
    "macos-x64": ("f3c46c612c2bee449d29f9480552437349ba97f9a89f523f2d4d368a4e5a3959", 1643862),
    "windows-arm64": ("0cc42e23e63218f4301b89c527a9109ed02adf6c0e226d1332046e6af0eb4c8f", 1324833),
    "windows-x64": ("5432be1d9e07b3069a1a010f71f885481b72f694175f2b7e46d92162ea6adee3", 1406676),
}


def _avault_archive_url(target: str) -> str:
    return (
        f"https://github.com/avibe-bot/avault/releases/download/v{AVAULT_VERSION}/"
        f"avault-{AVAULT_VERSION}-{target}.tar.gz"
    )


def avault_download_url() -> str | None:
    """The pinned avault archive for this platform, or None without a build."""
    target = _avault_target()[0]
    return _avault_archive_url(target) if target else None


def _download_pinned_release_file(url: str, path: Path, size: int) -> str:
    """Download a pinned release asset (mirror first) to ``path``; return its sha256."""
    fetch_to_path(url, path, timeout=30, size=size)
    digest = hashlib.sha256()
    with path.open("rb") as source:
        while chunk := source.read(1024 * 1024):
            digest.update(chunk)
    return digest.hexdigest()


def _truncate_install_output(output: str, limit: int = 8192) -> str:
    return output if len(output) <= limit else "...(truncated)\n" + output[-limit:]


def _managed_avault_release_satisfies_p2() -> bool:
    return _version_at_least(AVAULT_VERSION, AVAULT_P2_MIN_VERSION)


def _managed_avault_release_satisfies_grant_delivery() -> bool:
    return _version_at_least(AVAULT_VERSION, AVAULT_GRANT_DELIVERY_MIN_VERSION)


def _avault_p2_release_unavailable_result(
    *,
    existing: str | None = None,
    existing_version: str | None = None,
    required: str | None = None,
) -> dict:
    required = required or AVAULT_P2_MIN_VERSION
    return {
        "ok": False,
        "installed": bool(existing),
        "changed": False,
        "path": existing,
        "version": existing_version,
        "status": "upgrade_required",
        "reason": "avault_p2_release_unavailable",
        "message": backend_t(
            "dependencies.avault.p2ReleaseUnavailable",
            pinned=AVAULT_VERSION,
            required=required,
        ),
    }


def _avault_ready_min_version() -> str:
    # Managed avault readiness must satisfy both the resident grant-id delivery
    # protocol and the protected-record v2 AAD open fix; take the higher floor so
    # stale binaries (e.g. 0.1.5) are upgraded/blocked before protected delivery.
    # The fetch TLS floor is deliberately not part of it: only the fetch guards
    # enforce it, so run/inject/grant keep working on an older binary.
    if _version_at_least(AVAULT_PROTECTED_RECORD_MIN_VERSION, AVAULT_GRANT_DELIVERY_MIN_VERSION):
        return AVAULT_PROTECTED_RECORD_MIN_VERSION
    return AVAULT_GRANT_DELIVERY_MIN_VERSION


def _managed_avault_release_satisfies_ready_minimum() -> bool:
    return _version_at_least(AVAULT_VERSION, _avault_ready_min_version())


def _reset_avault_agent_after_binary_change(*, reason: str) -> None:
    from vibe.avault_agent import default_agent_socket_path

    with _AVAULT_AGENT_MANAGER_LOCK:
        manager = _AVAULT_AGENT_MANAGER
    socket_path = manager.socket_path if manager is not None else default_agent_socket_path()
    if manager is not None:
        try:
            manager.reset()
        except Exception:  # noqa: BLE001
            logger.warning("%s: failed to reset resident avault agent after binary change", reason, exc_info=True)
    try:
        _quarantine_resident_agent_socket(socket_path)
    except Exception:  # noqa: BLE001
        logger.warning("%s: failed to quarantine resident avault agent socket after binary change", reason, exc_info=True)


def _askill_platform() -> str | None:
    """askill's release platform name for this host when a build is pinned.

    askill names platforms as Node does (``darwin-arm64``, ``win32-x64``) where
    avault says ``macos-arm64`` and ``windows-x64`` for the same hosts.
    """
    target = _avault_target()[0]
    if target is None:
        return None
    system, _, arch = target.partition("-")
    system = {"macos": "darwin", "windows": "win32"}.get(system, system)
    name = f"{system}-{arch}"
    return name if name in _ASKILL_BINARIES else None


def _askill_binary_url(platform_name: str) -> str:
    suffix = ".exe" if platform_name.startswith("win32-") else ""
    return (
        f"https://github.com/avibe-bot/askill/releases/download/v{ASKILL_VERSION}/"
        f"askill-{platform_name}{suffix}"
    )


def askill_download_url() -> str | None:
    """The pinned askill binary for this platform, or None without a build."""
    platform_name = _askill_platform()
    return _askill_binary_url(platform_name) if platform_name else None


def askill_auto_install_supported() -> bool:
    """Return whether Avibe pins an askill build for this host."""
    return _askill_platform() is not None


def install_askill() -> dict:
    """Install (or refresh) the askill CLI — a required local dependency for Skills.

    Downloads this platform's pinned ``ASKILL_VERSION`` binary, verifies its
    pinned sha256, and atomically installs it where askill's own installer puts
    it: ``~/.local/bin``, the first place ``resolve_cli_path`` looks.
    """
    import tempfile

    platform_name = _askill_platform()
    if platform_name is None:
        platform_label = _avault_target()[1]
        return {
            "ok": False,
            "message": backend_t("dependencies.askill.noBuild", platform=platform_label),
            "reason": "askill_platform_unsupported",
            "platform": platform_label,
            "output": None,
        }
    url = _askill_binary_url(platform_name)
    expected_sha256, size = _ASKILL_BINARIES[platform_name]
    windows = platform_name.startswith("win32-")
    install_path = Path.home() / ".local" / "bin" / ("askill.exe" if windows else "askill")
    try:
        install_path.parent.mkdir(parents=True, exist_ok=True)
        with tempfile.TemporaryDirectory(prefix="askill-install-", dir=install_path.parent) as tmp_dir:
            tmp_path = Path(tmp_dir) / install_path.name
            actual_sha256 = _download_pinned_release_file(url, tmp_path, size)
            if actual_sha256 != expected_sha256:
                return {
                    "ok": False,
                    "message": backend_t("dependencies.askill.checksumMismatch"),
                    "reason": "askill_binary_checksum_mismatch",
                    "expected_sha256": expected_sha256,
                    "actual_sha256": actual_sha256,
                    "platform": platform_name,
                    "url": url,
                    "output": f"expected {expected_sha256}, got {actual_sha256}",
                }
            if not windows:
                tmp_path.chmod(0o755)
            os.replace(tmp_path, install_path)
        _clear_macos_quarantine(install_path)
    except Exception as exc:  # noqa: BLE001
        logger.warning("askill install failed: %s", exc, exc_info=True)
        result = {
            "ok": False,
            "message": backend_t("dependencies.askill.installFailed", error=str(exc)),
            "reason": "askill_install_failed",
            "error": str(exc),
            "platform": platform_name,
            "output": None,
        }
        if isinstance(exc, DependencyNetworkError):
            result["reason"] = "askill_download_failed"
            result["download_error"] = dict(exc.details)
            result["message"] = dependency_error_message(exc.details, label="askill download")
        return result
    return {
        "ok": True,
        "message": backend_t("dependencies.askill.installed", version=ASKILL_VERSION),
        "output": f"Installed askill {ASKILL_VERSION} for {platform_name}",
    }


def ensure_askill_installed(force: bool = False) -> dict:
    """Ensure askill is present. Idempotent — installs only when missing or forced.

    Reports success only when the binary is actually resolvable afterward: an
    installer can exit 0 while leaving the binary on a PATH this service does not
    inherit, and we must not claim "installed" while ``/api/skills`` still
    answers ``askill_not_found``.
    """
    if not _ASKILL_INSTALL_LOCK.acquire(blocking=False):
        return {
            "ok": False,
            "skipped": True,
            "reason": "askill_install_already_running",
            "message": "askill install or update is already running; try again shortly.",
        }
    try:
        existing = resolve_cli_path("askill")
        if existing and not force:
            return {"ok": True, "installed": True, "changed": False, "path": existing}
        result = install_askill()
        resolved = resolve_cli_path("askill")
        installed = bool(resolved)
        result["installed"] = installed
        result["changed"] = installed and bool(result.get("ok"))
        result["path"] = resolved
        if result.get("ok") and not installed:
            result["ok"] = False
            result["reason"] = "askill_install_path_missing"
            result["expected_path"] = "askill"
            result["message"] = (
                result.get("message") or "askill installed but was not found on PATH; restart the service or check PATH."
            )
        return result
    finally:
        _ASKILL_INSTALL_LOCK.release()


def askill_status() -> dict:
    """Report whether askill is installed and its version (best-effort)."""
    path = resolve_cli_path("askill")
    if not path:
        return {"id": "askill", "installed": False, "version": None, "status": "missing", "path": None}
    version: str | None = None
    try:
        proc = subprocess.run(
            [path, "--version"],
            capture_output=True,
            text=True,
            timeout=10,
            env=_command_env_for(path),
            **isolated_subprocess_kwargs(),
        )
        text = (proc.stdout or proc.stderr or "").strip()
        if proc.returncode == 0 and text:
            version = text.split()[-1]
    except Exception:  # noqa: BLE001
        version = None
    return {"id": "askill", "installed": True, "version": version, "status": "ready", "path": path}


def _configured_avault_cli_path() -> str:
    try:
        return str(V2Config.load().agents.avault.cli_path or "avault")
    except Exception:  # noqa: BLE001
        return "avault"


def _resolve_avault_cli_path() -> str | None:
    configured = _configured_avault_cli_path()
    resolved = resolve_cli_path(configured)
    if resolved:
        return resolved
    if configured != "avault":
        return resolve_cli_path("avault")
    return None


def _avault_target() -> tuple[str | None, str]:
    import platform

    system = platform.system()
    machine = platform.machine()
    normalized_system = system.lower()
    normalized_machine = machine.lower()
    platform_label = f"{system or 'unknown'}-{machine or 'unknown'}"

    if normalized_system == "darwin" and normalized_machine == "arm64":
        return "macos-arm64", platform_label
    if normalized_system == "darwin" and normalized_machine in {"x86_64", "amd64"}:
        return "macos-x64", platform_label
    if normalized_system == "linux" and normalized_machine in {"x86_64", "amd64"}:
        return "linux-x64", platform_label
    if normalized_system == "linux" and normalized_machine in {"aarch64", "arm64"}:
        return "linux-arm64", platform_label
    if normalized_system == "windows" and normalized_machine in {"amd64", "x86_64"}:
        return "windows-x64", platform_label
    if normalized_system == "windows" and normalized_machine == "arm64":
        return "windows-arm64", platform_label
    return None, platform_label


def _avault_binary_name_for_target(target: str) -> str:
    return "avault.exe" if target.startswith("windows-") else "avault"


def _avault_managed_bin_path(target: str | None = None) -> Path:
    target = target or (_avault_target()[0] or "")
    # Windows uses the same Avibe-managed bin directory, with the .exe name
    # that _candidate_cli_paths("avault") checks on Windows.
    return Path.home() / ".local" / "bin" / _avault_binary_name_for_target(target)


def _persist_avault_cli_path(path: str) -> None:
    try:
        try:
            load_config()
        except FileNotFoundError:
            save_config({})
        from config.v2_config import update_config_fields

        def _apply_avault_cli_path(cfg) -> None:
            # Read-decide-write INSIDE the transaction (#1458 stage ③).
            previous = getattr(cfg.agents.avault, "cli_path", "") or ""
            if previous != path:
                cfg.agents.avault.cli_path = path
                logger.info(
                    "install_avault: updated V2Config cli_path: %s -> %s",
                    previous or "<unset>",
                    path,
                )

        update_config_fields(_apply_avault_cli_path)
    except Exception as exc:
        logger.warning("install_avault: failed to persist cli_path: %s", exc)
        raise


def _extract_avault_binary(archive_bytes: bytes, output_path: Path, member_name: str = "avault") -> None:
    import io
    import tarfile

    output_real = output_path.parent.resolve()
    with tarfile.open(fileobj=io.BytesIO(archive_bytes), mode="r:gz") as archive:
        member = next((item for item in archive.getmembers() if item.name == member_name), None)
        if member is None or not member.isfile():
            raise ValueError("archive does not contain the avault executable")
        target = (output_path.parent / member.name).resolve()
        if target.parent != output_real or target.name != member_name:
            raise ValueError("archive contains an unsafe avault path")
        source = archive.extractfile(member)
        if source is None:
            raise ValueError("archive does not contain readable avault data")
        with output_path.open("wb") as out:
            shutil.copyfileobj(source, out)


def _clear_macos_quarantine(path: Path) -> None:
    if os.sys.platform != "darwin":
        return
    try:
        os.removexattr(path, "com.apple.quarantine")
    except (AttributeError, FileNotFoundError, OSError):
        pass


def install_avault(force: bool = False) -> dict:
    """Install (or refresh) avault, the required local custody-core dependency.

    Downloads the Avibe-pinned avault release archive, verifies its pinned
    sha256, safely extracts the single ``avault`` member, and atomically
    installs it into Avibe's managed CLI location.
    """
    path = _resolve_avault_cli_path()
    if path and not force:
        existing_version = _probe_avault_version(path)
        return {
            "ok": True,
            "message": backend_t("dependencies.avault.ready"),
            "output": None,
            "path": path,
            "version": existing_version,
        }

    import tempfile

    target, platform_label = _avault_target()
    if target is None:
        if path:
            existing_version = _probe_avault_version(path)
            return {
                "ok": True,
                "message": backend_t("dependencies.avault.ready"),
                "output": None,
                "path": path,
                "version": existing_version,
                "changed": False,
            }
        return {
            "ok": False,
            "message": backend_t("dependencies.avault.noBuild", platform=platform_label),
            "reason": "avault_platform_unsupported",
            "platform": platform_label,
            "output": None,
            "path": None,
        }

    try:
        expected_sha256, size = _AVAULT_ARCHIVES[target]
        archive_url = _avault_archive_url(target)
        member_name = _avault_binary_name_for_target(target)
        install_path = _avault_managed_bin_path(target)
        install_path.parent.mkdir(parents=True, exist_ok=True)
        with tempfile.TemporaryDirectory(prefix="avault-install-", dir=install_path.parent) as tmp_dir:
            archive_path = Path(tmp_dir) / "avault.tar.gz"
            actual_sha256 = _download_pinned_release_file(archive_url, archive_path, size)
            if actual_sha256 != expected_sha256:
                return {
                    "ok": False,
                    "message": backend_t("dependencies.avault.checksumMismatch"),
                    "reason": "avault_checksum_mismatch",
                    "expected_sha256": expected_sha256,
                    "actual_sha256": actual_sha256,
                    "platform": target,
                    "url": archive_url,
                    "output": f"expected {expected_sha256}, got {actual_sha256}",
                    "path": None,
                }
            tmp_path = Path(tmp_dir) / member_name
            _extract_avault_binary(archive_path.read_bytes(), tmp_path, member_name)
            if not target.startswith("windows-"):
                tmp_path.chmod(0o755)
            os.replace(tmp_path, install_path)
        if not target.startswith("windows-"):
            install_path.chmod(0o755)
            _clear_macos_quarantine(install_path)
        _persist_avault_cli_path(str(install_path))
        _reset_avault_agent_after_binary_change(reason="install_avault")
        if path:
            _check_avault_keychain_authorization_after_upgrade()

        return {
            "ok": True,
            "message": backend_t("dependencies.avault.installed", version=AVAULT_VERSION),
            "output": f"Installed avault {AVAULT_VERSION} for {target}",
            "path": str(install_path),
            "changed": True,
        }
    except Exception as exc:  # noqa: BLE001
        logger.warning("avault install failed: %s", exc, exc_info=True)
        result = {
            "ok": False,
            "message": backend_t("dependencies.avault.installFailed", error=str(exc)),
            "reason": "avault_install_failed",
            "error": str(exc),
            "platform": platform_label,
            "output": None,
            "path": None,
        }
        if isinstance(exc, DependencyNetworkError):
            result["reason"] = "avault_download_failed"
            result["download_error"] = dict(exc.details)
            result["message"] = dependency_error_message(exc.details, label="avault download")
        return result


def ensure_avault_installed(force: bool = False) -> dict:
    """Ensure avault is present.

    The dependency manager keeps Avibe's default avault at the resident delivery
    protocol minimum. Older P2 binaries can still handle some one-shot commands,
    but they are not ready for the protected Vaults surfaces that share this
    managed dependency.
    """
    if not _AVAULT_INSTALL_LOCK.acquire(blocking=False):
        return {
            "ok": False,
            "skipped": True,
            "reason": "avault_install_already_running",
            "message": backend_t("dependencies.avault.alreadyRunning"),
        }
    try:
        existing = _resolve_avault_cli_path()
        existing_version = _probe_avault_version(existing) if existing else None
        ready_minimum = _avault_ready_min_version()
        existing_is_ready = _version_at_least(existing_version, ready_minimum)
        can_managed_install_ready = _managed_avault_release_satisfies_ready_minimum()
        # Never downgrade: keep an existing binary that is strictly newer than the
        # managed pin, even under ``force``. ``force`` may still reinstall an equal
        # or older managed version to repair a binary, but it must not replace a
        # newer user/custom avault (e.g. 0.1.6) with the older managed release. A
        # genuinely broken binary can't report a version, so it isn't matched here
        # and still gets repaired below.
        existing_newer_than_pin = (
            existing_is_ready
            and _version_at_least(existing_version, AVAULT_VERSION)
            and not _version_at_least(AVAULT_VERSION, existing_version)
        )
        if existing and existing_newer_than_pin:
            return {
                "ok": True,
                "installed": True,
                "changed": False,
                "path": existing,
                "version": existing_version,
            }
        if existing and not existing_is_ready and force and not can_managed_install_ready:
            return _avault_p2_release_unavailable_result(
                existing=existing,
                existing_version=existing_version,
                required=ready_minimum,
            )
        if existing and (
            (existing_is_ready and (not force or not can_managed_install_ready))
            or (not existing_is_ready and not force and not can_managed_install_ready)
        ):
            return {
                "ok": True,
                "installed": True,
                "changed": False,
                "path": existing,
                "version": existing_version,
            }
        needs_upgrade = bool(existing and not existing_is_ready and can_managed_install_ready)
        result = install_avault(force=force or needs_upgrade)
        resolved = _resolve_avault_cli_path()
        installed = bool(resolved)
        resolved_version = _probe_avault_version(resolved) if resolved else None
        result["installed"] = installed
        result["version"] = resolved_version
        if "changed" not in result:
            result["changed"] = installed and bool(result.get("ok")) and (not existing or force or needs_upgrade)
        result["path"] = resolved
        if result.get("ok") and not installed:
            result["ok"] = False
            result["reason"] = "avault_install_path_missing"
            result["expected_path"] = "avault"
            result["message"] = (
                result.get("message") or backend_t("dependencies.avault.installedNotFound")
            )
        elif result.get("ok") and not _version_at_least(resolved_version, ready_minimum):
            result["status"] = "upgrade_required"
        return result
    finally:
        _AVAULT_INSTALL_LOCK.release()


def _probe_avault_version(path: str | None) -> str | None:
    if not path:
        return None
    try:
        proc = subprocess.run(
            [path, "version"],
            capture_output=True,
            text=True,
            timeout=10,
            env=_command_env_for(path),
            **isolated_subprocess_kwargs(),
        )
        text = (proc.stdout or proc.stderr or "").strip()
        if proc.returncode == 0 and text:
            return text.split()[-1]
    except Exception:  # noqa: BLE001
        return None
    return None


def refresh_avault_if_stale() -> dict:
    """Bring avault to the managed pin, installing only when that changes it.

    Sibling of ``refresh_askill_if_stale`` for the version-pinned dependency, so
    both managed local deps answer "am I current?" before paying for an install.
    The wanted version is ``AVAULT_VERSION`` rather than an upstream latest, so
    the staleness question is answered locally with no download at all.

    ``force`` on ``ensure_avault_installed`` stays a repair verb — it reinstalls
    an equal or older managed release on purpose — so callers that only want the
    pin satisfied come here instead of charging every call a ~20s reinstall of
    the release that is already on disk.

    Skipping the install may never report a healthier state than forcing it
    would. Being at the pin is not the whole of being current: when the
    readiness floor is raised ahead of the published pin, a binary equal to
    ``AVAULT_VERSION`` is still ``upgrade_required``, and only the forced path
    surfaces that release gap. So the question is asked of the status as a
    whole, not of the version alone.
    """
    status = avault_status()
    current = (
        bool(status.get("installed"))
        and status.get("status") == "ready"
        and _version_at_least(status.get("version"), AVAULT_VERSION)
    )
    return ensure_avault_installed(force=not current)


def avault_status() -> dict:
    """Report whether avault is installed and its version (best-effort)."""
    path = _resolve_avault_cli_path()
    if not path:
        return {"id": "avault", "installed": False, "version": None, "status": "missing", "path": None}
    version = _probe_avault_version(path)
    status = "ready" if _version_at_least(version, _avault_ready_min_version()) else "upgrade_required"
    return {"id": "avault", "installed": True, "version": version, "status": status, "path": path}


def _version_at_least(current: str | None, minimum: str) -> bool:
    if not current:
        return False
    try:
        from packaging.version import InvalidVersion, Version

        try:
            return Version(current) >= Version(minimum)
        except InvalidVersion:
            pass
    except Exception:  # pragma: no cover - packaging is a transitive dep
        pass

    def _parts(value: str) -> tuple[int, ...] | None:
        core = value.split("+", 1)[0].split("-", 1)[0]
        try:
            return tuple(int(part) for part in core.split("."))
        except ValueError:
            return None

    cur_parts = _parts(current)
    min_parts = _parts(minimum)
    if cur_parts is None or min_parts is None:
        return False
    width = max(len(cur_parts), len(min_parts))
    return cur_parts + (0,) * (width - len(cur_parts)) >= min_parts + (0,) * (width - len(min_parts))


def _require_avault_min_version(feature: str, minimum: str, *, managed_available: bool) -> None:
    status = avault_status()
    if not status.get("installed"):
        raise AvaultPreHandoffError(f"avault is required for {feature}")
    version = status.get("version")
    if not _version_at_least(version, minimum):
        detail = f"{feature} requires avault >= {minimum}; installed {version or 'unknown'}"
        if not managed_available:
            detail = f"{detail}; managed avault install is pinned to {AVAULT_VERSION}"
        raise AvaultPreHandoffError(detail)


def _require_avault_p2_surface(feature: str) -> None:
    _require_avault_min_version(
        feature,
        AVAULT_P2_MIN_VERSION,
        managed_available=_managed_avault_release_satisfies_p2(),
    )


def _require_avault_grant_delivery_surface(feature: str) -> None:
    # Guards protected grant/deliver operations that OPEN a protected record via
    # avault (resident-agent grant, agent binding, deliver run/fetch/inject; all
    # protected-only). These need the full Vaults-ready floor -- the grant-id
    # protocol AND the protected-record v2 AAD open fix -- since a binary that
    # clears only the old protocol minimum still fails protected open
    # ("open failed"). Release/revoke does NOT open a record and stays on
    # _require_avault_grant_protocol_surface() to avoid destructive cleanup.
    _require_avault_min_version(
        feature,
        _avault_ready_min_version(),
        managed_available=_managed_avault_release_satisfies_ready_minimum(),
    )


def _require_avault_grant_protocol_surface(feature: str) -> None:
    # Grant-lifecycle operations that do NOT open a protected record (release /
    # revoke) only need the grant-id delivery protocol, not the protected-record
    # v2 AAD fix. Gating them on the 0.1.6 floor would reject the release frame on
    # a host still on 0.1.4/0.1.5 and push cleanup into the destructive
    # release-failure path (resetting the resident agent + expiring active grants)
    # instead of revoking just the requested grant.
    _require_avault_min_version(
        feature,
        AVAULT_GRANT_DELIVERY_MIN_VERSION,
        managed_available=_managed_avault_release_satisfies_grant_delivery(),
    )


def _require_avault_fetch_surface(feature: str, *, floor: str | None = None) -> None:
    # Fetch egress needs the refreshed TLS trust on top of whatever floor the
    # path already requires (the resident path also opens a protected record).
    minimum = AVAULT_FETCH_TLS_MIN_VERSION
    if floor and not _version_at_least(minimum, floor):
        minimum = floor
    _require_avault_min_version(
        feature,
        minimum,
        managed_available=_version_at_least(AVAULT_VERSION, minimum),
    )


# ---------------------------------------------------------------------------
# avault client — Avibe's only path to value cryptography.
#
# Every Vaults value operation (seal on create, deliver on use, key backup) is a
# one-shot ``avault`` subprocess. Plaintext/keys flow only INTO avault via stdin;
# avault returns ciphertext, a delivery exit code, an HTTP response, or a written
# file — never plaintext. The daemon never holds the master key and never decrypts.
# (Design: avibe docs/plans/avault-custody-core.md §18; verbs: avault/docs/DESIGN.md.)
# ---------------------------------------------------------------------------

# avibe's wait must outlast avault's own fetch timeout (10s connect + 30s total).
_AVAULT_TIMEOUT_SECONDS = 20.0
_AVAULT_FETCH_TIMEOUT_SECONDS = 60.0
_AVAULT_STORE = "file"
_AVAULT_LINUX_TPM_DEVICE_PATHS = (Path("/dev/tpm0"), Path("/dev/tpmrm0"))


class AvaultError(Exception):
    """An ``avault`` invocation failed. Messages never carry secret material —
    avault is designed to keep secrets out of its stdout/stderr and errors."""


class AvaultPreHandoffError(AvaultError):
    """avault failed before receiving an envelope or performing delivery."""


class AvaultStaleLoginSessionError(AvaultError):
    """The Avibe process outlived the macOS login session that owns its user services."""

    code = "stale_login_session"


class AvaultStaleLoginSessionBeforeHandoffError(AvaultStaleLoginSessionError, AvaultPreHandoffError):
    """The stale-session check stopped a Vault operation before any handoff."""


class AvaultAuthorizationRequiredError(AvaultError):
    """macOS Keychain has not yet approved this avault binary for the master key.

    The user fixes it once with an explicit "Authorize avault" action; retrying
    the call cannot. One-shot ``deliver run`` raises this class itself, because
    it cannot prove its child never ran, so that delivery stays fail-closed.
    """

    code = "avault_authorization_required"


class AvaultAuthorizationRequiredBeforeHandoffError(AvaultAuthorizationRequiredError, AvaultPreHandoffError):
    """avault could not load the master key, so nothing was decrypted, delivered, or signed."""


# One-shot exit status for keychain_authorization_required (avault 0.1.8+, EX_NOPERM).
_AVAULT_EXIT_AUTHORIZATION_REQUIRED = 77
# ``avault key authorize`` waits for a person to reach the Mac and answer the dialog.
_AVAULT_AUTHORIZE_TIMEOUT_SECONDS = 600.0
_AVAULT_AUTHORIZE_DETAIL_LIMIT = 500


def _avault_authorization_required(
    detail: str | None = None,
    *,
    before_handoff: bool = True,
) -> AvaultAuthorizationRequiredError:
    avault_authorization.record_authorization_required()
    error = AvaultAuthorizationRequiredBeforeHandoffError if before_handoff else AvaultAuthorizationRequiredError
    return error(detail or "avault needs a one-time macOS Keychain authorization on the Mac running Avibe")


def _avault_detail(proc: "subprocess.CompletedProcess") -> str:
    """Best-effort, secret-free detail from a failed avault run (its stderr)."""
    raw = proc.stderr
    if isinstance(raw, bytes):
        raw = raw.decode("utf-8", "replace")
    return (raw or "").strip()


def _require_avault_path() -> str:
    path = _resolve_avault_cli_path()
    if not path:
        raise AvaultPreHandoffError(backend_t("dependencies.avault.missing"))
    return path


def _avault_agent_client():
    return _avault_agent_manager().client()


def _avault_agent_manager():
    from vibe.avault_agent import AvaultAgentManager

    global _AVAULT_AGENT_MANAGER
    with _AVAULT_AGENT_MANAGER_LOCK:
        if _AVAULT_AGENT_MANAGER is None:
            _AVAULT_AGENT_MANAGER = AvaultAgentManager(
                binary_resolver=_require_avault_path,
                command_env=_command_env_for,
            )
        manager = _AVAULT_AGENT_MANAGER
    return manager


def _avault_store_args() -> list[str]:
    if platform.system().lower() != "linux":
        return []
    if any(path.exists() for path in _AVAULT_LINUX_TPM_DEVICE_PATHS):
        return []
    return ["--store", _AVAULT_STORE]


def _avault_args(args: list[str]) -> list[str]:
    return [*_avault_store_args(), *args]


def _run_avault(
    args: list[str],
    *,
    stdin: bytes | None = None,
    timeout: float = _AVAULT_TIMEOUT_SECONDS,
) -> "subprocess.CompletedProcess":
    """Run a capturing one-shot avault command. Bulk blobs go via ``stdin``.

    Every capturing verb loads the master key first, so exit 77 here is always
    avault's keychain_authorization_required (older releases exit 70 for every
    failure) and success shows the key is readable.
    """
    path = _require_avault_path()
    try:
        proc = subprocess.run(
            [path, *_avault_args(args)],
            input=stdin,
            capture_output=True,
            timeout=timeout,
            env=_command_env_for(path),
            **isolated_subprocess_kwargs(),
        )
    except FileNotFoundError as exc:
        raise AvaultPreHandoffError("avault binary not found") from exc
    except subprocess.TimeoutExpired as exc:
        raise AvaultError("avault timed out") from exc
    if proc.returncode != 0 and macos_login_session_state() == "stale_login_session":
        error = (
            AvaultStaleLoginSessionBeforeHandoffError
            if proc.returncode == _AVAULT_EXIT_AUTHORIZATION_REQUIRED
            else AvaultStaleLoginSessionError
        )
        raise error(backend_t("errors.staleLoginSession"))
    if proc.returncode == _AVAULT_EXIT_AUTHORIZATION_REQUIRED:
        raise _avault_authorization_required(_avault_detail(proc))
    if proc.returncode == 0:
        avault_authorization.clear_authorization_required()
    return proc


def _raise_if_agent_authorization_required(exc: Exception) -> None:
    """Re-raise a resident-agent ``keychain_authorization_required`` frame as Avibe's error."""
    from vibe.avault_agent import AvaultAgentAuthorizationRequiredError

    if isinstance(exc, AvaultStaleLoginSessionError):
        raise
    if macos_login_session_state() == "stale_login_session":
        error = (
            AvaultStaleLoginSessionBeforeHandoffError
            if isinstance(exc, AvaultAgentAuthorizationRequiredError) or _avault_agent_error_is_absent(str(exc))
            else AvaultStaleLoginSessionError
        )
        raise error(backend_t("errors.staleLoginSession")) from exc
    if isinstance(exc, AvaultAgentAuthorizationRequiredError):
        raise _avault_authorization_required(str(exc)) from exc


def _avault_supports_keychain_authorization(path: str | None) -> bool:
    return _version_at_least(_probe_avault_version(path), AVAULT_KEYCHAIN_AUTHORIZATION_MIN_VERSION)


def _avault_master_key_needs_authorization() -> bool | None:
    """Ask avault, without any prompt, whether it can read the master key.

    Runs one-shot ``pubkey``, which loads the master key (and, like the first
    Vault use, creates it when none exists). True means authorization is
    required, False that the key loaded, None that the check failed otherwise.
    Callers must gate this on AVAULT_KEYCHAIN_AUTHORIZATION_MIN_VERSION: an
    older binary's background read may still prompt.
    """
    try:
        _run_avault(["pubkey"])
    except AvaultAuthorizationRequiredError:
        return True
    except AvaultError:
        logger.warning("avault master-key check failed", exc_info=True)
        return None
    return False


def _check_avault_keychain_authorization_after_upgrade() -> None:
    """Record, without prompting, whether the binary just installed needs authorization.

    A Developer ID avault cannot read a master key an ad-hoc release created
    until the user authorizes it once, so look right after replacing the binary
    and let the Web UI offer the action before a real Vault call fails.
    """
    if platform.system() != "Darwin":
        return
    try:
        if not _avault_supports_keychain_authorization(_resolve_avault_cli_path()):
            return
        _avault_master_key_needs_authorization()
    except Exception:  # noqa: BLE001 - the install already succeeded
        logger.warning("install_avault: avault Keychain authorization check failed", exc_info=True)


def _envelope_payload(sealed) -> dict:
    """Serialize a stored envelope for an avault stdin request (no plaintext)."""
    return {"ciphertext": sealed.ciphertext, "nonce": sealed.nonce, "wrap_meta": sealed.wrap_meta}


def avault_pubkey() -> dict:
    """Return avault's blind-box public key + fingerprint."""
    _require_avault_p2_surface("blind-box pubkey")
    proc = _run_avault(["pubkey"])
    if proc.returncode != 0:
        raise AvaultError(_avault_detail(proc) or "avault pubkey failed")
    try:
        payload = json.loads(proc.stdout)
    except (ValueError, TypeError) as exc:
        raise AvaultError("avault pubkey returned malformed output") from exc
    public_key = payload.get("public_key")
    fingerprint = payload.get("fingerprint")
    if not isinstance(public_key, str) or not isinstance(fingerprint, str) or not public_key or not fingerprint:
        raise AvaultError("avault pubkey returned malformed output")
    return {"public_key": public_key, "fingerprint": fingerprint}


def avault_agent_pubkey() -> dict:
    """Return the resident agent's ephemeral blind-box public key."""
    from vibe.avault_agent import AvaultAgentError

    _require_avault_p2_surface("resident agent pubkey")
    try:
        payload = _avault_agent_client().pubkey()
    except AvaultAgentError as exc:
        _raise_if_agent_authorization_required(exc)
        raise AvaultError(str(exc)) from exc
    public_key = payload.get("public_key")
    fingerprint = payload.get("fingerprint")
    if not isinstance(public_key, str) or not isinstance(fingerprint, str) or not public_key or not fingerprint:
        raise AvaultError("avault agent pubkey returned malformed output")
    return {"public_key": public_key, "fingerprint": fingerprint}


def avault_seal_blind_box(name_or_blind_box, blind_box: dict | None = None):
    """Relay a browser HPKE blind box to ``avault seal --blind-box``.

    ``avault`` requires the secret name for AAD binding. For convenience, callers may
    pass ``(name, blind_box)`` or a single object containing ``name`` and ``blind_box``.
    """
    from storage.vault_crypto import Sealed

    if blind_box is None:
        if not isinstance(name_or_blind_box, dict):
            raise AvaultError("blind-box request must be an object")
        request = name_or_blind_box
        name = str(request.get("name") or "")
        if isinstance(request.get("blind_box"), dict):
            blind_box = request["blind_box"]
        else:
            blind_box = {key: request[key] for key in ("scheme", "enc", "ct") if key in request}
    else:
        name = str(name_or_blind_box or "")
    if not name:
        raise AvaultError("secret name is required for blind-box seal")
    _require_avault_p2_surface("blind-box seal")
    body = json.dumps(blind_box).encode("utf-8")
    proc = _run_avault(["seal", "--name", name, "--blind-box"], stdin=body)
    if proc.returncode != 0:
        raise AvaultError(_avault_detail(proc) or "avault blind-box seal failed")
    try:
        payload = json.loads(proc.stdout)
        return Sealed(
            ciphertext=payload["ciphertext"],
            nonce=payload["nonce"],
            wrap_meta=payload["wrap_meta"],
        )
    except (ValueError, KeyError, TypeError) as exc:
        raise AvaultError("avault blind-box seal returned malformed output") from exc


def avault_sign(
    key_envelope,
    digest: str,
    scheme: str,
    *,
    name: str | None = None,
) -> dict:
    """Ask avault to sign a caller-computed 32-byte digest with a local key envelope."""
    if not name:
        raise AvaultError("secret name is required for avault sign")
    _require_avault_p2_surface("vault signing")
    body = json.dumps(
        {
            "name": name,
            "key_envelope": _envelope_payload(key_envelope),
            "digest": digest,
            "scheme": scheme,
        }
    ).encode("utf-8")
    proc = _run_avault(["sign"], stdin=body)
    if proc.returncode != 0:
        raise AvaultError(_avault_detail(proc) or "avault sign failed")
    try:
        payload = json.loads(proc.stdout)
    except (ValueError, TypeError) as exc:
        raise AvaultError("avault sign returned malformed output") from exc
    signature = payload.get("signature")
    if not isinstance(signature, str) or not signature:
        raise AvaultError("avault sign returned malformed output")
    return {"signature": signature, "recovery_id": payload.get("recovery_id")}


def avault_deliver_run(secrets: list[dict], command: list[str]) -> dict:
    """Run ``command`` with the secrets injected as env vars, inside avault.

    ``secrets`` is ``[{"name": <secret name>, "env": <env var>, "envelope": <Sealed>}]``.
    avault decrypts, spawns the child with that env, waits, and zeroizes — the
    plaintext never returns here. The child inherits this process's stdio so its
    output passes through; the run-secrets JSON (envelopes only, no plaintext)
    goes on avault's stdin to stay out of ``ps``. Returns the child's exit code
    (``128 + signal`` if signalled). Delivery is fail-closed: once avault returns
    an exit code, callers must treat the secret as handed to the child unless a
    future avault protocol provides a distinct pre-handoff failure signal.
    keychain_authorization_required is not one here: 77 may be the child's own
    status, so it is raised as ``AvaultAuthorizationRequiredError`` (still
    fail-closed) only when ``_deliver_run_needed_authorization`` confirms it.
    """
    if macos_login_session_state() == "stale_login_session":
        raise AvaultStaleLoginSessionBeforeHandoffError(backend_t("errors.staleLoginSession"))
    path = _require_avault_path()
    payload = json.dumps(
        [
            {"name": s["name"], "env": s["env"], "envelope": _envelope_payload(s["envelope"])}
            for s in secrets
        ]
    ).encode("utf-8")
    try:
        proc = subprocess.Popen(
            [path, *_avault_args(["deliver", "run"]), "--", *command],
            stdin=subprocess.PIPE,
            env=_command_env_for(path),
            **isolated_subprocess_kwargs(),
        )
    except FileNotFoundError as exc:
        raise AvaultError("avault binary not found") from exc
    try:
        assert proc.stdin is not None
        proc.stdin.write(payload)
        proc.stdin.close()
    except (BrokenPipeError, OSError):
        # avault exited before reading stdin (e.g. bad request); fall through to wait()
        # which surfaces its exit code.
        pass
    exit_code = proc.wait()
    if exit_code == _AVAULT_EXIT_AUTHORIZATION_REQUIRED and _deliver_run_needed_authorization(path):
        raise _avault_authorization_required(before_handoff=False)
    return {"exit_code": exit_code, "delivered": True}


def _deliver_run_needed_authorization(path: str) -> bool:
    """Whether one-shot ``deliver run``'s exit 77 most likely was avault's own.

    ``deliver run`` exits with its child's status, so 77 alone is ambiguous. A
    fresh master-key check that also needs authorization makes avault's own
    failure the likely cause, but it cannot prove that no child ran (the
    Keychain may have locked while one did), so callers keep the delivery
    fail-closed and only report the authorization the user must give.
    """
    return _avault_supports_keychain_authorization(path) and _avault_master_key_needs_authorization() is True


def _agent_secret_payload(secret: dict, *, target_field: str) -> dict:
    payload = {
        "name": secret["name"],
        target_field: secret[target_field],
        "envelope": _envelope_payload(secret["envelope"]),
    }
    tier = secret.get("tier")
    if tier is not None:
        payload["tier"] = tier
    return payload


def avault_agent_grant(
    *,
    grant_id: str,
    purpose: str,
    ttl_secs: int,
    deks: list[dict],
    expected_pubkey: dict | None = None,
) -> dict:
    """Cache browser-released protected DEKs in the resident agent."""
    from vibe.avault_agent import AvaultAgentError

    _require_avault_grant_delivery_surface("resident agent grant")
    validate_avault_agent_pubkey(expected_pubkey)
    try:
        return _avault_agent_client().grant(
            grant_id=grant_id,
            purpose="deliver",
            ttl_secs=ttl_secs,
            deks=deks,
        )
    except AvaultAgentError as exc:
        _raise_if_agent_authorization_required(exc)
        raise AvaultError(str(exc)) from exc


def validate_avault_agent_pubkey(expected_pubkey: dict | None) -> None:
    """Fail before DB approval if the browser sealed to a stale resident key."""
    if expected_pubkey is None:
        return
    current = avault_agent_pubkey()
    expected_fingerprint = expected_pubkey.get("fingerprint")
    if expected_fingerprint and expected_fingerprint != current.get("fingerprint"):
        raise AvaultError("avault agent pubkey fingerprint mismatch")
    expected_public_key = expected_pubkey.get("public_key")
    if expected_public_key and expected_public_key != current.get("public_key"):
        raise AvaultError("avault agent public key mismatch")


def avault_agent_release(*, grant_id: str) -> dict:
    """Drop a resident-agent protected grant if present."""
    from vibe.avault_agent import AvaultAgentClient, AvaultAgentError

    _require_avault_grant_protocol_surface("resident agent release")
    try:
        return AvaultAgentClient(_avault_agent_manager().socket_path, timeout=1.0).release(grant_id=grant_id)
    except AvaultAgentError as exc:
        _raise_if_agent_authorization_required(exc)
        raise AvaultError(str(exc)) from exc


def _agent_release_failure_is_absent(exc: AvaultError) -> bool:
    detail = str(exc).lower()
    return _avault_agent_error_is_absent(detail)


def _avault_agent_error_is_absent(detail: str) -> bool:
    text = detail.lower()
    return (
        "failed to connect to avault agent" in text
        and (
            "no such file" in text
            or "connection refused" in text
            or "errno 2" in text
            or "errno 61" in text
            or "errno 111" in text
        )
    )


def _quarantine_resident_agent_socket(path: Path) -> None:
    try:
        mode = path.lstat().st_mode
    except FileNotFoundError:
        return
    if stat.S_ISSOCK(mode):
        path.unlink(missing_ok=True)


def _fail_closed_resident_agent_after_release_failure() -> None:
    from storage import vault_service

    manager = _avault_agent_manager()
    manager.reset()
    _quarantine_resident_agent_socket(manager.socket_path)
    engine = _vault_engine()
    with engine.begin() as conn:
        vault_service.expire_active_grants(
            conn,
            reason="grant-expired-agent-cache-reset",
        )


def _release_failed_grant_scope(grant_id: str, *, reason: str) -> None:
    try:
        release_vault_agent_scopes([{"grant_id": grant_id}], reason=reason)
    except AvaultError:
        logger.warning(
            "%s: failed to clear resident agent scope after failed grant relay",
            reason,
            exc_info=True,
        )


def release_vault_agent_scopes(scopes: list[dict[str, str]], *, reason: str) -> None:
    seen: set[str] = set()
    for scope in scopes:
        grant_id = str(scope.get("grant_id") or "")
        if not grant_id:
            continue
        if grant_id in seen:
            continue
        seen.add(grant_id)
        try:
            avault_agent_release(grant_id=grant_id)
        except AvaultError as exc:
            if _agent_release_failure_is_absent(exc):
                logger.debug("%s: resident agent absent while releasing grant %s", reason, grant_id)
                continue
            try:
                _fail_closed_resident_agent_after_release_failure()
            except OSError as reset_exc:
                raise AvaultError("failed to clear resident agent after release failure") from reset_exc
            logger.warning(
                "%s: release failed for resident agent grant %s; reset resident agent cache",
                reason,
                grant_id,
                exc_info=True,
            )


def avault_agent_deliver_run(
    *,
    grant_id: str,
    secrets: list[dict],
    command: list[str],
    context: dict | None = None,
) -> dict:
    """Run a child under a protected grant. Plaintext stays inside avault."""
    from vibe.avault_agent import AvaultAgentError

    _require_avault_grant_delivery_surface("resident agent deliver run")
    try:
        result = _avault_agent_manager().client(timeout=None).deliver_run(
            grant_id=grant_id,
            command=command,
            secrets=[_agent_secret_payload(secret, target_field="env") for secret in secrets],
            context=context,
        )
    except AvaultAgentError as exc:
        _raise_if_agent_authorization_required(exc)
        if _avault_agent_error_is_absent(str(exc)):
            raise AvaultPreHandoffError(str(exc)) from exc
        raise AvaultError(str(exc)) from exc
    try:
        exit_code = int(result["exit_code"])
    except (KeyError, TypeError, ValueError) as exc:
        raise AvaultError("avault agent deliver run returned malformed output") from exc
    return {"exit_code": exit_code}


def avault_agent_deliver_fetch(
    *,
    grant_id: str,
    name: str,
    sealed,
    request: dict,
    context: dict | None = None,
) -> dict:
    """Broker an HTTP request under a protected grant."""
    from vibe.avault_agent import AvaultAgentError

    _require_avault_fetch_surface("resident agent deliver fetch", floor=_avault_ready_min_version())
    manager = _avault_agent_manager()
    if not manager.serves_current_binary():
        # The version check above probed the executable on disk; a resident agent
        # started from an older binary must not receive the credential. Drop it and
        # its DEK cache (expiring the grants it held) so the request is approved
        # again against an agent running the current binary.
        _fail_closed_resident_agent_after_release_failure()
        raise AvaultPreHandoffError(
            "resident avault agent predates the installed avault binary; "
            "the grant is missing or expired and must be approved again"
        )
    try:
        return manager.client(timeout=_AVAULT_FETCH_TIMEOUT_SECONDS).deliver_fetch(
            grant_id=grant_id,
            name=name,
            envelope=_envelope_payload(sealed),
            request=request,
            context=context,
        )
    except AvaultAgentError as exc:
        _raise_if_agent_authorization_required(exc)
        if _avault_agent_error_is_absent(str(exc)):
            raise AvaultPreHandoffError(str(exc)) from exc
        raise AvaultError(str(exc)) from exc


def avault_agent_deliver_inject(
    *,
    grant_id: str,
    path: str,
    fmt: str,
    secrets: list[dict],
) -> None:
    """Render a protected-grant secret file inside avault."""
    from vibe.avault_agent import AvaultAgentError

    _require_avault_grant_delivery_surface("resident agent deliver inject")
    try:
        result = _avault_agent_client().deliver_inject(
            grant_id=grant_id,
            path=str(path),
            fmt=fmt,
            secrets=[_agent_secret_payload(secret, target_field="key") for secret in secrets],
        )
    except AvaultAgentError as exc:
        _raise_if_agent_authorization_required(exc)
        if _avault_agent_error_is_absent(str(exc)):
            raise AvaultPreHandoffError(str(exc)) from exc
        raise AvaultError(str(exc)) from exc
    if result.get("ok") is not True:
        raise AvaultError("avault agent inject returned malformed output")


def avault_deliver_fetch(name: str, sealed, request: dict) -> dict:
    """Broker an HTTP request inside avault with the secret injected at egress.

    ``request`` must include ``allowed_hosts`` (avault rejects the target otherwise).
    Returns ``{"status", "headers", "body"}`` — the response only, never the secret.
    """
    _require_avault_fetch_surface("deliver fetch")
    body = json.dumps(
        {"name": name, "envelope": _envelope_payload(sealed), "request": request}
    ).encode("utf-8")
    proc = _run_avault(["deliver", "fetch"], stdin=body, timeout=_AVAULT_FETCH_TIMEOUT_SECONDS)
    # avault exits 0 for 2xx and 1 for a non-2xx HTTP status; both still emit the
    # response JSON. Any higher code is an avault-level failure (no response).
    if proc.returncode not in (0, 1):
        raise AvaultError(_avault_detail(proc) or "avault fetch failed")
    try:
        return json.loads(proc.stdout)
    except (ValueError, TypeError) as exc:
        raise AvaultError("avault fetch returned malformed output") from exc


def avault_deliver_inject(path: str, fmt: str, secrets: list[dict]) -> None:
    """Render the secrets to a 0600 file at ``path`` (dotenv/json) inside avault.

    ``secrets`` is ``[{"name": <secret name>, "key": <file key>, "envelope": <Sealed>}]``.
    """
    body = json.dumps(
        {
            "path": str(path),
            "format": fmt,
            "secrets": [
                {"name": s["name"], "key": s["key"], "envelope": _envelope_payload(s["envelope"])}
                for s in secrets
            ],
        }
    ).encode("utf-8")
    proc = _run_avault(["deliver", "inject"], stdin=body)
    if proc.returncode != 0:
        raise AvaultError(_avault_detail(proc) or "avault inject failed")


def avault_key_export(passphrase: str) -> dict:
    """Export the machine key as a passphrase-wrapped backup blob via avault."""
    proc = _run_avault(["key", "export"], stdin=passphrase.encode("utf-8"))
    if proc.returncode != 0:
        raise AvaultError(_avault_detail(proc) or "avault key export failed")
    try:
        return json.loads(proc.stdout)
    except (ValueError, TypeError) as exc:
        raise AvaultError("avault key export returned malformed output") from exc


def avault_key_import(blob: dict, passphrase: str, *, force: bool = False) -> None:
    """Restore the machine key from an :func:`avault_key_export` blob via avault."""
    body = json.dumps({"passphrase": passphrase, "blob": blob}).encode("utf-8")
    args = ["key", "import"] + (["--force"] if force else [])
    proc = _run_avault(args, stdin=body)
    if proc.returncode != 0:
        raise AvaultError(_avault_detail(proc) or "avault key import failed")


def avault_key_authorize() -> dict:
    """Run ``avault key authorize`` once: the only avault call that may show a dialog.

    It asks macOS to let this avault binary read the existing master key; the
    dialog appears on the screen of the Mac running this process, never in a
    browser. Call it only for an explicit user action (the Web "Authorize
    avault" button or ``vibe vault key authorize``), never from a poller, a
    retry, or an Agent tool. avault itself shares one dialog among concurrent
    callers and suppresses new ones for 120 s after a deny or cancel.

    Returns ``{"ok", "reason", "detail"?}``. ``reason`` is ``authorized``,
    ``not_applicable`` (no Keychain off macOS), ``avault_missing``,
    ``avault_upgrade_required``, ``timed_out``, ``stale_login_session`` (the
    process outlived its macOS login session), ``no_gui_session`` (this process
    provably cannot show the dialog), or ``not_completed`` (denied, cancelled,
    still cooling down, or failed; avault's own ``detail`` says which).
    """
    if platform.system() != "Darwin":
        return {"ok": True, "reason": "not_applicable"}
    path = _resolve_avault_cli_path()
    if not path:
        return {"ok": False, "reason": "avault_missing"}
    if not _avault_supports_keychain_authorization(path):
        return {"ok": False, "reason": "avault_upgrade_required"}
    try:
        proc = subprocess.run(
            [path, *_avault_args(["key", "authorize"])],
            stdin=subprocess.DEVNULL,
            capture_output=True,
            timeout=_AVAULT_AUTHORIZE_TIMEOUT_SECONDS,
            env=_command_env_for(path),
            **isolated_subprocess_kwargs(),
        )
    except FileNotFoundError:
        return {"ok": False, "reason": "avault_missing"}
    except subprocess.TimeoutExpired:
        return {"ok": False, "reason": "timed_out"}
    if proc.returncode == 0:
        avault_authorization.clear_authorization_required()
        return {"ok": True, "reason": "authorized"}
    # avault exits 70 for a deny, a cancel, the cooldown after one, and a session
    # that cannot show the dialog alike; classify the process's own session first.
    session_state = macos_login_session_state()
    if session_state == "stale_login_session":
        result = {"ok": False, "reason": session_state}
    elif session_state == "no_gui_session" or _process_cannot_show_macos_dialogs():
        result = {"ok": False, "reason": "no_gui_session"}
    else:
        result = {"ok": False, "reason": "not_completed"}
    detail = _avault_detail(proc)
    if detail and result["reason"] != "stale_login_session":
        result["detail"] = detail[-_AVAULT_AUTHORIZE_DETAIL_LIMIT:]
    return result


def macos_login_session_state(*, service_pid: int | None = None) -> str:
    """Return the redacted login-session state for this process or a target service."""
    if platform.system() != "Darwin":
        return "not_applicable"
    try:
        from vibe.macos_session_diagnostics import MacOSSessionProbe, login_session_state

        target = service_pid is not None and service_pid != os.getpid()
        if target:
            try:
                from vibe.internal_client import health_identity_sync

                service_state = (health_identity_sync() or {}).get("macos_login_session_state")
                if service_state in {"healthy", "stale_login_session", "no_gui_session", "unknown"}:
                    return service_state
            except Exception:  # noqa: BLE001 - diagnostics must never block a Vault call
                pass
        context = MacOSSessionProbe(
            service_pid=service_pid,
            service_pid_is_target=target,
        ).capture_context()
        return login_session_state(context)
    except Exception:  # noqa: BLE001 - diagnostics must never block a Vault call
        return "unknown"


def get_macos_login_session_status() -> dict:
    """Expose only the actionable login-session state to Web/remote surfaces."""
    state = macos_login_session_state()
    return {"ok": True, "state": state}


def _process_cannot_show_macos_dialogs() -> bool:
    """True only when this process provably runs outside the logged-in desktop session.

    The result distinguishes an ended login session from a normal headless or
    SSH-launched process so the user receives the only recovery that can work.
    """
    state = macos_login_session_state()
    return state in {"stale_login_session", "no_gui_session"}


def get_avault_authorization_status() -> dict:
    """Whether avault needs the one-time Keychain authorization, and this process's last attempt."""
    record = avault_authorization.read_record()
    return {
        "ok": True,
        "required": record is not None,
        "detected_at": record.get("detected_at") if record else None,
        "attempt": avault_authorization.current_attempt(),
        "login_session_state": macos_login_session_state(),
    }


def start_avault_authorization() -> dict:
    """Start the user's "Authorize avault" action, or join the one already running."""
    avault_authorization.start_authorization(avault_key_authorize)
    return get_avault_authorization_status()


def _askill_auto_update_disabled() -> bool:
    """Return whether the managed askill reconcile loop is explicitly disabled."""
    skip_value = os.environ.get(_ASKILL_SKIP_ENV, "").strip().lower()
    if skip_value in _TRUTHY_ENV_VALUES:
        return True
    value = os.environ.get(_ASKILL_AUTO_UPDATE_ENV, "").strip().lower()
    return value in _FALSY_ENV_VALUES


def askill_update_status() -> dict:
    """Return the local askill version and whether it is older than the pin."""
    current = askill_status()
    current_version = current.get("version") if current.get("installed") else None
    has_update = bool(current.get("installed") and _compare_versions(current_version, ASKILL_VERSION))
    out = {
        **current,
        "latest_version": ASKILL_VERSION,
        "has_update": has_update,
        "auto_update": not _askill_auto_update_disabled(),
    }
    if current.get("installed") and not _is_comparable_version(current_version):
        # Not just a missing version: a version nobody can order (``dev``, a git
        # sha) tells us as little as no version at all, and every consumer —
        # the Dependencies page, prepare — must read the same fact from the same
        # field rather than re-deriving it from the raw string.
        out["status"] = "unknown"
    return out


def refresh_askill_if_stale() -> dict:
    """Bring askill to the managed pin, installing only when that changes it.

    The single owner of "is the managed askill current, and make it so". Every
    caller that wants currency asks this instead of forcing an install, which
    re-downloads the ~100 MB binary: the wanted version is ``ASKILL_VERSION``,
    so the question is answered locally with no download at all.
    ``refresh_avault_if_stale`` is the same rule for the other pinned sibling.

    Callers own their own policy gate; this function only decides staleness. An
    install attempt is reported by ``action``, so its absence means the
    dependency was already current. An askill newer than the pin is current:
    Avibe never downgrades it.
    """
    status = askill_update_status()
    if not status.get("installed"):
        result = ensure_askill_installed(force=False)
        result["action"] = "install"
        return result

    if status.get("status") == "unknown":
        # A binary whose version cannot be ordered is not current, it is broken —
        # whether it reported nothing or reported ``dev``. The status field owns
        # that judgement (see ``askill_update_status``) so this path and the
        # Dependencies page cannot disagree.
        logger.info("askill local version is unknown; refreshing managed dependency")
        result = ensure_askill_installed(force=True)
        result["action"] = "refresh_unknown_version"
        result["latest_version"] = ASKILL_VERSION
        return result

    if not status.get("has_update"):
        return {"ok": True, "skipped": True, "reason": "up_to_date", "status": status}

    logger.info("askill update available: %s -> %s", status.get("version"), ASKILL_VERSION)
    result = ensure_askill_installed(force=True)
    result["action"] = "update"
    result["from_version"] = status.get("version")
    result["latest_version"] = ASKILL_VERSION
    return result


def reconcile_askill_auto_update() -> dict:
    """Install or refresh askill as a required managed dependency.

    This runs from the shared update checker cadence but is intentionally
    independent of ``update.auto_update``. Avibe owns askill as a local runtime
    dependency for Skills; disabling product self-upgrades must not strand that
    dependency on an incompatible CLI contract. Operators can still disable this
    reconcile loop with ``VIBE_ASKILL_AUTO_UPDATE=0`` or ``VIBE_INSTALL_SKIP_ASKILL``.
    """
    if _askill_auto_update_disabled():
        return {"ok": True, "skipped": True, "reason": "askill_auto_update_disabled"}
    return refresh_askill_if_stale()


# =============================================================================
# Dependencies aggregate + explicit manual install jobs
# =============================================================================

_ALLOWED_DEP_INSTALLS = {
    "askill",
    "avault",
    "model-hub-engine",
    "show-runtime",
    "tmux",
}
_STARTUP_DEPENDENCY_RECONCILE_LOCK = threading.Lock()
_STARTUP_DEPENDENCY_STATE_LOCK = threading.Lock()
_STARTUP_DEPENDENCY_RECONCILING: set[str] = set()
_STARTUP_DEPENDENCY_RECONCILE_GENERATION = 0
_DEFAULT_STARTUP_SHOW_PAGE_PREWARM_LIMIT = 3
_MAX_STARTUP_SHOW_PAGE_PREWARM_LIMIT = 10
_MODEL_HUB_CONTROLLER_POLL_INTERVAL_SECONDS = 0.05
_MODEL_HUB_ENGINE_PLATFORM_UNSUPPORTED_REASON = (
    "model_hub_engine_platform_unsupported"
)


def _startup_dependency_state_snapshot() -> tuple[int, set[str]]:
    with _STARTUP_DEPENDENCY_STATE_LOCK:
        return _STARTUP_DEPENDENCY_RECONCILE_GENERATION, set(_STARTUP_DEPENDENCY_RECONCILING)


def _set_startup_dependency_reconciling(dependency: str, active: bool) -> None:
    with _STARTUP_DEPENDENCY_STATE_LOCK:
        if active:
            _STARTUP_DEPENDENCY_RECONCILING.add(dependency)
        else:
            _STARTUP_DEPENDENCY_RECONCILING.discard(dependency)


def _published_running_version() -> str | None:
    from packaging.version import InvalidVersion, Version
    from vibe import __version__

    try:
        version = Version(__version__)
    except InvalidVersion:
        return None
    if version.local is not None:
        return None
    # Official index releases include dev versions. Source deployment is
    # rejected independently by readiness; a dev suffix is not provenance.
    return str(version)


def _model_hub_engine_dependency_status() -> dict:
    """Project the pinned CPA runtime into the shared dependency contract."""

    try:
        from vibe.model_hub_runtime.installer import EngineRuntimeManager

        manager = EngineRuntimeManager(offline=True)
        managed = manager.status()
        platform_supported = manager.supports_host_platform()
    except Exception as exc:  # noqa: BLE001
        logger.warning("Could not inspect the Model Hub engine dependency", exc_info=True)
        return {
            "id": "model-hub-engine",
            "kind": "runtime",
            "required": True,
            "installed": None,
            "version": None,
            "latest_version": None,
            "has_update": False,
            "status": "error",
            "action_class": "operator_only",
            "reason": "model_hub_engine_install_inspection_failed",
            "inspection_error": {"kind": type(exc).__name__, "message": str(exc)},
        }

    installed = bool(managed.get("installed"))
    selected_version = managed.get("selected_version")
    matches_manifest = managed.get("matches_manifest")
    reason = managed.get("reason")
    if not platform_supported:
        status = "unsupported"
        action_class = "none"
    elif not selected_version:
        status = "error"
        action_class = "operator_only"
    elif managed.get("status") == "error":
        status = "error"
        action_class = "repairable"
    elif installed and matches_manifest is True:
        status = "ready"
        action_class = "none"
    elif installed:
        status = "upgrade_required"
        action_class = "repairable"
    else:
        status = "missing"
        action_class = "repairable"
    return {
        "id": "model-hub-engine",
        "kind": "runtime",
        "required": platform_supported,
        "installed": installed,
        "version": managed.get("version"),
        "latest_version": selected_version,
        "has_update": bool(installed and matches_manifest is False),
        "status": status,
        "action_class": action_class,
        "reason": reason,
        "download_error": managed.get("download_error"),
    }


def _model_hub_controller_owns_engine(socket_path: Path | None) -> bool:
    """Wait out controller startup before deciding direct-install ownership.

    A missing dispatch socket means only that the endpoint is not ready. The
    service pid reservation and instance lock identify the controller owner
    before durable recovery completes and the socket is bound. If that owner
    remains alive through the startup deadline, it retains ownership even when
    the endpoint never becomes ready; returning true prevents a competing
    direct install from mutating the runtime under it.
    """

    from vibe import runtime

    owner_pid = runtime.resolve_service_owner_pid(include_starting=True)
    if owner_pid is None:
        return False

    deadline = time.monotonic() + runtime.SERVICE_SLOW_START_TIMEOUT_SECONDS
    from vibe.internal_client import health_sync

    while True:
        owner_pid = runtime.resolve_service_owner_pid(include_starting=True)
        if owner_pid is None:
            return False
        remaining = deadline - time.monotonic()
        if health_sync(
            socket_path,
            timeout=min(1.0, max(0.05, remaining)),
        ):
            return True
        if remaining <= 0:
            return True
        time.sleep(min(_MODEL_HUB_CONTROLLER_POLL_INTERVAL_SECONDS, remaining))


def _model_hub_engine_ensure_result(result: dict) -> dict:
    """Project an unsupported host as a successful non-applicable ensure."""

    if result.get("reason") != _MODEL_HUB_ENGINE_PLATFORM_UNSUPPORTED_REASON:
        return result
    return {
        **result,
        "ok": True,
        "installed": False,
        "changed": False,
        "skipped": True,
        "status": "unsupported",
    }


def ensure_model_hub_engine_installed(
    *,
    force: bool = False,
    offline: bool | None = None,
) -> dict:
    """Converge CPA to this Avibe release's pin without changing run intent."""

    from core.handlers.model_hub import ModelHubError
    from vibe.internal_client import default_socket_path
    from vibe.model_hub_runtime.installer import EngineRuntimeManager

    def ensure_directly() -> dict:
        return _model_hub_engine_ensure_result(
            EngineRuntimeManager(offline=offline).ensure(force=force)
        )

    socket_path = None if os.name == "nt" else default_socket_path().expanduser().resolve()
    if not _model_hub_controller_owns_engine(socket_path):
        return ensure_directly()

    try:
        from vibe.model_hub_client import ModelHubRemoteService

        runtime = ModelHubRemoteService().ensure_runtime_dependency(
            force=force,
            offline=offline is True,
        )
    except ModelHubError as exc:
        if exc.code == "runtime_platform_unsupported":
            return _model_hub_engine_ensure_result(
                {
                    "ok": False,
                    "installed": False,
                    "changed": False,
                    "reason": _MODEL_HUB_ENGINE_PLATFORM_UNSUPPORTED_REASON,
                    "message": exc.detail,
                }
            )
        dependency_reason = exc.data.get("reason")
        return {
            "ok": False,
            "reason": dependency_reason or exc.code,
            "message": exc.detail,
        }

    status = runtime.get("status") if isinstance(runtime.get("status"), dict) else {}
    installed = bool(status.get("verified"))
    return {
        "ok": installed,
        "installed": installed,
        "changed": bool(runtime.get("changed")),
        "version": status.get("installed_version"),
        "status": status,
        "reason": None if installed else status.get("error_key") or "model_hub_engine_install_failed",
    }


def _show_runtime_dependencies_status(*, offline: bool) -> tuple[dict, dict]:
    """Show Runtime and Node share one inspection and its failure evidence."""
    from core.show_runtime import ShowRuntimeManager, get_show_runtime_manager

    srt_manager = ShowRuntimeManager(offline=True) if offline else get_show_runtime_manager()
    srt = srt_manager.status()
    manifest = srt.get("manifest") if isinstance(srt.get("manifest"), dict) else {}
    install = srt.get("install") if isinstance(srt.get("install"), dict) else {}
    install_state = install.get("state")
    srt_installed = True if install_state == "installed" else False if install_state == "absent" else None
    installed_matches_manifest = install.get("matches_manifest")
    recovery_action = install.get("recovery_action")
    srt_status = "ready" if srt_installed is True else "missing" if srt_installed is False else "error"
    action_class = (
        "repairable"
        if srt_status in {"ready", "missing"} or recovery_action == "repair"
        else "operator_only"
    )
    runtime = {
        "id": "show-runtime",
        "kind": "runtime",
        "required": True,
        "installed": srt_installed,
        "version": install.get("runtime_version"),
        "latest_version": manifest.get("runtime_version"),
        "has_update": bool(srt_installed is True and installed_matches_manifest is False),
        "status": srt_status,
        "action_class": action_class,
        "reason": srt.get("reason"),
        "download_error": srt.get("download_error"),
        "inspection_error": srt.get("inspection_error"),
    }

    # Node present but below the Show Runtime minimum (node_supported is False)
    # is not actually usable — don't show it green while runtime repair fails.
    node_inspection_failed = (
        install_state == "failed"
        and srt.get("reason") == "runtime_install_inspection_failed"
    )
    node_ok = (
        None
        if node_inspection_failed
        else bool(srt.get("node_available")) and srt.get("node_supported") is not False
    )
    node = {
        "id": "node",
        "kind": "node",
        "required": True,
        "installed": node_ok,
        "version": srt.get("node_version"),
        "status": "error" if node_ok is None else "ready" if node_ok else "missing",
    }
    return runtime, node


DEPENDENCY_IDS = (
    "askill",
    "avault",
    "show-runtime",
    "model-hub-engine",
    "tmux",
    "node",
)


def dependencies_status(*, offline: bool = False, dependency_ids: list[str] | None = None) -> dict:
    """Inspect only the requested dependencies, preserving the full status contract.

    Omitting ids keeps the synchronous, complete inspection used by Doctor.
    Web consumers can request independent checks without waiting for unrelated
    CLI probes. Coupled rows share their existing inspection; no health result
    is cached or inferred from a different dependency.
    """
    generation_before, active_before = _startup_dependency_state_snapshot()
    reconciling_before = _STARTUP_DEPENDENCY_RECONCILE_LOCK.locked()
    requested = set(DEPENDENCY_IDS if dependency_ids is None else dependency_ids)
    unknown = requested.difference(DEPENDENCY_IDS)
    if unknown:
        raise ValueError(f"Unknown dependencies: {', '.join(sorted(unknown))}")
    deps: dict[str, dict] = {}
    if "askill" in requested:
        a = askill_update_status()
        deps["askill"] = {
            "id": "askill",
            "kind": "tool",
            "required": True,
            "installed": a["installed"],
            "version": a.get("version"),
            "latest_version": a.get("latest_version"),
            "has_update": a.get("has_update", False),
            "status": a["status"],
        }
    if "avault" in requested:
        av = avault_status()
        deps["avault"] = {
            "id": "avault",
            "kind": "tool",
            "required": True,
            "installed": av["installed"],
            "version": av.get("version"),
            "latest_version": AVAULT_VERSION,
            "has_update": bool(av["installed"] and not _version_at_least(av.get("version"), AVAULT_VERSION)),
            "status": av["status"],
            "authorization_required": bool(av["installed"]) and avault_authorization.authorization_required(),
        }
    if requested.intersection({"show-runtime", "node"}):
        deps["show-runtime"], deps["node"] = _show_runtime_dependencies_status(offline=offline)
    if "model-hub-engine" in requested:
        deps["model-hub-engine"] = _model_hub_engine_dependency_status()
    if "tmux" in requested:
        try:
            from core.tmux_runtime import TmuxRuntimeManager, tmux_status

            tmux = TmuxRuntimeManager(offline=True).status() if offline else tmux_status()
        except Exception as exc:  # noqa: BLE001
            tmux = {"installed": False, "version": None, "status": "missing", "reason": str(exc)}
        deps["tmux"] = {
            "id": "tmux",
            "kind": "tool",
            "required": False,
            "installed": bool(tmux.get("installed")),
            "version": tmux.get("version"),
            "status": "ready" if tmux.get("installed") else "missing",
            "reason": tmux.get("reason"),
            "download_error": tmux.get("download_error"),
        }

    generation_after, active_after = _startup_dependency_state_snapshot()
    return {
        "ok": True,
        "deps": [deps[dep] for dep in DEPENDENCY_IDS if dep in requested],
        "reconciling": (
            reconciling_before
            or _STARTUP_DEPENDENCY_RECONCILE_LOCK.locked()
            or generation_before != generation_after
        ),
        "reconciling_dependencies": sorted(active_before | active_after),
        "login_session_state": macos_login_session_state(),
    }


def _prepare_show_runtime_job() -> dict:
    try:
        from core.show_runtime import get_show_runtime_manager
        from vibe.i18n import t as i18n_t

        payload = get_show_runtime_manager().repair()
        ok = bool(payload.get("ok"))
        reason = payload.get("reason")
        healthy = payload.get("outcome") == "healthy"
        result = {
            "ok": ok,
            "message": (
                i18n_t("doctor.repair.showRuntimeHealthy")
                if healthy
                else i18n_t("runtime.prepare.prepared")
                if ok
                else i18n_t("runtime.prepare.failed", reason=reason or "unknown")
            ),
            "output": None,
            "outcome": payload.get("outcome"),
            "changed": payload.get("outcome") == "repaired",
        }
        if not ok:
            download_error = (
                payload.get("download_error")
                if isinstance(payload.get("download_error"), dict)
                else None
            )
            result["reason"] = reason
            result["download_error"] = download_error
            if download_error:
                result["message"] = dependency_error_message(download_error, label="Show Runtime download")
        return result
    except Exception as exc:  # noqa: BLE001
        return {"ok": False, "message": str(exc), "output": None}


def _prepare_tmux_job() -> dict:
    try:
        from core.tmux_runtime import ensure_tmux_installed

        payload = ensure_tmux_installed(force=True)
        ok = bool(payload.get("ok"))
        download_error = payload.get("download_error") if isinstance(payload.get("download_error"), dict) else None
        return {
            **payload,
            "ok": ok,
            "message": (
                "tmux runtime ready."
                if ok
                else (
                    dependency_error_message(download_error, label="tmux download")
                    if download_error
                    else (payload.get("message") or payload.get("reason") or "tmux install failed")
                )
            ),
            "output": payload.get("output"),
        }
    except Exception as exc:  # noqa: BLE001
        return {"ok": False, "message": str(exc), "output": None}


def _startup_dependency_reconcile_enabled() -> bool:
    value = os.environ.get("VIBE_STARTUP_DEPENDENCY_RECONCILE")
    return value is None or value.strip().lower() not in {"0", "false", "no", "off"}


def startup_show_page_prewarm_limit() -> int:
    raw = os.environ.get("VIBE_STARTUP_SHOW_PAGE_PREWARM_LIMIT")
    if raw is None or not raw.strip():
        return _DEFAULT_STARTUP_SHOW_PAGE_PREWARM_LIMIT
    try:
        value = int(raw)
    except ValueError:
        logger.warning("Invalid VIBE_STARTUP_SHOW_PAGE_PREWARM_LIMIT=%r; using default", raw)
        return _DEFAULT_STARTUP_SHOW_PAGE_PREWARM_LIMIT
    return max(0, min(value, _MAX_STARTUP_SHOW_PAGE_PREWARM_LIMIT))


def startup_show_page_prewarm_targets(limit: int | None = None) -> dict:
    """Recent non-offline Show Pages to warm after the runtime sidecar starts."""
    resolved_limit = startup_show_page_prewarm_limit() if limit is None else max(0, min(limit, _MAX_STARTUP_SHOW_PAGE_PREWARM_LIMIT))
    if resolved_limit <= 0:
        return {"ok": True, "limit": resolved_limit, "pages": []}

    from core.show_pages import (
        ShowPageStore,
        VISIBILITY_LIMITED,
        VISIBILITY_PRIVATE,
        VISIBILITY_PUBLIC,
    )
    from core.show_runtime import ShowRuntimeContext
    from storage.pagination import PageRequest

    store = ShowPageStore()
    try:
        candidates = [
            *store.list_page(visibility=VISIBILITY_PRIVATE, page_request=PageRequest(limit=resolved_limit)).items,
            *store.list_page(visibility=VISIBILITY_LIMITED, page_request=PageRequest(limit=resolved_limit)).items,
            *store.list_page(visibility=VISIBILITY_PUBLIC, page_request=PageRequest(limit=resolved_limit)).items,
        ]
    finally:
        store.close()

    candidates.sort(key=lambda page: (page.updated_at, page.session_id), reverse=True)
    pages = []
    for page in candidates[:resolved_limit]:
        context = ShowRuntimeContext.SHARED if page.visibility == VISIBILITY_PUBLIC else ShowRuntimeContext.PRIVATE
        pages.append(
            {
                "session_id": page.session_id,
                "visibility": page.visibility,
                "updated_at": page.updated_at,
                "context": context.value,
            }
        )
    return {"ok": True, "limit": resolved_limit, "pages": pages}


def reconcile_startup_dependencies() -> dict:
    """Best-effort startup repair for local capabilities.

    The main service must stay available even when these dependencies are slow
    or broken, so callers should run this in a background thread/task. Node is
    only detected here; installing system-level Node remains an explicit
    installer/settings action.
    """
    if not _startup_dependency_reconcile_enabled():
        return {"ok": True, "skipped": True, "reason": "disabled"}
    if not _STARTUP_DEPENDENCY_RECONCILE_LOCK.acquire(blocking=False):
        return {"ok": True, "skipped": True, "reason": "already_running"}

    global _STARTUP_DEPENDENCY_RECONCILE_GENERATION

    with _STARTUP_DEPENDENCY_STATE_LOCK:
        _STARTUP_DEPENDENCY_RECONCILE_GENERATION += 1
        _STARTUP_DEPENDENCY_RECONCILING.clear()

    started_at = time.monotonic()
    result: dict[str, Any] = {
        "ok": True,
        "node": {"ok": False, "status": "unknown"},
        "askill": {"ok": False, "status": "unknown"},
        "avault": {"ok": False, "status": "unknown"},
        "model_hub_engine": {"ok": False, "status": "unknown"},
        "show_runtime": {"ok": False, "status": "unknown"},
        "tmux": {"ok": False, "status": "unknown"},
        "ripgrep": {"ok": False, "status": "unknown"},
    }
    try:
        _set_startup_dependency_reconciling("askill", True)
        try:
            askill = ensure_askill_installed(force=False)
        except Exception as exc:  # noqa: BLE001
            logger.warning("Startup dependency reconcile failed to ensure askill: %s", exc, exc_info=True)
            askill = {"ok": False, "message": str(exc)}
        finally:
            _set_startup_dependency_reconciling("askill", False)
        result["askill"] = askill

        _set_startup_dependency_reconciling("avault", True)
        try:
            # Pin-aware: Desktop never runs `vibe runtime prepare`, so startup is
            # where an existing install below AVAULT_VERSION moves to the pin. The
            # operator opt-out that `vibe runtime prepare` honors applies here too.
            if os.environ.get("VIBE_INSTALL_SKIP_AVAULT", "").strip().lower() in _TRUTHY_ENV_VALUES:
                avault = {**avault_status(), "ok": True, "skipped": True, "reason": "VIBE_INSTALL_SKIP_AVAULT"}
            else:
                avault = refresh_avault_if_stale()
        except Exception as exc:  # noqa: BLE001
            logger.warning("Startup dependency reconcile failed to ensure avault: %s", exc, exc_info=True)
            avault = {"ok": False, "message": str(exc)}
        finally:
            _set_startup_dependency_reconciling("avault", False)
        result["avault"] = avault

        _set_startup_dependency_reconciling("model-hub-engine", True)
        try:
            model_hub_engine = ensure_model_hub_engine_installed(force=False)
        except Exception as exc:  # noqa: BLE001
            logger.warning(
                "Startup dependency reconcile failed to ensure the Model Hub engine: %s",
                exc,
                exc_info=True,
            )
            model_hub_engine = {"ok": False, "message": str(exc)}
        finally:
            _set_startup_dependency_reconciling("model-hub-engine", False)
        result["model_hub_engine"] = model_hub_engine

        try:
            from core.show_runtime import ShowRuntimeAvailability, get_show_runtime_manager

            manager = get_show_runtime_manager()
            status = manager.status(offline=True)
            node_available = bool(status.get("node_available"))
            node_supported = status.get("node_supported") is not False
            node_ok = node_available and node_supported
            node_status = "ready" if node_ok else "missing"
            if node_available and not node_supported:
                node_status = "unsupported"
            result["node"] = {
                "ok": node_ok,
                "status": node_status,
                "version": status.get("node_version"),
            }
            if node_ok:
                _set_startup_dependency_reconciling("show-runtime", True)
                try:
                    prepared = manager.prepare(force=False, automatic=True)
                finally:
                    _set_startup_dependency_reconciling("show-runtime", False)
                status = prepared.get("status") if isinstance(prepared.get("status"), dict) else status
            else:
                reason = "runtime_node_unsupported" if node_available else "runtime_node_missing"
                prepared = ShowRuntimeAvailability.from_install(install_reason=reason).as_payload()
                prepared["status"] = status

            policy = prepared.get("policy") if isinstance(prepared.get("policy"), dict) else {}
            install = prepared.get("install") if isinstance(prepared.get("install"), dict) else {}
            policy_state = policy.get("state")
            install_state = install.get("state")
            dependency_ok = install_state == "installed" or policy_state == "skipped"
            prepared["ok"] = dependency_ok
            prepared["status"] = (
                "pending_prewarm"
                if policy_state == "allowed" and install_state == "installed"
                else ("skipped" if policy_state == "skipped" else "failed")
            )
            result["show_runtime"] = prepared
        except Exception as exc:  # noqa: BLE001
            logger.warning("Startup dependency reconcile failed to prepare Show Runtime: %s", exc, exc_info=True)
            result["show_runtime"] = {"ok": False, "status": "failed", "reason": str(exc)}

        if os.environ.get("VIBE_UI_ENABLE_TERMINAL", "").strip().lower() in {"0", "false", "no", "off"}:
            # Terminal explicitly disabled — don't download the optional tmux runtime.
            result["tmux"] = {"ok": True, "status": "skipped", "reason": "terminal_disabled"}
        elif os.environ.get("VIBE_INSTALL_SKIP_TMUX", "").strip().lower() in _TRUTHY_ENV_VALUES:
            result["tmux"] = {"ok": True, "skipped": True, "reason": "VIBE_INSTALL_SKIP_TMUX"}
        else:
            _set_startup_dependency_reconciling("tmux", True)
            try:
                from core.tmux_runtime import ensure_tmux_installed

                result["tmux"] = ensure_tmux_installed(force=False)
            except Exception as exc:  # noqa: BLE001
                logger.warning("Startup dependency reconcile failed to ensure tmux runtime: %s", exc, exc_info=True)
                result["tmux"] = {"ok": False, "status": "failed", "reason": str(exc)}
            finally:
                _set_startup_dependency_reconciling("tmux", False)

        # Agent commands search with the managed ripgrep. `vibe runtime prepare`
        # installs it, but a Runtime that never runs prepare (the desktop app)
        # gets it only here. Its absence only changes Vibey's prompt line, so it
        # never fails startup.
        try:
            from core.ripgrep_runtime import RipgrepRuntimeManager

            result["ripgrep"] = RipgrepRuntimeManager().ensure(force=False)
        except Exception as exc:  # noqa: BLE001
            logger.warning("Startup dependency reconcile failed to ensure ripgrep: %s", exc, exc_info=True)
            result["ripgrep"] = {"ok": False, "status": "failed", "reason": str(exc)}

        result["duration_ms"] = int((time.monotonic() - started_at) * 1000)
        result["ok"] = (
            bool(result["askill"].get("ok"))
            and bool(result["avault"].get("ok"))
            and bool(result["model_hub_engine"].get("ok"))
            and bool(result["show_runtime"].get("ok"))
        )
        return result
    finally:
        with _STARTUP_DEPENDENCY_STATE_LOCK:
            _STARTUP_DEPENDENCY_RECONCILING.clear()
            _STARTUP_DEPENDENCY_RECONCILE_GENERATION += 1
        _STARTUP_DEPENDENCY_RECONCILE_LOCK.release()


def start_dependency_install_job(dep: str) -> dict:
    """Install/repair a required local dependency in a background job.

    Reuses the agent install-job store (lock / prune / latest-by-key and the
    ``get_agent_install_job`` poller) keyed by the dependency id, so the UI gets
    the same non-blocking install + poll experience without running
    package-manager subprocesses on the request path.
    """
    if dep not in _ALLOWED_DEP_INSTALLS:
        return {"ok": False, "message": f"Unknown dependency: {dep}"}

    job_id = uuid.uuid4().hex
    now = time.time()
    job = {
        "ok": True,
        "job_id": job_id,
        "backend": dep,
        "status": "running",
        "message": "Install started",
        "output": "",
        "path": None,
        "started_at": now,
        "finished_at": None,
    }
    with _AGENT_INSTALL_JOB_LOCK:
        _prune_agent_install_jobs(now)
        latest_job_id = _AGENT_INSTALL_LATEST_BY_BACKEND.get(dep)
        latest_job = _AGENT_INSTALL_JOBS.get(latest_job_id or "")
        if isinstance(latest_job, dict) and latest_job.get("status") == "running":
            return dict(latest_job)
        _AGENT_INSTALL_JOBS[job_id] = job
        _AGENT_INSTALL_LATEST_BY_BACKEND[dep] = job_id

    def _worker() -> None:
        try:
            if dep == "askill":
                result = ensure_askill_installed(force=True)
            elif dep == "avault":
                result = ensure_avault_installed(force=True)
            elif dep == "model-hub-engine":
                result = ensure_model_hub_engine_installed(force=True)
            elif dep == "show-runtime":
                result = _prepare_show_runtime_job()
            elif dep == "tmux":
                result = _prepare_tmux_job()
            else:
                result = {"ok": False, "message": f"Unknown dependency: {dep}", "output": None}
            ok = bool(result.get("ok"))
            with _AGENT_INSTALL_JOB_LOCK:
                current = _AGENT_INSTALL_JOBS.get(job_id)
                if current is not None:
                    current.update(result)
                    current["ok"] = ok
                    current["status"] = "succeeded" if ok else "failed"
                    current["finished_at"] = time.time()
        except Exception as exc:  # noqa: BLE001
            logger.warning("Dependency install job failed for %s: %s", dep, exc, exc_info=True)
            with _AGENT_INSTALL_JOB_LOCK:
                current = _AGENT_INSTALL_JOBS.get(job_id)
                if current is not None:
                    current.update(
                        {"ok": False, "status": "failed", "message": str(exc), "output": None, "finished_at": time.time()}
                    )

    threading.Thread(target=_worker, daemon=True, name=f"vibe-dep-install-{dep}-{job_id[:8]}").start()
    return dict(job)


# =============================================================================
# Backend lifecycle (version probe, latest check, restart)
# =============================================================================

# Published registry versions retain their cache; local health/version is one
# fresh observation because dependencies may change without touching the CLI.
_BACKEND_RUNTIME_USER_AGENT = "avibe/backend-runtime"
_ASKILL_AUTO_UPDATE_ENV = "VIBE_ASKILL_AUTO_UPDATE"
_ASKILL_SKIP_ENV = "VIBE_INSTALL_SKIP_ASKILL"
_TRUTHY_ENV_VALUES = {"1", "true", "yes", "on"}
_FALSY_ENV_VALUES = {"0", "false", "no", "off"}

def _http_opener_for_best_effort_probe():
    try:
        from vibe.proxy import resolve_proxy

        proxy = resolve_proxy(None)
    except Exception:
        proxy = None

    if proxy and not proxy.lower().startswith("socks"):
        return urllib.request.build_opener(urllib.request.ProxyHandler({"http": proxy, "https": proxy}))
    # SOCKS proxies need aiohttp_socks; latest-version probes are best-effort
    # so we silently fall back to direct urlopen rather than complicate the
    # cache path. Direct-connection failures are cached for a short TTL.
    return urllib.request.build_opener()


def _fetch_github_latest_release_version(repo: str, *, user_agent: str = _BACKEND_RUNTIME_USER_AGENT) -> str | None:
    """Best-effort GitHub release lookup. Returns a normalized version or None."""
    req = urllib.request.Request(
        f"https://api.github.com/repos/{repo}/releases/latest",
        headers={"Accept": "application/vnd.github+json", "User-Agent": user_agent},
    )
    try:
        with _http_opener_for_best_effort_probe().open(req, timeout=5) as resp:  # noqa: S310 - trusted registry
            payload = json.loads(resp.read().decode("utf-8"))
    except Exception as exc:  # pragma: no cover - network failure path
        logger.debug("Latest GitHub release probe failed for %s: %s", repo, exc)
        return None
    raw = payload.get("tag_name")
    if not isinstance(raw, str):
        return None
    return raw.lstrip("v").strip() or None


def _fetch_latest_version(name: str) -> str | None:
    """Best-effort upstream lookup. Returns ``None`` on any failure."""
    probe = latest_probe_for_backend(name)
    if not probe:
        return None
    kind, ident = probe
    if kind == "github":
        return _fetch_github_latest_release_version(ident)

    url = f"https://registry.npmjs.org/{ident}/latest"
    req = urllib.request.Request(url, headers={"User-Agent": _BACKEND_RUNTIME_USER_AGENT})

    try:
        with _http_opener_for_best_effort_probe().open(req, timeout=5) as resp:  # noqa: S310 - trusted registries
            payload = json.loads(resp.read().decode("utf-8"))
    except Exception as exc:  # pragma: no cover - network failure path
        logger.debug("Latest version probe failed for %s: %s", name, exc)
        return None
    raw = payload.get("version")
    if not isinstance(raw, str):
        return None
    return raw.lstrip("v").strip() or None


def _cached_latest(name: str) -> str | None:
    return latest_version_cache.cached_latest(name, lambda: _fetch_latest_version(name))


def _is_comparable_version(value: str | None) -> bool:
    """Whether *value* can be ordered against another version at all.

    The single owner of "do we actually have a version?", because a nonempty
    string is not the same fact: ``askill --version`` answers ``askill dev`` on a
    development build, and the last token of that is stored as the version. Both
    comparison helpers deliberately return False for anything they cannot parse,
    so every caller that asks a comparison instead of asking this reads "cannot
    tell" as "no update available" — which is how a broken binary comes to look
    current. Ask this first; a False answer means unknown, not healthy.
    """
    if not value:
        return False
    try:
        from packaging.version import InvalidVersion, Version

        try:
            Version(value)
            return True
        except InvalidVersion:
            pass
    except Exception:  # pragma: no cover - packaging is a transitive dep
        pass

    core = value.split("+", 1)[0].split("-", 1)[0]
    try:
        tuple(int(part) for part in core.split("."))
    except ValueError:
        return False
    return True


def _compare_versions(current: str | None, latest: str | None) -> bool:
    """Return True when *latest* is strictly greater than *current*.

    Honors PEP 440 / semver pre-release ordering when possible (e.g. ``0.77.1``
    is greater than ``0.77.1-beta.0``). Falls back to a conservative numeric
    tuple comparison; returns False on any parsing failure so we never nag the
    user with a phantom update. That conservatism is why "no update" is not a
    statement about health: use ``_is_comparable_version`` to tell the two apart.
    """
    if not _is_comparable_version(current) or not _is_comparable_version(latest) or current == latest:
        return False

    try:
        from packaging.version import InvalidVersion, Version

        try:
            return Version(latest) > Version(current)
        except InvalidVersion:
            pass
    except Exception:  # pragma: no cover - packaging is a transitive dep
        pass

    def _parts(value: str) -> tuple[tuple[int, ...], bool] | None:
        # Strip build metadata; keep pre-release tag to compare lexically.
        core, _, pre = value.split("+", 1)[0].partition("-")
        try:
            nums = tuple(int(part) for part in core.split("."))
        except ValueError:
            return None
        # A version with a pre-release suffix is "less than" the bare release.
        return nums, bool(pre)

    cur_parts = _parts(current)
    new_parts = _parts(latest)
    if cur_parts is None or new_parts is None:
        return False
    cur_nums, cur_is_pre = cur_parts
    new_nums, new_is_pre = new_parts
    if new_nums != cur_nums:
        return new_nums > cur_nums
    # Same numeric core: pre-release sorts before release.
    return cur_is_pre and not new_is_pre


def _opencode_process_status() -> str:
    from modules.agents.opencode.server import recorded_servers

    try:
        return "running" if recorded_servers() else "stopped"
    except Exception:  # noqa: BLE001
        return "unknown"


def _process_matches_codex_binary(cmdline: list[str], resolved_binary: str | None) -> bool:
    """Decide whether ``cmdline`` belongs to *our* codex app-server.

    The original cmdline-substring check matched any ``codex`` mention in any
    argument (e.g. a user invoking ``codex app-server`` themselves from a
    shell, or another tool whose args happen to contain those tokens), and
    a follow-up tightening only inspected ``argv[0]`` — which missed the
    ``npm install -g @openai/codex`` shim, where the live process is
    ``node /path/.../bin/codex app-server`` (``argv[0] == "node"``).

    We now scan the first few argv tokens (``argv[0]`` and ``argv[1]``)
    looking for the codex binary itself, since the kernel preserves the
    script path as ``argv[1]`` whenever a ``#!/usr/bin/env node`` shim is
    exec'd. The match requires:

      1. one of ``argv[0]``/``argv[1]`` resolves to the same absolute path
         as the configured codex binary (or, when no resolved binary is
         known, has basename starting with ``codex``); and
      2. one of the early arguments is exactly ``app-server``.
    """
    if not cmdline:
        return False
    try:
        target = (
            str(Path(resolved_binary).expanduser().resolve())
            if resolved_binary
            else None
        )
    except Exception:
        target = resolved_binary

    target_basename = os.path.basename(target) if target else None

    def _matches(token: str) -> bool:
        try:
            resolved = str(Path(token).expanduser().resolve())
        except Exception:
            resolved = token
        token_basename = os.path.basename(token) if token else ""
        if target is not None:
            # Exact-path match (absolute argv[0] / shim path) — strongest signal.
            if resolved == target or token == target:
                return True
            # Bare-name argv[0]: ``codex`` launched via PATH lookup. The
            # kernel records argv[0] verbatim, so ``token == "codex"`` and
            # ``Path("codex").resolve()`` becomes a cwd-relative path that
            # never equals ``target``. Fall back to a basename match —
            # combined with the upstream ``app-server`` marker check this
            # still excludes random unrelated tools. The cost of matching
            # a sibling codex install (different absolute path, same
            # basename) is acceptable: the lifecycle chip reflects "a
            # codex app-server is running", which is what users want.
            if token_basename and target_basename and token_basename == target_basename:
                return True
            return False
        # No resolved binary: best-effort basename match so the chip still
        # works when the configured CLI isn't on PATH right now.
        return os.path.basename(resolved).startswith("codex")

    # Check argv[0] and argv[1] — the latter is where ``node`` shebang shims
    # land the codex script path. We deliberately stop at argv[1] so an
    # unrelated tool with ``codex`` mentioned later in its args isn't swept up.
    if not any(_matches(tok) for tok in cmdline[:2] if tok):
        return False
    # ``codex app-server`` always passes ``app-server`` as an argv token; we
    # intentionally do NOT match it inside an arbitrary substring. Widen the
    # window slightly so the node-shim layout (``node script app-server``)
    # still hits.
    return "app-server" in cmdline[1:5]


def _codex_processes(resolved_binary: str | None) -> list[int]:
    """Find live ``codex app-server`` subprocesses owned by the current user.

    The match must hit our resolved codex binary so unrelated tools that
    happen to mention ``codex`` and ``app-server`` aren't swept up.
    """
    try:
        import psutil
    except ImportError:  # pragma: no cover - psutil is a hard dep elsewhere
        return []

    # ``uids`` is a POSIX-only psutil attribute; requesting it on Windows
    # makes ``process_iter`` raise ``ValueError: invalid attr name 'uids'``
    # and the entire probe blows up. Gate it on ``getuid`` availability,
    # which is the same signal we use to decide whether to filter at all.
    current_uid = os.getuid() if hasattr(os, "getuid") else None
    attrs = ["pid", "name", "cmdline"]
    if current_uid is not None:
        attrs.append("uids")
    pids: list[int] = []
    for proc in psutil.process_iter(attrs=attrs):
        try:
            info = proc.info
            cmdline = info.get("cmdline") or []
            if not _process_matches_codex_binary(cmdline, resolved_binary):
                continue
            if current_uid is not None:
                uids = info.get("uids")
                proc_uid = getattr(uids, "real", None) if uids else None
                if proc_uid is not None and proc_uid != current_uid:
                    continue
            pids.append(info["pid"])
        except (psutil.NoSuchProcess, psutil.AccessDenied):
            continue
    return pids


def _codex_process_status(resolved_binary: str | None) -> str:
    return "running" if _codex_processes(resolved_binary) else "stopped"


def _hub_backend_connection_auth(config: V2Config, backend: str) -> str:
    """Observe only configured supply owners; never resolve or invoke a model."""
    from core.handlers.model_hub.resolver import (
        source_after_cooldown_recovery,
        source_eligible_for_backend,
        source_runnable,
    )
    from vibe.model_hub_runtime.state import EngineStateStore

    hub = config.model_hub
    source_ids = list(dict.fromkeys([
        *hub.effective_source_order(backend),
        *(hop.source_id for route in hub.agents[backend].routes.values() for hop in route.hops),
    ]))
    by_id = {source.id: source for source in hub.sources}
    now = datetime.now(timezone.utc)
    credentials = EngineStateStore(paths.get_runtime_dir() / "model-hub" / "state")
    for source_id in source_ids:
        source = by_id.get(source_id)
        if source is None or not source_eligible_for_backend(source, backend) or not source_runnable(source, now=now):
            continue
        if source.supply_channel == "hub":
            if credentials.has_current_source_credential(
                source.credential_ref,
                source_id=source.id,
                kind=source.kind,
                vendor=source.vendor,
                protocol=source.protocol,
                base_url=source.base_url,
            ):
                return "api_key" if source.kind == "api_key" else "subscription"
        elif source.supply_channel == "native_cli" and source.kind == "subscription":
            from modules.agents.model_hub import ModelHubRuntimeRouter

            # The retained Source is the explicit subscription owner. Reuse
            # its launch checks, including native key/endpoint conflicts;
            # an arbitrary dormant native login cannot supply another Source.
            recovered = source_after_cooldown_recovery(source, now)
            if ModelHubRuntimeRouter._default_native_cli_ready(
                backend, verified_oauth=backend == "codex" and recovered.state.status == "active",
            ):
                return "subscription"
    return "none"


def _assert_direct_claude_custody() -> None:
    """Admit Direct Claude only under the takeover exclusion; read no credential."""
    with NativeCredentialLease(("claude",)) as lease:
        # The caller's config may predate an await or a completed takeover.
        # acquire() checks pending recovery; custody must be reread under lease.
        lease.assert_auth_custody("claude")


async def get_backend_connection(name: str) -> dict:
    """Observe persisted credential custody and application, without a model call.

    Direct Claude reports ``auth: "external"``: Claude authenticates itself,
    so ``ready`` / ``entry_eligible`` mean an execution may be attempted.
    """
    from core.backend_restart import pending_native_backends
    from vibe import internal_client, runtime

    if not is_agent_backend(name):
        return {"ok": False, "error": "unsupported_backend"}
    config = await asyncio.to_thread(load_config)
    builtin = is_builtin_backend(name)
    backend_config = None if builtin else getattr(config.agents, name)
    enabled = builtin or bool(backend_config.enabled)
    supply_mode = config.model_hub.agents[name].mode
    native = is_native_cli_backend(name)
    cli_health = await detect_cli_async(backend_config.cli_path or name, name) if native else None
    installed = cli_health["found"] if cli_health is not None else True
    result = {
        "ok": True, "backend": name, "installed": installed, "enabled": enabled,
        "cli_status": cli_health["status"] if cli_health is not None else None,
        "supply_mode": supply_mode,
        "auth": "unknown", "application": "unknown", "ready": False,
        "entry_eligible": False,
    }
    body = {}
    try:
        application = await internal_client.backend_application(name)
        body = application.get("body") or {}
        if application.get("status_code") == 200 and body.get("ok"):
            result["application"] = body.get("state") if body.get("state") in {"applied", "draining", "failed"} else "unknown"
            if enabled and body.get("disabled") is True and result["application"] == "applied":
                result["application"] = "unknown"
            if body.get("error"):
                result["message"] = body["error"]
    except internal_client.InternalServerUnavailable:
        if not await asyncio.to_thread(runtime.service_process_running):
            result["application"] = "stopped"
    with _backend_apply_receipts_lock:
        receipt = _backend_apply_receipts.get(name)
        # A confirmed new controller has applied persisted startup config.
        # Browser refresh or a recovered socket to the same owner cannot clear
        # an undelivered request. PID is existing runtime identity, not an epoch.
        if (receipt and receipt.get("controller_pid") and body.get("controller_pid")
                and receipt["controller_pid"] != body["controller_pid"]
                and result["application"] == "applied"):
            _backend_apply_receipts.pop(name, None)
            receipt = None
    if receipt and not receipt.get("ok") and result["application"] != "stopped":
        result["application"] = "failed"
        result["message"] = receipt.get("message") or receipt.get("error")
    if not installed or config.load_warnings or (cli_health is not None and cli_health["status"] != "ok"):
        return result
    if native and name in await asyncio.to_thread(pending_native_backends, paths.get_state_dir() / "native-takeover"):
        return result
    try:
        if supply_mode == "hub":
            # A backend the Hub cannot supply now has no credential to run on, whatever is saved.
            result["auth"] = (
                "none" if hub_supply_block(name, config.model_hub) is not None
                else await asyncio.to_thread(_hub_backend_connection_auth, config, name)
            )
        elif name == "opencode":
            if not enabled:
                return result
            # Read the same persisted launch sources as the provider catalog.
            # Readiness must not start an OpenCode daemon just to inspect auth.
            from vibe.opencode_config import read_opencode_provider_auth_entries

            key_ids = await _read_opencode_config_api_key_provider_ids()
            entries = await asyncio.to_thread(read_opencode_provider_auth_entries, logger_instance=logger)
            modes = {pid: entry.get("type") for pid, entry in entries.items() if isinstance(entry, dict)}
            modes.update({pid: "api" for pid in key_ids})
            effective = next((mode for mode in modes.values() if mode in {"api", "oauth"}), None)
            result["auth"] = {"api": "api_key", "oauth": "subscription"}.get(effective, "none")
        elif name == "claude":
            # Claude owns authentication: Direct capability never depends on
            # passive credential evidence. Join the worker so the custody
            # check's lease is released before this observation settles.
            await finish_native_operation(asyncio.to_thread(_assert_direct_claude_custody))
            result["auth"] = "external"
        else:
            auth = await asyncio.to_thread(get_codex_auth)
            if not auth.get("ok") or auth.get("auth_mode_uncertain"):
                return result
            result["auth"] = {"oauth": "subscription", "api_key": "api_key", "none": "none"}.get(auth.get("active_auth_mode"), "unknown")
        if name == "opencode" and enabled:
            permission = await asyncio.to_thread(opencode_permission_status)
            result["permission_required"] = bool(permission.get("ok")) and not permission.get("permission_allowed", False)
    except NativeMigrationBlockedError:
        return result
    except Exception as exc:
        result["message"] = str(exc)
        return result
    # An ownership transition may have started while the observation awaited
    # IPC or native read-only checks. Do not admit against a pending journal.
    if native and name in await asyncio.to_thread(pending_native_backends, paths.get_state_dir() / "native-takeover"):
        return result
    # ``external`` is launch capability with Claude-owned authentication; it
    # asserts no login. Every other gate above still applies to it.
    credential_ready = enabled and result["auth"] in {"subscription", "api_key", "external"} and not result.get("permission_required")
    result["ready"] = credential_ready and result["application"] == "applied"
    result["entry_eligible"] = credential_ready and result["application"] in {"applied", "stopped"}
    return result


def get_backend_runtime(name: str, cli_path: str | None = None) -> dict:
    """Synchronous non-HTTP entry; the HTTP route awaits the same owner."""
    return asyncio.run(get_backend_runtime_async(name, cli_path))


async def get_backend_runtime_async(name: str, cli_path: str | None = None) -> dict:
    """Lifecycle projection bound to the selected path's fresh CLI observation.

    Registry lookups retain their cache. Health is not cached by launcher stat:
    replacing an npm platform package can leave that stat entirely unchanged.
    """
    if not is_native_cli_backend(name):
        return {"ok": False, "error": f"Unknown backend: {name}"}

    try:
        config = await asyncio.to_thread(V2Config.load)
    except Exception as exc:
        logger.debug("Failed to load config for backend runtime: %s", exc)
        config = None

    backend_cfg = getattr(getattr(config, "agents", None), name, None) if config else None
    enabled = bool(getattr(backend_cfg, "enabled", False))
    configured_path = (cli_path or name) if cli_path is not None else (getattr(backend_cfg, "cli_path", "") or name)

    health = await detect_cli_async(configured_path, name)
    resolved_path = health["path"]
    installed = health["found"]
    private_backend = resolved_path is not None and is_desktop_backend_path(resolved_path)
    legacy_bundled_codex = (
        name == "codex"
        and resolved_path is not None
        and is_private_desktop_runtime_path(resolved_path)
    )
    managed_by = (
        "desktop"
        if private_backend or legacy_bundled_codex
        else None
    )

    current_version = health["version"]
    latest_version = None if legacy_bundled_codex else await asyncio.to_thread(_cached_latest, name)
    has_update = _compare_versions(current_version, latest_version)

    if name == "opencode":
        process_status = await asyncio.to_thread(_opencode_process_status) if installed else "stopped"
    elif name == "codex":
        process_status = await asyncio.to_thread(_codex_process_status, resolved_path) if installed else "stopped"
    elif name == "claude":
        process_status = "unknown"
    else:
        process_status = "unknown"

    return {
        "ok": True,
        "name": name,
        "enabled": enabled,
        "auto_update": bool(getattr(backend_cfg, "auto_update", True)),
        "cli_path": configured_path,
        "resolved_path": resolved_path,
        "installed": installed,
        "status": health["status"],
        "reason": health["reason"],
        "current_version": current_version,
        "latest_version": latest_version,
        "has_update": has_update,
        "managed_by": managed_by,
        "supports_restart": supports_runtime_refresh(name),
        "process_status": process_status,
    }


def _runtime_command_dir() -> Path:
    """Directory the controller watches for cross-process command markers."""
    base = paths.get_state_dir() / "runtime_commands"
    base.mkdir(parents=True, exist_ok=True)
    return base


def _wait_for_controller_ack(marker: Path, timeout: float) -> tuple[bool, str | None]:
    """Poll for ``marker`` removal as a signal that the controller ran it.

    Returns ``(handled, error)``:

    - ``handled=True, error=None`` — controller picked up the marker and the
      handler returned cleanly.
    - ``handled=True, error="..."`` — controller picked up the marker but
      the handler raised; the controller wrote the message to a companion
      ``<marker>.err`` file before deleting the request marker.
    - ``handled=False, error=None`` — timed out; the controller never
      consumed the marker. Caller must preserve the failed application.

    The companion ``.err`` file is consumed (unlinked) before returning so
    later requests start clean.
    """
    err_marker = marker.with_name(marker.name + ".err")
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        if not marker.exists():
            error: str | None = None
            if err_marker.exists():
                try:
                    error = err_marker.read_text(encoding="utf-8").strip() or "unknown error"
                except OSError:
                    error = "unknown error"
                try:
                    err_marker.unlink(missing_ok=True)
                except OSError:  # pragma: no cover - best-effort cleanup
                    pass
            return True, error
        time.sleep(0.1)
    return False, None


def _request_controller_restart(
    backend: str,
    timeout: float = 4.0,
    *,
    metadata: Optional[dict[str, Any]] = None,
) -> tuple[bool, str | None]:
    """Ask the controller to refresh a backend via the runtime-command marker.

    The controller's ``RuntimeCommandWatcher`` (see ``core/runtime_commands.py``)
    is the in-process owner of ``CodexAgent._transports`` / OpenCode server
    state. Killing those processes from the UI server would leave that cache
    stale, so the cleanest path is to ask the controller to call its existing
    ``_refresh_backend_runtime(backend)`` for us. We drop a marker file and
    wait briefly for the controller to delete it. An unreachable running
    controller remains an unconfirmed apply; no child-process kill can prove
    that its in-memory state accepted the saved configuration.

    Each request gets its own marker filename (``restart-<backend>.<reqid>.cmd``)
    so we can correlate failures back to *this* request. Without the reqid,
    a stale ``.err`` from a prior request that timed out caller-side — or an
    overlapping concurrent restart — could be mistaken for *our* failure and
    surface a phantom error toast.

    Returns ``(handled, error)`` — see ``_wait_for_controller_ack`` for the
    contract. ``handled=True`` does *not* imply success; check ``error`` too
    so the UI toast doesn't claim a restart when the controller's refresh
    actually raised.
    """
    reqid = uuid.uuid4().hex[:8]
    marker = _runtime_command_dir() / f"restart-{backend}.{reqid}.cmd"
    try:
        payload = {"backend": backend, "ts": time.time(), "reqid": reqid}
        if metadata:
            payload["metadata"] = {
                str(k): v
                for k, v in metadata.items()
                if isinstance(k, str) and v is not None
            }
        marker.write_text(
            json.dumps(payload),
            encoding="utf-8",
        )
    except OSError as exc:
        logger.debug("Failed to write controller restart marker for %s: %s", backend, exc)
        return False, None
    handled, error = _wait_for_controller_ack(marker, timeout)
    if handled:
        return True, error
    # Marker still present — controller didn't pick it up. Clean up the
    # request marker *and* any stray ``.err`` so the next attempt starts
    # from a clean slate.
    try:
        marker.unlink(missing_ok=True)
    except OSError:
        pass
    try:
        marker.with_name(marker.name + ".err").unlink(missing_ok=True)
    except OSError:
        pass
    return False, None


# Bounded to the supported backends; survives modal/HTTP lifetimes. This records
# undelivered apply requests which the controller cannot itself observe.
_backend_apply_receipts: dict[str, dict] = {}
_backend_apply_receipts_lock = threading.Lock()


def record_backend_apply_receipt(backend: str, result: dict) -> None:
    if not is_agent_backend(backend):
        return
    from vibe import runtime

    receipt = dict(result)
    receipt["controller_pid"] = runtime.resolve_service_owner_pid(include_starting=False)
    with _backend_apply_receipts_lock:
        _backend_apply_receipts[backend] = receipt


def restart_backend(name: str, *, metadata: Optional[dict[str, Any]] = None) -> dict:
    try:
        result = _restart_backend(name, metadata=metadata)
    except Exception as exc:
        result = {"ok": False, "message": str(exc)}
    record_backend_apply_receipt(name, result)
    return result


def _restart_backend(name: str, *, metadata: Optional[dict[str, Any]] = None) -> dict:
    """Refresh the backend so the next request picks up new config/env.

    Preferred path: drop a runtime-command marker that the controller
    observes and reacts to via ``_refresh_backend_runtime``. This keeps the
    controller's in-memory transport/session state consistent. A confirmed
    stopped controller applies persisted configuration on its next explicit
    start; a running controller with unavailable IPC remains a failed apply.

    Claude has no separate daemon, but the controller keeps SDK sessions
    and a loaded compat config; the marker path refreshes those in memory.
    """
    if not supports_runtime_refresh(name):
        return {"ok": False, "message": f"Restart is not supported for backend: {name}"}

    from vibe import runtime

    try:
        language = load_config().language
    except FileNotFoundError:
        language = "en"
    if not runtime.service_process_running():
        return {"ok": True, "apply_on_next_start": True, "message": backend_t("backendConnection.applyOnStart", lang=language)}

    controller_handled, controller_error = _request_controller_restart(name, metadata=metadata)

    if controller_handled:
        if controller_error:
            # Controller saw the request and ran the handler, but the handler
            # raised. Don't lie to the user — surface the failure so they can
            # retry or look at logs. (The next runtime probe will also reflect
            # the stale state, but the toast must already say so.)
            return {
                "ok": False,
                "message": f"Backend refresh failed: {controller_error}",
            }
        return {
            "ok": True,
            "message": backend_t(
                "backendConnection.restartAccepted", lang=language, agent=display_name_for_backend(name)
            ),
        }

    # A running service with broken IPC is not a stopped backend. Killing its
    # child process here would hide stale controller state and split ownership.
    return {"ok": False, "message": backend_t("backendConnection.applyUnacknowledged", lang=language)}


_VALID_AUTH_MODES = {"oauth", "api_key"}
_VALID_CLAUDE_CREDENTIAL_TYPES = {"api_key", "auth_token"}


def _mask_api_key(api_key: str | None) -> str | None:
    """Return a UI-safe preview of an API key.

    Pattern: keep the prefix up to (and including) the first ``-`` block
    (e.g. ``sk-proj-``, ``sk-ant-``) so the user can still recognize
    the key type, then dots, then the last 4 characters. Short keys
    (<= 12 chars) get a uniform 6-dots-plus-last-4 pattern so we never
    accidentally render plaintext for a malformed key.
    """
    if not isinstance(api_key, str) or not api_key.strip():
        return None
    key = api_key.strip()
    last4 = key[-4:]
    if len(key) > 12 and "-" in key:
        # Take the recognizable prefix up to and including the second dash
        # (handles both ``sk-...`` and ``sk-proj-...`` shapes).
        first_dash = key.find("-")
        second_dash = key.find("-", first_dash + 1)
        prefix_end = second_dash + 1 if second_dash != -1 else first_dash + 1
        prefix = key[:prefix_end]
        return f"{prefix}{'•' * 9}{last4}"
    return f"{'•' * 6}{last4}"


# ---------------------------------------------------------------------------
# Web Settings → Backends OAuth flow plumbing.
#
# FastAPI hosts these flows on the UI server's persistent ASGI event loop.
# On success we drop a ``restart-<backend>.cmd`` marker so the live
# controller refreshes its in-process agent state (mirroring what
# ``_refresh_backend_runtime`` does in-process for IM-driven flows).
# ---------------------------------------------------------------------------


class _WebControllerStub:
    """Minimal ``Controller``-shaped facade for the web OAuth flow service.

    ``AgentAuthService`` only touches ``controller.config`` (for
    ``cli_path``) and gracefully no-ops when ``agent_service`` /
    ``session_handler`` are absent. The stub re-reads V2Config from disk on
    every access so a freshly-saved ``cli_path`` is picked up on the next
    flow without restarting the UI server.
    """

    @property
    def config(self):
        return load_config()

    # The following attributes are inspected via ``getattr(..., None)`` in
    # ``AgentAuthService`` and gate platform-specific paths that web flows
    # never traverse (IM message dispatch, session lookup, agent refresh).
    agent_service = None
    session_handler = None
    im_client = None


_oauth_service_lock = threading.Lock()
_oauth_service: Any = None
_oauth_loop: asyncio.AbstractEventLoop | None = None
_oauth_loop_thread: threading.Thread | None = None


def _start_oauth_event_loop() -> tuple[asyncio.AbstractEventLoop, threading.Thread]:
    loop = asyncio.new_event_loop()

    def _runner() -> None:
        asyncio.set_event_loop(loop)
        loop.run_forever()

    thread = threading.Thread(target=_runner, daemon=True, name="vibe-oauth-loop")
    thread.start()
    return loop, thread


def _on_web_auth_success(backend: str) -> None:
    """Surface persistence/application separately from successful consent."""
    result = restart_backend(
        backend, metadata={"reason": "web_auth_success", "source": "oauth_callback"},
    )
    if not result.get("ok"):
        raise RuntimeError(result.get("message") or "backend_apply_failed")


def _get_oauth_service() -> Any:
    """Lazily build the (singleton) AgentAuthService for web flows."""
    global _oauth_service, _oauth_loop, _oauth_loop_thread
    with _oauth_service_lock:
        if _oauth_service is not None:
            return _oauth_service
        from core.agent_auth_service import AgentAuthService

        _oauth_loop, _oauth_loop_thread = _start_oauth_event_loop()
        controller = _WebControllerStub()
        _oauth_service = AgentAuthService(controller)
        _oauth_service._post_web_success_hook = _on_web_auth_success
        return _oauth_service


def _ensure_oauth_loop() -> asyncio.AbstractEventLoop:
    global _oauth_loop, _oauth_loop_thread
    with _oauth_service_lock:
        if _oauth_loop is None or _oauth_loop.is_closed():
            _oauth_loop, _oauth_loop_thread = _start_oauth_event_loop()
        return _oauth_loop


def _submit_oauth_coro(coro, *, timeout: float = 30.0):
    _get_oauth_service()  # ensures the persistent loop exists
    loop = _ensure_oauth_loop()
    future = asyncio.run_coroutine_threadsafe(coro, loop)
    return future.result(timeout=timeout)


def _serialize_web_flow_status(payload: dict) -> dict:
    """Strip server-only keys before returning to the browser."""
    if not isinstance(payload, dict):
        return {"ok": False, "error": "invalid_payload"}
    return payload


def start_oauth_web(
    backend: str,
    force_reset: bool = True,
    provider_id: Optional[str] = None,
) -> dict:
    return _submit_oauth_coro(
        start_oauth_web_async(backend, force_reset=force_reset, provider_id=provider_id),
        timeout=60.0,
    )


async def start_oauth_web_async(
    backend: str,
    force_reset: bool = True,
    provider_id: Optional[str] = None,
) -> dict:
    backend = (backend or "").strip().lower()
    if not supports_web_oauth(backend):
        return {"ok": False, "error": "unsupported_backend"}
    if backend == "opencode" and not (isinstance(provider_id, str) and provider_id.strip()):
        return {"ok": False, "error": "opencode_provider_id_required"}
    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}
    from core.agent_auth_service import BackendLoginInProgressError

    service = _get_oauth_service()
    try:
        flow = await service.start_web_setup(
            backend,
            force_reset=force_reset,
            provider_id=(provider_id.strip() if isinstance(provider_id, str) else None),
        )
    except BackendLoginInProgressError as exc:
        try:
            lang = load_config().language
        except Exception:  # noqa: BLE001
            lang = "en"
        return {
            "ok": False,
            "error": exc.code,
            "detail": backend_t(
                "command.setup.loginInProgress",
                lang,
                vendor=exc.vendor,
                backend=backend,
            ),
        }
    except NativeMigrationBlockedError as exc:
        return _native_write_blocked(exc)
    except Exception as exc:  # noqa: BLE001
        logger.error("Web OAuth start failed for %s: %s", backend, exc, exc_info=True)
        return {"ok": False, "error": "start_failed", "detail": str(exc)}

    if flow.state == "failed":
        return {
            "ok": False,
            "error": flow.error or "start_failed",
            "flow_id": flow.flow_id,
            "state": flow.state,
            "authorization_completed": flow.authorization_completed,
        }
    return {
        "ok": True,
        "flow_id": flow.flow_id,
        "backend": flow.backend,
        "state": flow.state,
        "url": flow.url,
        "device_code": flow.device_code,
        "awaiting_code": flow.awaiting_code,
        "callback_kind": flow.callback_kind,
        "provider": flow.provider,
        "authorization_completed": flow.authorization_completed,
    }


def get_oauth_web_status(flow_id: str) -> dict:
    flow_id = (flow_id or "").strip()
    if not flow_id:
        return {"ok": False, "error": "missing_flow_id"}
    service = _get_oauth_service()
    return _serialize_web_flow_status(service.get_web_flow_status(flow_id))


def submit_oauth_web_code(flow_id: str, code: str) -> dict:
    return _submit_oauth_coro(submit_oauth_web_code_async(flow_id, code), timeout=30.0)


async def submit_oauth_web_code_async(flow_id: str, code: str) -> dict:
    flow_id = (flow_id or "").strip()
    if not flow_id:
        return {"ok": False, "error": "missing_flow_id"}
    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}
    service = _get_oauth_service()
    try:
        return await service.submit_web_code(flow_id, code or "")
    except Exception as exc:  # noqa: BLE001
        logger.error("Web OAuth code submit failed: %s", exc, exc_info=True)
        return {"ok": False, "error": "submit_failed", "detail": str(exc)}


def remove_backend_auth(backend: str) -> dict:
    return _submit_oauth_coro(remove_backend_auth_async(backend), timeout=30.0)


async def remove_backend_auth_async(backend: str) -> dict:
    """Clear stored credentials for Claude or Codex (web Settings)."""
    backend = (backend or "").strip().lower()
    if not supports_web_oauth(backend):
        return {"ok": False, "error": "unsupported_backend"}
    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}
    service = _get_oauth_service()
    try:
        return await service.remove_web_auth(backend)
    except NativeMigrationBlockedError as exc:
        return _native_write_blocked(exc)
    except Exception as exc:  # noqa: BLE001
        logger.error("Web auth remove failed for %s: %s", backend, exc, exc_info=True)
        return {"ok": False, "error": "remove_failed", "detail": str(exc)}


async def remove_claude_oauth_credentials_async() -> dict:
    """Clear only Claude Code OAuth credentials, preserving API-key auth."""
    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}
    service = _get_oauth_service()
    try:
        return await service.clear_claude_oauth_credentials_only()
    except NativeMigrationBlockedError as exc:
        return _native_write_blocked(exc)
    except Exception as exc:  # noqa: BLE001
        logger.error("Claude OAuth credentials cleanup failed: %s", exc, exc_info=True)
        return {"ok": False, "error": "remove_failed", "detail": str(exc)}


def remove_claude_oauth_credentials() -> dict:
    return _submit_oauth_coro(remove_claude_oauth_credentials_async(), timeout=30.0)


def _clear_claude_oauth_credentials_after_api_key_save(service=None, *, lease=None) -> dict:
    service = service or _get_oauth_service()
    return _submit_oauth_coro(
        service.clear_claude_oauth_credentials_only(**({"lease": lease} if lease is not None else {})),
        # The outer writer owns this explicit lease until cleanup truly exits;
        # a Future.result timeout would leave that writer running unprotected.
        timeout=None if lease is not None else 30.0,
    )


@_native_auth_write()
def remove_backend_api_key(backend: str) -> dict:
    """Clear the stored API key for Claude / Codex without touching OAuth.

    Mirrors OpenCode's "Remove key" vs "Sign out" split: Claude and
    Codex can both carry ``api_key`` *and* OAuth credentials at the
    same time, and the CLI picks api_key when both are present. Without
    a way to drop just the API key, a stale or rejected key keeps
    forcing 401s even after the user signed in via OAuth.

    - **Codex**: re-applies ``apply_codex_auth(auth_mode='oauth')``
      which pops ``OPENAI_API_KEY`` from ``~/.codex/auth.json`` and
      keeps any ``tokens`` blob intact. V2Config's
      ``agents.codex.api_key`` is also cleared and ``auth_mode`` is
      flipped to ``oauth``. Triggers ``restart_backend('codex')`` so
      the persistent daemon reloads.
    - **Claude**: remove Anthropic env overrides from Claude's
      ``settings.json``, clear legacy V2Config ``api_key`` / ``base_url``
      cache fields, and flip ``auth_mode`` to ``oauth``.
      Claude Code's OAuth token store is left alone.
    """
    backend = (backend or "").strip().lower()
    if backend not in {"claude", "codex"}:
        return {"ok": False, "error": "unsupported_backend"}
    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}

    notices: list = []
    if backend == "codex":
        from vibe.codex_config import apply_codex_auth

        try:
            result = apply_codex_auth(auth_mode="oauth", api_key=None, base_url=None)
            if isinstance(result, dict):
                raw_notices = result.get("notices")
                if isinstance(raw_notices, list):
                    notices = raw_notices
        except Exception as exc:  # noqa: BLE001
            logger.error("apply_codex_auth(oauth) during remove-key failed: %s", exc, exc_info=True)
            return {"ok": False, "error": "remove_failed", "detail": str(exc)}
    elif backend == "claude":
        from vibe.claude_config import apply_claude_auth

        try:
            apply_claude_auth(auth_mode="oauth", api_key=None, base_url=None)
        except Exception as exc:  # noqa: BLE001
            logger.error("apply_claude_auth(oauth) during remove-key failed: %s", exc, exc_info=True)
            return {"ok": False, "error": "remove_failed", "detail": str(exc)}

    # Clear V2Config api_key for both backends.
    try:
        from config.v2_config import update_config_fields

        def _clear_auth_fields(cfg: V2Config) -> None:
            target = getattr(getattr(cfg, "agents", None), backend, None)
            if target is None:
                return
            target.auth_mode = "oauth"
            target.api_key = None
            # Drop base_url for both backends, not just Codex: a
            # stale Claude relay URL stored in V2Config gets
            # injected into the subprocess as ``ANTHROPIC_BASE_URL``
            # on every launch via ``build_claude_subprocess_env``.
            # After removing an API key (intent: fall back to
            # OAuth), the OAuth credentials would still be routed
            # to the api-key-only relay and silently 401.
            target.base_url = None
            # Remove key is an explicit OAuth choice — the relay
            # marker goes with it, or a later refresh would
            # repopulate the abandoned relay and reroute a freshly
            # entered official key to it (Codex-only field).
            if backend == "codex":
                target.oauth_relay_marker = None
            # User explicitly chose OAuth by clicking Remove key —
            # mark the flag so legacy env-var fallback in
            # ``build_claude_subprocess_env`` is bypassed and the
            # inherited ``ANTHROPIC_*`` env actually gets stripped.
            if backend == "claude":
                target.auth_mode_set = True

        update_config_fields(_clear_auth_fields)
    except Exception as exc:  # noqa: BLE001
        logger.warning("V2Config clear during remove-key failed for %s: %s", backend, exc)
        # The disk key is already gone (the user-visible truth — report
        # success), but the persisted V2Config copy (cached key/base_url/
        # relay marker) may still hold stale auth state (#1451). Surface
        # it as a notice so the UI can say "removed, but saved settings
        # may be stale" instead of silently claiming a clean wipe.
        # Append: an earlier ``cleared_custom_relay_pointer`` notice from
        # ``apply_codex_auth`` is still true and must survive.
        notices = notices + [
            {
                "code": "v2_clear_failed",
                "backend": backend,
                "detail": str(exc),
            }
        ]

    # Both backends keep runtime state in the controller. Codex owns a
    # persistent app-server; Claude owns cached SDK sessions and a loaded
    # compat config. Refresh through the same controller path so the next
    # request observes the new auth without restarting the Avibe service.
    try:
        restart = restart_backend(
            backend,
            metadata={"reason": "remove_api_key", "source": "ui_api"},
        )
    except Exception as exc:  # noqa: BLE001
        restart = {"ok": False, "message": str(exc)}
    response: dict = {"ok": True, "restart": restart}
    if notices:
        response["notices"] = notices
    return response


def test_backend_auth(backend: str, model: Optional[str] = None) -> dict:
    return _submit_oauth_coro(test_backend_auth_async(backend, model=model), timeout=60.0)


async def test_backend_auth_async(backend: str, model: Optional[str] = None) -> dict:
    """Send a ``Hi`` probe through the backend's production Agent transport.

    Claude uses the Agent SDK and Codex uses app-server, matching normal
    Avibe turns rather than a separate single-shot CLI mode. ``model`` lets
    the caller select the model used by that isolated turn.
    """
    backend = (backend or "").strip().lower()
    if not supports_web_oauth(backend):
        return {"ok": False, "error": "unsupported_backend"}
    service = _get_oauth_service()
    try:
        return await service.test_web_auth(backend, model=model)
    except NativeMigrationBlockedError as exc:
        return _native_write_blocked(exc)
    except Exception as exc:  # noqa: BLE001
        logger.error("Web auth test failed for %s: %s", backend, exc, exc_info=True)
        return {"ok": False, "error": "test_failed", "detail": str(exc)}


def test_opencode_provider(provider_id: str, model: Optional[str] = None) -> dict:
    return _submit_oauth_coro(test_opencode_provider_async(provider_id, model=model), timeout=90.0)


async def test_opencode_provider_async(provider_id: str, model: Optional[str] = None) -> dict:
    """Probe a single OpenCode provider over the live ``opencode serve`` HTTP API.

    OpenCode users typically wire up multiple providers (OpenAI, Poe,
    Anthropic, ...) but only a few will be active at any time. A single
    backend-wide button would either spuriously fail when one is broken
    or hide which one works. Per-provider probes echo the model's
    response so the user knows the round-trip actually returned text.
    """
    provider_id = (provider_id or "").strip()
    if not provider_id:
        return {"ok": False, "error": "missing_provider"}
    service = _get_oauth_service()
    try:
        return await service.test_opencode_provider(provider_id, model=model)
    except NativeMigrationBlockedError as exc:
        return _native_write_blocked(exc)
    except Exception as exc:  # noqa: BLE001
        logger.error(
            "OpenCode provider test failed for %s: %s",
            provider_id,
            exc,
            exc_info=True,
        )
        return {"ok": False, "error": "test_failed", "detail": str(exc)}


def cancel_oauth_web(flow_id: str) -> dict:
    return _submit_oauth_coro(cancel_oauth_web_async(flow_id), timeout=15.0)


async def cancel_oauth_web_async(flow_id: str) -> dict:
    flow_id = (flow_id or "").strip()
    if not flow_id:
        return {"ok": False, "error": "missing_flow_id"}
    service = _get_oauth_service()
    try:
        return await service.cancel_web_flow(flow_id)
    except Exception as exc:  # noqa: BLE001
        logger.error("Web OAuth cancel failed: %s", exc, exc_info=True)
        return {"ok": False, "error": "cancel_failed", "detail": str(exc)}


def get_codex_auth() -> dict:
    """Return the user-facing Codex auth state for the Settings UI.

    Merges two sources of truth:
    - on-disk ``~/.codex/{config.toml,auth.json}`` (what Codex actually
      reads at launch) — authoritative for ``has_api_key`` / ``base_url`` /
      ``has_chatgpt_tokens`` so the UI never lies when the user edited the
      files by hand.
    - ``V2Config.agents.codex`` — the mode we *intend* to be in, useful as
      a tiebreaker (e.g. user clicked OAuth but hasn't run ``codex login``
      yet, so disk has no tokens but our config says oauth).

    Secrets never leave the server; only length is returned.
    """
    from vibe.codex_config import read_codex_auth_state

    disk_state = read_codex_auth_state()
    try:
        config = load_config()
        cfg = getattr(getattr(config, "agents", None), "codex", None)
        configured_mode = getattr(cfg, "auth_mode", None)
        raw_relay_marker = getattr(cfg, "oauth_relay_marker", None)
    except Exception:
        configured_mode = None
        raw_relay_marker = None
    from vibe.codex_config import read_codex_relay_marker

    # Disk-first with the explicit OAuth-transition marker as fallback.
    # The disk chain (active provider → managed → legacy) is what a live
    # Codex launch would use. The marker (captured by
    # ``AgentAuthService._persist_backend_auth_mode`` before the OAuth
    # cleanup destroys the on-disk evidence) is the only recovery
    # source: it is consumed verbatim, with no ambient-state inference —
    # dormant sections and stale caches surface nothing. The marker is
    # only consulted while the disk shows live OAuth credentials AND the
    # credential store actually exposes the live state to us: once an
    # API key exists in ``auth.json`` (e.g. the user ran ``codex login
    # --with-api-key`` outside Avibe) the live disk configuration is
    # authoritative; when ``cli_auth_credentials_store`` is
    # ``auto``/``keyring`` the key may live in the OS keychain instead
    # (file-only ``has_api_key`` can't see it); and when the tokens are
    # gone too (e.g. ``codex logout`` during the OAuth window) the user
    # has signed out of the relay entirely (#1453) — in all three cases
    # the leftover marker must not surface or reroute a pasted key to
    # the relay it remembers.
    relay_marker = None
    if (
        not disk_state.get("has_api_key")
        and disk_state.get("file_store_active")
        and disk_state.get("has_chatgpt_tokens")
    ):
        relay_marker = read_codex_relay_marker(raw_relay_marker)
    if relay_marker:
        effective_base_url: str | None = disk_state.get("base_url") or relay_marker["base_url"]
    else:
        effective_base_url = disk_state.get("base_url")

    # Disk wins when it carries unambiguous evidence of API-key auth: an
    # ``OPENAI_API_KEY`` in ``~/.codex/auth.json`` is a concrete artefact
    # the user (or a prior ``codex login`` flow) placed there. ``V2Config``
    # may still default ``auth_mode`` to ``"oauth"`` on the upgrade path
    # (older configs lacked the field entirely), so trusting the config
    # alone would make the UI render OAuth and a subsequent save would
    # then wipe ``OPENAI_API_KEY``. Configured mode remains the source of
    # truth only when disk has no key — i.e., the user's stated intent
    # before they have signed in or pasted credentials.
    if disk_state.get("has_api_key"):
        auth_mode: str | None = "api_key"
    elif configured_mode in _VALID_AUTH_MODES:
        auth_mode = configured_mode
    else:
        auth_mode = disk_state.get("auth_mode")
    # The *active* auth source the running Codex CLI uses at launch is
    # determined entirely by ``~/.codex/auth.json``: a stored API key wins;
    # else ChatGPT tokens; else "not configured". This is what the user
    # cares about ("which one is actually working"), separate from the
    # ``auth_mode`` field above (which is the *intent* we'd save next).
    has_api_key_live = bool(disk_state.get("has_api_key"))
    has_chatgpt_live = bool(disk_state.get("has_chatgpt_tokens"))
    if has_api_key_live:
        active_auth_mode = "api_key"
    elif has_chatgpt_live:
        active_auth_mode = "oauth"
    else:
        active_auth_mode = "none"

    return {
        "ok": True,
        "auth_mode": auth_mode or "oauth",
        "active_auth_mode": active_auth_mode,
        "has_api_key": has_api_key_live,
        "api_key_length": int(disk_state.get("api_key_length") or 0),
        "api_key_masked": _mask_api_key(disk_state.get("api_key_raw")),
        "base_url": effective_base_url,
        "has_chatgpt_tokens": has_chatgpt_live,
        "chatgpt_account": disk_state.get("chatgpt_account"),
        # Forward the live Codex credentials-store status so the UI can
        # warn when the user is about to switch storage backends
        # (Codex's documented default is ``auto`` → keyring-preferred).
        # Dropping these here was the bug: the React page would treat
        # ``file_store_active`` as undefined and surface a keyring
        # warning even when the store is already ``file``.
        "credentials_store": disk_state.get("credentials_store") or "auto",
        "file_store_active": bool(disk_state.get("file_store_active")),
        # Surface "we can't read your key — it may live in the OS
        # keychain" so the UI doesn't claim "no key configured" when
        # Codex is in keyring-preferred mode and we have no disk
        # evidence. Saved intent cannot resolve an unreadable native store.
        "auth_mode_uncertain": bool(disk_state.get("auth_mode_uncertain")),
    }


@_native_auth_write("codex")
def save_codex_auth(payload: dict) -> dict:
    """Persist Codex auth: V2Config + ``~/.codex/{config.toml,auth.json}``.

    The on-disk write is what Codex actually reads; the V2Config write
    records the user's intent so the UI can render a coherent state after
    restart. We treat the disk write as authoritative — if it fails, we
    surface the error instead of leaving V2Config out of sync.

    After writing, we trigger ``restart_backend('codex')`` so the persistent
    app-server reloads with the new credentials. The restart failure is
    surfaced but does not roll back the config write; the user can retry.
    """
    if not isinstance(payload, dict):
        return {"ok": False, "message": "Payload must be an object"}

    auth_mode = payload.get("auth_mode")
    if auth_mode not in _VALID_AUTH_MODES:
        return {"ok": False, "message": f"auth_mode must be one of {sorted(_VALID_AUTH_MODES)}"}

    raw_api_key = payload.get("api_key")
    if raw_api_key is not None and not isinstance(raw_api_key, str):
        return {"ok": False, "message": "api_key must be a string"}
    api_key = raw_api_key.strip() if isinstance(raw_api_key, str) else None

    # Three-state ``base_url`` payload (matches the OpenCode provider save
    # handler and the new web Settings → OAuth flow): omitting the key
    # means "leave the stored value alone" so toggling auth_mode does not
    # accidentally clear a relay URL the user had set up in api_key mode.
    base_url_present = "base_url" in payload
    raw_base_url = payload.get("base_url") if base_url_present else None
    if base_url_present and raw_base_url is not None and not isinstance(raw_base_url, str):
        return {"ok": False, "message": "base_url must be a string"}
    base_url_change: Optional[str] = None
    if base_url_present:
        base_url_change = raw_base_url.strip() if isinstance(raw_base_url, str) else None
        if base_url_change == "":
            base_url_change = None

    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}

    if auth_mode == "api_key" and not api_key:
        # Allow callers to PATCH base_url alone by reusing the stored key.
        # ``auth.json`` is the live source Codex reads at launch, and it
        # captures keys rotated outside this flow (e.g. ``codex login
        # --with-api-key``). The V2Config cache can be stale relative to
        # disk, so trusting it first would silently revert a freshly
        # rotated key when we re-write ``auth.json`` below. Prefer disk;
        # fall back to V2Config only if disk has nothing (legacy installs
        # that never wrote ``auth.json``).
        try:
            from vibe.codex_config import read_codex_api_key

            api_key = read_codex_api_key()
        except Exception:
            api_key = None
        if not api_key:
            with CONFIG_LOCK:
                try:
                    existing = load_config()
                    stored = getattr(getattr(existing, "agents", None), "codex", None)
                    api_key = getattr(stored, "api_key", None) or None
                except Exception:
                    api_key = None
        if not api_key:
            return {"ok": False, "message": "api_key is required when auth_mode='api_key'"}

    # Resolve the effective base_url: explicit payload wins, otherwise
    # prefer the value Codex actually reads on disk, falling back to the
    # V2Config cache. Disk-first mirrors the api-key resolution above:
    # the live ``config.toml`` is what Codex reads at launch, so a relay
    # ``base_url`` hand-edited there (or left behind by an oauth pass
    # that cleared our managed section) must outrank a possibly-stale
    # cache. Trusting the cache alone either reverts hand edits or, when
    # the cache is empty, drops the relay entirely — sending a relay API
    # key to ``api.openai.com`` and surfacing as a confusing 401 after
    # an auth-mode switch.
    # Explicit OAuth-transition marker: the relay identity recorded when
    # the OAuth cleanup destroyed the on-disk evidence. Consumed
    # verbatim — a plain cached ``base_url`` is NOT a recovery source
    # (it is only the user's last saved preference and may be stale).
    # Gated on live OAuth credentials being observable: an API key in
    # ``auth.json`` (e.g. ``codex login --with-api-key`` outside Avibe)
    # means the live disk configuration already won; a non-file
    # credential store hides the key in the OS keychain; and cleared
    # tokens (``codex logout`` in the OAuth window) mean the user signed
    # out of the relay (#1453). In all three cases the leftover marker
    # must not reroute a pasted key to the relay it remembers.
    #
    # ``#1449``: an ``auth_mode="oauth"`` save through this endpoint is
    # itself an OAuth transition for non-React clients — capture the
    # live relay identity before ``apply_codex_auth`` destroys it, with
    # the same retention semantics as the controller path.
    marker = None
    captured_oauth_relay: Optional[dict] = None
    observed_api_key_auth = False
    codex_disk_state: dict = {}
    try:
        from vibe.codex_config import read_codex_auth_state, read_codex_relay_marker

        codex_disk_state = read_codex_auth_state()
        with CONFIG_LOCK:
            try:
                marker_cfg = load_config()
                marker_codex = getattr(getattr(marker_cfg, "agents", None), "codex", None)
                raw_marker = getattr(marker_codex, "oauth_relay_marker", None)
            except Exception:
                raw_marker = None
        if (
            not codex_disk_state.get("has_api_key")
            and codex_disk_state.get("file_store_active")
            and codex_disk_state.get("has_chatgpt_tokens")
        ):
            marker = read_codex_relay_marker(raw_marker)
        if auth_mode == "oauth":
            live_base_url = codex_disk_state.get("base_url")
            if isinstance(live_base_url, str) and live_base_url.strip():
                live_provider_id = codex_disk_state.get("active_provider_id")
                captured_oauth_relay = {
                    "base_url": live_base_url.strip(),
                    "provider_id": live_provider_id
                    if isinstance(live_provider_id, str) and live_provider_id.strip()
                    else "",
                }
            else:
                observed_api_key_auth = bool(codex_disk_state.get("has_api_key"))
    except Exception:
        logger.debug("Codex relay marker read failed", exc_info=True)
        marker = None

    # Durability (#1450): a fresh capture — or the official-key
    # transition's clear — is persisted BEFORE ``apply_codex_auth(oauth)``
    # destroys the on-disk relay evidence, so a later V2Config failure
    # cannot lose the transition state. A failed pre-persist only costs
    # switch-back recovery, never the save.
    if auth_mode == "oauth" and (captured_oauth_relay is not None or observed_api_key_auth):
        try:
            from vibe.codex_config import persist_codex_relay_marker

            # ``None`` here is deliberate for the official-key case: the
            # pre-persist records the transition's marker-clear.
            if not persist_codex_relay_marker(captured_oauth_relay):
                logger.warning(
                    "Codex relay marker pre-persist failed; switch-back recovery may be lost"
                )
        except Exception:
            logger.warning("Codex relay marker pre-persist raised", exc_info=True)

    if base_url_present:
        effective_base_url = base_url_change
    else:
        effective_base_url = None
        try:
            from vibe.codex_config import read_codex_auth_state

            disk_base_url = read_codex_auth_state().get("base_url")
            if isinstance(disk_base_url, str) and disk_base_url.strip():
                effective_base_url = disk_base_url.strip()
        except Exception:
            logger.debug("Codex disk base_url read failed", exc_info=True)
        if not effective_base_url and marker:
            effective_base_url = marker["base_url"]

    # Provider-identity restore hint: only when the marker actually
    # SUPPLIED the resolved URL — the omitted-``base_url`` fallback, or
    # an explicit form value pre-populated from the marker-backed state
    # while the disk chain itself carries no URL. When the disk chain
    # resolved the same URL (the user activated a different provider
    # section with an identical relay during the OAuth window), the
    # live pointer wins and must not be re-pointed at the marker's
    # provider.
    restore_provider_id: Optional[str] = None
    if (
        marker is not None
        and effective_base_url == marker["base_url"]
        and codex_disk_state.get("base_url") != effective_base_url
    ):
        restore_provider_id = marker["provider_id"]

    from vibe.codex_config import apply_codex_auth

    notices: list = []
    try:
        result = apply_codex_auth(
            auth_mode=auth_mode,
            api_key=api_key,
            base_url=effective_base_url,
            restore_provider_id=restore_provider_id,
        )
        if isinstance(result, dict):
            raw_notices = result.get("notices")
            if isinstance(raw_notices, list):
                notices = raw_notices
    except ValueError as exc:
        return {"ok": False, "message": str(exc)}
    except OSError as exc:
        logger.error("Failed to write Codex auth files: %s", exc, exc_info=True)
        return {"ok": False, "message": f"Failed to write Codex config: {exc}"}

    from config.v2_config import update_config_fields

    def _apply_codex_auth(cfg: V2Config) -> None:
        cfg.agents.codex.auth_mode = auth_mode
        cfg.agents.codex.api_key = api_key if auth_mode == "api_key" else None
        cfg.agents.codex.base_url = effective_base_url
        # Marker lifecycle on save: an explicit API-key save consumes
        # the OAuth-transition marker (the user just chose their
        # endpoint — restored, typed fresh, or official-only); an OAuth
        # save applies the same retention semantics as the controller
        # path (#1449): fresh capture overwrites, the official-key
        # transition clears, a repeated pure-OAuth save retains.
        if auth_mode == "api_key":
            cfg.agents.codex.oauth_relay_marker = None
        elif captured_oauth_relay is not None:
            cfg.agents.codex.oauth_relay_marker = captured_oauth_relay
        elif observed_api_key_auth:
            cfg.agents.codex.oauth_relay_marker = None

    try:
        update_config_fields(_apply_codex_auth)
    except Exception:
        # The on-disk codex files are authoritative and the durable
        # marker state was pre-persisted, but the V2Config mirror
        # (auth_mode / base_url intent the controller reloads via
        # ``_load_backend_runtime_config``) did NOT land — surface a
        # partial-failure notice instead of silently reporting
        # success while runtime reconciliation sees stale config.
        logger.warning("V2Config mirror write failed during codex auth save", exc_info=True)
        notices = notices + [
            {"code": "v2_mirror_save_failed", "detail": "saved to codex files but not to Avibe config"}
        ]

    restart_result = restart_backend(
        "codex",
        metadata={"reason": "save_codex_auth", "source": "ui_api"},
    )
    state = get_codex_auth()
    state["restart"] = restart_result
    if notices:
        # Surface non-fatal config-rewrite notices (e.g. "we cleared a
        # custom relay pointer because OAuth tokens won't validate
        # against ai-relay.chainbot.io") so the UI can show a one-time
        # banner. Without this the user sees a green "saved" toast then
        # hits a confusing 401 on their next request.
        state["notices"] = notices
    if not restart_result.get("ok", False):
        # Config written, restart failed — tell the UI both so the toast
        # can say "saved, but you may need to restart Codex manually".
        state["ok"] = True
        state["message"] = restart_result.get("message")
    return state


def _claude_oauth_store_state() -> str:
    """Classify safe native-store inventory without reading a secret value.

    ``present`` is inspectable Claude OAuth material, not a login. A Keychain
    container, denied/unreadable/invalid evidence or a failed read is
    ``unknown``: it proves neither a usable account nor its absence.
    """
    from vibe.native_oauth_store import read_native_oauth

    try:
        snapshot = read_native_oauth("claude", allow_secret=False)
    except Exception:
        logger.debug("Claude native OAuth inventory could not be observed")
        return "unknown"
    if snapshot is None:
        return "absent"
    return "present" if snapshot.exportable else "unknown"


def get_claude_auth() -> dict:
    """Return the Claude Settings inventory: saved configuration and native evidence.

    Claude owns authentication. This passive read never launches Claude,
    never predicts which credential Claude will select at launch, and never
    creates a working directory. It reports two local facts:

    1. The configuration this editor manages: the API-key / token /
       Base URL ``env`` in ``~/.claude/settings.json`` (Claude's own file),
       with legacy V2Config keys read only as a migration fallback.
    2. Native OAuth store inventory (``oauth_store_state``), which is not
       effective authentication or token validity.

    ``active_auth_mode`` is a legacy wire field kept conservatively at
    ``"none"`` with ``auth_mode_uncertain``; ``auth_mode`` is the saved
    editing choice, not runtime truth.
    """
    from vibe.claude_config import read_claude_auth_state, read_claude_settings_env

    disk_state = read_claude_auth_state()
    settings_env = read_claude_settings_env()
    settings_key = settings_env.get("ANTHROPIC_API_KEY") or settings_env.get("ANTHROPIC_AUTH_TOKEN") or ""
    settings_base = settings_env.get("ANTHROPIC_BASE_URL") or ""

    try:
        config = load_config()
        cfg = getattr(getattr(config, "agents", None), "claude", None)
        configured_mode = getattr(cfg, "auth_mode", None)
        configured_key = getattr(cfg, "api_key", None) or ""
        configured_base = getattr(cfg, "base_url", None) or ""
    except Exception:
        configured_mode = None
        configured_key = ""
        configured_base = ""

    configured_key = configured_key.strip() if isinstance(configured_key, str) else ""
    configured_base = configured_base.strip() if isinstance(configured_base, str) else ""

    # settings.json wins: it is the file Claude Code itself layers on top
    # of inherited env. V2Config is a legacy fallback only.
    effective_key = settings_key or configured_key
    effective_base = settings_base or configured_base
    has_api_key = bool(effective_key)

    if configured_mode in _VALID_AUTH_MODES:
        auth_mode = configured_mode
    elif effective_key:
        auth_mode = "api_key"
    else:
        auth_mode = "oauth"

    # Which storage the saved API key came from — helps the UI explain the
    # state ("Key configured in settings.json"). Plaintext never leaves
    # the server; only the mask is forwarded.
    if settings_key:
        api_key_source = "settings_json"
    elif configured_key:
        api_key_source = "v2config"
    else:
        api_key_source = None

    oauth_store_state = _claude_oauth_store_state()

    return {
        "ok": True,
        "auth_mode": auth_mode,
        "auth_managed_by": "claude",
        "active_auth_mode": "none",
        "auth_mode_uncertain": True,
        "oauth_store_state": oauth_store_state,
        "has_api_key": has_api_key,
        "api_key_length": len(effective_key),
        "api_key_masked": _mask_api_key(effective_key),
        "api_key_source": api_key_source,
        "has_oauth_credentials": oauth_store_state == "present",
        "can_remove_oauth_credentials": oauth_store_state != "absent",
        "base_url": effective_base or None,
        "settings_path": disk_state.get("settings_path"),
        "settings_exists": bool(disk_state.get("settings_exists")),
        "settings_env_has_key": bool(disk_state.get("settings_env_has_key")),
        "settings_env_key_length": int(disk_state.get("settings_env_key_length") or 0),
        "settings_env_key_var": disk_state.get("settings_env_key_var"),
        "credential_type": (
            disk_state.get("credential_type")
            if settings_key
            else ("api_key" if configured_key else None)
        ),
        "settings_env_base_url": disk_state.get("settings_env_base_url"),
        "settings_conflict": False,
    }


@_native_auth_write("claude", pass_lease=True)
def save_claude_auth(payload: dict, *, _native_lease=None) -> dict:
    """Persist Claude auth into Claude Code's own ``settings.json``.

    V2Config records only non-secret intent/legacy cleanup state. It must
    not carry the API key because Claude Code's ``settings.json`` env block
    wins at launch anyway.

    ``credential_type`` selects Claude Code's native credential variable:
    ``api_key`` writes ``ANTHROPIC_API_KEY`` and ``auth_token`` writes
    ``ANTHROPIC_AUTH_TOKEN``. The Base URL is independent and never changes
    that selection. When callers omit ``credential_type``, an existing
    settings variable is preserved; new and legacy credentials default to
    ``api_key`` for backwards compatibility.

    Empty ``api_key`` while in ``api_key`` mode means "keep the stored
    credential", so callers can update the Base URL or credential type without
    re-typing the secret. An empty value with no stored fallback is rejected.
    """
    if not isinstance(payload, dict):
        return {"ok": False, "message": "Payload must be an object"}

    auth_mode = payload.get("auth_mode")
    if auth_mode not in _VALID_AUTH_MODES:
        return {"ok": False, "message": f"auth_mode must be one of {sorted(_VALID_AUTH_MODES)}"}

    raw_api_key = payload.get("api_key")
    if raw_api_key is not None and not isinstance(raw_api_key, str):
        return {"ok": False, "message": "api_key must be a string"}
    api_key = raw_api_key.strip() if isinstance(raw_api_key, str) else None

    raw_credential_type = payload.get("credential_type")
    if (
        raw_credential_type is not None
        and (
            not isinstance(raw_credential_type, str)
            or raw_credential_type not in _VALID_CLAUDE_CREDENTIAL_TYPES
        )
    ):
        return {
            "ok": False,
            "message": backend_t("error.claudeCredentialTypeInvalid"),
        }

    # Three-state ``base_url`` payload semantics (matches Codex/OpenCode):
    # absent key → keep stored value; null/blank → clear; non-blank → set.
    base_url_present = "base_url" in payload
    raw_base_url = payload.get("base_url") if base_url_present else None
    if base_url_present and raw_base_url is not None and not isinstance(raw_base_url, str):
        return {"ok": False, "message": "base_url must be a string"}
    base_url_change: Optional[str] = None
    if base_url_present:
        base_url_change = raw_base_url.strip() if isinstance(raw_base_url, str) else None
        if base_url_change == "":
            base_url_change = None

    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}

    oauth_cleanup_service = _get_oauth_service() if auth_mode == "api_key" else None
    if oauth_cleanup_service is not None:
        # Construction may defer recovery because this outer operation already
        # owns the lease. Adopt it explicitly before reading/writing new settings.
        oauth_cleanup_service._recover_interrupted_claude_oauth_settings_backup(lease=_native_lease)

    settings_env: dict[str, str] = {}
    existing_credential_type: str | None = None
    existing_credential: str | None = None
    if auth_mode == "api_key":
        try:
            from vibe.claude_config import (
                read_claude_credential_from_settings,
                read_claude_settings_env,
            )

            settings_env = read_claude_settings_env()
            existing_credential_type, existing_credential = (
                read_claude_credential_from_settings()
            )
        except Exception:
            settings_env = {}

    credential_type = None
    if auth_mode == "api_key":
        credential_type = raw_credential_type or existing_credential_type or "api_key"
    credential = api_key or existing_credential

    if auth_mode == "api_key" and not credential:
        # Fall back to legacy V2Config only for older installs that have not
        # yet migrated their credential into Claude Code settings.
        with CONFIG_LOCK:
            try:
                existing = load_config()
                stored = getattr(getattr(existing, "agents", None), "claude", None)
                credential = getattr(stored, "api_key", None) or None
            except Exception:
                pass
        if not credential:
            return {"ok": False, "message": "api_key is required when auth_mode='api_key'"}

    effective_base_url = base_url_change if base_url_present else None
    if not base_url_present and auth_mode == "api_key":
        existing_base = settings_env.get("ANTHROPIC_BASE_URL")
        if isinstance(existing_base, str) and existing_base.strip():
            effective_base_url = existing_base.strip()
        else:
            with CONFIG_LOCK:
                try:
                    existing = load_config()
                    stored = getattr(getattr(existing, "agents", None), "claude", None)
                    effective_base_url = getattr(stored, "base_url", None) or None
                except Exception:
                    effective_base_url = None

    from vibe.claude_config import apply_claude_auth

    try:
        apply_claude_auth(
            auth_mode=auth_mode,
            api_key=(
                credential
                if auth_mode == "api_key" and credential_type == "api_key"
                else None
            ),
            base_url=effective_base_url if auth_mode == "api_key" else None,
            auth_token=(
                credential
                if auth_mode == "api_key" and credential_type == "auth_token"
                else None
            ),
        )
    except ValueError as exc:
        return {"ok": False, "message": str(exc)}
    except OSError as exc:
        logger.error("Failed to write Claude settings.json: %s", exc, exc_info=True)
        return {"ok": False, "message": f"Failed to write Claude settings: {exc}"}

    from config.v2_config import update_config_fields

    def _apply_claude_auth(cfg: V2Config) -> None:
        cfg.agents.claude.auth_mode = auth_mode
        # Flip the explicit marker so ``build_claude_subprocess_env``
        # honors ``auth_mode`` strictly (strip inherited env in OAuth
        # mode) for this and subsequent launches. Legacy installs that
        # have never been through this save path keep the flag at its
        # ``False`` default and continue to inherit shell env vars.
        cfg.agents.claude.auth_mode_set = True
        # Secrets and endpoint overrides live in Claude's own settings.json.
        # Clear legacy cache fields so future reads do not have two writers.
        cfg.agents.claude.api_key = None
        cfg.agents.claude.base_url = None

    update_config_fields(_apply_claude_auth)

    oauth_cleanup_result: dict | None = None
    if auth_mode == "api_key":
        try:
            oauth_cleanup_result = _clear_claude_oauth_credentials_after_api_key_save(
                oauth_cleanup_service, lease=_native_lease,
            )
        except Exception as exc:  # noqa: BLE001
            logger.warning("Failed to clear Claude OAuth credentials after API-key save: %s", exc)
            oauth_cleanup_result = {
                "ok": True,
                "partial": True,
                "warning": "oauth_cleanup_failed",
                "detail": str(exc),
            }

    # Claude SDK clients are cached by the controller. Roll them through
    # the existing backend refresh path so the next turn cannot retain the
    # previous mode's environment or loaded compatibility config.
    try:
        restart = restart_backend(
            "claude",
            metadata={"reason": "save_claude_auth", "source": "ui_api"},
        )
    except Exception as exc:  # noqa: BLE001
        restart = {"ok": False, "message": str(exc)}

    state = get_claude_auth()
    state["restart"] = restart
    if isinstance(oauth_cleanup_result, dict) and oauth_cleanup_result.get("partial"):
        state["partial"] = True
        state["warning"] = oauth_cleanup_result.get("warning") or "oauth_cleanup_failed"
        state["detail"] = oauth_cleanup_result.get("detail")
    return state


# ---------------------------------------------------------------------------
# OpenCode provider configuration
# ---------------------------------------------------------------------------
#
# The OpenCode page in Settings → Backends is fully dynamic: we never ship
# a hard-coded provider list. Instead we fan out to the running OpenCode
# server (``GET /provider`` for the catalog, ``GET /provider/auth`` for
# the auth-method index, ``GET /config/providers`` for model lists) and
# merge the responses into a per-card view with ``configured`` /
# ``oauth_available`` / ``local`` flags.
#
# Provider config writes update ``opencode.json`` directly because OpenCode
# stores custom providers, base URLs, user models, and provider option API keys
# there. ``auth.json`` remains OpenCode-owned: when we need to remove a stale
# or conflicting entry, we go through OpenCode's ``DELETE /auth/<id>`` wrapper
# instead of editing the auth file ourselves. We also persist
# ``default_provider`` into ``V2Config`` so the chip and routing layers stay in
# sync across restarts.


async def _opencode_lease(purpose: str):
    """Lease a controller-owned OpenCode generation for UI-process HTTP calls.

    The UI process never launches OpenCode. Returns ``None`` only when
    OpenCode is disabled. When it is enabled, a lease that cannot be had, for
    example because the controller is unreachable or no generation can start,
    raises: a caller must never take an unavailable runtime for a disabled one.
    """
    from config.v2_compat import to_app_config
    from modules.agents.opencode.client_manager import lease_opencode_server

    if not to_app_config(V2Config.load()).opencode:
        return None
    return await lease_opencode_server(purpose, ttl_seconds=60.0)


_LOCAL_PROVIDER_IDS = {"ollama", "lmstudio", "lm-studio"}
_OPENCODE_PROVIDER_REFRESH_ATTEMPTS = 3
_OPENCODE_PROVIDER_REFRESH_DELAY_SECONDS = 0.5


def _opencode_provider_model_ids(provider: dict) -> set[str]:
    raw_models = provider.get("models") if isinstance(provider, dict) else None
    if isinstance(raw_models, dict):
        return {model_id for model_id in raw_models if isinstance(model_id, str)}
    if isinstance(raw_models, list):
        ids: set[str] = set()
        for model in raw_models:
            model_id = model.get("id") if isinstance(model, dict) else None
            if isinstance(model_id, str):
                ids.add(model_id)
        return ids
    return set()


def _is_opencode_user_model(model_id: str, model_info: dict) -> bool:
    meta = model_info.get("vibe_remote") if isinstance(model_info, dict) else None
    if isinstance(meta, dict) and meta.get("user_model") is True:
        return True
    return model_info.get("id") == model_id and model_info.get("name") == model_id


def _is_local_provider(provider_id: str, auth_methods: list) -> bool:
    """Whether the provider runs on localhost and needs no credentials.

    Earlier this also tagged ``no auth methods → local`` but OpenCode
    1.14's ``/provider/auth`` only enumerates providers that have OAuth
    or special prompts — bare API-key providers (minimax, openrouter,
    poe…) are simply absent from that map. Treating absence as "local"
    pushed them into a fallback that kept ``configured`` True even
    after the user removed their key. Narrow to a known-local
    whitelist; the auth-methods param is kept for symmetry / future use.
    """
    _ = auth_methods  # noqa: F841 — kept for callsite symmetry
    return isinstance(provider_id, str) and provider_id.lower() in _LOCAL_PROVIDER_IDS


def _configured_opencode_provider_ids(
    *,
    providers_raw: dict,
    auth_entries: dict,
    config_api_key_provider_ids: set[str] | None = None,
    custom_config_provider_ids: set[str] | None = None,
) -> set[str]:
    connected = providers_raw.get("connected") if isinstance(providers_raw, dict) else None
    connected_set = {pid for pid in connected if isinstance(pid, str)} if isinstance(connected, list) else set()
    all_providers = _coerce_opencode_provider_catalog(providers_raw)
    configured = {pid for pid in auth_entries.keys() if isinstance(pid, str)}
    configured.update(config_api_key_provider_ids or set())
    configured.update(custom_config_provider_ids or set())
    for pid in connected_set:
        if _is_local_provider(pid, []):
            configured.add(pid)
    for pid in all_providers:
        if _is_local_provider(pid, []) and pid in connected_set:
            configured.add(pid)
    return configured


def _filter_opencode_models_to_configured_providers(
    models: dict,
    *,
    providers_raw: dict,
    auth_entries: dict,
    config_api_key_provider_ids: set[str] | None = None,
    custom_config_provider_ids: set[str] | None = None,
) -> dict:
    """Drop unconfigured cloud providers from OpenCode model options.

    OpenCode's ``/config/providers`` returns catalog models for providers
    even after the user removes credentials. Settings/Agents model pickers
    should only offer models the runtime can actually use: providers with
    auth.json entries, provider option API keys, custom provider config,
    plus known local providers that are connected.
    """

    if not isinstance(models, dict):
        return models
    from modules.agents.opencode.utils import (
        filter_opencode_models_to_allowed_providers,
    )

    allowed = _configured_opencode_provider_ids(
        providers_raw=providers_raw,
        auth_entries=auth_entries,
        config_api_key_provider_ids=config_api_key_provider_ids,
        custom_config_provider_ids=custom_config_provider_ids,
    )
    filtered = filter_opencode_models_to_allowed_providers(models, allowed)
    providers = list(filtered.get("providers", []) or [])
    seen: set[str] = set()
    for provider in providers:
        if not isinstance(provider, dict):
            continue
        pid = _opencode_provider_id(provider)
        if isinstance(pid, str):
            seen.add(pid)

    for pid in allowed:
        if pid in seen:
            continue
        providers.append({"id": pid, "models": {}})

    return {**filtered, "providers": providers}


def _merge_opencode_user_models(
    models: dict,
    user_model_index: dict[str, dict[str, dict]],
    *,
    allowed_provider_ids: set[str] | None = None,
) -> dict:
    """Overlay user-configured ``provider.<id>.models`` onto model metadata."""

    if not isinstance(models, dict):
        return models
    providers_raw = models.get("providers")
    if not isinstance(providers_raw, list):
        return models
    if allowed_provider_ids is not None:
        from modules.agents.opencode.utils import (
            filter_opencode_models_to_allowed_providers,
        )

        models = filter_opencode_models_to_allowed_providers(
            models,
            allowed_provider_ids,
        )
        providers_raw = models.get("providers", [])
    if not user_model_index:
        return models

    providers = []
    seen: set[str] = set()
    for provider in providers_raw:
        if not isinstance(provider, dict):
            providers.append(provider)
            continue
        pid = provider.get("id") or provider.get("provider_id") or provider.get("name")
        if not isinstance(pid, str) or pid not in user_model_index:
            providers.append(provider)
            continue
        if allowed_provider_ids is not None and pid not in allowed_provider_ids:
            providers.append(provider)
            continue
        seen.add(pid)
        provider_models = provider.get("models")
        user_models = user_model_index.get(pid) or {}
        if isinstance(provider_models, dict):
            merged_models = {**provider_models, **user_models}
        elif isinstance(provider_models, list):
            merged_models = {
                model.get("id"): model
                for model in provider_models
                if isinstance(model, dict) and isinstance(model.get("id"), str)
            }
            merged_models.update(user_models)
        else:
            merged_models = dict(user_models)
        providers.append({**provider, "models": merged_models})

    for pid, user_models in user_model_index.items():
        if pid in seen:
            continue
        if allowed_provider_ids is not None and pid not in allowed_provider_ids:
            continue
        providers.append({"id": pid, "models": dict(user_models)})

    return {**models, "providers": providers, "default": {}}


def _opencode_provider_id(entry: dict) -> str | None:
    pid = entry.get("id") or entry.get("provider_id") or entry.get("name")
    return pid if isinstance(pid, str) and pid else None


async def _read_opencode_user_model_index() -> dict[str, dict[str, dict]]:
    try:
        opencode_probe = await asyncio.to_thread(
            load_first_opencode_user_config, logger_instance=logger
        )
    except Exception as exc:
        logger.debug("Could not read opencode.json for user model overlay: %s", exc)
        return {}

    if opencode_probe is None or not isinstance(opencode_probe.config, dict):
        return {}
    provider_block = opencode_probe.config.get("provider")
    if not isinstance(provider_block, dict):
        return {}

    user_model_index: dict[str, dict[str, dict]] = {}
    for pid_key, pid_config in provider_block.items():
        if not isinstance(pid_key, str) or not isinstance(pid_config, dict):
            continue
        models = pid_config.get("models")
        if not isinstance(models, dict):
            continue
        user_models = {
            model_id: model_info
            for model_id, model_info in models.items()
            if isinstance(model_id, str) and isinstance(model_info, dict)
        }
        if user_models:
            user_model_index[pid_key] = user_models
    return user_model_index


async def _read_opencode_custom_provider_ids() -> set[str]:
    try:
        from vibe.opencode_config import read_opencode_custom_providers

        custom_providers = await asyncio.to_thread(read_opencode_custom_providers, logger_instance=logger)
    except Exception as exc:
        logger.debug("Could not read opencode.json for custom providers: %s", exc)
        return set()
    if not isinstance(custom_providers, dict):
        return set()
    return {pid for pid in custom_providers if isinstance(pid, str)}


async def _read_opencode_config_api_key_provider_ids() -> set[str]:
    try:
        opencode_probe = await asyncio.to_thread(
            load_first_opencode_user_config, logger_instance=logger
        )
    except Exception as exc:
        logger.debug("Could not read opencode.json for provider apiKey options: %s", exc)
        return set()

    if opencode_probe is None or not isinstance(opencode_probe.config, dict):
        return set()
    provider_block = opencode_probe.config.get("provider")
    if not isinstance(provider_block, dict):
        return set()

    provider_ids: set[str] = set()
    for pid_key, pid_config in provider_block.items():
        if not isinstance(pid_key, str) or not isinstance(pid_config, dict):
            continue
        options = pid_config.get("options")
        if not isinstance(options, dict):
            continue
        api_key = options.get("apiKey")
        if isinstance(api_key, str) and api_key.strip():
            provider_ids.add(pid_key)
    return provider_ids


async def _read_opencode_config_api_key(provider_id: str) -> str | None:
    """Return provider.<id>.options.apiKey from opencode.json, if present."""

    if not isinstance(provider_id, str) or not provider_id.strip():
        return None
    pid = provider_id.strip()
    try:
        opencode_probe = await asyncio.to_thread(
            load_first_opencode_user_config, logger_instance=logger
        )
    except Exception as exc:
        logger.debug("Could not read opencode.json for provider apiKey: %s", exc)
        return None
    if opencode_probe is None or not isinstance(opencode_probe.config, dict):
        return None
    provider_block = opencode_probe.config.get("provider")
    if not isinstance(provider_block, dict):
        return None
    provider_config = provider_block.get(pid)
    if not isinstance(provider_config, dict):
        return None
    options = provider_config.get("options")
    if not isinstance(options, dict):
        return None
    api_key = options.get("apiKey")
    if isinstance(api_key, str) and api_key.strip():
        return api_key.strip()
    return None


def _custom_opencode_provider_row(provider_id: str, provider_config: dict) -> dict:
    meta = provider_config.get("vibe_remote")
    adapter_label = ""
    if isinstance(meta, dict):
        adapter_label = str(meta.get("adapter_label") or "")
    return {
        "id": provider_id,
        "name": provider_config.get("name") or provider_id,
        "description": adapter_label,
        "models": provider_config.get("models") if isinstance(provider_config.get("models"), dict) else {},
    }


def _coerce_opencode_provider_catalog(providers_raw) -> dict:
    """Normalize OpenCode ``/provider`` payloads into an id-keyed map.

    OpenCode 1.x returns ``{all: [Provider, ...], default: {...},
    connected: [...]}`` where ``all`` is a list. A pre-1.x prototype
    returned ``{all: {pid: Provider}}`` (dict). The original legacy shape
    was ``{providers: [...]}`` under a different top-level key. Tolerate
    all three so an OpenCode upgrade-in-place or a stale client cannot
    leave the Settings grid empty.
    """
    if not isinstance(providers_raw, dict):
        return {}
    out: dict = {}
    raw_all = providers_raw.get("all")
    if isinstance(raw_all, dict):
        return raw_all
    if isinstance(raw_all, list):
        for entry in raw_all:
            if isinstance(entry, dict):
                pid = entry.get("id")
                if pid:
                    out[pid] = entry
        return out
    legacy = providers_raw.get("providers")
    if isinstance(legacy, list):
        for entry in legacy:
            pid = entry.get("id") if isinstance(entry, dict) else None
            if pid:
                out[pid] = entry
    return out


async def _get_opencode_providers_async() -> dict:
    """Build the merged provider catalog reported to the Settings UI."""
    lease = await _opencode_lease("provider catalog")
    if lease is None:
        return {"ok": False, "message": "OpenCode is disabled in V2Config"}

    server = lease.server
    try:
        providers_raw, auth_raw, config_raw = await asyncio.gather(
            server.get_providers(),
            server.get_provider_auth(),
            server.get_native_available_models(os.path.expanduser("~")),
            return_exceptions=False,
        )
    finally:
        await lease.release()

    all_providers = _coerce_opencode_provider_catalog(providers_raw)

    connected = providers_raw.get("connected") if isinstance(providers_raw, dict) else None
    connected_set = {pid for pid in connected if isinstance(pid, str)} if isinstance(connected, list) else set()

    model_index: dict = {}
    if isinstance(config_raw, dict):
        for entry in config_raw.get("providers", []) or []:
            pid = entry.get("id") if isinstance(entry, dict) else None
            if pid:
                model_index[pid] = entry

    auth_index = auth_raw if isinstance(auth_raw, dict) else {}

    # Resolve the user-configured default provider. ``None`` means
    # the user has not picked one — the UI surfaces that as "no
    # default selected" so clicking a provider actually persists the
    # choice. Previously we fell back to ``"anthropic"`` here, which
    # made the UI render Anthropic as already-selected, and clicking
    # it became a no-op (no state change to persist), silently
    # blocking users from picking Anthropic explicitly.
    default_provider: str | None = None
    try:
        config = load_config()
        cfg = getattr(getattr(config, "agents", None), "opencode", None)
        configured_default = getattr(cfg, "default_provider", None)
        if isinstance(configured_default, str) and configured_default.strip():
            default_provider = configured_default.strip()
    except Exception:
        pass

    # Pre-load the user-config provider overrides once so we can attach
    # them to each row without re-parsing the JSON file per provider.
    try:
        from vibe.opencode_config import load_first_opencode_user_config

        opencode_probe = await asyncio.to_thread(
            load_first_opencode_user_config, logger_instance=logger
        )
    except Exception as exc:
        logger.debug("Could not read opencode.json for baseURL pre-population: %s", exc)
        opencode_probe = None
    base_url_index: dict = {}
    user_model_index: dict[str, dict[str, dict]] = {}
    custom_provider_index: dict[str, dict] = {}
    config_api_key_mask_index: dict[str, str] = {}
    if opencode_probe is not None and isinstance(opencode_probe.config, dict):
        provider_block = opencode_probe.config.get("provider")
        if isinstance(provider_block, dict):
            for pid_key, pid_config in provider_block.items():
                if not isinstance(pid_config, dict):
                    continue
                try:
                    from vibe.opencode_config import get_opencode_custom_provider_adapter

                    custom_adapter = get_opencode_custom_provider_adapter(pid_key, pid_config)
                except Exception:
                    custom_adapter = None
                if custom_adapter is not None:
                    custom_provider_index[pid_key] = pid_config
                models = pid_config.get("models")
                if isinstance(models, dict):
                    user_model_index[pid_key] = {
                        model_id: model_info
                        for model_id, model_info in models.items()
                        if isinstance(model_id, str) and isinstance(model_info, dict)
                    }
                options = pid_config.get("options")
                if not isinstance(options, dict):
                    continue
                candidate = options.get("baseURL")
                if isinstance(candidate, str) and candidate.strip():
                    base_url_index[pid_key] = candidate.strip()
                api_key = options.get("apiKey")
                if isinstance(api_key, str) and api_key.strip():
                    masked = _mask_api_key(api_key.strip())
                    if masked:
                        config_api_key_mask_index[pid_key] = masked
    for pid_key, pid_config in custom_provider_index.items():
        all_providers.setdefault(pid_key, _custom_opencode_provider_row(pid_key, pid_config))

    # Per-provider stored credentials, masked server-side so the
    # Settings UI can show a masked preview without leaking plaintext.
    # API keys managed by avibe live in opencode.json provider
    # options; auth.json is reserved for OpenCode's own connect/OAuth
    # flows and older installs that have not been repaired yet.
    try:
        from vibe.opencode_config import read_opencode_provider_auth_entries

        auth_entries = await asyncio.to_thread(
            read_opencode_provider_auth_entries, logger_instance=logger
        )
    except Exception as exc:
        logger.debug("Could not read OpenCode auth.json for masked keys: %s", exc)
        auth_entries = {}
    api_key_mask_index: dict = {}
    active_auth_type_index: dict = {}
    for pid_key, entry in auth_entries.items():
        entry_type = entry.get("type") if isinstance(entry, dict) else None
        if entry_type == "api":
            raw_key = entry.get("key") if isinstance(entry, dict) else None
            masked = _mask_api_key(raw_key) if raw_key else None
            if masked:
                api_key_mask_index[pid_key] = masked
            active_auth_type_index[pid_key] = "api"
        elif entry_type == "oauth":
            active_auth_type_index[pid_key] = "oauth"
        elif entry_type:
            active_auth_type_index[pid_key] = entry_type
    auth_file_provider_set: set = set(auth_entries.keys())
    config_api_key_provider_set: set = set(config_api_key_mask_index.keys())
    configured_provider_set = (
        auth_file_provider_set
        | config_api_key_provider_set
        | set(custom_provider_index.keys())
    )
    for pid_key, masked in config_api_key_mask_index.items():
        api_key_mask_index[pid_key] = masked
        active_auth_type_index[pid_key] = "api"

    out_providers = []
    for pid, entry in all_providers.items():
        if not isinstance(entry, dict):
            continue
        auth_methods = auth_index.get(pid)
        auth_methods_list = auth_methods if isinstance(auth_methods, list) else []
        oauth_available = any(
            isinstance(method, dict) and method.get("type") == "oauth"
            for method in auth_methods_list
        )
        local = _is_local_provider(pid, auth_methods_list)
        custom_config = custom_provider_index.get(pid, {})
        custom_meta = custom_config.get("vibe_remote")
        custom = pid in custom_provider_index
        if isinstance(custom_meta, dict):
            adapter = custom_meta.get("adapter")
        else:
            try:
                from vibe.opencode_config import get_opencode_custom_provider_adapter

                adapter = get_opencode_custom_provider_adapter(pid, custom_config)
            except Exception:
                adapter = None
        # Authoritative source for the "configured" badge:
        # - If auth.json carries an entry → configured (user explicitly
        #   set it up, even if OpenCode's cache hasn't caught up yet).
        # - Custom providers are configured by their opencode.json block; API
        #   keys are optional for local OpenAI-compatible endpoints.
        # - If auth.json is empty AND ``connected`` lists it → configured
        #   only when ``local`` (Ollama / LM Studio don't need keys).
        #   Otherwise treat ``connected`` as stale — the user just
        #   removed the key and the daemon hasn't restarted yet.
        if pid in configured_provider_set:
            configured = True
        elif local and pid in connected_set:
            configured = True
        else:
            configured = False
        models_for_provider = model_index.get(pid, {})
        provider_models = models_for_provider.get("models")
        user_models = user_model_index.get(pid, {})
        if isinstance(provider_models, dict):
            merged_models = {**provider_models, **user_models}
            model_ids = sorted(merged_models.keys())
        elif isinstance(provider_models, list):
            model_ids = [m.get("id") for m in provider_models if isinstance(m, dict) and m.get("id")]
            for user_model_id in user_models:
                if user_model_id not in model_ids:
                    model_ids.append(user_model_id)
            model_ids = sorted(model_ids)
        else:
            model_ids = sorted(user_models.keys())
        model_entries = []
        for model_id in model_ids:
            model_info = user_models.get(model_id)
            user_managed = (
                _is_opencode_user_model(model_id, model_info)
                if isinstance(model_id, str) and isinstance(model_info, dict)
                else False
            )
            variants = model_info.get("variants") if isinstance(model_info, dict) else None
            reasoning_efforts = sorted(variants.keys()) if isinstance(variants, dict) else []
            model_entries.append(
                {
                    "id": model_id,
                    "user_managed": user_managed,
                    "reasoning_efforts": reasoning_efforts,
                }
            )
        out_providers.append(
            {
                "id": pid,
                "name": entry.get("name") or pid,
                "description": entry.get("description") or "",
                "configured": configured,
                "has_auth": pid in auth_file_provider_set or pid in config_api_key_provider_set,
                "oauth_available": oauth_available,
                "local": local,
                "custom": custom,
                "adapter": adapter if isinstance(adapter, str) else None,
                "models": model_ids,
                "model_entries": model_entries,
                "base_url": base_url_index.get(pid),
                "api_key_masked": api_key_mask_index.get(pid),
                # ``api`` / ``oauth`` / null — the type the daemon will
                # actually use at launch. Lets the UI badge the right
                # source for dual-mode providers (e.g. openai supports
                # both, but only one entry lives in auth.json at a time).
                "active_auth_type": active_auth_type_index.get(pid),
            }
        )

    out_providers.sort(key=lambda p: (not p["configured"], p["local"], p["id"]))

    # Surface the current ``permission`` setting from opencode.json so the
    # Settings page can hide the "Allow tool calls" affordance once it's
    # already ``allow`` — and strengthen the copy when it isn't, since a
    # missing/blocking setting silently makes every tool call wait for an
    # approval prompt that avibe can't reply to.
    permission_allowed = opencode_permission_allowed(opencode_probe)

    return {
        "ok": True,
        "providers": out_providers,
        "default_provider": default_provider,
        "permission_allowed": permission_allowed,
    }


def get_opencode_providers() -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(get_opencode_providers_async())


async def get_opencode_providers_async() -> dict:
    """Return the OpenCode provider catalog."""
    try:
        return await _get_opencode_providers_async()
    except Exception as exc:
        logger.warning("OpenCode providers fetch failed: %s", exc, exc_info=True)
        return {"ok": False, "message": str(exc)}


def _opencode_provider_models_loaded(catalog: dict, provider_id: str) -> bool:
    if not isinstance(catalog, dict) or catalog.get("ok") is False:
        return False
    providers = catalog.get("providers")
    if not isinstance(providers, list):
        return False
    for provider in providers:
        if not isinstance(provider, dict):
            continue
        if provider.get("id") != provider_id:
            continue
        models = provider.get("models")
        return isinstance(models, list) and len(models) > 0
    return False


def _opencode_provider_present(catalog: dict, provider_id: str) -> bool:
    if not isinstance(catalog, dict) or catalog.get("ok") is False:
        return False
    providers = catalog.get("providers")
    if not isinstance(providers, list):
        return False
    return any(
        isinstance(provider, dict) and provider.get("id") == provider_id
        for provider in providers
    )


async def _refresh_opencode_provider_catalog_async(provider_id: str, *, require_models: bool = True) -> dict:
    """Fetch the provider catalog after an auth/config write.

    OpenCode keeps provider/auth state in the running daemon. After saving a
    key or base URL we restart/refresh the daemon and then force a fresh catalog
    read so Settings and Agents do not keep showing the pre-save empty model
    list until the generic options cache expires.
    """

    pid = provider_id.strip()
    last_catalog: dict | None = None
    for attempt in range(_OPENCODE_PROVIDER_REFRESH_ATTEMPTS):
        if attempt > 0:
            await asyncio.sleep(_OPENCODE_PROVIDER_REFRESH_DELAY_SECONDS)
        catalog = await get_opencode_providers_async()
        if isinstance(catalog, dict):
            last_catalog = catalog
        loaded = (
            _opencode_provider_models_loaded(catalog, pid)
            if require_models
            else _opencode_provider_present(catalog, pid)
        )
        if loaded:
            return {"ok": True, "provider_id": pid, "catalog": catalog}
    message = (
        "Provider saved, but model catalog has not refreshed yet"
        if require_models
        else "Provider saved, but provider catalog has not refreshed yet"
    )
    if isinstance(last_catalog, dict) and last_catalog.get("message"):
        message = str(last_catalog.get("message"))
    return {
        "ok": False,
        "provider_id": pid,
        "message": message,
        "catalog": last_catalog,
    }


def save_opencode_provider_model(provider_id: str, payload: dict) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(save_opencode_provider_model_async(provider_id, payload))


def _normalize_custom_provider_payload(payload: dict) -> tuple[str, str, str, str, str | None]:
    if not isinstance(payload, dict):
        raise ValueError("Payload must be an object")
    provider_id = payload.get("provider_id")
    name = payload.get("name")
    adapter = payload.get("adapter")
    base_url = payload.get("base_url")
    api_key = payload.get("api_key")
    if not isinstance(provider_id, str) or not provider_id.strip():
        raise ValueError("provider_id is required")
    if not isinstance(name, str) or not name.strip():
        raise ValueError("name is required")
    if not isinstance(adapter, str) or not adapter.strip():
        raise ValueError("adapter is required")
    if not isinstance(base_url, str) or not base_url.strip():
        raise ValueError("base_url is required")
    if api_key is not None and not isinstance(api_key, str):
        raise ValueError("api_key must be a string")
    api_key_value = api_key.strip() if isinstance(api_key, str) and api_key.strip() else None
    return provider_id.strip(), name.strip(), adapter.strip(), base_url.strip(), api_key_value


@_native_auth_write("opencode")
async def save_opencode_custom_provider_async(payload: dict) -> dict:
    try:
        provider_id, name, adapter, base_url, api_key = _normalize_custom_provider_payload(payload)
    except ValueError as exc:
        return {"ok": False, "message": str(exc)}
    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}

    try:
        from vibe.opencode_config import is_reserved_opencode_provider_id

        if is_reserved_opencode_provider_id(provider_id):
            return {"ok": False, "message": "provider_id already exists"}
    except Exception as exc:
        logger.debug("OpenCode reserved provider check failed for %s: %s", provider_id, exc)

    try:
        providers = await _get_opencode_providers_async()
    except Exception as exc:
        logger.warning("OpenCode provider catalog fetch failed during custom provider save: %s", exc, exc_info=True)
        return {"ok": False, "message": "provider catalog is unavailable"}
    if not isinstance(providers, dict) or providers.get("ok") is False:
        message = providers.get("message") if isinstance(providers, dict) else None
        return {"ok": False, "message": message or "provider catalog is unavailable"}
    existing_providers = providers.get("providers") if isinstance(providers, dict) else []
    if not isinstance(existing_providers, list):
        return {"ok": False, "message": "provider catalog is unavailable"}
    if isinstance(existing_providers, list):
        normalized_id = provider_id.strip().lower()
        normalized_name = name.strip().lower()
        for provider in existing_providers:
            if not isinstance(provider, dict):
                continue
            existing_id = str(provider.get("id") or "").lower()
            existing_name = str(provider.get("name") or "").lower()
            if existing_id == normalized_id:
                if provider.get("custom") is not True:
                    return {"ok": False, "message": "provider_id already exists"}
            if existing_name and existing_name == normalized_name and existing_id != normalized_id:
                return {"ok": False, "message": "provider name already exists"}

    try:
        from vibe.opencode_config import upsert_opencode_custom_provider

        await asyncio.to_thread(
            upsert_opencode_custom_provider,
            provider_id,
            name,
            adapter,
            base_url,
            logger_instance=logger,
        )
    except Exception as exc:
        logger.warning("OpenCode custom provider save failed for %s: %s", provider_id, exc, exc_info=True)
        return {"ok": False, "message": str(exc)}

    _OPENCODE_OPTIONS_CACHE.clear()
    try:
        restart = restart_backend("opencode")
    except Exception as exc:
        restart = {"ok": False, "message": str(exc)}
    _OPENCODE_OPTIONS_CACHE.clear()

    if api_key:
        auth_result = await _save_opencode_provider_auth_async(
            provider_id.strip().lower(),
            None,
            _BASE_URL_UNCHANGED,
            config_api_key=api_key,
        )
        _OPENCODE_OPTIONS_CACHE.clear()
        try:
            restart = restart_backend("opencode")
        except Exception as exc:
            restart = {"ok": False, "message": str(exc)}
        _OPENCODE_OPTIONS_CACHE.clear()
        if not auth_result.get("ok"):
            return {
                "ok": False,
                "provider_id": provider_id.strip().lower(),
                "message": auth_result.get("message") or "Provider saved, but API key save failed",
                "restart": restart,
            }

    catalog_refresh = await _refresh_opencode_provider_catalog_async(
        provider_id.strip().lower(),
        require_models=False,
    )
    return {
        "ok": True,
        "provider_id": provider_id.strip().lower(),
        "restart": restart,
        "catalog_refresh": catalog_refresh,
    }


def save_opencode_custom_provider(payload: dict) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(save_opencode_custom_provider_async(payload))


@_native_auth_write("opencode")
async def delete_opencode_custom_provider_async(provider_id: str) -> dict:
    if not isinstance(provider_id, str) or not provider_id.strip():
        return {"ok": False, "message": "provider_id is required"}
    pid = provider_id.strip().lower()
    recovery_message = _config_recovery_message()
    if recovery_message:
        return {
            "ok": False,
            "error": "config_recovery",
            "provider_id": pid,
            "message": recovery_message,
        }
    try:
        from vibe.opencode_config import (
            is_opencode_custom_provider,
            read_opencode_provider_auth_entries,
            remove_opencode_custom_provider,
        )

        custom = await asyncio.to_thread(
            is_opencode_custom_provider,
            pid,
            logger_instance=logger,
        )
        if not custom:
            return {"ok": False, "message": "Only custom providers can be removed"}
        auth_entries = await asyncio.to_thread(
            read_opencode_provider_auth_entries,
            logger_instance=logger,
        )
        if pid in auth_entries:
            auth_result = await _delete_opencode_provider_auth_async(pid)
            if not auth_result.get("ok"):
                return {
                    "ok": False,
                    "provider_id": pid,
                    "message": auth_result.get("message") or "Provider auth removal failed",
                }
        await asyncio.to_thread(
            remove_opencode_custom_provider,
            pid,
            logger_instance=logger,
        )
    except Exception as exc:
        logger.warning("OpenCode custom provider delete failed for %s: %s", pid, exc, exc_info=True)
        return {"ok": False, "message": str(exc)}

    try:
        _clear_opencode_default_provider_if(pid)
    except Exception as exc:
        logger.warning(
            "Failed to revalidate opencode.default_provider after custom provider delete for %s: %s",
            pid,
            exc,
        )

    _OPENCODE_OPTIONS_CACHE.clear()
    try:
        restart = restart_backend("opencode")
    except Exception as exc:
        restart = {"ok": False, "message": str(exc)}
    _OPENCODE_OPTIONS_CACHE.clear()
    return {"ok": True, "provider_id": pid, "restart": restart}


def delete_opencode_custom_provider(provider_id: str) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(delete_opencode_custom_provider_async(provider_id))


@_native_auth_write("opencode", authentication=False)
async def save_opencode_provider_model_async(provider_id: str, payload: dict) -> dict:
    """Add or update a user-managed OpenCode model under one provider."""

    if not isinstance(provider_id, str) or not provider_id.strip():
        return {"ok": False, "message": "provider_id is required"}
    if not isinstance(payload, dict):
        return {"ok": False, "message": "Payload must be an object"}
    raw_model_id = payload.get("model_id")
    if not isinstance(raw_model_id, str) or not raw_model_id.strip():
        return {"ok": False, "message": "model_id is required"}
    model_id = raw_model_id.strip()
    pid = provider_id.strip()
    if model_id.lower().startswith(f"{pid.lower()}/"):
        return {"ok": False, "message": "model_id must not include a provider prefix"}

    reasoning_efforts = payload.get("reasoning_efforts", [])

    # Prevent duplicates against both OpenCode's live catalog and the
    # user-managed overlay. Updating an existing user-managed model is
    # allowed; adding a duplicate built-in model is not.
    existing_user_models: dict = {}
    try:
        from vibe.opencode_config import read_opencode_provider_user_models

        existing_user_models = await asyncio.to_thread(
            read_opencode_provider_user_models, pid, logger_instance=logger
        )
    except Exception as exc:
        logger.debug("OpenCode user-model lookup failed for %s: %s", pid, exc)

    try:
        lease = await _opencode_lease("provider model save")
    except Exception as exc:
        # Without the live catalog the save could shadow a built-in model.
        logger.warning("No OpenCode generation to validate %s/%s: %s", pid, model_id, exc)
        return {"ok": False, "message": "provider model catalog is unavailable"}
    try:
        if lease is not None:
            try:
                config_raw = await lease.server.get_native_available_models(os.path.expanduser("~"))
            except Exception as exc:
                logger.warning(
                    "OpenCode provider model catalog fetch failed for %s/%s: %s",
                    pid,
                    model_id,
                    exc,
                    exc_info=True,
                )
                return {"ok": False, "message": str(exc)}
            if not isinstance(config_raw, dict):
                return {"ok": False, "message": "provider model catalog is unavailable"}
            custom_provider_ids = await _read_opencode_custom_provider_ids()
            model_index = {}
            provider_found = False
            for entry in config_raw.get("providers", []) or []:
                entry_pid = entry.get("id") if isinstance(entry, dict) else None
                if entry_pid == pid:
                    provider_found = True
                    model_index = _opencode_provider_model_ids(entry)
                    break
            if not provider_found:
                if pid not in custom_provider_ids:
                    return {"ok": False, "message": "provider model catalog is unavailable"}
            if model_id in model_index and model_id not in existing_user_models:
                return {"ok": False, "message": "model_id already exists"}
    finally:
        if lease is not None:
            await lease.release()

    try:
        from vibe.opencode_config import upsert_opencode_provider_model

        await asyncio.to_thread(
            upsert_opencode_provider_model,
            pid,
            model_id,
            reasoning_efforts=reasoning_efforts,
            logger_instance=logger,
        )
    except Exception as exc:
        logger.warning("OpenCode provider model save failed for %s/%s: %s", pid, model_id, exc, exc_info=True)
        return {"ok": False, "message": str(exc)}

    _OPENCODE_OPTIONS_CACHE.clear()
    try:
        restart = restart_backend("opencode")
    except Exception as exc:
        restart = {"ok": False, "message": str(exc)}
    _OPENCODE_OPTIONS_CACHE.clear()
    return {"ok": True, "provider_id": pid, "model_id": model_id, "restart": restart}


def delete_opencode_provider_model(provider_id: str, model_id: str) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(delete_opencode_provider_model_async(provider_id, model_id))


@_native_auth_write("opencode", authentication=False)
async def delete_opencode_provider_model_async(provider_id: str, model_id: str) -> dict:
    if not isinstance(provider_id, str) or not provider_id.strip():
        return {"ok": False, "message": "provider_id is required"}
    if not isinstance(model_id, str) or not model_id.strip():
        return {"ok": False, "message": "model_id is required"}
    pid = provider_id.strip()
    mid = model_id.strip()

    try:
        from vibe.opencode_config import read_opencode_provider_user_models, remove_opencode_provider_model

        user_models = await asyncio.to_thread(
            read_opencode_provider_user_models, pid, logger_instance=logger
        )
        if mid not in user_models:
            return {"ok": False, "message": "Only user-managed models can be removed"}
        await asyncio.to_thread(
            remove_opencode_provider_model,
            pid,
            mid,
            logger_instance=logger,
        )
    except Exception as exc:
        logger.warning("OpenCode provider model delete failed for %s/%s: %s", pid, mid, exc, exc_info=True)
        return {"ok": False, "message": str(exc)}

    _OPENCODE_OPTIONS_CACHE.clear()
    try:
        restart = restart_backend("opencode")
    except Exception as exc:
        restart = {"ok": False, "message": str(exc)}
    _OPENCODE_OPTIONS_CACHE.clear()
    return {"ok": True, "provider_id": pid, "model_id": mid, "restart": restart}


# Sentinel used by ``save_opencode_provider_auth`` to distinguish three
# states of the optional ``base_url`` field:
#   * key absent from payload      → ``_BASE_URL_UNCHANGED`` (no-op)
#   * key present, value blank     → ``None``                (clear stored)
#   * key present, value non-blank → ``str``                 (upsert)
# Without this, a payload like ``{"api_key": "..."}`` (re-saving just
# the API key) would silently wipe the stored ``baseURL`` because the
# server cannot tell "omitted" from "explicitly empty".
_BASE_URL_UNCHANGED: object = object()


async def _save_opencode_provider_auth_async(
    provider_id: str,
    api_key: str | None,
    base_url: Any = _BASE_URL_UNCHANGED,
    *,
    config_api_key: str | None = None,
) -> dict:
    from vibe.opencode_config import (
        remove_opencode_provider_base_url,
        read_opencode_provider_auth_entries,
        upsert_opencode_provider_api_key,
        upsert_opencode_provider_base_url,
    )

    # Treat API keys entered through avibe's Settings UI as OpenCode
    # config provider options, not OpenCode daemon auth entries. The
    # daemon's /auth store is still used by OpenCode's own connect/OAuth
    # flow, but provider options are the source OpenCode-compatible
    # providers consistently use at invocation time.
    config_key = config_api_key or api_key
    if config_key:
        try:
            await asyncio.to_thread(
                upsert_opencode_provider_api_key,
                provider_id,
                config_key,
                logger_instance=logger,
            )
        except Exception as exc:
            logger.warning(
                "OpenCode provider apiKey mirror persist failed for %s: %s",
                provider_id,
                exc,
                exc_info=True,
            )
            return {
                "ok": False,
                "message": (
                    "Provider credential persistence failed: "
                    f"{exc}"
                ),
            }

        try:
            auth_entries = await asyncio.to_thread(
                read_opencode_provider_auth_entries,
                logger_instance=logger,
            )
            if provider_id in auth_entries:
                auth_cleanup = await _delete_opencode_provider_auth_async(provider_id)
                if not auth_cleanup.get("ok"):
                    return {
                        "ok": False,
                        "message": auth_cleanup.get("message")
                        or "API key saved, but stale OpenCode auth cleanup failed",
                    }
        except Exception as exc:
            logger.warning(
                "OpenCode stale auth cleanup failed for %s: %s",
                provider_id,
                exc,
                exc_info=True,
            )
            return {
                "ok": False,
                "message": (
                    "API key saved, but stale OpenCode auth cleanup failed: "
                    f"{exc}"
                ),
            }

    # ``baseURL`` is different: OpenCode's auth endpoint has no field for
    # it, so this write is the *only* place it gets persisted. A silent
    # failure would surface as "save success, value lost on reload" — the
    # exact UX bug Codex flagged. Surface those errors to the caller so
    # the UI can show a useful message.
    if base_url is _BASE_URL_UNCHANGED:
        return {"ok": True}

    try:
        if base_url:
            await asyncio.to_thread(
                upsert_opencode_provider_base_url,
                provider_id,
                base_url,
                logger_instance=logger,
            )
        else:
            await asyncio.to_thread(
                remove_opencode_provider_base_url,
                provider_id,
                logger_instance=logger,
            )
    except Exception as exc:
        logger.warning(
            "OpenCode base_url persist failed for %s: %s", provider_id, exc, exc_info=True
        )
        return {
            "ok": False,
            "message": (
                "API key saved, but base URL persistence failed: "
                f"{exc}"
            ),
        }
    return {"ok": True}


def save_opencode_provider_auth(provider_id: str, payload: dict) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(save_opencode_provider_auth_async(provider_id, payload))


@_native_auth_write("opencode")
async def save_opencode_provider_auth_async(provider_id: str, payload: dict) -> dict:
    """Persist a single OpenCode provider's API key (and optional base URL).

    The API key is persisted into ``opencode.json`` under
    ``provider.<id>.options.apiKey``. ``auth.json`` remains OpenCode's
    own connect/OAuth store and is touched only through the OpenCode auth
    API when we need to clear a conflicting entry. The optional
    ``base_url`` override is also persisted into ``opencode.json``.

    ``base_url`` field semantics in the payload:
      * absent              → resolve from disk first, then the stored value
      * empty / whitespace  → clear the stored value
      * non-empty string    → upsert (must start with http:// or https://)
    """
    if not isinstance(provider_id, str) or not provider_id.strip():
        return {"ok": False, "message": "provider_id is required"}
    if not isinstance(payload, dict):
        return {"ok": False, "message": "Payload must be an object"}
    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}
    raw_key = payload.get("api_key")
    # ``api_key`` is optional when the provider is already configured: the
    # UI's "Replace" flow hides the plaintext and only sends ``base_url``
    # for relay-URL fixes. Without this, base-URL-only edits fail unless
    # the user retypes the secret. We detect "already configured" by
    # consulting provider.<id>.options.apiKey in opencode.json first,
    # then falling back to OpenCode auth.json only to repair older
    # split-store installs. This mirrors the Settings catalog badge, so a
    # masked key shown in the UI can always save a base URL without
    # requiring replacement.
    api_key: str | None = raw_key.strip() if isinstance(raw_key, str) and raw_key.strip() else None
    has_existing_key = False
    existing_api_key: str | None = None
    if api_key is None:
        try:
            existing_api_key = await _read_opencode_config_api_key(provider_id.strip())
            if existing_api_key:
                has_existing_key = True
            if not has_existing_key:
                from vibe.opencode_config import read_opencode_provider_keys

                existing_keys = read_opencode_provider_keys(logger_instance=logger)
                maybe_existing_key = existing_keys.get(provider_id.strip())
                if isinstance(maybe_existing_key, str) and maybe_existing_key:
                    has_existing_key = True
                    existing_api_key = maybe_existing_key
            if not has_existing_key:
                config_key_ids = await _read_opencode_config_api_key_provider_ids()
                has_existing_key = provider_id.strip() in config_key_ids
            if not has_existing_key:
                custom_provider_ids = await _read_opencode_custom_provider_ids()
                has_existing_key = provider_id.strip() in custom_provider_ids
        except Exception as exc:  # noqa: BLE001
            logger.debug(
                "OpenCode auth lookup failed during base-url-only save for %s: %s",
                provider_id,
                exc,
            )
            has_existing_key = False
        if not has_existing_key:
            return {"ok": False, "message": "api_key is required"}

    base_url: Any = _BASE_URL_UNCHANGED
    if "base_url" in payload:
        raw_base_url = payload.get("base_url")
        if raw_base_url is None:
            base_url = None
        elif isinstance(raw_base_url, str):
            candidate = raw_base_url.strip()
            if not candidate:
                base_url = None
            else:
                if not candidate.lower().startswith(("http://", "https://")):
                    return {
                        "ok": False,
                        "message": "base_url must start with http:// or https://",
                    }
                base_url = candidate
        else:
            return {"ok": False, "message": "base_url must be a string"}
        if base_url is None:
            custom_provider_ids = await _read_opencode_custom_provider_ids()
            if provider_id.strip() in custom_provider_ids:
                return {"ok": False, "message": "base_url is required for custom providers"}

    try:
        result = await _save_opencode_provider_auth_async(
            provider_id.strip(),
            None,
            base_url,
            config_api_key=api_key or existing_api_key,
        )
    except Exception as exc:
        logger.warning("OpenCode set-auth failed for %s: %s", provider_id, exc, exc_info=True)
        return {"ok": False, "message": str(exc)}

    if result.get("ok"):
        _OPENCODE_OPTIONS_CACHE.clear()

    # Ask the live controller to refresh the OpenCode server so the
    # daemon's in-memory ``connected`` cache picks up the new auth.
    # Without this, ``GET /provider`` keeps returning the pre-save
    # state until OpenCode restarts on its own (typically next idle
    # cleanup cycle). The restart is best-effort: we report it under a
    # separate ``restart`` key so the UI can show "saved, but daemon
    # refresh failed" when applicable.
    try:
        result["restart"] = restart_backend("opencode")
    except Exception as exc:
        logger.warning("OpenCode auto-restart after save failed for %s: %s", provider_id, exc)
        result["restart"] = {"ok": False, "message": str(exc)}
    if result.get("ok"):
        result["catalog_refresh"] = await _refresh_opencode_provider_catalog_async(provider_id.strip())
    return result


async def _delete_opencode_provider_auth_async(provider_id: str) -> dict:
    try:
        lease = await _opencode_lease("provider auth removal")
    except Exception as exc:
        logger.warning("No OpenCode generation to remove %s auth: %s", provider_id, exc)
        return {"ok": False, "message": f"OpenCode is unavailable: {exc}"}
    if lease is None:
        return {"ok": False, "message": "OpenCode is disabled in V2Config"}
    try:
        await lease.server.remove_provider_auth(provider_id)
    finally:
        await lease.release()
    return {"ok": True}


def _clear_opencode_default_provider_if(provider_id: str) -> None:
    """Clear the saved OpenCode default if it points at ``provider_id``."""

    from config import paths as _paths
    from config.v2_config import update_config_fields

    if not _paths.get_config_path().exists():
        return

    def _clear_if_matching(cfg) -> None:
        # Compare-and-clear INSIDE the transaction on the lock-fresh
        # config (#1458 stage ③): a concurrent default switch to another
        # provider must not be cleared by a stale comparison.
        opencode_cfg = getattr(getattr(cfg, "agents", None), "opencode", None)
        current_default = getattr(opencode_cfg, "default_provider", None)
        if isinstance(current_default, str) and current_default.strip() == provider_id:
            opencode_cfg.default_provider = None
            logger.info(
                "clear_opencode_default_provider: cleared default_provider after removing %s",
                provider_id,
            )

    update_config_fields(_clear_if_matching)


def delete_opencode_provider_auth(provider_id: str) -> dict:
    from vibe.async_bridge import run_coroutine_blocking

    return run_coroutine_blocking(delete_opencode_provider_auth_async(provider_id))


@_native_auth_write("opencode")
async def delete_opencode_provider_auth_async(provider_id: str) -> dict:
    """Drop a single provider's stored credentials.

    Same restart pattern as save: the daemon caches ``connected`` at
    startup, so a fresh DELETE on ``/auth/<id>`` doesn't flip the
    runtime state until the daemon restarts. We trigger
    ``restart_backend("opencode")`` so the UI's next refresh reflects
    reality. The restart status comes back under ``restart`` so the
    page can warn on "removed, but daemon refresh failed".

    If the deleted provider is still recorded as
    ``agents.opencode.default_provider``, clear the saved default too.
    ``OpenCodeAgent`` injects that ``providerID`` for bare model IDs,
    so leaving a stale default behind makes every subsequent request
    target an unconfigured provider and fail.
    """
    if not isinstance(provider_id, str) or not provider_id.strip():
        return {"ok": False, "message": "provider_id is required"}
    recovery_message = _config_recovery_message()
    if recovery_message:
        return {"ok": False, "error": "config_recovery", "message": recovery_message}
    pid = provider_id.strip()
    try:
        from vibe.opencode_config import (
            read_opencode_provider_auth_entries,
            remove_opencode_provider_api_key,
        )

        auth_entries = await asyncio.to_thread(
            read_opencode_provider_auth_entries,
            logger_instance=logger,
        )
        config_api_key_provider_ids = await _read_opencode_config_api_key_provider_ids()
        result = {"ok": True}
        removed_auth = False
        if pid in auth_entries:
            result = await _delete_opencode_provider_auth_async(pid)
            removed_auth = bool(result.get("ok"))
        if pid in config_api_key_provider_ids:
            await asyncio.to_thread(
                remove_opencode_provider_api_key,
                pid,
                logger_instance=logger,
            )
            removed_auth = True
    except Exception as exc:
        logger.warning("OpenCode delete-auth failed for %s: %s", provider_id, exc, exc_info=True)
        return {"ok": False, "message": str(exc)}

    # Revalidate the saved default. Best-effort: a V2Config write
    # failure here is non-fatal because the daemon already dropped the
    # credential, but log it so the user can investigate if the
    # default sticks around after a "Remove key" click.
    if removed_auth:
        _OPENCODE_OPTIONS_CACHE.clear()
        try:
            _clear_opencode_default_provider_if(pid)
        except Exception as exc:  # noqa: BLE001
            logger.warning(
                "Failed to revalidate opencode.default_provider after delete for %s: %s",
                pid,
                exc,
            )

    try:
        result["restart"] = restart_backend("opencode")
    except Exception as exc:
        logger.warning("OpenCode auto-restart after delete failed for %s: %s", provider_id, exc)
        result["restart"] = {"ok": False, "message": str(exc)}
    return result


def set_opencode_default_provider(payload: dict) -> dict:
    """Persist ``V2Config.agents.opencode.default_provider``.

    No daemon contact required — OpenCode itself accepts a per-request
    ``provider`` field on messages, so the "default" is purely our
    routing concern. Storing it in V2Config keeps the chip and the
    routing layer in sync across restarts.
    """
    if not isinstance(payload, dict):
        return {"ok": False, "message": "Payload must be an object"}
    raw = payload.get("provider_id")
    if not isinstance(raw, str) or not raw.strip():
        return {"ok": False, "message": "provider_id is required"}
    provider_id = raw.strip()

    from config.v2_config import update_config_fields

    def _apply(cfg: V2Config) -> None:
        cfg.agents.opencode.default_provider = provider_id

    update_config_fields(_apply)
    return {"ok": True, "default_provider": provider_id}


def codex_models(*, schedule_refresh: bool = True) -> dict:
    """Return the immediate shared Codex model-catalog snapshot."""
    return backend_model_catalog.backend_model_snapshot("codex", schedule_refresh=schedule_refresh)


def _lark_api_base(domain: str = "feishu") -> str:
    """Return the API base URL for the given Lark/Feishu domain."""
    if domain == "lark":
        return "https://open.larksuite.com"
    return "https://open.feishu.cn"


def _lark_tenant_token(
    app_id: str,
    app_secret: str,
    domain: str = "feishu",
    proxy_url: str | None = None,
) -> Optional[str]:
    import urllib.request

    from vibe.proxy import is_socks_proxy

    url = f"{_lark_api_base(domain)}/open-apis/auth/v3/tenant_access_token/internal"
    body = json.dumps({"app_id": app_id, "app_secret": app_secret}).encode()
    headers = {"Content-Type": "application/json"}

    if proxy_url and is_socks_proxy(proxy_url):
        result = _https_json_request_via_socks(
            proxy_url,
            url,
            method="POST",
            body=body,
            headers=headers,
        )
    else:
        if proxy_url:
            opener = urllib.request.build_opener(
                urllib.request.ProxyHandler({"http": proxy_url, "https": proxy_url})
            )
        else:
            opener = urllib.request.build_opener()
        req = urllib.request.Request(url, data=body, headers=headers)
        with opener.open(req, timeout=10) as resp:
            result = json.loads(resp.read().decode())

    if result.get("code") == 0:
        return result.get("tenant_access_token")
    return None


async def _lark_tenant_token_async(
    app_id: str,
    app_secret: str,
    domain: str = "feishu",
    proxy_url: str | None = None,
) -> Optional[str]:
    """Get Lark tenant access token (internal helper, not exposed to frontend).

    ``proxy_url`` is honored when set: SOCKS schemes route through
    ``aiohttp_socks``, HTTP schemes use ``urllib.ProxyHandler``. The runtime
    Feishu/Lark adapter still bypasses this because ``lark-oapi`` has no
    proxy hook — that gap is surfaced by the adapter, not here.
    """
    import urllib.request

    from vibe.proxy import is_socks_proxy

    url = f"{_lark_api_base(domain)}/open-apis/auth/v3/tenant_access_token/internal"
    body = json.dumps({"app_id": app_id, "app_secret": app_secret}).encode()
    headers = {"Content-Type": "application/json"}

    if proxy_url and is_socks_proxy(proxy_url):
        result = await _lark_tenant_token_via_aiohttp(url, body, headers, proxy_url)
    else:
        def _request() -> dict:
            if proxy_url:
                opener = urllib.request.build_opener(
                    urllib.request.ProxyHandler({"http": proxy_url, "https": proxy_url})
                )
            else:
                opener = urllib.request.build_opener()
            req = urllib.request.Request(url, data=body, headers=headers)
            with opener.open(req, timeout=10) as resp:
                return json.loads(resp.read().decode())

        result = await asyncio.to_thread(_request)

    if result.get("code") == 0:
        return result.get("tenant_access_token")
    return None


async def _lark_tenant_token_via_aiohttp(url: str, body: bytes, headers: dict, proxy: str) -> dict:
    import aiohttp
    from aiohttp_socks import ProxyConnector

    connector = ProxyConnector.from_url(proxy, rdns=True)
    timeout = aiohttp.ClientTimeout(total=10)
    async with aiohttp.ClientSession(connector=connector, timeout=timeout) as session:
        async with session.post(url, data=body, headers=headers) as resp:
            resp.raise_for_status()
            return await resp.json()


def lark_auth_test(
    app_id: str,
    app_secret: str,
    domain: str = "feishu",
    proxy_url: str | None = None,
) -> dict:
    app_id = app_id or _stored_platform_field("lark", "app_id")
    app_secret = app_secret or _stored_platform_secret("lark", "app_secret")
    domain = domain or _stored_platform_field("lark", "domain", "feishu")
    from vibe.proxy import resolve_proxy

    proxy = resolve_proxy(proxy_url)
    try:
        token = _lark_tenant_token(app_id, app_secret, domain, proxy_url=proxy)
        if not token:
            return {"ok": False, "error": "Invalid credentials"}
        return {"ok": True}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


async def lark_auth_test_async(
    app_id: str,
    app_secret: str,
    domain: str = "feishu",
    proxy_url: str | None = None,
) -> dict:
    """Test Lark/Feishu app credentials. Only returns ok/error, never exposes token.

    ``proxy_url`` is honored for the auth call itself; the runtime SDK
    (``lark-oapi``) has no proxy hook and bypasses it — that limitation is
    surfaced by ``modules/im/feishu.py`` once at adapter init.
    """
    app_id = app_id or _stored_platform_field("lark", "app_id")
    app_secret = app_secret or _stored_platform_secret("lark", "app_secret")
    domain = domain or _stored_platform_field("lark", "domain", "feishu")
    from vibe.proxy import resolve_proxy

    proxy = resolve_proxy(proxy_url)
    try:
        token = await _lark_tenant_token_async(app_id, app_secret, domain, proxy_url=proxy)
        if not token:
            return {"ok": False, "error": "Invalid credentials"}
        return {"ok": True}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


def lark_list_chats(
    app_id: str,
    app_secret: str,
    domain: str = "feishu",
    force: bool = False,
    include_not_returned: bool = False,
) -> dict:
    from core import chat_discovery

    app_id = app_id or _stored_platform_field("lark", "app_id")
    app_secret = app_secret or _stored_platform_secret("lark", "app_secret")
    domain = domain or _stored_platform_field("lark", "domain", "feishu")
    return chat_discovery.channels_response(
        "lark",
        app_id=app_id,
        app_secret=app_secret,
        domain=domain,
        force=force,
        include_not_returned=include_not_returned,
    )


def lark_list_chats_live(app_id: str, app_secret: str, domain: str = "feishu") -> dict:
    """List Lark/Feishu group chats the bot has joined (with pagination)."""
    import time
    import urllib.error
    import urllib.request

    def _get_with_retry(req: "urllib.request.Request", *, attempts: int = 5) -> dict:
        for attempt in range(attempts):
            try:
                with urllib.request.urlopen(req, timeout=10) as resp:
                    return json.loads(resp.read().decode())
            except urllib.error.HTTPError as http_exc:
                # Retry on rate-limit / transient server errors with backoff.
                if http_exc.code in (429, 500, 502, 503, 504) and attempt < attempts - 1:
                    retry_after = http_exc.headers.get("Retry-After") if http_exc.headers else None
                    try:
                        wait = max(int(retry_after), 2**attempt) if retry_after else 2**attempt
                    except (TypeError, ValueError):
                        wait = 2**attempt
                    logger.warning(
                        "Lark rate-limited/transient (%d), retrying after %ds (attempt %d/%d)",
                        http_exc.code,
                        wait,
                        attempt + 1,
                        attempts,
                    )
                    time.sleep(wait)
                    continue
                raise
        raise RuntimeError("Lark request exhausted retries")

    try:
        token = _lark_tenant_token(app_id, app_secret, domain)
        if not token:
            return {"ok": False, "error": "Failed to get access token"}

        base = _lark_api_base(domain)
        channels = []
        page_token = ""
        seen_page_tokens: set = set()
        max_pages = 50  # safety cap to prevent infinite loop
        page = 0
        # `truncated` marks an INCOMPLETE inventory. Any early/abnormal exit while
        # the server still reports more pages must set it, so the caller never
        # marks the unseen chats not_returned from a partial list.
        truncated = False
        while True:
            if page >= max_pages:
                truncated = True
                break
            url = f"{base}/open-apis/im/v1/chats?page_size=100"
            if page_token:
                url = f"{url}&page_token={page_token}"
            req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
            result = _get_with_retry(req)
            if result.get("code") != 0:
                return {"ok": False, "error": result.get("msg", "Unknown error")}
            data = result.get("data", {})
            items = data.get("items", [])
            channels.extend(
                {
                    "id": c.get("chat_id"),
                    "name": c.get("name"),
                    "chat_type": c.get("chat_type"),
                    "chat_mode": c.get("chat_mode"),
                    "is_private": c.get("chat_type") == "private",
                }
                for c in items
            )
            has_more = bool(data.get("has_more"))
            page_token = data.get("page_token") or ""
            if not has_more:
                break
            if not page_token:
                # Server claims more pages but gave no cursor — cannot continue.
                truncated = True
                break
            if page_token in seen_page_tokens:
                # Server returned a repeated cursor — avoid an infinite loop, but
                # the remaining pages are unreachable, so the list is incomplete.
                truncated = True
                break
            seen_page_tokens.add(page_token)
            page += 1
        return {"ok": True, "channels": channels, "truncated": truncated}
    except Exception as exc:
        return {"ok": False, "error": str(exc)}


# ---------------------------------------------------------------------------
# User and Bind Code management (for admin permission feature)
# ---------------------------------------------------------------------------


def get_users(platform: Optional[str] = None) -> dict:
    """Get all bound users."""
    store = SettingsStore.get_instance()
    platform = platform or _current_platform()
    users = {}
    for user_id, u in store.get_users_for_platform(platform).items():
        users[user_id] = _user_settings_payload(u, platform)
    return {"ok": True, "users": users}


def save_users(payload: dict, *, user_context: Any = None) -> dict:
    """Save user settings (bulk update from UI)."""
    from vibe.authorization import require_instance_role

    require_instance_role(user_context, "member")
    # Keep unvalidated request candidates out of the process-wide cache.
    with contextlib.closing(SettingsStore()) as store:
        platform = payload.get("platform") or _current_platform()

        users = {}
        for user_id, up in (payload.get("users") or {}).items():
            if not isinstance(up, dict):
                continue
            # Preserve dm_chat_id from existing user (not editable via UI)
            existing = store.get_user(user_id, platform=platform)
            users[user_id] = UserSettings(
                display_name=up.get("display_name", ""),
                is_admin=up.get("is_admin", existing.is_admin if existing else False),
                bound_at=up.get("bound_at", existing.bound_at if existing else ""),
                enabled=up.get("enabled", existing.enabled if existing else True),
                show_message_types=scope_settings.normalize_scope_message_types(up.get("show_message_types"), platform),
                custom_cwd=up.get("custom_cwd"),
                routing=_parse_routing(scope_settings.normalize_scope_routing(up.get("routing") or {})),
                dm_chat_id=existing.dm_chat_id if existing else "",
                pending_bind_menu_hint=existing.pending_bind_menu_hint if existing else False,
                _agent_name_at_load=up.get("expected_agent_name", _UNSET_AGENT_BINDING),
            )

        # Merge instead of replace: update existing users and add new ones,
        # but preserve users not included in the payload (e.g. concurrently bound)
        current_users = store.get_users_for_platform(platform)
        for uid, user_settings in users.items():
            current_users[uid] = user_settings
        store.set_users_for_platform(platform, current_users)
        store.save(user_context=user_context)
        return get_users(platform)


def toggle_admin(user_id: str, is_admin: bool, platform: Optional[str] = None) -> dict:
    """Toggle admin status for a user."""
    store = SettingsStore.get_instance()
    platform = platform or _current_platform()
    if not store.set_admin(user_id, is_admin, platform=platform):
        if not store.is_bound_user(user_id, platform=platform):
            return {"ok": False, "error": "User not found"}
        return {"ok": False, "error": "Failed to update admin status"}
    return {"ok": True}


def remove_user(user_id: str, platform: Optional[str] = None) -> dict:
    """Remove a bound user."""
    store = SettingsStore.get_instance()
    platform = platform or _current_platform()
    user = store.get_user(user_id, platform=platform)
    if user is None:
        return {"ok": False, "error": "User not found"}
    store.remove_user(user_id, platform=platform)
    return {"ok": True}


def get_bind_codes() -> dict:
    """Get all bind codes."""
    store = SettingsStore.get_instance()
    codes = []
    for bc in store.get_bind_codes():
        codes.append(
            {
                "code": bc.code,
                "type": bc.type,
                "created_at": bc.created_at,
                "expires_at": bc.expires_at,
                "is_active": bc.is_active,
                "used_by": bc.used_by,
            }
        )
    return {"ok": True, "bind_codes": codes}


def create_bind_code(code_type: str = "one_time", expires_at: Optional[str] = None) -> dict:
    """Create a new bind code."""
    if code_type not in ("one_time", "expiring"):
        return {"ok": False, "error": "type must be 'one_time' or 'expiring'"}
    if code_type == "expiring" and not expires_at:
        return {"ok": False, "error": "expires_at is required for expiring bind codes"}
    store = SettingsStore.get_instance()
    try:
        bc = store.create_bind_code(code_type, expires_at)
    except ValueError as exc:
        return {
            "ok": False,
            "error": {
                "code": "bind_code_limit_reached",
                "message": str(exc),
            },
        }
    return {
        "ok": True,
        "bind_code": {
            "code": bc.code,
            "type": bc.type,
            "created_at": bc.created_at,
            "expires_at": bc.expires_at,
            "is_active": bc.is_active,
        },
    }


def delete_bind_code(code: str) -> dict:
    """Deactivate a bind code."""
    store = SettingsStore.get_instance()
    if store.deactivate_bind_code(code):
        return {"ok": True}
    return {"ok": False, "error": "Bind code not found"}


def get_first_bind_code() -> dict:
    """Get or create the initial bind code for setup wizard."""
    store = SettingsStore.get_instance()
    # If any valid (active + not expired) code exists, return it
    for bc in store.get_bind_codes():
        if bc.is_active and store.validate_bind_code(bc.code) is not None:
            return {"ok": True, "code": bc.code, "is_new": False}
    # Otherwise create a new one-time code
    bc = store.create_bind_code("one_time")
    return {"ok": True, "code": bc.code, "is_new": True}


def auto_bind_wechat_user(user_id: str) -> dict:
    """Auto-create a UserSettings entry for the WeChat user on QR login.

    WeChat is 1:1 DM only — no channels, no bind codes needed.
    The QR scan itself is the authentication, so we auto-bind the user
    and mark the one-time menu hint to be sent on the user's next message.
    """
    from config.v2_settings import _now_iso

    store = SettingsStore.get_instance()
    platform = "wechat"

    if store.is_bound_user(user_id, platform=platform):
        existing = store.get_user(user_id, platform=platform)
        if existing is None:
            logger.warning("WeChat user %s is marked bound but missing settings", user_id)
        else:
            existing.pending_bind_menu_hint = True
            store.update_user(user_id, existing, platform=platform)
            store.save()
            logger.info("Re-armed WeChat bind menu hint for already-bound user %s", user_id)
        return {
            "ok": True,
            "already_bound": True,
            "is_admin": bool(getattr(existing, "is_admin", False)),
            "pending_bind_menu_hint": bool(getattr(existing, "pending_bind_menu_hint", True)),
        }

    config = load_config()
    is_admin = not store.has_enabled_admin(platform=platform)
    user = UserSettings(
        display_name=user_id,
        is_admin=is_admin,
        bound_at=_now_iso(),
        enabled=True,
        custom_cwd=config.runtime.default_cwd or None,
        routing=RoutingSettings(),
        pending_bind_menu_hint=True,
    )

    current_users = store.get_users_for_platform(platform)
    current_users[user_id] = user
    store.set_users_for_platform(platform, current_users)
    store.save()

    logger.info("Auto-bound WeChat user %s (admin=%s)", user_id, is_admin)
    return {"ok": True, "already_bound": False, "is_admin": is_admin, "pending_bind_menu_hint": True}


# ---------------------------------------------------------------------------
# Lark temporary WebSocket connection (for setup wizard)
# ---------------------------------------------------------------------------
# The Feishu console only shows the "Use Long Connection" option when an
# active WebSocket connection exists.  During the setup wizard we start a
# temporary WS client so the user can configure event subscriptions.

_temp_ws_lock = __import__("threading").Lock()
_temp_ws_client = None
_temp_ws_thread = None


def lark_temp_ws_start(app_id: str, app_secret: str, domain: str = "feishu") -> dict:
    """Start a temporary WebSocket connection so the Feishu console shows the long-connection option."""
    global _temp_ws_client, _temp_ws_thread

    app_id = app_id or _stored_platform_field("lark", "app_id")
    app_secret = app_secret or _stored_platform_secret("lark", "app_secret")
    domain = domain or _stored_platform_field("lark", "domain", "feishu")
    with _temp_ws_lock:
        # Stop any existing temp connection first
        _stop_temp_ws_internal()

        try:
            import lark_oapi as lark

            sdk_domain = lark.LARK_DOMAIN if domain == "lark" else lark.FEISHU_DOMAIN

            # Minimal event handler (does nothing, just keeps the connection alive)
            handler = lark.EventDispatcherHandler.builder("", "").build()

            client = lark.ws.Client(
                app_id=app_id,
                app_secret=app_secret,
                event_handler=handler,
                log_level=lark.LogLevel.INFO,
                domain=sdk_domain,
            )

            import threading

            def _run():
                try:
                    client.start()
                except Exception:
                    pass  # Thread exits silently on stop

            t = threading.Thread(target=_run, daemon=True, name="lark-temp-ws")
            t.start()

            _temp_ws_client = client
            _temp_ws_thread = t

            return {"ok": True, "message": "Temporary WebSocket connection started"}
        except Exception as exc:
            return {"ok": False, "error": str(exc)}


def lark_temp_ws_stop() -> dict:
    """Stop the temporary WebSocket connection."""
    with _temp_ws_lock:
        _stop_temp_ws_internal()
    return {"ok": True}


def _stop_temp_ws_internal():
    """Internal helper to stop temp WS (caller must hold _temp_ws_lock)."""
    global _temp_ws_client, _temp_ws_thread
    if _temp_ws_client is not None:
        try:
            # Prevent auto-reconnect and close the underlying connection
            _temp_ws_client._auto_reconnect = False
            from lark_oapi.ws.client import loop as ws_loop

            ws_loop.call_soon_threadsafe(ws_loop.create_task, _temp_ws_client._disconnect())
        except Exception:
            pass
        _temp_ws_client = None
        _temp_ws_thread = None


# --- Agent Skills (askill CLI shell) --------------------------------------
# Thin orchestration over core/services/skills.py: resolve the askill binary,
# call the async service, and normalize failures into the {ok: false, error}
# envelope the Web UI already reads. The resolved path is injected into the
# service so core/ never imports vibe/. See docs/plans/workbench-skills-page.md.


def _skills_error_message(exc, context, project_id):
    if exc.code != "project_dir_missing" or not project_id or context is None:
        return exc.message
    from storage import project_access_service
    from storage.db import get_cached_sqlite_engine

    engine = get_cached_sqlite_engine()
    with engine.connect() as connection:
        role = project_access_service.get_effective_project_role(connection, context, project_id)
    if project_access_service.role_allows(role, "editor"):
        return exc.message
    return "The configured project folder is unavailable."


async def _skills_guarded(call, *, user_context=None, project_id=None):
    askill = resolve_cli_path("askill")
    if not askill:
        return {"ok": False, "error": {"code": "askill_not_found", "message": "askill CLI not found on PATH"}}
    from core.services import skills as skills_service

    try:
        return await call(askill, skills_service)
    except skills_service.SkillsError as exc:
        message = _skills_error_message(exc, user_context, project_id)
        return {"ok": False, "error": {"code": exc.code, "message": message, "details": exc.details}}
    except LookupError:
        return {"ok": False, "error": {"code": "askill_not_found", "message": "askill CLI not found on PATH"}}


async def list_skills(
    *,
    scope: str = "all",
    project_dir: Optional[str] = None,
    project_id: Optional[str] = None,
    backends: Optional[List[str]] = None,
    user_context: Any = None,
) -> dict:
    context = resolve_resource_access_context() if user_context is None else user_context
    return await _skills_guarded(
        lambda askill, svc: svc.list_skills(
            askill,
            scope=scope,
            project_dir=project_dir,
            project_id=project_id,
            backends=backends,
            user_context=context,
        ),
        user_context=context,
        project_id=project_id,
    )


async def preview_skill_source(
    source: str,
    *,
    project_dir: Optional[str] = None,
    project_id: Optional[str] = None,
    user_context: Any = None,
) -> dict:
    context = resolve_resource_access_context() if user_context is None else user_context
    return await _skills_guarded(
        lambda askill, svc: svc.preview_source(
            askill,
            source,
            project_dir=project_dir,
            project_id=project_id,
            user_context=context,
        ),
        user_context=context,
        project_id=project_id,
    )


async def add_skill(
    source: str,
    *,
    scope: str = "project",
    project_dir: Optional[str] = None,
    project_id: Optional[str] = None,
    backends: Optional[List[str]] = None,
    all_skills: bool = False,
    skill: Optional[str] = None,
    copy: bool = False,
    user_context: Any = None,
) -> dict:
    context = resolve_resource_access_context() if user_context is None else user_context
    return await _skills_guarded(
        lambda askill, svc: svc.add_skill(
            askill,
            source,
            scope=scope,
            project_dir=project_dir,
            project_id=project_id,
            backends=backends,
            all_skills=all_skills,
            skill=skill,
            copy=copy,
            user_context=context,
        ),
        user_context=context,
        project_id=project_id,
    )


async def remove_skill(
    name: str,
    *,
    scope: str = "project",
    project_dir: Optional[str] = None,
    project_id: Optional[str] = None,
    backends: Optional[List[str]] = None,
    user_context: Any = None,
) -> dict:
    context = resolve_resource_access_context() if user_context is None else user_context
    return await _skills_guarded(
        lambda askill, svc: svc.remove_skill(
            askill,
            name,
            scope=scope,
            project_dir=project_dir,
            project_id=project_id,
            backends=backends,
            user_context=context,
        ),
        user_context=context,
        project_id=project_id,
    )


async def find_skills(query: str = "", *, user_context: Any = None) -> dict:
    context = resolve_resource_access_context() if user_context is None else user_context
    return await _skills_guarded(
        lambda askill, svc: svc.find_skills(askill, query, user_context=context)
    )


async def check_skills(
    *,
    scope: str = "project",
    project_dir: Optional[str] = None,
    project_id: Optional[str] = None,
    user_context: Any = None,
) -> dict:
    context = resolve_resource_access_context() if user_context is None else user_context
    return await _skills_guarded(
        lambda askill, svc: svc.check(
            askill,
            scope=scope,
            project_dir=project_dir,
            project_id=project_id,
            user_context=context,
        ),
        user_context=context,
        project_id=project_id,
    )


async def update_skill(
    name: str,
    *,
    scope: str = "project",
    project_dir: Optional[str] = None,
    project_id: Optional[str] = None,
    user_context: Any = None,
) -> dict:
    context = resolve_resource_access_context() if user_context is None else user_context
    return await _skills_guarded(
        lambda askill, svc: svc.update(
            askill,
            name,
            scope=scope,
            project_dir=project_dir,
            project_id=project_id,
            user_context=context,
        ),
        user_context=context,
        project_id=project_id,
    )


async def upload_skill_zip(
    payload: dict,
    *,
    project_dir: Optional[str] = None,
    project_id: Optional[str] = None,
    user_context: Any = None,
) -> dict:
    """Decode a base64 .zip, unpack it to a temp dir, and preview its skills.

    The UI then calls add_skill with ``source`` = the returned ``dir``. The
    temp dir is local-only; askill does the actual install/symlink from it.
    """
    import base64
    import binascii
    import io
    import os
    import shutil
    import tempfile
    import time
    import zipfile

    from vibe.authorization import require_instance_role
    from core.services import skills as skills_service

    context = resolve_resource_access_context() if user_context is None else user_context
    try:
        if project_id:
            skills_service.require_project_editor_access(context, project_id)
        else:
            require_instance_role(context, "editor")
    except skills_service.SkillsError as exc:
        return {"ok": False, "error": {"code": exc.code, "message": exc.message}}

    max_b64 = 24 * 1024 * 1024  # ~18 MB archive — skills are tiny; cap the body.
    max_uncompressed = 64 * 1024 * 1024
    max_entries = 2000

    # Best-effort sweep of stale unpack dirs from earlier uploads (the dir has to
    # outlive this request so add_skill can install from it, so it can't be
    # removed in a finally; sweep anything older than a couple hours instead).
    tmp_root = tempfile.gettempdir()
    try:
        cutoff = time.time() - 2 * 3600
        for name in os.listdir(tmp_root):
            if name.startswith("askill-upload-"):
                stale = os.path.join(tmp_root, name)
                try:
                    if os.path.getmtime(stale) < cutoff:
                        shutil.rmtree(stale, ignore_errors=True)
                except OSError:
                    pass
    except OSError:
        pass

    content_b64 = payload.get("content_base64") or ""
    if not content_b64:
        return {"ok": False, "error": {"code": "missing_file", "message": "no file content"}}
    if len(content_b64) > max_b64:
        return {"ok": False, "error": {"code": "file_too_large", "message": "archive exceeds the size limit"}}
    try:
        raw = base64.b64decode(content_b64, validate=True)
    except (binascii.Error, ValueError):
        return {"ok": False, "error": {"code": "bad_file", "message": "invalid base64 content"}}

    workdir = tempfile.mkdtemp(prefix="askill-upload-")
    unpack = os.path.join(workdir, "skill")
    os.makedirs(unpack, exist_ok=True)
    unpack_root = os.path.realpath(unpack)
    try:
        with zipfile.ZipFile(io.BytesIO(raw)) as archive:
            infos = archive.infolist()
            if len(infos) > max_entries:
                raise ValueError("archive has too many entries")
            if sum(info.file_size for info in infos) > max_uncompressed:
                raise ValueError("archive is too large uncompressed")
            for info in infos:
                target = os.path.realpath(os.path.join(unpack, info.filename))
                # Reject zip-slip (entries that escape the unpack dir).
                if target != unpack_root and not target.startswith(unpack_root + os.sep):
                    raise ValueError("archive contains unsafe paths")
            archive.extractall(unpack)
    except zipfile.BadZipFile:
        shutil.rmtree(workdir, ignore_errors=True)
        return {"ok": False, "error": {"code": "bad_zip", "message": "not a valid .zip archive"}}
    except ValueError as exc:
        shutil.rmtree(workdir, ignore_errors=True)
        return {"ok": False, "error": {"code": "bad_zip", "message": str(exc)}}
    except (RuntimeError, NotImplementedError, OSError) as exc:
        # Encrypted entry / unsupported compression method / filesystem error —
        # extractall raises these (not BadZipFile), so catch them too.
        shutil.rmtree(workdir, ignore_errors=True)
        return {"ok": False, "error": {"code": "bad_zip", "message": f"could not extract archive: {exc}"}}

    preview = await _skills_guarded(
        lambda askill, svc: svc.preview_source(
            askill,
            unpack,
            project_dir=project_dir,
            project_id=project_id,
            user_context=context,
        ),
        user_context=context,
        project_id=project_id,
    )
    if preview.get("ok"):
        preview["dir"] = unpack
    else:
        # Nothing will install from it — don't leak the dir.
        shutil.rmtree(workdir, ignore_errors=True)
    return preview