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.

75.4 KB
Raw Blame
from __future__ import annotations

import hashlib
import hmac
import json
import logging
import os
import re
import secrets
import shutil
import stat
import threading
from dataclasses import asdict, dataclass
from pathlib import Path
from typing import Any, Callable, Sequence

from config.atomic_io import write_atomic
from config.v2_config import (
    GEMINI_NATIVE_BASE_URL,
    normalize_model_hub_base_url,
    on_gemini_openai_compatible_endpoint,
    validate_model_hub_protocol_vendor,
)
from core import private_fs
from core.handlers.model_hub.events import contains_credential_material
from core.handlers.model_hub.identifiers import model_id_without_credential_address
from vibe.model_hub_runtime.api_key_vendors import (
    google_api_base_url,
    official_api_key_base_url,
    validate_api_key_auth_scheme,
)


logger = logging.getLogger(__name__)

_CREDENTIAL_REF_RE = re.compile(r"^cred_[A-Za-z0-9_-]{6,128}$")
_BEARER_CREDENTIAL_REF_RE = re.compile(r"^cred_auth_bearer_[0-9a-f]{32}$")
_PROTOCOLS = {"anthropic", "openai_responses", "openai_chat", "google", "search"}
_SOURCE_ID_RE = re.compile(r"^src_[a-z0-9]{8,}$")
# The engine writes its file log to ``logs`` under its working directory, the instance directory, only
# when that directory already exists; otherwise it falls back to ``<auth-dir>/logs``, among the
# credentials (CLIProxyAPI internal/logging/global_logger.go ResolveLogDirectory).
ENGINE_LOG_DIR = "logs"


class EngineStateError(RuntimeError):
    pass


class EngineStateContentError(EngineStateError):
    """A state file that was read but does not hold a JSON object: its contents, not its access, are bad."""


@dataclass(frozen=True)
class RuntimeSecrets:
    management_key: str
    gateway_token: str


def _without_credential_addresses(payload: dict[str, Any]) -> dict[str, Any]:
    """Read a record an earlier release stored with addressed model names.

    The address belongs to the outbound call, not to the file, but releases
    before this one persisted whatever the engine's management API answered
    with — which is already addressed. Healing on load rather than in a
    one-shot script keeps one spelling in memory no matter which release wrote
    the file, and the next ordinary write persists it.

    A record names the prefix it is addressed by, so only that exact address is
    removed. Nothing is claimed about any other name: a model whose own identity
    happens to be spelled like an address belongs to whoever named it.

    Unwrapping can collapse two stored names onto one identity. The strict
    parse below refuses a repeated reasoning key and a repeated route target,
    so this keeps the first of each instead: a file that loads today must keep
    loading, and a healed duplicate is the same model named twice, not a
    conflict to report. Any shape this cannot read is left exactly as it was,
    so the parse still reports it.
    """

    prefix = payload.get("prefix")
    if not isinstance(prefix, str) or not prefix:
        return payload

    healed = dict(payload)
    model_ids = payload.get("model_ids")
    if isinstance(model_ids, list):
        healed["model_ids"] = list(
            dict.fromkeys(
                model_id_without_credential_address(str(model), prefix)
                for model in model_ids
            )
        )
    route_model_ids = payload.get("route_model_ids")
    if isinstance(route_model_ids, list) and all(
        isinstance(model, str) for model in route_model_ids
    ):
        healed["route_model_ids"] = list(
            dict.fromkeys(
                model_id_without_credential_address(model, prefix)
                for model in route_model_ids
            )
        )
    reasoning_efforts = payload.get("model_reasoning_efforts")
    if isinstance(reasoning_efforts, list) and all(
        isinstance(item, list) and len(item) == 2 and isinstance(item[0], str)
        for item in reasoning_efforts
    ):
        healed_efforts: dict[str, Any] = {}
        for model_id, efforts in reasoning_efforts:
            healed_efforts.setdefault(
                model_id_without_credential_address(model_id, prefix), efforts
            )
        healed["model_reasoning_efforts"] = [
            [model_id, efforts] for model_id, efforts in healed_efforts.items()
        ]
    return healed


@dataclass(frozen=True)
class SourceRecord:
    source_id: str
    vendor: str
    protocol: str
    base_url: str | None
    credential_ref: str
    allowed_origins: tuple[str, ...]
    model_ids: tuple[str, ...]
    prefix: str
    model_reasoning_efforts: tuple[tuple[str, tuple[str, ...]], ...] = ()
    route_model_ids: tuple[str, ...] = ()
    text_only_model_ids: tuple[str, ...] = ()

    @classmethod
    def from_payload(cls, payload: dict[str, Any]) -> SourceRecord:
        payload = _without_credential_addresses(payload)
        try:
            raw_reasoning_efforts = payload["model_reasoning_efforts"]
        except KeyError as exc:
            raise EngineStateError("invalid engine source reasoning state") from exc
        if not isinstance(raw_reasoning_efforts, list):
            raise EngineStateError("invalid engine source reasoning state")
        raw_model_ids = payload.get("model_ids", [])
        if not isinstance(raw_model_ids, list):
            raise EngineStateError("invalid engine source state")
        model_ids = tuple(str(model) for model in raw_model_ids)
        route_model_ids = payload.get("route_model_ids", [])
        if not isinstance(route_model_ids, list) or any(
            not isinstance(model, str) or not model or model != model.strip()
            for model in route_model_ids
        ) or len(set(route_model_ids)) != len(route_model_ids):
            raise EngineStateError("invalid engine route model state")
        parsed_reasoning_efforts: list[tuple[str, tuple[str, ...]]] = []
        seen_reasoning_models: set[str] = set()
        for item in raw_reasoning_efforts:
            if (
                not isinstance(item, list)
                or len(item) != 2
                or not isinstance(item[0], str)
                or not item[0]
                or item[0] not in model_ids
                or not isinstance(item[1], list)
                or any(not isinstance(effort, str) or not effort for effort in item[1])
                or len(set(item[1])) != len(item[1])
                or item[0] in seen_reasoning_models
            ):
                raise EngineStateError("invalid engine source reasoning state")
            seen_reasoning_models.add(item[0])
            parsed_reasoning_efforts.append((item[0], tuple(item[1])))
        return cls(
            source_id=str(payload["source_id"]),
            vendor=str(payload["vendor"]),
            protocol=str(payload["protocol"]),
            base_url=str(payload["base_url"]) if payload.get("base_url") else None,
            credential_ref=str(payload["credential_ref"]),
            allowed_origins=tuple(str(item) for item in payload.get("allowed_origins", [])),
            model_ids=model_ids,
            prefix=str(payload["prefix"]),
            model_reasoning_efforts=tuple(parsed_reasoning_efforts),
            route_model_ids=tuple(route_model_ids),
            text_only_model_ids=_stored_text_only_model_ids(
                str(payload["source_id"]), payload.get("text_only_model_ids", [])
            ),
        )


def _stored_text_only_model_ids(source_id: str, raw: object) -> tuple[str, ...]:
    # Undeclared input is the engine's default, so a list this release cannot
    # read degrades to that rather than failing the source. The next sync
    # rewrites it; until then the Source's images are forwarded, and the log
    # says why.
    if not isinstance(raw, list) or not all(isinstance(model, str) and model for model in raw):
        logger.warning(
            "Engine source %s has an unreadable text-only model list; its models are undeclared until the next sync",
            source_id,
        )
        return ()
    return tuple(dict.fromkeys(raw))


