netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/admin/web.py

@@ -0,0 +1,2717 @@
+"""Authenticated in-process Admin Web application and lifecycle runner."""
+
+from __future__ import annotations
+
+import asyncio
+import errno
+import hashlib
+import html
+import importlib.resources
+import ipaddress
+import json
+import logging
+import socket
+import time
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass
+from http.cookies import SimpleCookie
+from pathlib import Path
+from typing import Any, TypeVar
+from urllib.parse import parse_qs, quote, urlsplit
+
+from .auth import (
+    ActionCsrfRejected,
+    AdmissionClosed,
+    AdminAuth,
+    AdminAuthError,
+    AuthCapacityExceeded,
+    ConsumedActionGrant,
+    ExpectedValue,
+    LoginRejected,
+    MalformedActionGrant,
+    SessionRejected,
+    StaleActionGrant,
+)
+from .errors import AdminWebError
+from .presentation import (
+    _binding_result,
+    _chat_open_url,
+    _jsonable,
+    _project_result,
+    _release_check_message,
+    _release_disposition_message,
+    _runtime_binding_json,
+    _runtime_side_json,
+    _schedule_plan_json,
+    _settings_json,
+    _stop_disposition_message,
+    _topic_open_url,
+)
+from .queries import (
+    _created_range_query,
+    _current_query,
+    _decode_binding_cursor,
+    _decode_project_cursor,
+    _decode_side_cursor,
+    _encode_binding_cursor,
+    _encode_project_cursor,
+    _encode_side_cursor,
+    _fingerprint,
+    _id_query,
+    _optional_bool_query,
+    _optional_one,
+    _optional_text_query,
+    _page_size,
+    _require_query_keys,
+    _scope_kinds_query,
+    _session_inventory_states,
+    _session_page_size,
+    _text_set_query,
+)
+from .transport import AdminHttpState, AdminHttpTransport, Request, Response
+from .port_config import ConfigFileSnapshot, persist_admin_port
+from ..instance import instance_digest
+from ..settings import validate_access_host
+from ..bindings import (
+    AmbiguousBinding,
+    BindingNotFound,
+    BindingQuery,
+    BindingQueryBusy,
+    BindingQueryClosed,
+    BindingQueryTimeout,
+    BindingSettingsRevisionConflict,
+    BindingTurnSettings,
+    ProjectConflict as StoredProjectConflict,
+    ScopeNotFound,
+    SideTopicNotFound,
+    SideTopicQuery,
+    SideTopicState,
+    ThreadBinding,
+)
+from ..management.blocking_io import (
+    BlockingIODrainTimeout,
+    BlockingIOExecutorClosed,
+    BlockingIOExecutorSaturated,
+    BlockingIOResultUnknown,
+    BlockingIOShutdownTimeout,
+)
+from ..management.updates import UpdateError
+from ..runtime.contracts import (
+    NativeThreadCatalogState,
+    RuntimeClosed,
+    SideCloseFailed,
+    SideSessionConflict,
+    SideSessionNotFound,
+    ThreadArchived,
+    ThreadBackgroundTerminalsActive,
+    ThreadCatalogError,
+    ThreadCatalogDeadlineExceeded,
+    ThreadCompacting,
+    ThreadDeleteUnavailable,
+    ThreadGoalActive,
+    ThreadLifecycleError,
+    ThreadLifecycleStateUnknown,
+    ThreadNotArchived,
+    ThreadNotMaterialized,
+    ThreadOccupied,
+    ThreadReleaseError,
+    ThreadReleaseStateUnknown,
+    ThreadRunningConfiguration,
+)
+from ..domain import MentionContextMode, ScopeKind
+from ..management import (
+    ActivePointerChanged,
+    BindingStatusProjection,
+    ChatLabel,
+    BindingScopeMismatch,
+    CurrentSideTarget,
+    ExactBindingTarget,
+    InstanceManagementService,
+    NativeCatalogInconsistent,
+    NativeThreadMissing,
+    ProjectDeletionResult,
+    RuntimePrecondition,
+    RuntimeStateChanged,
+    SessionInventoryItem,
+    SessionQuery,
+    SideIdentityMismatch,
+)
+from ..projects import (
+    ProjectAlreadyExists,
+    ProjectDisabled,
+    ProjectError,
+    StaleProject,
+    UnknownProject,
+)
+from ..schedules.models import AmbiguousLocalTime, ScheduleError, resolve_once_local
+from ..defaults import DefaultConfigurationError
+
+
+logger = logging.getLogger(__name__)
+
+
+_SESSION_COOKIE = "netizen_admin_session"
+_PREAUTH_COOKIE = "netizen_admin_preauth"
+_JSON_TYPE = "application/json"
+_FORM_TYPE = "application/x-www-form-urlencoded"
+_QUERY_DEADLINE_SECONDS = 5.0
+_SESSION_QUERY_DEADLINE_SECONDS = 10.0
+_MUTATION_DEADLINE_SECONDS = 15.0
+_MAX_QUERY_FIELDS = 256
+_MAX_JSON_FIELDS = 20
+_RUNTIME_SNAPSHOT_BATCH_SIZE = 50
+_AUTO_PORTS = range(8787, 8887)
+
+_SECURITY_HEADERS = (
+    (b"Cache-Control", b"no-store"),
+    (
+        b"Content-Security-Policy",
+        b"default-src 'self'; script-src 'self'; style-src 'self'; "
+        b"object-src 'none'; base-uri 'none'; frame-ancestors 'none'; "
+        b"form-action 'self'",
+    ),
+    (b"X-Content-Type-Options", b"nosniff"),
+    # Basic HTML form submissions serialize Origin as "null" under
+    # no-referrer.  same-origin keeps cross-origin referrers suppressed while
+    # preserving the exact Origin required by the login CSRF boundary.
+    (b"Referrer-Policy", b"same-origin"),
+    (b"X-Frame-Options", b"DENY"),
+)
+
+
+class AdminMutationDrainTimeout(TimeoutError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class AdminActionTarget:
+    resource: str
+    target_id: str
+    scope_key: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AdminActionPreconditions:
+    active_binding_id: ExpectedValue[str]
+    project_revision: ExpectedValue[int]
+    settings_revision: ExpectedValue[int]
+    native_thread_id: ExpectedValue[str]
+    activity_revision: ExpectedValue[int]
+    physical_turn_id: ExpectedValue[str]
+    side_app_id: ExpectedValue[str]
+    side_chat_id: ExpectedValue[str]
+    side_topic_id: ExpectedValue[str]
+    side_root_message_id: ExpectedValue[str]
+    inventory_fingerprint: ExpectedValue[str]
+    schedule_revision: ExpectedValue[int]
+    default_revision: ExpectedValue[int]
+    default_order_revision: ExpectedValue[int]
+
+
+@dataclass(frozen=True, slots=True)
+class _RequestContext:
+    request: Request
+    method: str
+    path: str
+    query: Mapping[str, list[str]]
+    authority: str
+    source_ip: str
+    session_token: str | None
+    session_log_handle: str | None
+
+
+T = TypeVar("T")
+
+
+class AdminWebApplication:
+    """HTTP application with no direct access to CodexRuntime or SQLite."""
+
+    def __init__(
+        self,
+        *,
+        auth: AdminAuth,
+        management: InstanceManagementService,
+        instance_root: Path | None = None,
+    ) -> None:
+        self._auth = auth
+        self._management = management
+        self._instance_root = instance_root
+        suffix = f"_{instance_digest(instance_root)}" if instance_root is not None else ""
+        self._session_cookie = _SESSION_COOKIE + suffix
+        self._preauth_cookie = _PREAUTH_COOKIE + suffix
+        self._ready = False
+        self._authorities: frozenset[str] = frozenset()
+        self._origins: frozenset[str] = frozenset()
+        self._mutation_tasks: set[asyncio.Task[object]] = set()
+        self._assets = _load_assets()
+        self._assets["index.html"] = self._assets["index.html"].replace(
+            b"__NETIZEN_INSTANCE_ROOT__", html.escape(_root_label(instance_root)).encode("utf-8")
+        )
+
+    @property
+    def ready(self) -> bool:
+        return self._ready
+
+    @property
+    def mutation_task_count(self) -> int:
+        return len(self._mutation_tasks)
+
+    def configure_authorities(self, authorities: Sequence[str]) -> None:
+        if self._ready:
+            raise RuntimeError("cannot change Admin authorities after admission")
+        normalized = frozenset(authority.lower() for authority in authorities)
+        if not normalized or any(not authority for authority in normalized):
+            raise ValueError("Admin authority allowlist must not be empty")
+        self._authorities = normalized
+        self._origins = frozenset(f"http://{authority}" for authority in normalized)
+
+    def open_admission(self) -> None:
+        if not self._authorities:
+            raise RuntimeError("Admin authorities are not configured")
+        if not self._auth.admission_open:
+            raise RuntimeError("Admin authentication admission is closed")
+        self._ready = True
+
+    def close_admission(self) -> None:
+        self._ready = False
+
+    def close_auth(self) -> None:
+        self._ready = False
+        self._auth.close()
+
+    async def drain(self, deadline: float) -> None:
+        while self._mutation_tasks:
+            remaining = deadline - asyncio.get_running_loop().time()
+            if remaining <= 0:
+                raise AdminMutationDrainTimeout(
+                    "Admin mutations did not drain before shutdown deadline"
+                )
+            done, _pending = await asyncio.wait(
+                tuple(self._mutation_tasks),
+                timeout=remaining,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            if not done:
+                raise AdminMutationDrainTimeout(
+                    "Admin mutations did not drain before shutdown deadline"
+                )
+
+    async def handle(self, request: Request) -> Response:
+        try:
+            context = self._context(request)
+            response = await self._dispatch(context)
+        except AdminWebError as error:
+            response = _json_error(
+                request.request_id,
+                error.status,
+                error.code,
+                error.message,
+            )
+        except BaseException as error:
+            if isinstance(error, asyncio.CancelledError):
+                raise
+            mapped = _map_error(error)
+            if mapped is None:
+                # Exception text can originate in filesystem/native adapters
+                # and may contain cwd, title, preview, or request-derived data.
+                # Keep the server-side signal useful without serializing it.
+                logger.error(
+                    "admin request failed request_id=%s error_type=%s",
+                    request.request_id,
+                    type(error).__name__,
+                )
+                mapped = AdminWebError(500, "internal_error", "服务内部错误。")
+            response = _json_error(
+                request.request_id,
+                mapped.status,
+                mapped.code,
+                mapped.message,
+            )
+        return _secure(response)
+
+    def _context(self, request: Request) -> _RequestContext:
+        authority = _single_header(request, b"host").decode("ascii").lower()
+        if authority not in self._authorities:
+            raise AdminWebError(400, "invalid_host", "请求 Host 不受信任。")
+        try:
+            target = request.target.decode("ascii")
+        except UnicodeDecodeError:
+            raise AdminWebError(400, "invalid_target", "请求 URL 无效。") from None
+        split = urlsplit(target)
+        if not split.path.startswith("/") or split.scheme or split.netloc or split.fragment:
+            raise AdminWebError(400, "invalid_target", "请求 URL 无效。")
+        try:
+            query = parse_qs(
+                split.query,
+                keep_blank_values=True,
+                strict_parsing=True,
+                max_num_fields=_MAX_QUERY_FIELDS,
+            )
+        except ValueError:
+            raise AdminWebError(400, "invalid_query", "查询参数无效。") from None
+        cookies = _cookies(request)
+        peer = request.peer
+        if not isinstance(peer, tuple) or not peer or not isinstance(peer[0], str):
+            raise AdminWebError(400, "invalid_source", "请求来源无效。")
+        return _RequestContext(
+            request=request,
+            method=request.method.decode("ascii"),
+            path=split.path,
+            query=query,
+            authority=authority,
+            source_ip=peer[0],
+            session_token=cookies.get(self._session_cookie),
+            session_log_handle=None,
+        )
+
+    async def _dispatch(self, context: _RequestContext) -> Response:
+        if context.path == "/health/ready" and context.method == "GET":
+            return Response(204 if self._ready else 503)
+        if not self._ready:
+            raise AdminWebError(503, "not_ready", "管理服务尚未就绪。")
+        if context.path == "/static/admin.css" and context.method == "GET":
+            # The login page reuses the same inert stylesheet.  Keep HTML,
+            # JavaScript, API routes, and all instance state authenticated.
+            return Response(
+                200,
+                ((b"Content-Type", b"text/css; charset=utf-8"),),
+                self._assets["admin.css"],
+            )
+        if context.path == "/login" and context.method == "GET":
+            return self._login_page(context)
+        if context.path == "/login" and context.method == "POST":
+            self._require_origin(context)
+            return self._login(context)
+
+        if context.path == "/" and context.method == "GET":
+            # The browser entry point redirects anonymous visitors to the
+            # login page.  Every other route (API, static assets other than
+            # the login stylesheet, and unknown paths) still fails closed
+            # with a JSON 401 so the anonymous content surface stays minimal.
+            session = self._authenticate_or_none(context)
+            if session is None:
+                return Response(303, ((b"Location", b"/login"),))
+        else:
+            session = self._authenticate(context)
+        context = _RequestContext(
+            request=context.request,
+            method=context.method,
+            path=context.path,
+            query=context.query,
+            authority=context.authority,
+            source_ip=context.source_ip,
+            session_token=context.session_token,
+            session_log_handle=session.log_handle,
+        )
+        if context.method == "POST":
+            self._require_origin(context)
+        return await self._dispatch_authenticated(context)
+
+    def _authenticate(self, context: _RequestContext):
+        try:
+            return self._auth.authenticate(context.session_token)
+        except (SessionRejected, AdmissionClosed):
+            raise AdminWebError(401, "not_authenticated", "请先登录。") from None
+
+    def _authenticate_or_none(self, context: _RequestContext):
+        try:
+            return self._auth.authenticate(context.session_token)
+        except (SessionRejected, AdmissionClosed):
+            return None
+
+    def _require_origin(self, context: _RequestContext) -> None:
+        try:
+            origin = _single_header(context.request, b"origin").decode("ascii")
+        except UnicodeDecodeError:
+            raise AdminWebError(403, "invalid_origin", "请求 Origin 不受信任。") from None
+        if origin not in self._origins:
+            raise AdminWebError(403, "invalid_origin", "请求 Origin 不受信任。")
+
+    def _login_page(self, context: _RequestContext) -> Response:
+        try:
+            challenge = self._auth.issue_preauth(context.source_ip)
+        except LoginRejected:
+            raise AdminWebError(401, "login_rejected", "登录暂不可用，请稍后重试。") from None
+        page = _login_html(challenge.form_nonce, self._instance_root)
+        return Response(
+            200,
+            headers=(
+                (b"Content-Type", b"text/html; charset=utf-8"),
+                (b"Set-Cookie", _cookie(self._preauth_cookie, challenge.cookie_token)),
+            ),
+            body=page,
+        )
+
+    def _login(self, context: _RequestContext) -> Response:
+        form = _parse_form(context.request)
+        cookies = _cookies(context.request)
+        try:
+            issued = self._auth.login(
+                source_ip=context.source_ip,
+                cookie_token=cookies.get(self._preauth_cookie),
+                form_nonce=_one(form, "nonce"),
+                credential=_one(form, "credential"),
+            )
+        except LoginRejected:
+            raise AdminWebError(401, "login_rejected", "登录凭据无效。") from None
+        return Response(
+            303,
+            headers=(
+                (b"Location", b"/"),
+                (b"Set-Cookie", _cookie(self._session_cookie, issued.token)),
+                (b"Set-Cookie", _expired_cookie(self._preauth_cookie)),
+            ),
+        )
+
+    async def _dispatch_authenticated(self, context: _RequestContext) -> Response:
+        route = (context.method, context.path)
+        if route == ("GET", "/"):
+            return Response(
+                200,
+                ((b"Content-Type", b"text/html; charset=utf-8"),),
+                self._assets["index.html"],
+            )
+        if route == ("GET", "/static/admin.js"):
+            return Response(
+                200,
+                ((b"Content-Type", b"text/javascript; charset=utf-8"),),
+                self._assets["admin.js"],
+            )
+        if route == ("POST", "/logout"):
+            self._auth.logout(context.session_token)
+            return Response(
+                204,
+                ((b"Set-Cookie", _expired_cookie(self._session_cookie)),),
+            )
+        if route == ("GET", "/api/v1/projects"):
+            return await self._projects(context)
+        if route == ("GET", "/api/v1/schedules"):
+            return await self._schedules(context)
+        if route == ("GET", "/api/v1/defaults"):
+            return await self._defaults(context)
+        if route == ("GET", "/api/v1/sessions"):
+            return await self._sessions(context)
+        if route == ("GET", "/api/v1/projects/options"):
+            return await self._project_options(context)
+        if route == ("GET", "/api/v1/runtime-snapshots"):
+            return await self._runtime_snapshots(context)
+        if route == ("GET", "/api/v1/side-topics"):
+            return await self._side_topics(context)
+        if route == ("GET", "/api/v1/updates"):
+            _require_query_keys(context.query, set())
+            return self._updates_response(
+                context, await self._management.update_status()
+            )
+
+        mutations: dict[str, Callable[[_RequestContext], Awaitable[Response]]] = {
+            "/api/v1/defaults/save": self._default_save,
+            "/api/v1/defaults/delete": self._default_delete,
+            "/api/v1/defaults/reorder": self._default_reorder,
+            "/api/v1/schedules/create": self._schedule_create,
+            "/api/v1/schedules/update": self._schedule_update,
+            "/api/v1/schedules/delete": self._schedule_delete,
+            "/api/v1/schedules/run-now": self._schedule_run_now,
+            "/api/v1/updates/check": self._updates_check,
+            "/api/v1/updates/install": self._updates_install,
+            "/api/v1/updates/restart": self._updates_restart,
+            "/api/v1/projects/register": self._project_register,
+            "/api/v1/projects/create-directory": self._project_create_directory,
+            "/api/v1/projects/set-enabled": self._project_set_enabled,
+            "/api/v1/projects/delete-preview": self._project_delete_preview,
+            "/api/v1/projects/delete": self._project_delete,
+            "/api/v1/sessions/create-lazy": self._session_create_lazy,
+            "/api/v1/sessions/activate": self._session_activate,
+            "/api/v1/sessions/configure": self._session_configure,
+            "/api/v1/sessions/rename": self._session_rename,
+            "/api/v1/sessions/archive": self._session_archive,
+            "/api/v1/sessions/unarchive": self._session_unarchive,
+            "/api/v1/sessions/delete-lazy": self._session_delete_lazy,
+            "/api/v1/sessions/delete-materialized": (
+                self._session_delete_materialized
+            ),
+            "/api/v1/sessions/stop": self._session_stop,
+            "/api/v1/sessions/release": self._session_release,
+            "/api/v1/side-topics/close": self._side_close,
+        }
+        handler = mutations.get(context.path) if context.method == "POST" else None
+        if handler is not None:
+            return await handler(context)
+        raise AdminWebError(404, "not_found", "管理接口不存在。")
+
+    def _updates_response(
+        self, context: _RequestContext, status: dict[str, Any]
+    ) -> Response:
+        payload = dict(status)
+        checking_error_code = payload.pop("checkingErrorCode")
+        payload["message"] = "程序更新属于 Python 环境级操作，请在对应环境运行 netizen update；管理页只重启当前实例。"
+        payload["checkingError"] = _release_check_message(checking_error_code)
+        actions: dict[str, object] = {
+            "check": None,
+            "install": None,
+            "restart": None,
+        }
+        if status.get("restartAvailable") is True:
+            actions["restart"] = self._grant(
+                context,
+                "updates.restart",
+                AdminActionTarget("instance-restart", status["current"]["installationId"]),
+                _empty_preconditions(),
+            )
+        return _json_response(
+            200,
+            {**payload, "requestId": context.request.request_id, "actions": actions},
+        )
+
+    async def _updates_check(self, context: _RequestContext) -> Response:
+        raise AdminWebError(409, "update_unsupported", "请在对应 Python 环境运行 netizen update。")
+
+    async def _updates_install(self, context: _RequestContext) -> Response:
+        raise AdminWebError(409, "update_unsupported", "请在对应 Python 环境运行 netizen update。")
+
+    async def _updates_restart(self, context: _RequestContext) -> Response:
+        _require_query_keys(context.query, set())
+        _, grant = self._redeem(
+            context, "updates.restart", expected_resource="instance-restart"
+        )
+        operation = await self._mutation(
+            context,
+            "updates.restart",
+            grant.target.target_id,
+            self._management.restart_service(installation_id=grant.target.target_id),
+        )
+        return _json_response(
+            202, {"requestId": context.request.request_id, "operation": operation}
+        )
+
+    async def _default_manage(self, request: dict[str, object]) -> dict[str, Any]:
+        try:
+            return await self._management.defaults.manage(request)
+        except DefaultConfigurationError as error:
+            status = 409 if error.code in {"revision_conflict", "order_conflict", "not_found"} else 400
+            if error.code in {"unavailable", "chat_unavailable", "chat_kind_unknown", "model_catalog_unavailable"}:
+                status = 503
+            raise AdminWebError(status, error.code, str(error)) from error
+
+    def _default_record(
+        self, context: _RequestContext, rule: dict[str, Any], chat: ChatLabel | None = None,
+    ) -> dict[str, Any]:
+        target = AdminActionTarget("default-rule", rule["id"])
+        preconditions = _empty_preconditions(default_revision=ExpectedValue.expect(rule["revision"]))
+        result = {**rule, "actions": {
+            mode: self._grant(context, f"defaults.{mode}", target, preconditions)
+            for mode in ("save", "delete")
+        }}
+        if chat is not None:
+            result["chat"] = {
+                "chatId": chat.chat_id,
+                "chatLabel": chat.display_name,
+                "chatLabelResolved": chat.resolved,
+                "chatMode": chat.chat_mode,
+                "chatType": chat.chat_type,
+                "chatOpenUrl": _chat_open_url(chat),
+            }
+        return result
+
+    async def _defaults(self, context: _RequestContext) -> Response:
+        mode = _optional_one(context.query, "mode") or "list"
+        allowed = {
+            "list": {"mode", "kind", "offset", "limit"},
+            "view": {"mode", "chat_id"},
+            "options": {"mode", "chat_id"},
+        }
+        if mode not in allowed:
+            raise AdminWebError(400, "invalid_query", "默认配置查询类型无效。")
+        _require_query_keys(context.query, allowed[mode])
+        request: dict[str, object] = {"mode": mode}
+        for key in allowed[mode] - {"mode"}:
+            value = _optional_text_query(context.query, key)
+            if value is not None:
+                if key in {"offset", "limit"}:
+                    if not value.isascii() or not value.isdigit():
+                        raise AdminWebError(400, "invalid_query", "分页参数无效。")
+                    request[key] = int(value)
+                else:
+                    request[key] = value
+        if mode == "list":
+            request.setdefault("kind", "chat")
+        result = await self._default_manage(request)
+        if mode == "list":
+            kind = request.get("kind", "chat")
+            chats = await self._management.resolve_chat_labels(
+                (rule["chat_id"] for rule in result["items"]),
+                deadline=asyncio.get_running_loop().time() + _QUERY_DEADLINE_SECONDS,
+            ) if kind == "chat" else {}
+            result = {**result, "items": [
+                self._default_record(context, rule, chats.get(rule["chat_id"])) for rule in result["items"]
+            ],
+                "actions": {"create": self._grant(
+                    context, "defaults.save", AdminActionTarget("default-registry", str(kind)), _empty_preconditions(),
+                )}}
+            if kind == "group_name":
+                result["actions"]["reorder"] = self._grant(
+                    context, "defaults.reorder", AdminActionTarget("default-registry", "group_name"),
+                    _empty_preconditions(default_order_revision=ExpectedValue.expect(result["order_revision"])),
+                )
+        elif mode == "view":
+            if result["exact"] is not None:
+                result = {**result, "exact": self._default_record(context, result["exact"])}
+            result = {**result, "actions": {"create": self._grant(
+                context, "defaults.save", AdminActionTarget("default-registry", "chat"), _empty_preconditions(),
+            )}}
+        return _json_response(200, {**result, "requestId": context.request.request_id})
+
+    async def _default_save(self, context: _RequestContext) -> Response:
+        _require_query_keys(context.query, set())
+        payload = _parse_json(context.request)
+        _require_body_keys(payload, _ACTION_KEYS | {"definition"})
+        target = _action_target(payload)
+        if target.resource not in {"default-registry", "default-rule"}:
+            raise AdminWebError(400, "invalid_target", "默认配置目标无效。")
+        grant = self._redeem_parsed(context, payload, "defaults.save", target, expected_resource=target.resource)
+        definition = payload.get("definition")
+        if not isinstance(definition, dict) or set(definition) - {
+            "kind", "chat_id", "keyword", "project", "session_settings",
+        }:
+            raise AdminWebError(400, "invalid_input", "默认配置字段无效。")
+        request: dict[str, object] = {**definition, "mode": "save", "expected_revision": None}
+        if target.resource == "default-rule":
+            request.update(id=grant.target.target_id, expected_revision=_expected_value(
+                _grant_preconditions(grant).default_revision, "Default revision",
+            ))
+        elif definition.get("kind") != grant.target.target_id:
+            raise AdminWebError(400, "invalid_target", "默认配置类型与操作凭据不一致。")
+        result = await self._mutation(context, "defaults.save", grant.target.target_id, self._default_manage(request))
+        return _json_response(200, {**result, "requestId": context.request.request_id})
+
+    async def _default_delete(self, context: _RequestContext) -> Response:
+        _require_query_keys(context.query, set())
+        _, grant = self._redeem(context, "defaults.delete", expected_resource="default-rule")
+        request: dict[str, object] = {"mode": "delete", "id": grant.target.target_id,
+            "expected_revision": _expected_value(_grant_preconditions(grant).default_revision, "Default revision")}
+        result = await self._mutation(context, "defaults.delete", grant.target.target_id, self._default_manage(request))
+        return _json_response(200, {**result, "requestId": context.request.request_id})
+
+    async def _default_reorder(self, context: _RequestContext) -> Response:
+        _require_query_keys(context.query, set())
+        payload, grant = self._redeem(context, "defaults.reorder", expected_resource="default-registry", allowed_extra={"rule_ids"})
+        request: dict[str, object] = {"mode": "reorder", "rule_ids": payload.get("rule_ids"),
+            "order_revision": _expected_value(_grant_preconditions(grant).default_order_revision, "Default order revision")}
+        result = await self._mutation(context, "defaults.reorder", grant.target.target_id, self._default_manage(request))
+        return _json_response(200, {**result, "requestId": context.request.request_id})
+
+    async def _schedules(self, context: _RequestContext) -> Response:
+        mode = _optional_one(context.query, "mode") or "list"
+        allowed = {
+            "list": {"mode", "chat_id", "project", "enabled", "ended", "cursor"},
+            "view": {"mode", "plan_id"},
+            "runs": {"mode", "plan_id", "cursor"},
+            "preview": {"mode", "schedule", "plan_id", "chat_id", "session_settings", "target_kind", "target_binding_id", "local_at", "utc_offset", "local_end_at", "end_utc_offset"},
+            "options": {"mode", "chat_id", "binding_query"},
+        }
+        if mode not in allowed:
+            raise AdminWebError(400, "invalid_query", "定时任务查询类型无效。")
+        _require_query_keys(context.query, allowed[mode])
+        request: dict[str, object] = {"mode": mode}
+        for key in allowed[mode] - {"mode", "enabled", "ended", "schedule", "session_settings"}:
+            value = _optional_text_query(context.query, key)
+            if value is not None:
+                request[key] = value
+        if mode == "list":
+            request["all"] = True
+            for key in ("enabled", "ended"):
+                value = _optional_bool_query(context.query, key)
+                if value is not None:
+                    request[key] = value
+        if mode == "preview":
+            raw = _optional_text_query(context.query, "schedule", maximum=2048)
+            try:
+                schedule = json.loads(raw or "null")
+            except ValueError:
+                raise AdminWebError(400, "invalid_query", "时间规则无效。") from None
+            if not isinstance(schedule, dict):
+                raise AdminWebError(400, "invalid_query", "时间规则无效。")
+            preview_request = {key: value for key, value in request.items() if key != "mode"}
+            local_at = preview_request.pop("local_at", None)
+            utc_offset = preview_request.pop("utc_offset", None)
+            local_end_at = preview_request.pop("local_end_at", None)
+            end_utc_offset = preview_request.pop("end_utc_offset", None)
+            local_fields = (("at", local_at, utc_offset), ("end_at", local_end_at, end_utc_offset))
+            previous = None
+            if any(local is not None or offset is not None for _, local, offset in local_fields) and "plan_id" in preview_request:
+                current = await self._management.schedules.manage(
+                    {"mode": "view", "plan_id": preview_request["plan_id"]}, source="admin",
+                )
+                _require_schedule_success(current)
+                previous = current["plan"]["schedule"]
+            for field, local, offset in local_fields:
+                if local is None and offset is None:
+                    continue
+                supported = schedule.get("kind") == "once" if field == "at" else schedule.get("kind") in {"daily", "weekly", "interval"}
+                if not supported or local is None or field in schedule:
+                    raise AdminWebError(400, "invalid_input", "当地执行时间仅用于一次性规则，截止时间仅用于重复规则，且不能与带偏移时间同时指定。")
+                original_at = previous.get(field) if previous and previous["timezone"] == schedule.get("timezone") else None
+                try:
+                    schedule[field] = resolve_once_local(
+                        local, schedule.get("timezone"), original_at=original_at, utc_offset=offset,
+                    )
+                except AmbiguousLocalTime as error:
+                    return _json_response(400, {"requestId": context.request.request_id,
+                        "code": "ambiguous_end_time" if field == "end_at" else error.code,
+                        "message": str(error), "choices": error.choices})
+                except ScheduleError as error:
+                    raise AdminWebError(400, error.code, str(error)) from error
+            preview_request["schedule"] = schedule
+            settings_raw = _optional_text_query(context.query, "session_settings", maximum=4096)
+            if settings_raw is not None:
+                try:
+                    settings = json.loads(settings_raw)
+                except ValueError:
+                    raise AdminWebError(400, "invalid_query", "会话配置无效。") from None
+                if not isinstance(settings, dict):
+                    raise AdminWebError(400, "invalid_query", "会话配置无效。")
+                preview_request["session_settings"] = settings
+            result = await self._management.schedules.preview(preview_request)
+        else:
+            result = await self._management.schedules.manage(request, source="admin")
+        _require_schedule_success(result)
+        if mode == "list":
+            chats = await self._management.resolve_chat_labels(
+                (plan["chat_id"] for plan in result["plans"]),
+                deadline=asyncio.get_running_loop().time() + _QUERY_DEADLINE_SECONDS,
+            )
+            result = {
+                **result,
+                "plans": [self._schedule_plan(context, plan, chats[plan["chat_id"]]) for plan in result["plans"]],
+                "actions": {"create": self._grant(
+                    context, "schedules.create", AdminActionTarget("schedule-registry", "schedules"),
+                    _empty_preconditions(),
+                )},
+            }
+        elif mode == "view":
+            plan = result["plan"]
+            chats = await self._management.resolve_chat_labels(
+                (plan["chat_id"],), deadline=asyncio.get_running_loop().time() + _QUERY_DEADLINE_SECONDS,
+            )
+            result = {**result, "plan": self._schedule_plan(context, plan, chats[plan["chat_id"]])}
+        return _json_response(200, {**result, "requestId": context.request.request_id})
+
+    def _schedule_plan(self, context: _RequestContext, plan: dict[str, Any], chat: ChatLabel) -> dict[str, Any]:
+        target = AdminActionTarget("schedule", plan["id"])
+        preconditions = _empty_preconditions(
+            schedule_revision=ExpectedValue.expect(plan["revision"]),
+        )
+        return {**_schedule_plan_json(plan, chat), "actions": {
+            mode: self._grant(context, f"schedules.{mode}", target, preconditions)
+            if mode != "run_now" or plan.get("can_run_now") is True else None
+            for mode in ("update", "delete", "run_now")
+        }}
+
+    async def _schedule_create(self, context: _RequestContext) -> Response:
+        return await self._schedule_mutate(context, "create")
+
+    async def _schedule_update(self, context: _RequestContext) -> Response:
+        return await self._schedule_mutate(context, "update")
+
+    async def _schedule_delete(self, context: _RequestContext) -> Response:
+        return await self._schedule_mutate(context, "delete")
+
+    async def _schedule_run_now(self, context: _RequestContext) -> Response:
+        return await self._schedule_mutate(context, "run_now")
+
+    async def _schedule_mutate(self, context: _RequestContext, mode: str) -> Response:
+        _require_query_keys(context.query, set())
+        payload, grant = self._redeem(
+            context, f"schedules.{mode}",
+            expected_resource="schedule-registry" if mode == "create" else "schedule",
+            allowed_extra={"definition"} if mode in {"create", "update"} else set(),
+        )
+        definition = payload.get("definition", {})
+        if not isinstance(definition, dict) or set(definition) - {
+            "name", "instructions", "project", "chat_id", "schedule", "enabled", "session_settings", "target_kind", "target_binding_id",
+        }:
+            raise AdminWebError(400, "invalid_input", "定时任务定义字段无效。")
+        request: dict[str, object] = {
+            **definition,
+            "mode": mode,
+            # Only an opaque digest crosses into durable management deduplication;
+            # browser authentication/action credentials remain process-local.
+            "request_id": hashlib.sha256(str(payload["actionToken"]).encode()).hexdigest(),
+        }
+        if mode != "create":
+            request["plan_id"] = grant.target.target_id
+            request["expected_revision"] = _expected_value(
+                _grant_preconditions(grant).schedule_revision, "Schedule revision",
+            )
+
+        async def operate() -> dict[str, Any]:
+            result = await self._management.schedules.manage(request, source="admin")
+            _require_schedule_success(result)
+            return result
+
+        result = await self._mutation(
+            context, f"schedules.{mode}", grant.target.target_id,
+            operate(),
+        )
+        return _json_response(202 if mode == "run_now" else 200, {**result, "requestId": context.request.request_id})
+
+    async def _projects(self, context: _RequestContext) -> Response:
+        allowed = {"cursor", "pageSize"}
+        _require_query_keys(context.query, allowed)
+        page_size = _page_size(context.query)
+        fingerprint = _fingerprint("projects", {"pageSize": page_size})
+        cursor = _decode_project_cursor(_optional_one(context.query, "cursor"), fingerprint)
+        deadline = asyncio.get_running_loop().time() + _QUERY_DEADLINE_SECONDS
+        page = await self._management.query_projects(
+            cursor=cursor,
+            limit=page_size,
+            deadline=deadline,
+        )
+        registry_target = AdminActionTarget("project-registry", "new")
+        empty = _empty_preconditions()
+        actions = {
+            "register": self._grant(
+                context,
+                "projects.register",
+                registry_target,
+                empty,
+            ),
+            "createDirectory": self._grant(
+                context,
+                "projects.create-directory",
+                registry_target,
+                empty,
+            ),
+        }
+        items = []
+        for item in page.items:
+            project = item.aggregate.project
+            project_target = AdminActionTarget("project", project.alias)
+            preconditions = _empty_preconditions(
+                project_revision=ExpectedValue.expect(project.revision)
+            )
+            project_actions: dict[str, object] = {
+                "setEnabled": self._grant(
+                    context,
+                    "projects.set-enabled",
+                    project_target,
+                    preconditions,
+                ),
+                "previewDelete": self._grant(
+                    context,
+                    "projects.delete-preview",
+                    project_target,
+                    preconditions,
+                ),
+            }
+            if item.deleting:
+                project_actions = {}
+            items.append(
+                {
+                    "alias": project.alias,
+                    "cwd": project.cwd,
+                    "enabled": project.enabled,
+                    "deleting": item.deleting,
+                    "revision": project.revision,
+                    "createdAt": project.created_at,
+                    "updatedAt": project.updated_at,
+                    "bindingCount": item.aggregate.binding_count,
+                    "lazyBindingCount": item.aggregate.lazy_binding_count,
+                    "materializedBindingCount": item.aggregate.materialized_binding_count,
+                    "archivedBindingCount": item.archived_binding_count,
+                    "unconfirmedBindingCount": item.unconfirmed_binding_count,
+                    "lastActivatedAt": item.aggregate.last_activated_at,
+                    "actions": project_actions,
+                }
+            )
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "items": items,
+                "nextCursor": _encode_project_cursor(page.next_cursor, fingerprint),
+                "actions": actions,
+            },
+        )
+
+    async def _project_options(self, context: _RequestContext) -> Response:
+        _require_query_keys(context.query, {"cursor", "pageSize"})
+        page_size = _page_size(context.query)
+        fingerprint = _fingerprint("project-options", {"pageSize": page_size})
+        cursor = _decode_project_cursor(_optional_one(context.query, "cursor"), fingerprint)
+        page = await self._management.query_project_options(
+            cursor=cursor,
+            limit=page_size,
+            deadline=asyncio.get_running_loop().time() + _QUERY_DEADLINE_SECONDS,
+        )
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "items": [
+                    {"alias": item.project.alias, "enabled": item.project.enabled}
+                    for item in page.items
+                ],
+                "nextCursor": _encode_project_cursor(page.next_cursor, fingerprint),
+            },
+        )
+
+    async def _sessions(self, context: _RequestContext) -> Response:
+        allowed = {
+            "cursor",
+            "pageSize",
+            "project",
+            "scopeKind",
+            "chatId",
+            "topicId",
+            "identity",
+            "inventoryState",
+            "current",
+            "createdFrom",
+            "createdBefore",
+        }
+        _require_query_keys(context.query, allowed)
+        page_size = _session_page_size(context.query)
+        created_from, created_before = _created_range_query(context.query)
+        local = BindingQuery(
+            project_aliases=_text_set_query(context.query, "project"),
+            scope_kinds=_scope_kinds_query(context.query),
+            chat_id=_optional_text_query(context.query, "chatId"),
+            topic_id=_optional_text_query(context.query, "topicId"),
+            identity=_optional_text_query(context.query, "identity"),
+            current=_current_query(context.query),
+            created_from=created_from,
+            created_before=created_before,
+        )
+        inventory_states = _session_inventory_states(context.query)
+        filter_values = {
+            "pageSize": page_size,
+            "local": _jsonable(local),
+            "inventoryState": (
+                tuple(state.value for state in inventory_states)
+                if inventory_states is not None
+                else "all"
+            ),
+        }
+        fingerprint = _fingerprint("sessions", filter_values)
+        cursor = _decode_binding_cursor(_optional_one(context.query, "cursor"), fingerprint)
+        deadline = (
+            asyncio.get_running_loop().time() + _SESSION_QUERY_DEADLINE_SECONDS
+        )
+        page = await self._management.query_sessions(
+            query=SessionQuery(
+                local=local,
+                inventory_states=inventory_states,
+            ),
+            cursor=cursor,
+            limit=page_size,
+            deadline=deadline,
+        )
+        binding_ids = tuple(item.record.binding.id for item in page.items)
+        catalog_states = {
+            item.record.binding.id: (
+                item.native.state if item.native is not None else None
+            )
+            for item in page.items
+        }
+        snapshots_by_id = {}
+        for batch in _batches(binding_ids, _RUNTIME_SNAPSHOT_BATCH_SIZE):
+            snapshots = await self._management.binding_statuses_exact(
+                binding_ids=batch,
+                catalog_states={item: catalog_states[item] for item in batch},
+                deadline=deadline,
+            )
+            snapshots_by_id.update(
+                (snapshot.binding_id, snapshot) for snapshot in snapshots
+            )
+        items = [
+            self._session_item(context, item, snapshots_by_id[item.record.binding.id])
+            for item in page.items
+        ]
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "items": items,
+                "nextCursor": _encode_binding_cursor(page.next_cursor, fingerprint),
+                "pageSize": page_size,
+                "catalogAvailable": page.catalog_available,
+            },
+        )
+
+    def _session_item(
+        self,
+        context: _RequestContext,
+        item: SessionInventoryItem,
+        status: BindingStatusProjection,
+    ) -> dict[str, object]:
+        binding = item.record.binding
+        scope = item.record.scope
+        runtime = status.snapshot
+        target = AdminActionTarget("binding", binding.id, binding.scope_key)
+        active_expected = (
+            ExpectedValue.expect_none()
+            if scope.active_binding_id is None
+            else ExpectedValue.expect(scope.active_binding_id)
+        )
+        native_expected = (
+            ExpectedValue.expect_none()
+            if binding.native_thread_id is None
+            else ExpectedValue.expect(binding.native_thread_id)
+        )
+        physical_turn_id = runtime.turn.turn_id if runtime.turn is not None else None
+        preconditions = _empty_preconditions(
+            active_binding_id=active_expected,
+            settings_revision=ExpectedValue.expect(binding.settings_revision),
+            native_thread_id=native_expected,
+            activity_revision=ExpectedValue.expect(runtime.activity_revision),
+            physical_turn_id=(
+                ExpectedValue.expect_none()
+                if physical_turn_id is None
+                else ExpectedValue.expect(physical_turn_id)
+            ),
+        )
+        lifecycle_preconditions = _empty_preconditions()
+        delete_preconditions = _empty_preconditions(
+            native_thread_id=native_expected,
+        )
+        actions: dict[str, object] = {
+            "configure": self._grant(
+                context, "sessions.configure", target, preconditions
+            )
+        }
+        native_state = item.native.state if item.native is not None else None
+        if (
+            binding.message_context_mode is MentionContextMode.CURRENT_ONLY
+            and status.pointer_state != "current"
+            and (
+                binding.native_thread_id is None
+                or native_state is NativeThreadCatalogState.ACTIVE
+            )
+        ):
+            actions["activate"] = self._grant(
+                context, "sessions.activate", target, preconditions
+            )
+        if binding.native_thread_id is None:
+            actions["deleteLazy"] = self._grant(
+                context, "sessions.delete-lazy", target, preconditions
+            )
+        elif native_state is NativeThreadCatalogState.ACTIVE:
+            actions["rename"] = self._grant(
+                context, "sessions.rename", target, preconditions
+            )
+            actions["archive"] = self._grant(
+                context,
+                "sessions.archive",
+                target,
+                lifecycle_preconditions,
+            )
+            if status.can_release:
+                actions["release"] = self._grant(
+                    context, "sessions.release", target, preconditions
+                )
+        elif native_state is NativeThreadCatalogState.ARCHIVED:
+            actions["unarchive"] = self._grant(
+                context, "sessions.unarchive", target, preconditions
+            )
+            if binding.message_context_mode is MentionContextMode.CURRENT_ONLY:
+                actions["unarchiveCurrent"] = self._grant(
+                    context, "sessions.unarchive-current", target, preconditions
+                )
+        if (
+            self._management.native_delete_available
+            and native_state
+            in {
+                NativeThreadCatalogState.ACTIVE,
+                NativeThreadCatalogState.ARCHIVED,
+            }
+        ):
+            actions["deleteMaterialized"] = self._grant(
+                context,
+                "sessions.delete-materialized",
+                target,
+                delete_preconditions,
+            )
+        if status.can_stop:
+            actions["stop"] = self._grant(
+                context, "sessions.stop", target, preconditions
+            )
+        actions["createLazy"] = self._grant(
+            context,
+            "sessions.create-lazy",
+            AdminActionTarget("scope", binding.scope_key, binding.scope_key),
+            preconditions,
+        )
+        metadata = item.native.metadata if item.native is not None else None
+        return {
+            "bindingId": binding.id,
+            "shortId": binding.short_id,
+            "scopeKey": binding.scope_key,
+            "scopeKind": scope.kind.value,
+            "appId": scope.app_id,
+            "chatId": scope.chat_id,
+            "chatLabel": item.chat.display_name,
+            "chatLabelResolved": item.chat.resolved,
+            "chatMode": item.chat.chat_mode,
+            "chatType": item.chat.chat_type,
+            "chatOpenUrl": _chat_open_url(item.chat),
+            "topicOpenUrl": (
+                _topic_open_url(scope.chat_id, scope.topic_id)
+                if scope.kind is ScopeKind.TOPIC and scope.topic_id
+                else None
+            ),
+            "topicId": scope.topic_id,
+            "sessionType": (
+                "topic" if scope.kind is ScopeKind.TOPIC else "message"
+            ),
+            "pointerState": status.pointer_state,
+            "catalogState": item.inventory_state.value,
+            "projectAlias": binding.project_alias,
+            "nativeThreadId": binding.native_thread_id,
+            "nativeTitle": metadata.name if metadata is not None else None,
+            "nativePreview": metadata.preview if metadata is not None else None,
+            "updatedAt": metadata.updated_at if metadata is not None else None,
+            "creator": binding.creator_id,
+            "createdAt": binding.created_at,
+            "activatedAt": binding.activated_at,
+            "settingsRevision": binding.settings_revision,
+            "turnSettings": _settings_json(binding.turn_settings),
+            "messageContextMode": binding.message_context_mode.value,
+            "contextRevision": binding.context_revision,
+            "runtime": _runtime_binding_json(status),
+            "actions": actions,
+        }
+
+    async def _runtime_snapshots(self, context: _RequestContext) -> Response:
+        _require_query_keys(
+            context.query,
+            {"bindingIds", "sideIds", "resolvePrimary"},
+        )
+        binding_ids = _id_query(context.query, "bindingIds")
+        side_ids = _id_query(context.query, "sideIds")
+        if len(binding_ids) + len(side_ids) > _RUNTIME_SNAPSHOT_BATCH_SIZE:
+            raise ValueError("runtime snapshot request accepts at most 50 IDs")
+        resolve_primary = (
+            _optional_bool_query(context.query, "resolvePrimary") or False
+        )
+        if resolve_primary:
+            bindings = await self._management.binding_statuses_exact(
+                binding_ids=binding_ids,
+                deadline=(
+                    asyncio.get_running_loop().time() + _QUERY_DEADLINE_SECONDS
+                ),
+            )
+            side_snapshots = self._management.runtime_snapshots(side_ids=side_ids)
+        else:
+            snapshots = self._management.runtime_snapshots(
+                binding_ids=binding_ids,
+                side_ids=side_ids,
+            )
+            bindings = snapshots.bindings
+            side_snapshots = snapshots
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "bindings": [
+                    _runtime_binding_json(snapshot) for snapshot in bindings
+                ],
+                "sides": [
+                    _runtime_side_json(snapshot) for snapshot in side_snapshots.sides
+                ],
+                "missingSideIds": list(side_snapshots.missing_side_ids),
+            },
+        )
+
+    async def _side_topics(self, context: _RequestContext) -> Response:
+        allowed = {
+            "cursor",
+            "pageSize",
+            "project",
+            "parentBindingId",
+            "appId",
+            "chatId",
+            "topicId",
+            "rootMessageId",
+            "state",
+            "createdFrom",
+            "createdBefore",
+        }
+        _require_query_keys(context.query, allowed)
+        page_size = _page_size(context.query)
+        state_value = _optional_text_query(context.query, "state")
+        try:
+            state = SideTopicState(state_value) if state_value is not None else None
+        except ValueError:
+            raise AdminWebError(400, "invalid_state", "Side 状态筛选无效。") from None
+        created_from, created_before = _created_range_query(context.query)
+        query = SideTopicQuery(
+            project_alias=_optional_text_query(context.query, "project"),
+            parent_binding_id=_optional_text_query(context.query, "parentBindingId"),
+            app_id=_optional_text_query(context.query, "appId"),
+            chat_id=_optional_text_query(context.query, "chatId"),
+            topic_id=_optional_text_query(context.query, "topicId"),
+            root_message_id=_optional_text_query(context.query, "rootMessageId"),
+            state=state,
+            created_from=created_from,
+            created_before=created_before,
+        )
+        fingerprint = _fingerprint(
+            "side-topics",
+            {"pageSize": page_size, "query": _jsonable(query)},
+        )
+        cursor = _decode_side_cursor(_optional_one(context.query, "cursor"), fingerprint)
+        page = await self._management.query_side_topics(
+            query=query,
+            cursor=cursor,
+            limit=page_size,
+            deadline=asyncio.get_running_loop().time() + _QUERY_DEADLINE_SECONDS,
+        )
+        items = []
+        for item in page.items:
+            side = item.record.side_topic
+            actions: dict[str, object] = {}
+            if side.state is SideTopicState.OPEN and item.runtime is not None:
+                target = AdminActionTarget("side", side.id, None)
+                preconditions = _empty_preconditions(
+                    side_app_id=ExpectedValue.expect(side.app_id),
+                    side_chat_id=ExpectedValue.expect(side.chat_id),
+                    side_topic_id=(
+                        ExpectedValue.expect_none()
+                        if side.topic_id is None
+                        else ExpectedValue.expect(side.topic_id)
+                    ),
+                    side_root_message_id=(
+                        ExpectedValue.expect_none()
+                        if side.root_message_id is None
+                        else ExpectedValue.expect(side.root_message_id)
+                    ),
+                )
+                actions["close"] = self._grant(
+                    context,
+                    "side-topics.close",
+                    target,
+                    preconditions,
+                )
+            items.append(
+                {
+                    "sideId": side.id,
+                    "parentBindingId": side.parent_binding_id,
+                    "projectAlias": item.record.project_alias,
+                    "appId": side.app_id,
+                    "chatId": side.chat_id,
+                    "chatLabel": item.chat.display_name,
+                    "chatLabelResolved": item.chat.resolved,
+                    "chatMode": item.chat.chat_mode,
+                    "chatType": item.chat.chat_type,
+                    "topicId": side.topic_id,
+                    "rootMessageId": side.root_message_id,
+                    "sourceMessageId": side.source_message_id,
+                    "state": side.state.value,
+                    "createdAt": side.created_at,
+                    "updatedAt": side.updated_at,
+                    "runtime": (
+                        _runtime_side_json(item.runtime)
+                        if item.runtime is not None
+                        else None
+                    ),
+                    "actions": actions,
+                }
+            )
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "items": items,
+                "nextCursor": _encode_side_cursor(page.next_cursor, fingerprint),
+            },
+        )
+
+    async def _project_register(self, context: _RequestContext) -> Response:
+        payload, _grant = self._redeem(
+            context,
+            "projects.register",
+            expected_resource="project-registry",
+            allowed_extra={"alias", "path"},
+        )
+        alias = _required_text(payload, "alias", maximum=64)
+        path = _required_text(payload, "path", maximum=4_096)
+        project = await self._mutation(
+            context,
+            "projects.register",
+            "project-registry",
+            self._management.register_project(
+                alias=alias,
+                path=path,
+                create_directory=False,
+                deadline=asyncio.get_running_loop().time()
+                + _MUTATION_DEADLINE_SECONDS,
+            ),
+        )
+        return _json_response(
+            200,
+            _project_result(context.request.request_id, project),
+        )
+
+    async def _project_create_directory(
+        self,
+        context: _RequestContext,
+    ) -> Response:
+        payload, _grant = self._redeem(
+            context,
+            "projects.create-directory",
+            expected_resource="project-registry",
+            allowed_extra={"alias", "path"},
+        )
+        alias = _required_text(payload, "alias", maximum=64)
+        path = _optional_text_body(payload, "path", maximum=4_096)
+        project = await self._mutation(
+            context,
+            "projects.create-directory",
+            "project-registry",
+            self._management.register_project(
+                alias=alias,
+                path=path,
+                create_directory=True,
+                deadline=asyncio.get_running_loop().time()
+                + _MUTATION_DEADLINE_SECONDS,
+            ),
+        )
+        return _json_response(
+            200,
+            _project_result(context.request.request_id, project),
+        )
+
+    async def _project_set_enabled(self, context: _RequestContext) -> Response:
+        payload, grant = self._redeem(
+            context,
+            "projects.set-enabled",
+            expected_resource="project",
+            allowed_extra={"enabled"},
+        )
+        enabled = _required_bool(payload, "enabled")
+        preconditions = _grant_preconditions(grant)
+        revision = _expected_value(preconditions.project_revision, "Project revision")
+        project = await self._mutation(
+            context,
+            "projects.set-enabled",
+            grant.target.target_id,
+            self._management.set_project_enabled(
+                alias=grant.target.target_id,
+                enabled=enabled,
+                expected_revision=revision,
+            ),
+        )
+        return _json_response(
+            200,
+            _project_result(context.request.request_id, project),
+        )
+
+    async def _project_delete_preview(self, context: _RequestContext) -> Response:
+        _require_query_keys(context.query, set())
+        _, grant = self._redeem(
+            context, "projects.delete-preview", expected_resource="project",
+        )
+        snapshot = await self._management.preview_project_delete(
+            alias=grant.target.target_id,
+            expected_revision=_expected_value(
+                _grant_preconditions(grant).project_revision, "Project revision",
+            ),
+            deadline=asyncio.get_running_loop().time() + _QUERY_DEADLINE_SECONDS,
+        )
+        project = snapshot.project
+        lazy_count = sum(item.binding.native_thread_id is None for item in snapshot.bindings)
+        return _json_response(200, {
+            "requestId": context.request.request_id,
+            "project": {"alias": project.alias, "cwd": project.cwd, "revision": project.revision},
+            "sessionCount": len(snapshot.bindings),
+            "lazySessionCount": lazy_count,
+            "materializedSessionCount": len(snapshot.bindings) - lazy_count,
+            "sideCount": len(snapshot.sides),
+            "scheduledPlanCount": len(snapshot.scheduled_plans),
+            "scheduledRunCount": len(snapshot.scheduled_runs),
+            "actions": {"delete": self._grant(
+                context, "projects.delete", AdminActionTarget("project", project.alias),
+                _empty_preconditions(
+                    project_revision=ExpectedValue.expect(project.revision),
+                    inventory_fingerprint=ExpectedValue.expect(snapshot.fingerprint),
+                ),
+            )},
+        })
+
+    async def _project_delete(self, context: _RequestContext) -> Response:
+        _require_query_keys(context.query, set())
+        _, grant = self._redeem(context, "projects.delete", expected_resource="project")
+        preconditions = _grant_preconditions(grant)
+        result = await self._mutation(
+            context, "projects.delete", grant.target.target_id,
+            self._management.delete_project(
+                alias=grant.target.target_id,
+                expected_revision=_expected_value(preconditions.project_revision, "Project revision"),
+                expected_inventory_fingerprint=_expected_value(
+                    preconditions.inventory_fingerprint, "Project inventory",
+                ),
+            ),
+        )
+        messages = {
+            "outcome_unknown": "有会话的删除结果未确认，请先对账；本次操作不会自动重试。",
+            "deadline_exceeded": "删除等待已到期，正在处理的目标可能尚未确认；请先查看剩余会话状态。",
+            "inventory_changed": "关联会话在执行期间发生变化，请查看剩余项后重新确认。",
+            "side_close_failed": "关联 Side 的关闭未完成，请先处理该 Side。",
+            "side_creation_in_progress": "关联 Side 正在创建飞书话题，请等待创建完成后刷新并重新确认。",
+            "schedule_creation_in_progress": "关联定时任务仍在创建话题或执行交接结果未决，请查看剩余记录后重新确认。",
+            "delete_failed": "删除未全部完成，请查看剩余会话状态后重新确认。",
+        }
+        if result.deleted:
+            message = f"已删除 Project {result.project_alias} 及关联 Sessions，代码目录已保留。"
+        else:
+            message = (
+                f"Project {result.project_alias} 已保留并停用。"
+                f"已清理 {result.deleted_session_count} 个 Sessions，"
+                f"剩余 {len(result.remaining_sessions)} 个 Sessions、{result.remaining_side_count} 个 Side。"
+                + messages[result.code]
+            )
+        if result.deleted_plan_count:
+            message += f"已删除 {result.deleted_plan_count} 个定时计划；后续会话清理失败也不会恢复计划。"
+        return _json_response(200, {
+            "requestId": context.request.request_id,
+            "deleted": result.deleted,
+            "projectAlias": result.project_alias,
+            "deletedSessionCount": result.deleted_session_count,
+            "remainingSessionCount": len(result.remaining_sessions),
+            "remainingSessions": [
+                {"bindingId": binding.id, "shortId": binding.short_id, "scopeKey": binding.scope_key}
+                for binding in result.remaining_sessions
+            ],
+            "remainingSideCount": result.remaining_side_count,
+            "deletedPlanCount": result.deleted_plan_count,
+            "remainingScheduledRunCount": result.remaining_scheduled_run_count,
+            "failedBindingId": result.failed_binding_id,
+            "failedSideId": result.failed_side_id,
+            "code": result.code,
+            "message": message,
+        })
+
+    async def _session_create_lazy(self, context: _RequestContext) -> Response:
+        payload, grant = self._redeem(
+            context,
+            "sessions.create-lazy",
+            expected_resource="scope",
+            allowed_extra={
+                "projectAlias",
+                "projectRevision",
+                "activate",
+                "turnSettings",
+            },
+        )
+        project_alias = _required_text(payload, "projectAlias", maximum=64)
+        project_revision = _required_int(payload, "projectRevision", minimum=1)
+        activate = _required_bool(payload, "activate")
+        settings = await self._validated_settings(payload.get("turnSettings"))
+        preconditions = _grant_preconditions(grant)
+        created = await self._mutation(
+            context,
+            "sessions.create-lazy",
+            grant.target.target_id,
+            self._management.create_exact_lazy_binding(
+                scope_key=grant.target.target_id,
+                project_alias=project_alias,
+                expected_project_revision=project_revision,
+                expected_active_binding_id=_expected_optional(
+                    preconditions.active_binding_id,
+                    "active Binding",
+                ),
+                activate=activate,
+                turn_settings=settings,
+                deadline=asyncio.get_running_loop().time()
+                + _MUTATION_DEADLINE_SECONDS,
+            ),
+        )
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "bindingId": created.binding.id,
+                "scopeKey": created.binding.scope_key,
+                "projectAlias": created.project.alias,
+                "current": created.binding.active,
+            },
+        )
+
+    async def _session_activate(self, context: _RequestContext) -> Response:
+        _payload, grant = self._redeem(
+            context,
+            "sessions.activate",
+            expected_resource="binding",
+        )
+        binding = await self._mutation(
+            context,
+            "sessions.activate",
+            grant.target.target_id,
+            self._management.activate_exact_binding(
+                target=_binding_target(grant)
+            ),
+        )
+        return _json_response(
+            200,
+            _binding_result(context.request.request_id, binding),
+        )
+
+    async def _session_configure(self, context: _RequestContext) -> Response:
+        payload, grant = self._redeem(
+            context,
+            "sessions.configure",
+            expected_resource="binding",
+            allowed_extra={"turnSettings"},
+        )
+        settings = await self._validated_settings(payload.get("turnSettings"))
+        preconditions = _grant_preconditions(grant)
+        revision = _expected_value(
+            preconditions.settings_revision,
+            "Binding settings revision",
+        )
+        binding = await self._mutation(
+            context,
+            "sessions.configure",
+            grant.target.target_id,
+            self._management.configure_exact_binding(
+                target=_binding_target(grant),
+                expected_settings_revision=revision,
+                settings=settings,
+            ),
+        )
+        return _json_response(
+            200,
+            _binding_result(context.request.request_id, binding),
+        )
+
+    async def _session_rename(self, context: _RequestContext) -> Response:
+        payload, grant = self._redeem(
+            context,
+            "sessions.rename",
+            expected_resource="binding",
+            allowed_extra={"name"},
+        )
+        name = _required_text(payload, "name", maximum=120)
+        renamed = await self._mutation(
+            context,
+            "sessions.rename",
+            grant.target.target_id,
+            self._management.rename_exact_binding(
+                target=_binding_target(grant),
+                name=name,
+            ),
+        )
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "bindingId": renamed.binding.id,
+                "name": renamed.name,
+            },
+        )
+
+    async def _session_archive(self, context: _RequestContext) -> Response:
+        _payload, grant = self._redeem(
+            context,
+            "sessions.archive",
+            expected_resource="binding",
+        )
+        binding = await self._mutation(
+            context,
+            "sessions.archive",
+            grant.target.target_id,
+            self._management.archive_exact_binding(
+                target=_lifecycle_binding_target(grant),
+            ),
+        )
+        return _json_response(
+            200,
+            _binding_result(context.request.request_id, binding),
+        )
+
+    async def _session_unarchive(self, context: _RequestContext) -> Response:
+        payload = _parse_json(context.request)
+        target = _action_target(payload)
+        action_kind = _required_text(payload, "actionKind", maximum=128)
+        if action_kind not in {"sessions.unarchive", "sessions.unarchive-current"}:
+            raise AdminWebError(400, "invalid_action", "恢复动作无效。")
+        _require_body_keys(
+            payload,
+            _ACTION_KEYS | {"actionKind"},
+        )
+        grant = self._redeem_parsed(
+            context,
+            payload,
+            action_kind,
+            target,
+            expected_resource="binding",
+        )
+        operation = (
+            self._management.restore_exact_binding_as_current(
+                target=_binding_target(grant)
+            )
+            if action_kind == "sessions.unarchive-current"
+            else self._management.restore_exact_binding(target=_binding_target(grant))
+        )
+        binding = await self._mutation(
+            context,
+            action_kind,
+            grant.target.target_id,
+            operation,
+        )
+        return _json_response(
+            200,
+            _binding_result(context.request.request_id, binding),
+        )
+
+    async def _session_delete_lazy(self, context: _RequestContext) -> Response:
+        _payload, grant = self._redeem(
+            context,
+            "sessions.delete-lazy",
+            expected_resource="binding",
+        )
+        binding = await self._mutation(
+            context,
+            "sessions.delete-lazy",
+            grant.target.target_id,
+            self._management.delete_exact_lazy_binding(
+                target=_binding_target(grant)
+            ),
+        )
+        return _json_response(
+            200,
+            _binding_result(context.request.request_id, binding),
+        )
+
+    async def _session_delete_materialized(
+        self,
+        context: _RequestContext,
+    ) -> Response:
+        _payload, grant = self._redeem(
+            context,
+            "sessions.delete-materialized",
+            expected_resource="binding",
+        )
+        target = _lifecycle_binding_target(grant)
+        expected_native_thread_id = _expected_value(
+            _grant_preconditions(grant).native_thread_id,
+            "native Thread",
+        )
+        binding = await self._mutation(
+            context,
+            "sessions.delete-materialized",
+            target.binding_id,
+            self._management.delete_exact_binding(
+                target=target,
+                expected_native_thread_id=expected_native_thread_id,
+            ),
+        )
+        return _json_response(
+            200,
+            _binding_result(context.request.request_id, binding),
+        )
+
+    async def _session_stop(self, context: _RequestContext) -> Response:
+        _payload, grant = self._redeem(
+            context,
+            "sessions.stop",
+            expected_resource="binding",
+        )
+        stopped = await self._mutation(
+            context,
+            "sessions.stop",
+            grant.target.target_id,
+            self._management.stop_exact_binding(
+                target=_binding_target(grant),
+                runtime_precondition=_runtime_precondition(grant),
+            ),
+        )
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "bindingId": stopped.binding.id,
+                "disposition": stopped.disposition.value,
+                "message": _stop_disposition_message(stopped.disposition),
+            },
+        )
+
+    async def _session_release(self, context: _RequestContext) -> Response:
+        _payload, grant = self._redeem(
+            context,
+            "sessions.release",
+            expected_resource="binding",
+        )
+        released = await self._mutation(
+            context,
+            "sessions.release",
+            grant.target.target_id,
+            self._management.release_exact_binding(
+                target=_binding_target(grant),
+                runtime_precondition=_runtime_precondition(grant),
+            ),
+        )
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "bindingId": released.binding.id,
+                "disposition": released.disposition.value,
+                "message": _release_disposition_message(released.disposition),
+            },
+        )
+
+    async def _side_close(self, context: _RequestContext) -> Response:
+        _payload, grant = self._redeem(
+            context,
+            "side-topics.close",
+            expected_resource="side",
+        )
+        preconditions = _grant_preconditions(grant)
+        closed = await self._mutation(
+            context,
+            "side-topics.close",
+            grant.target.target_id,
+            self._management.close_side(
+                target=CurrentSideTarget(
+                    side_id=grant.target.target_id,
+                    app_id=_expected_value(preconditions.side_app_id, "Side app"),
+                    chat_id=_expected_value(preconditions.side_chat_id, "Side chat"),
+                    topic_id=_expected_optional(
+                        preconditions.side_topic_id,
+                        "Side topic",
+                    ),
+                    root_message_id=_expected_optional(
+                        preconditions.side_root_message_id,
+                        "Side root message",
+                    ),
+                )
+            ),
+        )
+        return _json_response(
+            200,
+            {
+                "requestId": context.request.request_id,
+                "sideId": closed.record.id,
+                "state": closed.record.state.value,
+                "alreadyTerminal": closed.outcome is None,
+                "missingRuntimeSession": closed.missing_runtime_session,
+            },
+        )
+
+    async def _validated_settings(self, value: object) -> BindingTurnSettings | None:
+        if value is None:
+            return None
+        if not isinstance(value, dict):
+            raise AdminWebError(400, "invalid_settings", "会话配置必须是对象或 null。")
+        _require_body_keys(value, {"modelId", "effortId", "serviceTierId"})
+        return await self._management.resolve_turn_settings(
+            model_id=_required_text(value, "modelId", maximum=256),
+            effort_id=_required_text(value, "effortId", maximum=128),
+            service_tier_id=_required_text(value, "serviceTierId", maximum=128),
+        )
+
+    def _grant(
+        self,
+        context: _RequestContext,
+        action_kind: str,
+        target: AdminActionTarget,
+        preconditions: AdminActionPreconditions,
+    ) -> dict[str, object]:
+        try:
+            issued = self._auth.issue_action(
+                context.session_token,
+                action_kind=action_kind,
+                target=target,
+                preconditions=preconditions,
+            )
+        except AuthCapacityExceeded:
+            raise AdminWebError(
+                503,
+                "action_capacity",
+                "操作凭据容量已满，请稍后刷新页面。",
+            ) from None
+        return {
+            "actionKind": action_kind,
+            "csrfToken": issued.csrf_token,
+            "actionToken": issued.action_token,
+            "target": _action_target_json(target),
+        }
+
+    def _redeem(
+        self,
+        context: _RequestContext,
+        action_kind: str,
+        *,
+        expected_resource: str,
+        allowed_extra: set[str] | None = None,
+    ):
+        payload = _parse_json(context.request)
+        _require_body_keys(payload, _ACTION_KEYS | (allowed_extra or set()))
+        target = _action_target(payload)
+        grant = self._redeem_parsed(
+            context,
+            payload,
+            action_kind,
+            target,
+            expected_resource=expected_resource,
+        )
+        return payload, grant
+
+    def _redeem_parsed(
+        self,
+        context: _RequestContext,
+        payload: Mapping[str, object],
+        action_kind: str,
+        target: AdminActionTarget,
+        *,
+        expected_resource: str,
+    ):
+        if target.resource != expected_resource:
+            raise AdminWebError(400, "invalid_target", "操作目标类型无效。")
+        try:
+            return self._auth.redeem_action(
+                context.session_token,
+                csrf_token=payload.get("csrfToken"),
+                action_token=payload.get("actionToken"),
+                action_kind=action_kind,
+                target=target,
+            )
+        except ActionCsrfRejected:
+            raise AdminWebError(403, "csrf_rejected", "操作校验失败。") from None
+        except MalformedActionGrant:
+            raise AdminWebError(400, "invalid_action", "操作凭据无效。") from None
+        except (StaleActionGrant, ConsumedActionGrant):
+            raise AdminWebError(
+                409,
+                "stale_or_consumed",
+                "操作已过期或已执行，请刷新页面后重试。",
+            ) from None
+        except AdminAuthError:
+            raise AdminWebError(401, "not_authenticated", "请重新登录。") from None
+
+    async def _mutation(
+        self,
+        context: _RequestContext,
+        action_kind: str,
+        target_id: str,
+        operation: Awaitable[T],
+    ) -> T:
+        async def execute() -> T:
+            started = time.monotonic()
+            terminal = "success"
+            error_name: str | None = None
+            try:
+                result = await operation
+                if isinstance(result, ProjectDeletionResult) and not result.deleted:
+                    terminal = "incomplete"
+                    error_name = result.code
+                return result
+            except BaseException as error:
+                terminal = "cancelled" if isinstance(error, asyncio.CancelledError) else "error"
+                error_name = type(error).__name__
+                raise
+            finally:
+                event = {
+                    "event": "admin_mutation",
+                    "requestId": context.request.request_id,
+                    "session": context.session_log_handle,
+                    "action": action_kind,
+                    "targetId": target_id,
+                    "terminal": terminal,
+                    "elapsedMs": round((time.monotonic() - started) * 1000),
+                    "errorType": error_name,
+                }
+                logger.info(json.dumps(event, separators=(",", ":"), sort_keys=True))
+
+        task: asyncio.Task[T] = asyncio.create_task(
+            execute(),
+            name=f"netizen-admin:{action_kind}",
+        )
+        self._mutation_tasks.add(task)  # type: ignore[arg-type]
+        task.add_done_callback(self._mutation_finished)
+        try:
+            return await asyncio.shield(task)
+        except asyncio.CancelledError:
+            # The exact operation remains strongly tracked and is drained by
+            # the Admin runner; a disconnected HTTP response is not rollback.
+            raise
+
+    def _mutation_finished(self, task: asyncio.Task[object]) -> None:
+        self._mutation_tasks.discard(task)
+        if not task.cancelled():
+            task.exception()
+
+
+class AdminWebRunner:
+    """Bind, admit, and drain the Admin application on one event loop."""
+
+    def __init__(
+        self,
+        *,
+        host: str,
+        port: int | None,
+        credential_path: Path,
+        management: InstanceManagementService | None = None,
+        auth: AdminAuth | None = None,
+        instance_root: Path | None = None,
+        config_path: Path | None = None,
+        config_snapshot: ConfigFileSnapshot | None = None,
+        access_host: str | None = None,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._instance_root = instance_root
+        self._config_path = config_path
+        self._config_snapshot = config_snapshot
+        self._access_host = validate_access_host(access_host) if access_host is not None else None
+        self._urls: tuple[str, ...] = ()
+        self._loopback_only = False
+        self._bound = False
+        self._auth = auth or AdminAuth(credential_path)
+        self._application: AdminWebApplication | None = None
+        self._authorities: tuple[str, ...] | None = None
+        if management is not None:
+            self.attach_management(management)
+        self._transport = AdminHttpTransport(host, port if port is not None else 8787, self._handle)
+
+    @property
+    def application(self) -> AdminWebApplication:
+        application = self._application
+        if application is None:
+            raise RuntimeError("Admin management application is not attached")
+        return application
+
+    @property
+    def transport(self) -> AdminHttpTransport:
+        return self._transport
+
+    @property
+    def addresses(self):
+        return self._transport.addresses
+
+    @property
+    def instance_root(self) -> Path | None:
+        return self._instance_root
+
+    @property
+    def urls(self) -> tuple[str, ...]:
+        """Bound runtime addresses, never guesses from pending disk settings."""
+        return self._urls
+
+    @property
+    def loopback_only(self) -> bool:
+        return self._loopback_only
+
+    async def bind(self) -> None:
+        if self._bound:
+            raise RuntimeError("Admin Web runner can only bind once")
+        self._bound = True
+        try:
+            if self._port is None:
+                snapshot = self._config_snapshot
+                if self._config_path is None or snapshot is None or snapshot.path != self._config_path:
+                    raise ValueError("automatic Admin port allocation requires the startup configuration snapshot")
+                for port in _AUTO_PORTS:
+                    self._transport = AdminHttpTransport(self._host, port, self._handle)
+                    try:
+                        await self._transport.bind()
+                    except OSError as error:
+                        if error.errno != errno.EADDRINUSE:
+                            raise
+                    else:
+                        persist_admin_port(snapshot, port)
+                        self._port = port
+                        break
+                else:
+                    raise OSError(
+                        errno.EADDRINUSE,
+                        f"Admin ports 8787–8886 are occupied; configure adminWeb.port in {self._config_path}",
+                    )
+            else:
+                try:
+                    await self._transport.bind()
+                except OSError as error:
+                    if error.errno == errno.EADDRINUSE and self._config_path is not None:
+                        raise OSError(
+                            errno.EADDRINUSE,
+                            f"Admin port {self._port} is occupied; configure adminWeb.port in {self._config_path}",
+                        ) from error
+                    raise
+            assert self._port is not None
+            self._authorities = await asyncio.to_thread(
+                accepted_authorities,
+                self._host,
+                self._port,
+                self._transport.addresses,
+            )
+            if self._access_host is not None:
+                self._authorities = tuple(sorted({
+                    *self._authorities,
+                    *(_format_authority(self._access_host, port) for port in _bound_ports(self.addresses)),
+                }))
+            self._loopback_only = _loopback_addresses(self.addresses)
+            self._urls = admin_access_urls(
+                self._host, self.addresses, self._authorities, self._access_host,
+            )
+            if self._application is not None:
+                self._application.configure_authorities(self._authorities)
+        except BaseException:
+            try:
+                # Failure before bind has no loop-owned transport to close.
+                if self._transport.state is not AdminHttpState.NEW:
+                    await self._transport.close()
+            finally:
+                self._urls = ()
+                self._auth.close()
+            raise
+
+    def attach_management(self, management: InstanceManagementService) -> None:
+        """Attach the sole application service after the closed listener binds."""
+
+        if self._application is not None:
+            raise RuntimeError("Admin management application is already attached")
+        application = AdminWebApplication(
+            auth=self._auth, management=management, instance_root=self._instance_root,
+        )
+        if self._authorities is not None:
+            application.configure_authorities(self._authorities)
+        self._application = application
+
+    async def _handle(self, request: Request) -> Response:
+        application = self._application
+        if application is None:
+            return _secure(
+                _json_error(
+                    request.request_id,
+                    503,
+                    "not_ready",
+                    "服务尚未就绪。",
+                )
+            )
+        return await application.handle(request)
+
+    def open_admission(self) -> None:
+        self.application.open_admission()
+        self._transport.open_admission()
+
+    def close_admission(self) -> None:
+        self._transport.close_admission()
+        if self._application is not None:
+            self._application.close_admission()
+
+    async def close_listener(self) -> None:
+        self.close_admission()
+        await self._transport.close()
+        self._urls = ()
+
+    async def drain(self, deadline: float) -> None:
+        await self._transport.drain(deadline)
+        self._urls = ()
+        if self._application is not None:
+            await self._application.drain(deadline)
+
+    def close_auth(self) -> None:
+        if self._application is not None:
+            self._application.close_auth()
+        else:
+            self._auth.close()
+
+
+def accepted_authorities(
+    bind_host: str,
+    configured_port: int,
+    addresses: Sequence[object],
+) -> tuple[str, ...]:
+    """Build the exact Host allowlist from local names and bound sockets."""
+
+    ports: set[int] = set()
+    hosts: set[str] = {"localhost", "127.0.0.1", "::1"}
+    for address in addresses:
+        if isinstance(address, tuple) and len(address) >= 2:
+            if isinstance(address[0], str):
+                hosts.add(address[0].split("%", 1)[0])
+            if isinstance(address[1], int):
+                ports.add(address[1])
+    if not ports:
+        ports.add(configured_port)
+    if bind_host not in {"0.0.0.0", "::", ""}:
+        hosts.add(bind_host.split("%", 1)[0])
+    for name in (socket.gethostname(), socket.getfqdn()):
+        if name:
+            hosts.add(name.rstrip(".").lower())
+    try:
+        infos = socket.getaddrinfo(
+            socket.gethostname(),
+            None,
+            type=socket.SOCK_STREAM,
+        )
+    except OSError:
+        infos = []
+    for _family, _kind, _protocol, _canonical, sockaddr in infos:
+        if isinstance(sockaddr, tuple) and sockaddr and isinstance(sockaddr[0], str):
+            hosts.add(sockaddr[0].split("%", 1)[0])
+    authorities = {
+        _format_authority(host, port)
+        for host in hosts
+        for port in ports
+        if host
+    }
+    return tuple(sorted(authorities))
+
+
+def _format_authority(host: str, port: int) -> str:
+    normalized = host.rstrip(".").lower()
+    try:
+        address = ipaddress.ip_address(normalized)
+    except ValueError:
+        rendered = normalized
+    else:
+        rendered = f"[{address.compressed}]" if address.version == 6 else address.compressed
+    return f"{rendered}:{port}"
+
+
+def _bound_ports(addresses: Sequence[object]) -> tuple[int, ...]:
+    return tuple(sorted({
+        address[1] for address in addresses
+        if isinstance(address, tuple) and len(address) >= 2 and isinstance(address[1], int)
+    }))
+
+
+def _loopback_addresses(addresses: Sequence[object]) -> bool:
+    hosts = [address[0] for address in addresses if isinstance(address, tuple) and address]
+    return bool(hosts) and all(ipaddress.ip_address(host).is_loopback for host in hosts)
+
+
+def admin_access_urls(
+    bind_host: str,
+    addresses: Sequence[object],
+    authorities: Sequence[str],
+    access_host: str | None = None,
+) -> tuple[str, ...]:
+    """A bounded set of URLs using the actual bound port and accepted Hosts."""
+
+    ports = _bound_ports(addresses)
+    if not ports:
+        return ()
+    if access_host is not None:
+        selected = [_format_authority(access_host, port) for port in ports]
+    elif _loopback_addresses(addresses):
+        selected = [
+            _format_authority(str(address[0]), int(address[1]))
+            for address in addresses if isinstance(address, tuple)
+        ]
+    elif bind_host not in {"0.0.0.0", "::", ""}:
+        selected = [_format_authority(bind_host, port) for port in ports]
+    else:
+        family_ports = {
+            (ipaddress.ip_address(str(address[0])).version, int(address[1]))
+            for address in addresses if isinstance(address, tuple) and len(address) >= 2
+        }
+        selected = []
+        for authority in authorities:
+            parsed = urlsplit(f"http://{authority}")
+            hostname = parsed.hostname
+            if not hostname or hostname == "localhost":
+                continue
+            if parsed.port not in ports:
+                continue
+            try:
+                address = ipaddress.ip_address(hostname)
+            except ValueError:
+                # A discovered name may resolve only to an unbound address
+                # family. Advertise the discovered IPs; accessHost remains
+                # the explicit choice for a hostname.
+                continue
+            if (
+                (address.version, parsed.port) not in family_ports
+                or address.is_unspecified or address.is_loopback or address.is_link_local
+            ):
+                continue
+            selected.append(authority)
+        if not selected:
+            selected = [
+                _format_authority("127.0.0.1" if family == 4 else "::1", port)
+                for family, port in sorted(family_ports)
+            ]
+    allowed = set(authorities)
+    return tuple(f"http://{authority}/" for authority in dict.fromkeys(selected) if authority in allowed)[:4]
+
+
+def _load_assets() -> dict[str, bytes]:
+    root = importlib.resources.files("netizen_cli.admin").joinpath("static")
+    assets: dict[str, bytes] = {}
+    for name in ("index.html", "admin.css", "admin.js"):
+        assets[name] = root.joinpath(name).read_bytes()
+    return assets
+
+
+def _root_label(root: Path | None) -> str:
+    return str(root) if root is not None else "非受管开发实例"
+
+
+def _login_html(nonce: str, instance_root: Path | None = None) -> bytes:
+    escaped = html.escape(nonce, quote=True)
+    return (
+        "<!doctype html><html lang='zh-CN'><head><meta charset='utf-8'>"
+        "<meta name='viewport' content='width=device-width,initial-scale=1'>"
+        "<title>Netizen Admin 登录</title>"
+        "<link rel='stylesheet' href='/static/admin.css'></head>"
+        "<body class='login-body'><main class='login-card'>"
+        "<p class='eyebrow'>INSTANCE CONTROL PLANE</p>"
+        "<h1>Netizen Admin</h1><p>输入实例管理员密钥。</p>"
+        f"<p class='instance-root'>{html.escape(_root_label(instance_root))}</p>"
+        "<form method='post' action='/login'>"
+        f"<input type='hidden' name='nonce' value='{escaped}'>"
+        "<label for='credential'>管理员密钥</label>"
+        "<input id='credential' name='credential' type='password' "
+        "autocomplete='current-password' required autofocus>"
+        "<button type='submit'>登录</button></form></main></body></html>"
+    ).encode("utf-8")
+
+
+def _secure(response: Response) -> Response:
+    existing = {name.lower() for name, _value in response.headers}
+    headers = list(response.headers)
+    headers.extend(
+        (name, value)
+        for name, value in _SECURITY_HEADERS
+        if name.lower() not in existing
+    )
+    return Response(response.status, tuple(headers), response.body)
+
+
+def _json_response(status: int, payload: object) -> Response:
+    body = json.dumps(
+        payload,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    return Response(
+        status,
+        ((b"Content-Type", b"application/json; charset=utf-8"),),
+        body,
+    )
+
+
+def _json_error(
+    request_id: str,
+    status: int,
+    code: str,
+    message: str,
+) -> Response:
+    return _json_response(
+        status,
+        {"requestId": request_id, "code": code, "message": message},
+    )
+
+
+def _single_header(request: Request, name: bytes) -> bytes:
+    values = request.header_values(name)
+    if len(values) != 1 or not values[0]:
+        raise AdminWebError(400, "invalid_headers", "请求头无效。")
+    return values[0]
+
+
+def _optional_single_header(request: Request, name: bytes) -> bytes | None:
+    values = request.header_values(name)
+    if not values:
+        return None
+    if len(values) != 1:
+        raise AdminWebError(400, "invalid_headers", "请求头无效。")
+    return values[0]
+
+
+def _cookies(request: Request) -> dict[str, str]:
+    raw = _optional_single_header(request, b"cookie")
+    if raw is None:
+        return {}
+    try:
+        text = raw.decode("ascii")
+        parsed = SimpleCookie()
+        parsed.load(text)
+    except (UnicodeDecodeError, ValueError):
+        raise AdminWebError(400, "invalid_cookie", "Cookie 无效。") from None
+    return {name: morsel.value for name, morsel in parsed.items()}
+
+
+def _cookie(name: str, value: str) -> bytes:
+    return (
+        f"{name}={value}; Path=/; HttpOnly; SameSite=Strict"
+    ).encode("ascii")
+
+
+def _expired_cookie(name: str) -> bytes:
+    return (
+        f"{name}=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0"
+    ).encode("ascii")
+
+
+def _content_type(request: Request) -> str:
+    raw = _single_header(request, b"content-type")
+    try:
+        return raw.decode("ascii").split(";", 1)[0].strip().lower()
+    except UnicodeDecodeError:
+        raise AdminWebError(415, "invalid_content_type", "请求格式不支持。") from None
+
+
+def _parse_form(request: Request) -> Mapping[str, list[str]]:
+    if _content_type(request) != _FORM_TYPE:
+        raise AdminWebError(415, "invalid_content_type", "登录表单格式无效。")
+    try:
+        body = request.body.decode("utf-8")
+        values = parse_qs(
+            body,
+            keep_blank_values=True,
+            strict_parsing=True,
+            max_num_fields=4,
+        )
+    except (UnicodeDecodeError, ValueError):
+        raise AdminWebError(400, "invalid_form", "登录表单无效。") from None
+    if set(values) != {"nonce", "credential"}:
+        raise AdminWebError(400, "invalid_form", "登录表单无效。")
+    return values
+
+
+def _parse_json(request: Request) -> dict[str, object]:
+    if _content_type(request) != _JSON_TYPE:
+        raise AdminWebError(415, "invalid_content_type", "请求必须使用 JSON。")
+    try:
+        text = request.body.decode("utf-8")
+
+        def pairs(values: list[tuple[str, object]]) -> dict[str, object]:
+            if len(values) > _MAX_JSON_FIELDS:
+                raise ValueError("too many JSON fields")
+            result: dict[str, object] = {}
+            for key, value in values:
+                if key in result:
+                    raise ValueError("duplicate JSON field")
+                result[key] = value
+            return result
+
+        value = json.loads(text, object_pairs_hook=pairs)
+    except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
+        raise AdminWebError(400, "invalid_json", "请求 JSON 无效。") from None
+    if not isinstance(value, dict):
+        raise AdminWebError(400, "invalid_json", "请求 JSON 必须是对象。")
+    return value
+
+
+def _one(values: Mapping[str, list[str]], name: str) -> str:
+    items = values.get(name)
+    if items is None or len(items) != 1 or not items[0]:
+        raise AdminWebError(400, "invalid_input", f"缺少字段 {name}。")
+    return items[0]
+
+
+def _batches(values: Sequence[str], size: int) -> tuple[tuple[str, ...], ...]:
+    if size < 1:
+        raise ValueError("batch size must be positive")
+    return tuple(
+        tuple(values[index : index + size])
+        for index in range(0, len(values), size)
+    )
+
+
+def _required_text(
+    payload: Mapping[str, object],
+    name: str,
+    *,
+    maximum: int,
+) -> str:
+    value = payload.get(name)
+    if (
+        not isinstance(value, str)
+        or not value
+        or value.strip() != value
+        or len(value.encode("utf-8")) > maximum
+        or any(ord(character) < 0x20 for character in value)
+    ):
+        raise AdminWebError(400, "invalid_input", f"字段 {name} 无效。")
+    return value
+
+
+def _optional_text_body(
+    payload: Mapping[str, object],
+    name: str,
+    *,
+    maximum: int,
+) -> str | None:
+    value = payload.get(name)
+    if value is None:
+        return None
+    return _required_text(payload, name, maximum=maximum)
+
+
+def _required_bool(payload: Mapping[str, object], name: str) -> bool:
+    value = payload.get(name)
+    if not isinstance(value, bool):
+        raise AdminWebError(400, "invalid_input", f"字段 {name} 必须是布尔值。")
+    return value
+
+
+def _required_int(
+    payload: Mapping[str, object],
+    name: str,
+    *,
+    minimum: int,
+) -> int:
+    value = payload.get(name)
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        raise AdminWebError(400, "invalid_input", f"字段 {name} 必须是整数。")
+    return value
+
+
+def _require_body_keys(payload: Mapping[str, object], allowed: set[str]) -> None:
+    if payload.keys() != allowed:
+        missing = allowed - payload.keys()
+        unknown = payload.keys() - allowed
+        if missing or unknown:
+            raise AdminWebError(400, "invalid_input", "请求字段不完整或包含未知字段。")
+
+
+_ACTION_KEYS = {"csrfToken", "actionToken", "target"}
+
+
+def _require_schedule_success(result: dict[str, Any]) -> None:
+    if result.get("ok") is False:
+        error = result["error"]
+        code = error["code"]
+        status = {
+            "revision_conflict": 409, "request_conflict": 409,
+            "run_in_progress": 409, "blocked_unknown": 409,
+            "project_disabled": 409, "project_unavailable": 409,
+            "not_found": 404, "unavailable": 503,
+        }.get(code, 400)
+        raise AdminWebError(status, code, error["message"])
+
+
+def _action_target(payload: Mapping[str, object]) -> AdminActionTarget:
+    raw = payload.get("target")
+    if not isinstance(raw, dict):
+        raise AdminWebError(400, "invalid_target", "操作目标无效。")
+    allowed = {"resource", "targetId", "scopeKey"}
+    if not set(raw).issubset(allowed) or {"resource", "targetId"} - set(raw):
+        raise AdminWebError(400, "invalid_target", "操作目标无效。")
+    resource = _required_text(raw, "resource", maximum=64)
+    target_id = _required_text(raw, "targetId", maximum=512)
+    scope_key = _optional_text_body(raw, "scopeKey", maximum=1_024)
+    return AdminActionTarget(resource, target_id, scope_key)
+
+
+def _action_target_json(
+    target: AdminActionTarget,
+) -> dict[str, object]:
+    return {
+        "resource": target.resource,
+        "targetId": target.target_id,
+        "scopeKey": target.scope_key,
+    }
+
+
+def _empty_preconditions(
+    *,
+    active_binding_id: ExpectedValue[str] | None = None,
+    project_revision: ExpectedValue[int] | None = None,
+    settings_revision: ExpectedValue[int] | None = None,
+    native_thread_id: ExpectedValue[str] | None = None,
+    activity_revision: ExpectedValue[int] | None = None,
+    physical_turn_id: ExpectedValue[str] | None = None,
+    side_app_id: ExpectedValue[str] | None = None,
+    side_chat_id: ExpectedValue[str] | None = None,
+    side_topic_id: ExpectedValue[str] | None = None,
+    side_root_message_id: ExpectedValue[str] | None = None,
+    inventory_fingerprint: ExpectedValue[str] | None = None,
+    schedule_revision: ExpectedValue[int] | None = None,
+    default_revision: ExpectedValue[int] | None = None,
+    default_order_revision: ExpectedValue[int] | None = None,
+) -> AdminActionPreconditions:
+    return AdminActionPreconditions(
+        active_binding_id or ExpectedValue.dont_check(),
+        project_revision or ExpectedValue.dont_check(),
+        settings_revision or ExpectedValue.dont_check(),
+        native_thread_id or ExpectedValue.dont_check(),
+        activity_revision or ExpectedValue.dont_check(),
+        physical_turn_id or ExpectedValue.dont_check(),
+        side_app_id or ExpectedValue.dont_check(),
+        side_chat_id or ExpectedValue.dont_check(),
+        side_topic_id or ExpectedValue.dont_check(),
+        side_root_message_id or ExpectedValue.dont_check(),
+        inventory_fingerprint or ExpectedValue.dont_check(),
+        schedule_revision or ExpectedValue.dont_check(),
+        default_revision or ExpectedValue.dont_check(),
+        default_order_revision or ExpectedValue.dont_check(),
+    )
+
+
+def _grant_preconditions(grant: object) -> AdminActionPreconditions:
+    value = getattr(grant, "preconditions", None)
+    if not isinstance(value, AdminActionPreconditions):
+        raise RuntimeError("Admin action precondition type mismatch")
+    return value
+
+
+def _expected_value(expected: ExpectedValue[T], label: str) -> T:
+    if expected.mode.value != "expect_value" or expected.value is None:
+        raise RuntimeError(f"{label} action precondition is unavailable")
+    return expected.value
+
+
+def _expected_optional(expected: ExpectedValue[T], label: str) -> T | None:
+    if expected.mode.value == "expect_none":
+        return None
+    return _expected_value(expected, label)
+
+
+def _binding_target(grant: object) -> ExactBindingTarget:
+    target = getattr(grant, "target", None)
+    if not isinstance(target, AdminActionTarget) or target.scope_key is None:
+        raise RuntimeError("Binding action target type mismatch")
+    preconditions = _grant_preconditions(grant)
+    expected = preconditions.active_binding_id
+    if expected.mode.value == "expect_none":
+        active = None
+    else:
+        active = _expected_value(expected, "active Binding")
+    return ExactBindingTarget(
+        scope_key=target.scope_key,
+        binding_id=target.target_id,
+        expected_active_binding_id=active,
+    )
+
+
+def _lifecycle_binding_target(grant: object) -> ExactBindingTarget:
+    """Resolve an exact Binding without coupling lifecycle to Scope activity."""
+
+    target = getattr(grant, "target", None)
+    if not isinstance(target, AdminActionTarget) or target.scope_key is None:
+        raise RuntimeError("Binding action target type mismatch")
+    return ExactBindingTarget(
+        scope_key=target.scope_key,
+        binding_id=target.target_id,
+        expected_active_binding_id=None,
+    )
+
+
+def _runtime_precondition(grant: object) -> RuntimePrecondition:
+    preconditions = _grant_preconditions(grant)
+    activity_revision = _expected_value(
+        preconditions.activity_revision,
+        "runtime activity revision",
+    )
+    physical_turn_id = _expected_optional(
+        preconditions.physical_turn_id,
+        "physical Turn",
+    )
+    return RuntimePrecondition(activity_revision, physical_turn_id)
+
+
+_UPDATE_HTTP_ERRORS = {
+    "invalid_update_target": (400, "invalid_update_target", "升级目标无效。"),
+    "update_unsupported": (409, "update_unsupported", "请在对应 Python 环境运行 netizen update。"),
+    "restart_unsupported": (409, "restart_unsupported", "仅绑定当前 Python 环境的受管实例支持 Admin 重启。"),
+    "update_target_changed": (409, "update_target_changed", "升级目标已变化，请重新检查更新。"),
+    "update_busy": (409, "update_busy", "另一个安装或维护操作正在执行，请稍后查看结果。"),
+    "update_state_unavailable": (
+        503, "update_state_unavailable", "维护状态无法确认，请检查实例维护记录。",
+    ),
+    "update_lock_unavailable": (
+        503, "update_state_unavailable", "无法取得维护锁，请检查实例状态。",
+    ),
+    "update_installation_changed": (
+        409, "update_target_changed", "当前安装已变化，请重新连接。",
+    ),
+    "update_already_submitted": (409, "update_busy", "维护操作已提交，请查看已有操作结果。"),
+    "update_recovery_required": (
+        409, "update_recovery_required", "上次维护结果未确认，请检查服务状态并使用 netizen restart 恢复。",
+    ),
+    "update_cleanup_unavailable": (
+        503, "update_cleanup_unavailable", "暂时无法清理上次维护任务，请稍后重试。",
+    ),
+    "update_submission_unknown": (
+        503, "update_state_unavailable", "维护操作提交结果无法确认，请刷新查看；不要重复提交。",
+    ),
+}
+
+
+def _map_error(error: BaseException) -> AdminWebError | None:
+    if isinstance(error, AdminWebError):
+        return error
+    if isinstance(error, ThreadOccupied):
+        return AdminWebError(409, "thread_occupied", str(error))
+    if isinstance(error, UpdateError):
+        mapped = _UPDATE_HTTP_ERRORS.get(error.code)
+        return AdminWebError(*mapped) if mapped is not None else None
+    if isinstance(error, (ValueError, AmbiguousBinding)) and not isinstance(error, ProjectError):
+        return AdminWebError(400, "invalid_input", "请求参数无效。")
+    if isinstance(
+        error,
+        (BindingNotFound, ScopeNotFound, SideTopicNotFound, UnknownProject),
+    ):
+        return AdminWebError(404, "not_found", "目标不存在。")
+    if isinstance(
+        error,
+        (
+            ActivePointerChanged,
+            BindingScopeMismatch,
+            BindingSettingsRevisionConflict,
+            RuntimeStateChanged,
+            StaleProject,
+            StoredProjectConflict,
+            ProjectAlreadyExists,
+            ProjectDisabled,
+            SideIdentityMismatch,
+            SideSessionConflict,
+            ThreadArchived,
+            ThreadNotArchived,
+            ThreadNotMaterialized,
+            ThreadDeleteUnavailable,
+            ThreadCompacting,
+            ThreadGoalActive,
+            ThreadRunningConfiguration,
+            ThreadBackgroundTerminalsActive,
+            NativeThreadMissing,
+        ),
+    ):
+        return AdminWebError(409, "stale_or_conflict", "状态已变化，请刷新后重试。")
+    if isinstance(error, (BindingQueryBusy, BlockingIOExecutorSaturated)):
+        return AdminWebError(429, "busy", "管理服务繁忙，请稍后重试。")
+    if isinstance(error, BindingQueryTimeout):
+        return AdminWebError(504, "query_timeout", "查询超时，请缩小筛选范围。")
+    if isinstance(error, ThreadCatalogDeadlineExceeded):
+        return AdminWebError(504, "query_timeout", "原生会话查询超时。")
+    if isinstance(error, TimeoutError):
+        return AdminWebError(504, "deadline_exceeded", "操作等待超时，请刷新对账。")
+    if isinstance(
+        error,
+        (
+            AdmissionClosed,
+            AuthCapacityExceeded,
+            BindingQueryClosed,
+            BlockingIOExecutorClosed,
+            BlockingIOResultUnknown,
+            BlockingIODrainTimeout,
+            BlockingIOShutdownTimeout,
+            NativeCatalogInconsistent,
+            RuntimeClosed,
+            ThreadCatalogError,
+            ThreadLifecycleStateUnknown,
+            ThreadReleaseStateUnknown,
+        ),
+    ):
+        return AdminWebError(503, "state_unknown", "结果未确认，请刷新对账。")
+    if isinstance(error, MalformedActionGrant):
+        return AdminWebError(400, "invalid_action", "操作凭据无效。")
+    if isinstance(
+        error,
+        (
+            ProjectError,
+            SideCloseFailed,
+            SideSessionNotFound,
+            ThreadLifecycleError,
+            ThreadReleaseError,
+        ),
+    ):
+        return AdminWebError(409, "operation_rejected", str(error)[:500])
+    return None