class EngineStateStore:
    """Restricted local state for engine-only keys and upstream credentials."""

    def __init__(self, root: Path) -> None:
        self.root = root
        self._lock = threading.RLock()

    @property
    def auth_dir(self) -> Path:
        return self.root / "auth"

    @property
    def oauth_staging_dir(self) -> Path:
        return self.root / "oauth-staging"

    def prepare_instance(self, install_id: str, *, rotate: bool = False) -> tuple[Path, RuntimeSecrets]:
        with self._lock:
            self._ensure_private_dir(self.root)
            self.audit_auth_permissions()
            instance_dir = self.root / "instances" / _safe_identifier(install_id)
            self._ensure_private_dir(instance_dir)
            self._ensure_private_dir(instance_dir / ENGINE_LOG_DIR)
            self._remove_obsolete_instances(instance_dir)
            secrets_path = instance_dir / "runtime-secrets.json"
            if not rotate:
                self._assert_private_file(secrets_path, "runtime secret permissions are unsafe")
                existing = self._read_json(secrets_path)
                if existing:
                    management_key = existing.get("management_key")
                    gateway_token = existing.get("gateway_token")
                    if isinstance(management_key, str) and isinstance(gateway_token, str):
                        return instance_dir, RuntimeSecrets(management_key, gateway_token)
            generated = RuntimeSecrets(
                management_key=secrets.token_urlsafe(48),
                gateway_token=secrets.token_urlsafe(48),
            )
            self._secure_write_json(secrets_path, asdict(generated))
            return instance_dir, generated

    def list_sources(self) -> list[SourceRecord]:
        with self._lock:
            try:
                payload = self._read_json(self.root / "sources.json") or {}
                raw_sources = payload.get("sources", [])
                if not isinstance(raw_sources, list):
                    raise EngineStateError("invalid engine source state")
                return [
                    SourceRecord.from_payload(item)
                    for item in raw_sources
                    if isinstance(item, dict)
                ]
            except (KeyError, TypeError, ValueError) as exc:
                raise EngineStateError(f"invalid engine source state: {exc}") from exc

    def get_source(self, source_id: str) -> SourceRecord | None:
        return next((source for source in self.list_sources() if source.source_id == source_id), None)

    def validate_source_id(self, source_id: str) -> None:
        _validated_source_id(source_id)

    def store_api_key(
        self,
        value: str,
        *,
        vendor: str = "custom",
        protocol: str = "openai_chat",
        base_url: str | None = None,
        auth_scheme: str | None = None,
        on_reserved: Callable[[str], None] | None = None,
    ) -> str:
        if not isinstance(value, str) or not value:
            raise EngineStateError("credential is empty")
        normalized_vendor = vendor.strip().lower()
        if not normalized_vendor:
            raise EngineStateError("credential vendor is empty")
        if protocol not in _PROTOCOLS:
            raise EngineStateError("unsupported source protocol")
        try:
            validate_api_key_auth_scheme(
                normalized_vendor, protocol, base_url, value, auth_scheme,
            )
        except ValueError:
            raise EngineStateError("unsupported API key authentication scheme") from None
        normalized_base_url = _validated_base_url(base_url)
        with self._lock:
            prefix = "cred_auth_bearer_" if auth_scheme == "bearer" else "cred_"
            credential_ref = f"{prefix}{secrets.token_hex(16)}"
            credential_path, credential_tmp, stage_path, stage_tmp = (
                self._reserve_credential_namespace(credential_ref)
            )
            try:
                if on_reserved is not None:
                    on_reserved(credential_ref)
                self._write_reserved_json(
                    credential_path,
                    {
                        "kind": "api_key",
                        "vendor": normalized_vendor,
                        "protocol": protocol,
                        "base_url": normalized_base_url,
                        "value": value,
                        **({"auth_scheme": auth_scheme} if auth_scheme is not None else {}),
                    },
                    temporary_path=credential_tmp,
                    credential_ref=credential_ref,
                )
                self._remove_private_file_if_present(stage_path)
                self._remove_private_file_if_present(stage_tmp)
            except BaseException:
                self._cleanup_private_paths(
                    (credential_path, credential_tmp, stage_path, stage_tmp)
                )
                raise
            return credential_ref

    def bind_oauth_credential(self, source_id: str, vendor: str, auth_name: str) -> str:
        _validated_source_id(source_id)
        if not vendor.strip() or not auth_name.strip():
            raise EngineStateError("OAuth credential binding is incomplete")
        normalized_vendor = vendor.strip().lower()
        normalized_auth_name = auth_name.strip()
        with self._lock:
            matches = [
                (credential_ref, payload)
                for credential_ref, payload in self._oauth_credentials()
                if payload.get("auth_name") == normalized_auth_name
            ]
            if matches:
                if len(matches) != 1:
                    raise EngineStateError("OAuth auth record binding is ambiguous")
                credential_ref, payload = matches[0]
                if payload.get("source_id") != source_id or payload.get("vendor") != normalized_vendor:
                    raise EngineStateError("OAuth auth record is already bound to another source")
                return credential_ref
            credential_ref = f"cred_{secrets.token_hex(16)}"
            prefix = f"avibe-{secrets.token_hex(12)}"
            self._secure_write_json(
                self._credential_path(credential_ref),
                {
                    "kind": "oauth",
                    "source_id": source_id,
                    "vendor": normalized_vendor,
                    "auth_name": normalized_auth_name,
                    "prefix": prefix,
                },
            )
            return credential_ref

    def stage_oauth_credential(
        self,
        source_id: str,
        vendor: str,
        auth_name: str,
        payload: dict[str, Any],
        on_reserved: Callable[[str], None] | None = None,
    ) -> str:
        """Persist an OAuth grant outside the engine's watched auth directory."""

        _validated_source_id(source_id)
        normalized_vendor = vendor.strip().lower()
        normalized_auth_name = _validated_oauth_auth_name(auth_name)
        if not normalized_vendor:
            raise EngineStateError("OAuth credential binding is incomplete")
        if not isinstance(payload, dict) or not isinstance(payload.get("type"), str):
            raise EngineStateError("invalid OAuth auth payload")
        with self._lock:
            self._ensure_private_dir(self.root)
            self._ensure_private_dir(self.oauth_staging_dir)
            credential_ref = f"cred_{secrets.token_hex(16)}"
            prefix = f"avibe-{secrets.token_hex(12)}"
            staged_payload = {
                **payload,
                # CPA's file synthesizer reads the prefix from the auth JSON.
                # It must be part of the fully-written staged bytes before the
                # file can become visible in the watched auth directory.
                "prefix": prefix,
            }
            expected_provider = _oauth_provider_for_vendor(normalized_vendor)
            if str(staged_payload.get("type") or "").strip().lower() != expected_provider:
                raise EngineStateError("OAuth auth payload provider does not match vendor")
            credential_path, credential_tmp, stage_path, stage_tmp = (
                self._reserve_credential_namespace(credential_ref)
            )
            try:
                if on_reserved is not None:
                    on_reserved(credential_ref)
                self._write_reserved_json(
                    stage_path,
                    staged_payload,
                    temporary_path=stage_tmp,
                    credential_ref=credential_ref,
                )
                stage_revision = self._file_revision(stage_path)
                self._write_reserved_json(
                    credential_path,
                    {
                        "kind": "oauth",
                        "source_id": source_id,
                        "vendor": normalized_vendor,
                        "auth_name": normalized_auth_name,
                        "prefix": prefix,
                        "activation_state": "staged",
                        "engine_published": False,
                        "prefix_published": False,
                        "stage_revision": stage_revision,
                        "published_revision": None,
                        "published_identity": None,
                    },
                    temporary_path=credential_tmp,
                    credential_ref=credential_ref,
                )
            except BaseException as exc:
                self._cleanup_private_paths(
                    (credential_path, credential_tmp, stage_path, stage_tmp)
                )
                raise EngineStateError("unable to stage OAuth credential") from exc
            return credential_ref

    def write_oauth_auth_file(self, auth_name: str, payload: dict[str, Any]) -> None:
        """Write an imported OAuth grant into the engine auth directory."""
        normalized = _validated_oauth_auth_name(auth_name)
        if not isinstance(payload, dict) or not isinstance(payload.get("type"), str):
            raise EngineStateError("invalid OAuth auth payload")
        with self._lock:
            self.audit_auth_permissions(enforce=True)
            self._secure_write_json(self.auth_dir / normalized, payload)

    def activate_oauth_auth_file(
        self,
        credential_ref: str,
    ) -> tuple[str, dict[str, Any], str, bool]:
        """Publish one staged grant without replacing an existing live file.

        The watched path is the durable owner after publication. CPA may rotate
        the access and refresh tokens in that same file at any time, so retries
        validate only the opaque file identity (name, provider, prefix), never
        the bytes or a token hash captured before publication.
        """

        with self._lock:
            metadata = self.credential_metadata(credential_ref)
            if metadata.get("kind") != "oauth":
                raise EngineStateError("OAuth credential is unavailable")
            auth_name = _validated_oauth_auth_name(str(metadata.get("auth_name") or ""))
            target = self.auth_dir / auth_name
            self.audit_auth_permissions(enforce=True)

            # A live watched file always wins over private staging. This is the
            # crash/refresh recovery rule: never re-publish stale R0 bytes after
            # CPA has already observed or rotated the file.
            if target.exists():
                payload = self._decode_oauth_payload(target)
                identity = self._assert_oauth_auth_file_owned_locked(metadata, target, payload)
                updated = {
                    **metadata,
                    "activation_state": "active",
                    "prefix_published": True,
                    "published_identity": identity,
                }
                self._secure_write_json(self._credential_path(credential_ref), updated)
                self._remove_oauth_stage_if_present(credential_ref)
                return auth_name, payload, identity["prefix"], metadata.get("activation_state") == "active"

            stage_path = self._oauth_stage_path(credential_ref)
            staged_bytes = self._read_private_bytes(
                stage_path,
                "OAuth staging file is unsafe",
            )
            stage_revision = metadata.get("stage_revision")
            actual_stage_revision = hashlib.sha256(staged_bytes).hexdigest()
            if isinstance(stage_revision, str) and actual_stage_revision != stage_revision:
                raise EngineStateError("OAuth staging record is inconsistent")
            staged_payload = self._decode_oauth_payload(stage_path)
            self._assert_oauth_payload_identity(metadata, auth_name, staged_payload)
            try:
                self._publish_staged_no_replace(stage_path, target)
            except FileExistsError:
                # The watcher or another retry won the publication race. Read
                # that winner and bind to it; do not upload stale staged bytes.
                if not target.exists():
                    raise EngineStateError("OAuth auth file publication is inconclusive") from None
                payload = self._decode_oauth_payload(target)
                identity = self._assert_oauth_auth_file_owned_locked(metadata, target, payload)
            else:
                payload = self._decode_oauth_payload(target)
                identity = self._assert_oauth_auth_file_owned_locked(metadata, target, payload)

            updated = {
                **metadata,
                "activation_state": "active",
                "prefix_published": True,
                "published_identity": identity,
            }
            self._secure_write_json(self._credential_path(credential_ref), updated)
            self._remove_oauth_stage_if_present(credential_ref)
            return auth_name, payload, identity["prefix"], False

    def mark_oauth_engine_published(self, credential_ref: str) -> None:
        with self._lock:
            metadata = self.credential_metadata(credential_ref)
            if metadata.get("kind") != "oauth":
                raise EngineStateError("OAuth credential is unavailable")
            auth_name = _validated_oauth_auth_name(str(metadata.get("auth_name") or ""))
            identity = self._assert_oauth_auth_file_owned_locked(
                metadata,
                self.auth_dir / auth_name,
            )
            self._secure_write_json(
                self._credential_path(credential_ref),
                {
                    **metadata,
                    "activation_state": "active",
                    "engine_published": True,
                    "prefix_published": True,
                    "published_identity": identity,
                },
            )

    def assert_oauth_auth_file_unchanged(self, credential_ref: str) -> None:
        """Backward-compatible name for the post-publication ownership check."""

        with self._lock:
            metadata = self.credential_metadata(credential_ref)
            if metadata.get("kind") != "oauth":
                raise EngineStateError("OAuth credential is unavailable")
            auth_name = _validated_oauth_auth_name(str(metadata.get("auth_name") or ""))
            self._assert_oauth_auth_file_owned_locked(metadata, self.auth_dir / auth_name)

    def mark_oauth_prefix_published(self, credential_ref: str) -> None:
        with self._lock:
            metadata = self.credential_metadata(credential_ref)
            if metadata.get("kind") != "oauth":
                raise EngineStateError("OAuth credential is unavailable")
            auth_name = _validated_oauth_auth_name(str(metadata.get("auth_name") or ""))
            identity = self._assert_oauth_auth_file_owned_locked(
                metadata,
                self.auth_dir / auth_name,
            )
            self._secure_write_json(
                self._credential_path(credential_ref),
                {
                    **metadata,
                    "activation_state": "active",
                    "prefix_published": True,
                    "published_identity": identity,
                },
            )

    def matches_api_key_credential(
        self,
        credential_ref: str,
        vendor: str,
        protocol: str,
        secret: str,
        base_url: str | None,
        *,
        auth_scheme: str | None = None,
    ) -> bool:
        """Compare transient native material with an engine-owned API key."""

        metadata = self.credential_metadata(credential_ref)
        if metadata.get("kind") != "api_key":
            return False
        try:
            validate_api_key_auth_scheme(vendor, protocol, base_url, secret, auth_scheme)
        except ValueError:
            raise EngineStateError("unsupported API key authentication scheme") from None
        normalized_base_url = _validated_base_url(base_url)
        if (
            metadata.get("vendor") != vendor.strip().lower()
            or metadata.get("protocol") != protocol
            or metadata.get("base_url") != normalized_base_url
            or metadata.get("auth_scheme") != auth_scheme
        ):
            return False
        if not isinstance(secret, str):
            return False
        stored = self.read_api_key(credential_ref)
        return hmac.compare_digest(
            stored.encode("utf-8"),
            secret.encode("utf-8"),
        )

    def sync_sources(self, bindings: Sequence[Any]) -> list[SourceRecord]:
        """Atomically replace the engine projection using opaque credential refs."""
        with self._lock:
            path = self.root / "sources.json"
            try:
                existing = {source.source_id: source for source in self.list_sources()}
            except EngineStateError as exc:
                self._discard_invalid_state_file(path, exc)
                existing = {}
            records: list[SourceRecord] = []
            seen: set[str] = set()
            for binding in bindings:
                source_id = _validated_source_id(str(binding.source_id))
                if source_id in seen:
                    raise EngineStateError("duplicate source binding")
                seen.add(source_id)
                credential_ref = str(binding.credential_ref)
                credential = self.credential_metadata(credential_ref)
                protocol = str(binding.protocol)
                if protocol not in _PROTOCOLS:
                    raise EngineStateError("unsupported source protocol")
                vendor = str(binding.vendor).strip().lower()
                base_url = _validated_base_url(binding.base_url)
                _validate_source_target(
                    vendor,
                    protocol,
                    base_url,
                    credential_kind=credential["kind"],
                )
                credential = self._follow_native_gemini(credential_ref, credential, vendor, protocol, base_url)
                if credential["kind"] == "api_key":
                    if (
                        credential.get("vendor") != vendor
                        or credential.get("protocol") != protocol
                        or credential.get("base_url") != base_url
                    ):
                        raise EngineStateError("credential does not match source binding")
                elif (
                    credential.get("source_id") != source_id
                    or credential.get("vendor") != vendor
                    or base_url is not None
                ):
                    raise EngineStateError("OAuth credential does not match source binding")
                allowed_origins = tuple(dict.fromkeys(str(origin).strip() for origin in binding.allowed_origins))
                if any(not origin for origin in allowed_origins):
                    raise EngineStateError("allowed origin cannot be empty")
                if credential["kind"] == "oauth" and not allowed_origins:
                    raise EngineStateError("OAuth source requires at least one allowed origin")
                previous = existing.get(source_id)
                # Settle the address this Source is reached by before reading any
                # model name, so a name carrying it is unwrapped against the one
                # prefix that owns it rather than against the shape of a prefix.
                prefix = (
                    str(credential["prefix"])
                    if credential.get("prefix")
                    else previous.prefix
                    if previous
                    else f"avibe-{secrets.token_hex(12)}"
                )
                model_ids = tuple(
                    dict.fromkeys(
                        model_id_without_credential_address(str(model).strip(), prefix)
                        for model in binding.model_ids
                    )
                )
                if any(not model for model in model_ids):
                    raise EngineStateError("model id cannot be empty")
                route_model_ids = tuple(binding.route_model_ids)
                if any(not isinstance(model, str) or not model or model != model.strip() for model in route_model_ids):
                    raise EngineStateError("invalid route model id")
                reasoning_by_model: dict[str, tuple[str, ...]] = {}
                # Which spelling each entry arrived under. A caller naming one
                # model twice is still refused, but two names that meet only
                # because the address came off collapse onto the first — the
                # same collision ``model_ids`` above absorbs, and the same one a
                # stored record absorbs on load. A Source may legitimately hold
                # both spellings until its rows are repaired, and refusing the
                # pair here would leave the engine unsynchronized instead.
                spellings: dict[str, str] = {}
                for model_id, efforts in binding.model_reasoning_efforts:
                    answered = str(model_id).strip()
                    normalized_model_id = model_id_without_credential_address(answered, prefix)
                    if not normalized_model_id or normalized_model_id not in model_ids:
                        raise EngineStateError("reasoning model id is not registered")
                    normalized_efforts = tuple(
                        dict.fromkeys(str(effort).strip() for effort in efforts)
                    )
                    if any(not effort for effort in normalized_efforts):
                        raise EngineStateError("reasoning effort cannot be empty")
                    held = spellings.get(normalized_model_id)
                    if held is not None:
                        if held == answered:
                            raise EngineStateError("duplicate reasoning model id")
                        continue
                    spellings[normalized_model_id] = answered
                    reasoning_by_model[normalized_model_id] = normalized_efforts
                normalized_route_model_ids = tuple(
                    sorted(
                        {
                            model_id_without_credential_address(model, prefix)
                            for model in route_model_ids
                        }
                    )
                )
                text_only_model_ids = tuple(
                    dict.fromkeys(
                        model_id_without_credential_address(str(model).strip(), prefix)
                        for model in binding.text_only_model_ids
                    )
                )
                if any(
                    model not in (*model_ids, *normalized_route_model_ids)
                    for model in text_only_model_ids
                ):
                    raise EngineStateError("text-only model id is not registered")
                records.append(
                    SourceRecord(
                        source_id=source_id,
                        vendor=vendor,
                        protocol=protocol,
                        base_url=base_url,
                        credential_ref=credential_ref,
                        allowed_origins=allowed_origins,
                        model_ids=model_ids,
                        route_model_ids=normalized_route_model_ids,
                        prefix=prefix,
                        model_reasoning_efforts=tuple(reasoning_by_model.items()),
                        text_only_model_ids=text_only_model_ids,
                    )
                )
            self._write_sources(records)
            return records

    def replace_sources(self, sources: Sequence[SourceRecord]) -> None:
        """Restore a previously validated source projection."""
        with self._lock:
            self._write_sources(sources)

    def set_models(self, source_id: str, model_ids: Sequence[str]) -> SourceRecord:
        with self._lock:
            sources = self.list_sources()
            current = next((source for source in sources if source.source_id == source_id), None)
            if current is None:
                raise EngineStateError("source is not registered")
            models = tuple(
                dict.fromkeys(
                    model_id_without_credential_address(
                        str(model).strip(), current.prefix
                    )
                    for model in model_ids
                )
            )
            if not models:
                raise EngineStateError("source requires at least one model id")
            if any(not model for model in models):
                raise EngineStateError("model id cannot be empty")
            retained_reasoning = tuple(
                (model_id, efforts)
                for model_id, efforts in current.model_reasoning_efforts
                if model_id in models
            )
            retained_text_only = tuple(
                model_id
                for model_id in current.text_only_model_ids
                if model_id in models or model_id in current.route_model_ids
            )
            updated_record = SourceRecord(
                **{
                    **asdict(current),
                    "model_ids": models,
                    "model_reasoning_efforts": retained_reasoning,
                    "text_only_model_ids": retained_text_only,
                }
            )
            self._write_sources([updated_record if source.source_id == source_id else source for source in sources])
            return updated_record

    def _follow_native_gemini(
        self, credential_ref: str, credential: dict[str, Any], vendor: str, protocol: str, base_url: str | None,
    ) -> dict[str, Any]:
        """The credential a Gemini Source moved to the native protocol is bound by, moved with it.

        ``_migrate_gemini_native_sources`` moves a Gemini API key's Source from Google's OpenAI-compatible endpoint to
        the native root; the key it holds is the same key on the same account, so its binding follows the first time
        the Source asks for it. Any other mismatch is still the caller's refusal.
        """

        if not (
            credential.get("kind") == "api_key"
            and vendor == "gemini" and protocol == "google"
            and base_url in (None, _validated_base_url(GEMINI_NATIVE_BASE_URL))
            and on_gemini_openai_compatible_endpoint(
                credential.get("vendor"), credential.get("protocol"), credential.get("base_url"),
            )
        ):
            return credential
        moved = {**credential, "protocol": protocol, "base_url": base_url}
        with self._lock:
            self._secure_write_json(self._credential_path(credential_ref), moved)
        return moved

    def credential_metadata(self, credential_ref: str) -> dict[str, Any]:
        payload = self.credential_metadata_if_present(credential_ref)
        if payload is None:
            raise EngineStateError("credential is unavailable")
        return payload

    def credential_metadata_if_present(
        self,
        credential_ref: str,
    ) -> dict[str, Any] | None:
        with self._lock:
            path = self._credential_path(credential_ref)
            try:
                mode = path.lstat().st_mode
            except FileNotFoundError:
                return None
            if not stat.S_ISREG(mode) or not private_fs.is_private(path, mode):
                raise EngineStateError("credential permissions are unsafe")
            payload = self._read_json(path)
            if payload is None:
                return None
            if payload.get("kind") == "reservation" and payload.get("credential_ref") == credential_ref:
                return None
            _validate_credential_auth_scheme(credential_ref, payload)
            return payload

    def credential_auth_scheme(self, credential_ref: str) -> str | None:
        """Recover replacement transport without requiring the previous secret.

        Only a safe missing or content-corrupt document permits ref fallback.
        Readable identity conflicts, unsafe paths and I/O failures stay errors.
        Plain refs predate explicit transport; intact unpublished Bearer
        metadata is supported, but its complete loss cannot be reconstructed.
        """
        with self._lock:
            ref_scheme = _credential_ref_auth_scheme(credential_ref)
            payload = self._read_replacement_credential_document(credential_ref)
            if payload is None:
                return ref_scheme
            _validate_credential_auth_scheme(credential_ref, payload, require_secret=False)
            if payload.get("kind") != "api_key":
                raise EngineStateError("API key credential is unavailable")
            return payload.get("auth_scheme")

    def api_key_credential_is_search(self, credential_ref: str) -> bool:
        """Identify tool-only retirement without requiring an intact old secret.

        Missing/corrupt documents retain ordinary API-key config invalidation;
        readable identity conflicts and unsafe paths still refuse retirement.
        """
        with self._lock:
            payload = self._read_replacement_credential_document(credential_ref)
            if payload is None:
                return False
            _validate_credential_auth_scheme(credential_ref, payload, require_secret=False)
            if payload.get("kind") != "api_key":
                raise EngineStateError("API key credential is unavailable")
            return payload.get("protocol") == "search"

    def _private_credential_directory_present(self, directory: Path) -> bool:
        """Observe owned directories without creating or repairing them."""
        for path in (self.root, directory):
            try:
                mode = path.lstat().st_mode
                private = stat.S_ISDIR(mode) and private_fs.is_private(path, mode)
            except FileNotFoundError:
                return False
            except OSError as exc:
                raise EngineStateError("unable to inspect credential directory") from exc
            if not private:
                raise EngineStateError("credential directory permissions are unsafe")
        return True

    def _read_replacement_credential_document(
        self, credential_ref: str,
    ) -> dict[str, Any] | None:
        """Read safe identity evidence; only missing/corrupt contents are absent."""
        _credential_ref_auth_scheme(credential_ref)
        directory = self.root / "credentials"
        if not self._private_credential_directory_present(directory):
            return None
        path = directory / f"{credential_ref}.json"
        try:
            mode = path.lstat().st_mode
        except FileNotFoundError:
            return None
        except OSError as exc:
            raise EngineStateError("unable to inspect credential file") from exc
        if not stat.S_ISREG(mode) or not private_fs.is_private(path, mode):
            raise EngineStateError("credential permissions are unsafe")
        try:
            # Do not turn an open/read failure into content corruption. Ref
            # recovery is safe only after a private regular file was read.
            descriptor = os.open(
                path,
                os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
                | getattr(os, "O_BINARY", 0),
            )
            with os.fdopen(descriptor, "rb") as handle:
                mode = os.fstat(handle.fileno()).st_mode
                if not stat.S_ISREG(mode) or not private_fs.is_private(path, mode, fd=handle.fileno()):
                    raise EngineStateError("credential permissions are unsafe")
                raw = handle.read()
        except OSError as exc:
            raise EngineStateError("unable to read credential file") from exc
        try:
            payload = json.loads(raw)
        except ValueError:
            return None
        return payload if isinstance(payload, dict) else None

    def has_current_source_credential(
        self,
        credential_ref: str,
        *,
        source_id: str,
        kind: str,
        vendor: str,
        protocol: str,
        base_url: str | None,
    ) -> bool:
        """Observe a Source's current credential binding without repair or secrets.

        Unlike credential_metadata(), this read never creates directories or
        fixes permissions. It proves local ownership/existence, not upstream
        authentication, refreshability, or model entitlement. OAuth auth files
        remain entirely engine-owned and are not opened by this observation.
        """
        try:
            _credential_ref_auth_scheme(credential_ref)
            _validated_source_id(source_id)
            credential_kind = {"api_key": "api_key", "subscription": "oauth"}.get(kind)
            if credential_kind is None or not isinstance(vendor, str) or protocol not in _PROTOCOLS:
                return False
            normalized_vendor = vendor.strip().lower()
            normalized_base_url = _validated_base_url(base_url)
            _validate_source_target(
                normalized_vendor, protocol, normalized_base_url, credential_kind=credential_kind,
            )
            credentials_dir = self.root / "credentials"
            for directory in (self.root, credentials_dir):
                mode = directory.lstat().st_mode
                if not stat.S_ISDIR(mode) or not private_fs.is_private(directory, mode):
                    return False
            payload = json.loads(self._read_private_bytes(
                credentials_dir / f"{credential_ref}.json",
                "credential path is unsafe",
            ))
            if not isinstance(payload, dict) or (
                payload.get("kind") != credential_kind or payload.get("vendor") != normalized_vendor
            ):
                return False
            _validate_credential_auth_scheme(credential_ref, payload)
            if credential_kind == "api_key":
                validate_api_key_auth_scheme(
                    normalized_vendor, protocol, normalized_base_url,
                    payload.get("value"), payload.get("auth_scheme"),
                )
                return (
                    payload.get("protocol") == protocol
                    and payload.get("base_url") == normalized_base_url
                    and isinstance(payload.get("value"), str)
                    and bool(payload["value"].strip())
                )
            auth_name = payload.get("auth_name")
            return (
                normalized_base_url is None
                and payload.get("source_id") == source_id
                and payload.get("activation_state") in {None, "active"}
                and isinstance(auth_name, str)
                and bool(_validated_oauth_auth_name(auth_name))
            )
        except (OSError, ValueError, TypeError, EngineStateError):
            return False

    def validate_api_key_target(
        self,
        credential_ref: str,
        *,
        vendor: str,
        protocol: str,
        base_url: str | None,
    ) -> str | None:
        normalized_base_url = _validated_base_url(base_url)
        metadata = self._follow_native_gemini(
            credential_ref, self.credential_metadata(credential_ref), vendor.strip().lower(), protocol, normalized_base_url,
        )
        if (
            metadata["kind"] != "api_key"
            or metadata.get("vendor") != vendor.strip().lower()
            or metadata.get("protocol") != protocol
            or metadata.get("base_url") != normalized_base_url
        ):
            raise EngineStateError("credential does not match discovery target")
        return normalized_base_url

    def assert_credential_unbound(self, credential_ref: str) -> None:
        if any(source.credential_ref == credential_ref for source in self.list_sources()):
            raise EngineStateError("credential is still bound to a source")

    def revoke_credential(self, credential_ref: str) -> None:
        with self._lock:
            self.assert_credential_unbound(credential_ref)
            path, temporary_path, stage_path, stage_temporary_path = (
                self._credential_namespace_paths(credential_ref)
            )
            self.credential_metadata_if_present(credential_ref)
            self._remove_private_file_if_present(stage_path)
            self._remove_private_file_if_present(stage_temporary_path)
            self._remove_private_file_if_present(temporary_path)
            self._remove_private_file_if_present(path)

    def revoke_search_credential(self, credential_ref: str) -> None:
        """Retire a search-only namespace even after its document disappeared."""
        with self._lock:
            payload = self._read_replacement_credential_document(credential_ref)
            if payload is not None and payload.get("protocol") != "search":
                raise EngineStateError("credential is not a search API key")
            self.revoke_api_key_credential(credential_ref)

    def revoke_api_key_credential(self, credential_ref: str) -> None:
        """Retire a known API-key ref, never a watched OAuth auth file.

        The caller's durable API-key-only intent permits cleanup when the old
        document is missing/content-corrupt. Readable identity conflicts still
        reject. Exact private namespace ownership does not depend on a secret.
        """
        with self._lock:
            self.assert_credential_unbound(credential_ref)
            self.credential_auth_scheme(credential_ref)
            paths = self._credential_namespace_paths(credential_ref, create=False)
            present_directories = {
                directory
                for directory in {path.parent for path in paths}
                if self._private_credential_directory_present(directory)
            }
            # Validate every owned path before deleting any, including temp and
            # staging remnants. Never follow an auth_name in document contents.
            for path in paths:
                self._assert_private_file(path, "engine state path is unsafe")
            for path in reversed(paths):
                if path.parent in present_directories:
                    self._remove_private_file_if_present(path)

    def clear_runtime_configs(self, *, keep: Path | None = None) -> None:
        """Remove persisted engine configs after any credential is revoked.

        ``keep`` names the live instance directory whose config was just
        re-rendered without the revoked credential.
        """
        with self._lock:
            self._ensure_private_dir(self.root)
            instances_dir = self.root / "instances"
            if not instances_dir.exists():
                return
            self._ensure_private_dir(instances_dir)
            for instance_dir in instances_dir.iterdir():
                mode = instance_dir.lstat().st_mode
                if not stat.S_ISDIR(mode):
                    raise EngineStateError("engine instance directory is unsafe")
                if keep is not None and instance_dir == keep:
                    continue
                config_path = instance_dir / "config.yaml"
                try:
                    config_mode = config_path.lstat().st_mode
                except FileNotFoundError:
                    continue
                if not stat.S_ISREG(config_mode):
                    raise EngineStateError("engine config path is unsafe")
                config_path.unlink()

    def read_api_key(self, credential_ref: str) -> str:
        payload = self.credential_metadata(credential_ref)
        value = payload.get("value") if payload.get("kind") == "api_key" else None
        if not isinstance(value, str) or not value:
            raise EngineStateError("API key credential is unavailable")
        return value

    def oauth_auth_name(self, credential_ref: str) -> str | None:
        payload = self.credential_metadata(credential_ref)
        value = payload.get("auth_name") if payload.get("kind") == "oauth" else None
        return str(value) if value else None

    def reconcile_claude_login(self, auth_name: str) -> None:
        """Follow a login's preserved prefix, never infer ownership from account fields.

        CPA c404af96 saveTokenRecord saves the new canonical name with the
        previous file's metadata, then deletes that previous file. Only the
        OAuth-completion path calls this; ordinary loads/refreshes keep names.
        """
        auth_name = _validated_oauth_auth_name(auth_name)
        with self._lock:
            payload = self._read_json(self.auth_dir / auth_name)
            if payload is None:
                raise EngineStateError("OAuth credential is unavailable")
            prefix = payload.get("prefix")
            if not isinstance(prefix, str) or not prefix:
                return
            if payload.get("type") != "claude":
                raise EngineStateError("OAuth auth record provider conflicts")
            credentials = self._oauth_credentials()
            owners = [
                (ref, metadata) for ref, metadata in credentials
                if metadata.get("vendor") == "anthropic" and metadata.get("prefix") == prefix
            ]
            if not owners:
                return
            if len(owners) != 1:
                raise EngineStateError("OAuth auth record binding is ambiguous")
            credential_ref, metadata = owners[0]
            if any(
                ref != credential_ref and record.get("auth_name") == auth_name
                for ref, record in credentials
            ):
                raise EngineStateError("OAuth auth record binding is ambiguous")
            previous_name = _validated_oauth_auth_name(str(metadata.get("auth_name") or ""))
            if previous_name == auth_name:
                return
            # A failed legacy-file deletion leaves two grants. Keep both and
            # the original binding; do not choose or clean up either one.
            try:
                (self.auth_dir / previous_name).lstat()
            except FileNotFoundError:
                pass
            else:
                raise EngineStateError("OAuth auth record binding is ambiguous")
            self._secure_write_json(
                self._credential_path(credential_ref),
                {**metadata, "auth_name": auth_name},
            )

    def oauth_account_label(
        self, credential_ref: str, *, source_id: str, vendor: str, auth_provider: str,
    ) -> str | None:
        """Project optional identity without changing custody or repairing files."""
        payload = self._bound_oauth_payload(
            credential_ref, source_id=source_id, vendor=vendor, auth_provider=auth_provider,
        )
        return _oauth_account_label(payload) if payload is not None else None

    def _bound_oauth_payload(
        self, credential_ref: str, *, source_id: str, vendor: str, auth_provider: str,
    ) -> dict[str, Any] | None:
        """Read a Source's active grant as the engine holds it, or None; never repairs."""
        try:
            with self._lock:
                _validated_source_id(source_id)
                metadata = self._read_replacement_credential_document(credential_ref)
                if (
                    metadata is None
                    or metadata.get("kind") != "oauth"
                    or metadata.get("source_id") != source_id
                    or metadata.get("vendor") != vendor
                    or metadata.get("activation_state") not in {None, "active"}
                    or not self._private_credential_directory_present(self.auth_dir)
                ):
                    return None
                auth_name = metadata.get("auth_name")
                if not isinstance(auth_name, str):
                    return None
                auth_name = _validated_oauth_auth_name(auth_name)
                payload = json.loads(self._read_private_bytes(
                    self.auth_dir / auth_name, "engine auth credential path is unsafe",
                ))
                if not isinstance(payload, dict):
                    return None
                self._assert_oauth_payload_identity(metadata, auth_name, payload, auth_provider=auth_provider)
                return payload
        except (EngineStateError, OSError, ValueError, TypeError):
            # Grant metadata is optional. A missing/unsafe grant stays under
            # its existing auth recovery policy; reading must not repair it.
            return None

    def oauth_credential_ref(self, auth_name: str) -> str | None:
        normalized = auth_name.strip()
        with self._lock:
            matches = [
                credential_ref
                for credential_ref, payload in self._oauth_credentials()
                if payload.get("auth_name") == normalized
            ]
        if len(matches) > 1:
            raise EngineStateError("OAuth auth record binding is ambiguous")
        return matches[0] if matches else None

    def delete_oauth_auth_file(self, auth_name: str) -> None:
        """Delete one managed OAuth file without requiring a running engine.

        Its engine lock sidecar goes with it, best effort: since CPA v8.0.28 the
        engine locks a Codex grant through ``<name>.lock`` beside it and never
        removes that file. The engine may hold it during a refresh, which on
        Windows blocks the delete; a leftover sidecar locks nothing and passes
        the auth audit, so it is not worth failing the grant's removal over.
        """
        normalized = _validated_oauth_auth_name(auth_name)
        with self._lock:
            self.audit_auth_permissions(enforce=True)
            self._remove_private_file_if_present(self.auth_dir / normalized)
            try:
                self._remove_private_file_if_present(self.auth_dir / f"{normalized}.lock")
            except EngineStateError:
                logger.warning("Could not remove the engine lock beside a deleted OAuth grant", exc_info=True)

    def audit_auth_permissions(self, *, enforce: bool = False) -> None:
        self._ensure_private_dir(self.root)
        if not self.auth_dir.exists():
            self.auth_dir.mkdir(parents=True, mode=0o700)
        auth_mode = self.auth_dir.lstat().st_mode
        if not stat.S_ISDIR(auth_mode):
            raise EngineStateError("engine auth directory is unsafe")
        if not private_fs.is_private(self.auth_dir, auth_mode):
            raise EngineStateError("engine auth directory permissions are unsafe")
        for entry in self.auth_dir.iterdir():
            mode = entry.lstat().st_mode
            if not stat.S_ISREG(mode):
                raise EngineStateError("engine auth directory contains an unsafe entry")
            if private_fs.is_private(entry, mode):
                continue
            if not enforce:
                raise EngineStateError("engine auth credential permissions are unsafe")
            private_fs.make_private_file(entry)

    def _credential_path(self, credential_ref: str) -> Path:
        _credential_ref_auth_scheme(credential_ref)
        self._ensure_private_dir(self.root)
        credentials_dir = self.root / "credentials"
        self._ensure_private_dir(credentials_dir)
        return credentials_dir / f"{credential_ref}.json"

    def _credential_namespace_paths(
        self,
        credential_ref: str,
        *,
        create: bool = True,
    ) -> tuple[Path, Path, Path, Path]:
        _credential_ref_auth_scheme(credential_ref)
        credential_path = (
            self._credential_path(credential_ref)
            if create else self.root / "credentials" / f"{credential_ref}.json"
        )
        stage_path = (
            self._oauth_stage_path(credential_ref)
            if create else self.oauth_staging_dir / f"{credential_ref}.json"
        )
        return (
            credential_path,
            credential_path.with_name(f".{credential_path.name}.tmp"),
            stage_path,
            stage_path.with_name(f".{stage_path.name}.tmp"),
        )

    def _reserve_credential_namespace(
        self,
        credential_ref: str,
    ) -> tuple[Path, Path, Path, Path]:
        paths = self._credential_namespace_paths(credential_ref)
        reserved: list[Path] = []
        try:
            for path in paths:
                self._reserve_path(path, credential_ref)
                reserved.append(path)
        except BaseException:
            try:
                self._cleanup_private_paths(tuple(reserved))
            except BaseException:
                logger.warning(
                    "Unable to discard provisional credential reservations for %s",
                    credential_ref,
                    exc_info=True,
                )
            raise
        return paths

    def _oauth_stage_path(self, credential_ref: str) -> Path:
        _credential_ref_auth_scheme(credential_ref)
        self._ensure_private_dir(self.oauth_staging_dir)
        return self.oauth_staging_dir / f"{credential_ref}.json"

    def _oauth_credentials(self) -> list[tuple[str, dict[str, Any]]]:
        self._ensure_private_dir(self.root)
        credentials_dir = self.root / "credentials"
        self._ensure_private_dir(credentials_dir)
        result: list[tuple[str, dict[str, Any]]] = []
        for path in credentials_dir.glob("cred_*.json"):
            mode = path.lstat().st_mode
            if not stat.S_ISREG(mode) or not private_fs.is_private(path, mode):
                raise EngineStateError("credential permissions are unsafe")
            credential_ref = path.stem
            if path.suffix != ".json" or _CREDENTIAL_REF_RE.fullmatch(credential_ref) is None:
                raise EngineStateError("credential state contains an unsafe entry")
            _credential_ref_auth_scheme(credential_ref)
            payload = self._read_json(path)
            if payload and payload.get("kind") == "oauth":
                _validate_credential_auth_scheme(credential_ref, payload)
                result.append((credential_ref, payload))
        return result

    def _write_sources(self, sources: Sequence[SourceRecord]) -> None:
        self._secure_write_json(
            self.root / "sources.json",
            {
                "sources": [
                    {
                        **asdict(source),
                        "allowed_origins": list(source.allowed_origins),
                        "model_ids": list(source.model_ids),
                        "route_model_ids": list(source.route_model_ids),
                        "model_reasoning_efforts": [
                            [model_id, list(efforts)]
                            for model_id, efforts in source.model_reasoning_efforts
                        ],
                        "text_only_model_ids": list(source.text_only_model_ids),
                    }
                    for source in sources
                ]
            },
        )

    def _remove_obsolete_instances(self, active_instance: Path) -> None:
        instances_dir = active_instance.parent
        self._ensure_private_dir(instances_dir)
        for instance_dir in instances_dir.iterdir():
            if instance_dir == active_instance:
                continue
            mode = instance_dir.lstat().st_mode
            if not stat.S_ISDIR(mode):
                raise EngineStateError("engine instance directory is unsafe")
            shutil.rmtree(instance_dir)

    @staticmethod
    def _discard_invalid_state_file(path: Path, error: EngineStateError) -> None:
        invalid_path = path.with_name(f"{path.name}.invalid")
        try:
            path.replace(invalid_path)
        except FileNotFoundError:
            pass
        except OSError as exc:
            raise EngineStateError(
                f"unable to discard invalid engine state file: {path.name}"
            ) from exc
        logger.warning("Discarded invalid engine state file %s: %s", path.name, error)

    @staticmethod
    def _read_json(path: Path) -> dict[str, Any] | None:
        try:
            payload = json.loads(path.read_text(encoding="utf-8"))
        except FileNotFoundError:
            return None
        except ValueError as exc:
            raise EngineStateContentError(f"invalid engine state file: {path.name}") from exc
        except OSError as exc:
            raise EngineStateError(f"invalid engine state file: {path.name}") from exc
        if not isinstance(payload, dict):
            raise EngineStateContentError(f"invalid engine state file: {path.name}")
        return payload

    @classmethod
    def _secure_write_json(cls, path: Path, payload: dict[str, Any]) -> None:
        # The file is 0600 by ``write_atomic``; the directory is this store's own
        # concern, since it holds the engine's secrets alongside its state.
        cls._ensure_private_dir(path.parent)
        write_atomic(path, json.dumps(payload, sort_keys=True) + "\n")

    @classmethod
    def _reserve_path(cls, path: Path, credential_ref: str) -> None:
        """Create a no-secret, no-replace reservation for one exact path."""

        cls._ensure_private_dir(path.parent)
        payload = json.dumps(
            {"kind": "reservation", "credential_ref": credential_ref},
            sort_keys=True,
        ).encode("utf-8") + b"\n"
        try:
            # O_BINARY: Windows would otherwise write each LF as CRLF.
            descriptor = os.open(
                path,
                os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0),
                0o600,
            )
        except FileExistsError as exc:
            raise EngineStateError("credential reference collision") from exc
        try:
            with os.fdopen(descriptor, "wb") as handle:
                descriptor = -1
                handle.write(payload)
                handle.flush()
                os.fsync(handle.fileno())
            cls._fsync_directory(path.parent)
        finally:
            if descriptor >= 0:
                os.close(descriptor)

    @classmethod
    def _write_reserved_json(
        cls,
        path: Path,
        payload: dict[str, Any],
        *,
        temporary_path: Path,
        credential_ref: str,
    ) -> None:
        """Write complete bytes to a deterministic per-ref temp before rename."""

        cls._ensure_private_dir(path.parent)
        serialized = json.dumps(payload, sort_keys=True).encode("utf-8") + b"\n"
        reservation = {"credential_ref": credential_ref, "kind": "reservation"}
        if cls._read_json(path) != reservation or cls._read_json(temporary_path) != reservation:
            raise EngineStateError("credential reference collision")
        descriptor = -1
        try:
            descriptor = os.open(temporary_path, os.O_WRONLY | os.O_TRUNC | getattr(os, "O_BINARY", 0))
            with os.fdopen(descriptor, "wb") as handle:
                descriptor = -1
                handle.write(serialized)
                handle.flush()
                os.fsync(handle.fileno())
            os.replace(temporary_path, path)
            cls._fsync_directory(path.parent)
        finally:
            if descriptor >= 0:
                os.close(descriptor)

    @classmethod
    def _remove_private_file_if_present(cls, path: Path) -> bool:
        try:
            try:
                mode = path.lstat().st_mode
            except FileNotFoundError:
                # A prior unlink may have succeeded before its directory fsync
                # failed. Retrying an absent path must still establish the
                # directory durability boundary before cleanup can converge.
                cls._fsync_directory(path.parent)
                return False
            if not stat.S_ISREG(mode) or not private_fs.is_private(path, mode):
                raise EngineStateError("engine state path is unsafe")
            path.unlink()
            cls._fsync_directory(path.parent)
            return True
        except EngineStateError:
            raise
        except OSError as exc:
            raise EngineStateError("unable to remove engine state file") from exc

    @classmethod
    def _cleanup_private_paths(cls, paths: Sequence[Path]) -> None:
        first_error: BaseException | None = None
        for path in paths:
            try:
                cls._remove_private_file_if_present(path)
            except BaseException as exc:
                if first_error is None:
                    first_error = exc
        if first_error is not None:
            raise first_error

    @staticmethod
    def _file_revision(path: Path) -> str:
        return hashlib.sha256(
            EngineStateStore._read_private_bytes(
                path,
                "engine auth credential path is unsafe",
            )
        ).hexdigest()

    @staticmethod
    def _read_private_bytes(path: Path, message: str) -> bytes:
        try:
            mode = path.lstat().st_mode
        except FileNotFoundError as exc:
            raise EngineStateError("OAuth credential is unavailable") from exc
        if not stat.S_ISREG(mode) or not private_fs.is_private(path, mode):
            raise EngineStateError(message)
        try:
            return path.read_bytes()
        except OSError as exc:
            raise EngineStateError("OAuth credential is unavailable") from exc

    @staticmethod
    def _decode_oauth_payload(path: Path) -> dict[str, Any]:
        payload = EngineStateStore._read_json(path)
        if not isinstance(payload, dict) or not isinstance(payload.get("type"), str):
            raise EngineStateError("OAuth credential is unavailable")
        return payload

    @staticmethod
    def _publish_staged_no_replace(stage_path: Path, target: Path) -> None:
        """Atomically expose a complete staged file without replacing a target.

        ``link`` adds the fully-written staging inode to the watched directory
        as one directory-entry operation. It is intentionally followed by
        directory fsyncs and only then removes the private staging name.
        """

        try:
            os.link(stage_path, target, follow_symlinks=False)
        except FileExistsError:
            raise
        except OSError as exc:
            raise EngineStateError("unable to publish OAuth auth file") from exc
        try:
            EngineStateStore._fsync_directory(target.parent)
            stage_path.unlink()
            EngineStateStore._fsync_directory(stage_path.parent)
        except OSError as exc:
            raise EngineStateError("unable to finalize OAuth staging") from exc

    @staticmethod
    def _fsync_directory(path: Path) -> None:
        flags = getattr(os, "O_DIRECTORY", 0)
        if not flags:
            return
        descriptor = os.open(path, flags | os.O_RDONLY)
        try:
            os.fsync(descriptor)
        finally:
            os.close(descriptor)

    def _assert_oauth_auth_file_owned_locked(
        self,
        metadata: dict[str, Any],
        path: Path,
        payload: dict[str, Any] | None = None,
    ) -> dict[str, str]:
        auth_name = _validated_oauth_auth_name(str(metadata.get("auth_name") or ""))
        current = payload if payload is not None else self._decode_oauth_payload(path)
        return self._assert_oauth_payload_identity(metadata, auth_name, current)

    @staticmethod
    def _assert_oauth_payload_identity(
        metadata: dict[str, Any],
        auth_name: str,
        payload: dict[str, Any],
        *,
        auth_provider: str | None = None,
    ) -> dict[str, str]:
        expected_provider = auth_provider or _oauth_provider_for_vendor(str(metadata.get("vendor") or ""))
        actual_provider = str(payload.get("type") or "").strip().lower()
        expected_prefix = str(metadata.get("prefix") or "").strip()
        actual_prefix = str(payload.get("prefix") or "").strip().strip("/")
        if (
            actual_provider != expected_provider
            or not expected_prefix
            or actual_prefix != expected_prefix
        ):
            raise EngineStateError("OAuth auth file ownership is unavailable")
        return {
            "auth_name": auth_name,
            "provider": expected_provider,
            "prefix": expected_prefix,
        }

    def _remove_oauth_stage_if_present(self, credential_ref: str) -> None:
        self._remove_private_file_if_present(self._oauth_stage_path(credential_ref))

    @staticmethod
    def _ensure_private_dir(path: Path) -> None:
        if path.exists() and not stat.S_ISDIR(path.lstat().st_mode):
            raise EngineStateError("engine state path is unsafe")
        try:
            private_fs.ensure_private_directory(path)
        except private_fs.PrivatePathError as exc:
            raise EngineStateError("engine state path is unsafe") from exc

    @staticmethod
    def _assert_private_file(path: Path, message: str) -> None:
        try:
            mode = path.lstat().st_mode
        except FileNotFoundError:
            return
        if not stat.S_ISREG(mode) or not private_fs.is_private(path, mode):
            raise EngineStateError(message)


def _oauth_account_label(payload: dict[str, Any]) -> str | None:
    """Only provider-declared public identity fields can become UI metadata."""
    secrets = {
        value.strip()
        for key in ("access_token", "refresh_token", "id_token")
        if isinstance(value := payload.get(key), str)
    }
    for key in ("email", "username"):
        value = payload.get(key)
        if not isinstance(value, str):
            continue
        candidate = value.strip()
        if (
            not candidate
            or len(candidate) > 254
            or any(
                ord(character) < 32 or ord(character) == 127 or 0xD800 <= ord(character) <= 0xDFFF
                for character in candidate
            )
            or contains_credential_material(candidate)
            or candidate in secrets
            or (key == "email" and re.fullmatch(r"[^@\s]+@[^@\s]+", candidate) is None)
        ):
            continue
        return candidate
    return None


def _credential_ref_auth_scheme(credential_ref: str) -> str | None:
    """Decode private immutable transport identity; callers keep refs opaque."""
    if not isinstance(credential_ref, str) or _CREDENTIAL_REF_RE.fullmatch(credential_ref) is None:
        raise EngineStateError("invalid credential reference")
    if credential_ref.startswith("cred_auth_"):
        if _BEARER_CREDENTIAL_REF_RE.fullmatch(credential_ref) is None:
            raise EngineStateError("unsupported credential reference authentication scheme")
        return "bearer"
    return None


def _validate_credential_auth_scheme(
    credential_ref: str,
    payload: dict[str, Any],
    *,
    require_secret: bool = True,
) -> None:
    ref_scheme = _credential_ref_auth_scheme(credential_ref)
    kind = payload.get("kind")
    if not isinstance(kind, str) or kind not in {"api_key", "oauth"}:
        raise EngineStateError("credential is unavailable")
    scheme = payload.get("auth_scheme")
    if ref_scheme is not None and (kind != "api_key" or scheme != ref_scheme):
        raise EngineStateError("unsupported API key authentication scheme")
    if kind == "oauth":
        if scheme is not None:
            raise EngineStateError("unsupported API key authentication scheme")
        return
    try:
        # Metadata-only replacement validates transport independently of the
        # old value. The new value must pass ordinary provisioning/discovery.
        validate_api_key_auth_scheme(
            payload.get("vendor"), payload.get("protocol"), payload.get("base_url"),
            payload.get("value") if require_secret else None, scheme,
        )
        if scheme is not None and (
            payload.get("protocol") != "anthropic"
            or (require_secret and (
                not isinstance(payload.get("value"), str) or not payload["value"]
            ))
        ):
            raise ValueError
    except ValueError:
        raise EngineStateError("unsupported API key authentication scheme") from None


def _validated_oauth_auth_name(value: str) -> str:
    normalized = value.strip()
    if (
        not normalized
        or "\x00" in normalized
        or "\\" in normalized
        or Path(normalized).name != normalized
        or not normalized.lower().endswith(".json")
    ):
        raise EngineStateError("invalid OAuth auth file name")
    return normalized


def _oauth_provider_for_vendor(vendor: str) -> str:
    normalized = vendor.strip().lower()
    provider = {
        "anthropic": "claude",
        "claude": "claude",
        "openai": "codex",
        "codex": "codex",
    }.get(normalized)
    if provider is None:
        raise EngineStateError("native OAuth vendor is unsupported")
    return provider


def _safe_identifier(value: str) -> str:
    cleaned = "".join(character if character.isalnum() or character in "._-" else "_" for character in value)
    return cleaned or "unknown"


def _validated_source_id(value: str) -> str:
    if _SOURCE_ID_RE.fullmatch(value) is None:
        raise EngineStateError("invalid source id")
    return value


def _validated_base_url(value: str | None) -> str | None:
    try:
        return normalize_model_hub_base_url(value)
    except (TypeError, ValueError):
        raise EngineStateError("invalid source base URL")


# `_append_source` raises these same three strings when it reaches a Source whose
# upstream it cannot resolve. The check below is the earlier refusal of that one
# condition, so it answers with the message the renderer would have.
_MISSING_BASE_URL_ERRORS = {
    "anthropic": "Anthropic-compatible source requires a base URL",
    "openai_responses": "Responses API source requires a base URL",
    "openai_chat": "OpenAI-compatible source requires a base URL",
}


def _validate_source_target(
    vendor: str,
    protocol: str,
    base_url: str | None,
    *,
    credential_kind: str,
) -> None:
    """Reject a Source whose upstream this runtime cannot resolve.

    This asks exactly what `_append_source` asks when it renders the YAML: an
    api-key Source is reachable over its own ``base_url``, or over the official
    one the shipped catalog holds for its vendor, and over nothing else.

    It deliberately does not compare the Source's protocol against that vendor's
    catalog pin. Which protocols a vendor may be added as belongs to the create
    path's proof ladder — a catalog pin, a client declaration on `custom`, or a
    protocol-shaped response — and that decision was made when the Source was
    saved. Re-deciding it here would judge a stored Source by a pin that can
    change under it: a vendor repinned between releases would retroactively
    invalidate the Sources its own earlier pin admitted. Since `sync_sources`
    replaces the whole projection atomically, that verdict is not private to the
    Source it falls on — it would take every other Source down with it.

    An engine-held credential has no upstream to resolve at all: the auth file
    stays inside the engine, `_append_source` returns before rendering it, and
    `sync_sources` already requires ``base_url is None``. The requirement does
    not reach it.
    """

    if credential_kind != "api_key":
        return
    if protocol == "search":
        return
    if protocol == "google":
        try:
            validate_model_hub_protocol_vendor(vendor, protocol)
            google_api_base_url(base_url or official_api_key_base_url(vendor))
        except ValueError as exc:
            raise EngineStateError(str(exc)) from None
        return
    if base_url is not None:
        return
    if official_api_key_base_url(vendor) is not None:
        return
    raise EngineStateError(_MISSING_BASE_URL_ERRORS[protocol])