feat(ops): install and repair managed local Server runtimes

docs/en/docs/operate/local-server-ops.md

@@ -10,9 +10,12 @@ current-user service controller used by `powercontext service`; it does not need
 Its own Python and dependencies must be distributed separately from the Server runtime it manages. A missing Server
 interpreter therefore does not prevent the tool itself from starting or inspecting the registered service.
 
-This boundary supports prepared Server runtimes. Downloading and repairing the managed runtime, the Desktop native
-bridge, and the installation UI are separate capabilities. Existing human-facing CLI commands remain available.
+This service boundary supports prepared Server runtimes. For fixed managed resources and the install/repair policy,
+see [Managed local Server installation](managed-local-server.md). The Desktop native bridge and installation UI are
+separate capabilities. Existing human-facing CLI commands remain available.
 Ops is not an HTTP API and does not add a daemon.
+Managed registrations carrying `isolated_runtime=true` require the bundled Ops or a matching-version service tool;
+an older CLI that does not support this definition field rejects it instead of managing the registration.
 
 ## Operator binding and invocation
 

docs/en/docs/operate/managed-local-server.md

@@ -0,0 +1,173 @@
+---
+title: Managed local Server installation
+description: Install or repair a fixed personal Server runtime while preserving configuration and database state.
+---
+
+# Managed local Server installation
+
+The independent Ops tool prepares a fixed Server runtime and manages its current-user service. Ops has its own
+interpreter and dependencies, so repairing a missing Server interpreter does not require the damaged environment to
+run. Desktop integration uses this boundary; a running HTTP connection is not required for installation or repair.
+
+## Installation and repair plans
+
+Installation and repair use the explicit `preflight`, `apply`, `operation_status`, `cancel`, and `resume` protocol
+described in [Local Server operations](local-server-ops.md). The caller displays the complete plan and obtains approval
+before applying it. Retain the operation ID when starting a request; after interruption, inspect the saved attempt and
+current facts before approving a recovery plan.
+
+If a later stop operation supersedes an interrupted repair, approve a new repair plan instead of resuming the
+superseded operation. The new plan can continue the original repair guard only after checking its journal, installation
+and resource identities, exact service definition, and completed native commands. It does not restart the service or
+restore a registration that was subsequently removed.
+
+The packaged Ops interpreter accepts one JSON request per process. Its trusted host supplies the protected catalog
+and the SHA-256 digest pinned by the distribution:
+
+```text
+<ops-python> -I -S -B <ops-entry.py> --catalog-file <protected-catalog.json> --catalog-sha256 <trusted-sha256>
+```
+
+For example, send this single line on standard input to inspect a first installation:
+
+```json
+{"protocol_version":1,"request_id":"inspect-install","action":"preflight","operation":"install","options":{}}
+```
+
+The response includes the fixed resource, program/configuration/data locations, endpoint, database classification,
+required space, and startup effects. Pass the returned complete plan unchanged to `apply`, with a unique operation ID
+and explicit authorization for its `plan_id`, as in the shared Ops protocol. To prepare same-version repair, use
+`"operation":"repair"`. Managed locations are selected by the host; `--state-dir` belongs to the separate operator-owned
+`--target-file` mode and cannot override a managed installation. These commands require a qualified producer catalog;
+they do not discover a public release or produce one.
+
+Only the trusted producer selects resource URLs, executable layout, platform, architecture, package version, and file
+digests. The renderer cannot supply a command, download URL, or arbitrary installation path. Resources are downloaded
+to staging, checked against the fixed catalog, and verified before publication. A checksum supplied alongside an
+untrusted download does not establish trust. A cache hit must pass the same integrity checks as a download.
+
+Repair uses the same fixed resource identity and version. It preserves the installation identity, existing
+configuration, and user data. It does not upgrade to `latest`, reset authentication or models, or delete an existing
+database. Repair stops the owned service before replacing resources and completes without restarting it. A stopped
+service stays stopped. Repeating installation for a verified current installation reports current
+facts without restarting the service or opening its database.
+
+Managed service definitions explicitly select isolated runtime startup (`isolated_runtime=true`). The target Python
+runs with `-I -B`, excluding `PYTHONPATH` and user-site imports and avoiding generated bytecode changes in the verified
+resource tree. Manage these definitions with the bundled Ops tool or a matching-version service tool. Older CLI
+versions that do not recognize this field reject the definition; they are not a supported way to manage the new
+registration. Existing definitions without this field retain their previous startup behavior.
+
+An independent installation is not automatically adopted. Unknown ownership, damaged control records, mismatched
+native service definitions, or unresolved native commands require inspection before modification. Removing a service
+registration preserves the environment, configuration, and database; it is not a database deletion operation.
+
+## New personal configuration
+
+The new-configuration policy explicitly sets:
+
+| Setting | New managed installation |
+| --- | --- |
+| HTTP listener | `127.0.0.1` and the approved port |
+| Database | SQLite at an explicit absolute path in the selected user-data directory |
+| Dashboard | Enabled |
+| Access mode | `disabled` |
+| Legacy bearer authentication | Disabled, with no token |
+| MCP | Uses the same local access mode as HTTP |
+| Models | No generation, embedding, reranking, or decision model is configured |
+
+This is local access without a token, not a separate anonymous credential. Keep the listener on loopback. The policy
+does not change authentication for existing or remote connections, and repair does not overwrite an existing user's
+choices. Selecting an authenticated existing installation retains its protected configuration.
+
+The default data directory follows the platform's `powercontext_data_dir()` location while ignoring an inherited
+`POWERCONTEXT_HOME`. New configuration also ignores inherited `POWERCONTEXT_SERVER_*`, `PYTHONPATH`, and `PYTHONHOME`
+settings during resolution. It records the chosen data root and SQLite path explicitly. Existing installations retain
+their verified registered data directory; program directories and data directories are separate.
+
+Preflight reads configuration through the protected-file interface and returns only the file identity and necessary
+local summary fields. Configuration contents, tokens, and model credentials do not enter plans or operation journals.
+Preflight does not create a configuration file, data directory, or database.
+
+## Database compatibility boundary
+
+Database inventory does not construct a Server runtime, connect to SQLite, initialize tables, change WAL settings, or
+apply migrations. It observes the selected file and recovery sidecars and binds that observation to the exact target
+Server version. Ops' own package version cannot prove compatibility with the target Server.
+
+Program-only repair binds the existing database's file identity and target version, allowing normal writes and WAL
+checkpointing while resources are prepared. Replacing the database invalidates the plan. This repair observation does
+not authorize startup; installation and startup retain strict database and recovery-sidecar observations.
+
+| Observation | Installer behavior |
+| --- | --- |
+| Database and SQLite recovery sidecars are absent | Classify as `new`; the approved target Server may initialize a new database during startup. |
+| An existing SQLite file, including an empty file | Classify as `existing_unknown`; do not automatically start or restart against it. |
+| An existing file has an unsupported database header | Classify as `incompatible`; preserve it and block startup. |
+| Orphan sidecars, a linked or unverified location, an unreadable file, or a changing observation | Classify as `unknown`; preserve the files and block startup. |
+
+The current public maintenance checks cover individual domains, not complete Server schema, indexes, persisted task
+formats, and all configured capabilities. A Dream or processing check, an Atomic Memory verification, or a migration
+bundle reporting `ready` therefore cannot lift the installer gate. A `pc_schema_revision` marker does not establish
+whole-Server readiness. The installer does not create one for new databases.
+
+For existing data without a qualified whole-database check for the fixed target version, keep the service stopped and
+preserve the database. Same-version program repair can complete while the database remains `existing_unknown`; that
+does not authorize startup. There is no general maintenance command that this installer can recommend to make every
+such database compatible. Consult [Database migrations](database-migrations.md) for the actual supported bundle
+boundary, and wait for a maintenance release supporting the specific database before attempting a data transition.
+Do not repeatedly run a partial migration as an automatic repair.
+
+This also limits normal operation today: after first startup creates a database, subsequent `start`, `restart`, and
+`config_apply` with `restart=true` when it would restart an active service are rejected through the managed entry while
+whole-database compatibility remains unknown. An already stopped service stays stopped during configuration changes,
+including when `restart=true` is supplied. A previous successful startup or the installation manifest does not bypass
+this gate. Inspection, stopping,
+configuration changes without restart, and same-version program repair remain available. Repeating `install` for an
+owned current installation only reports facts. This implementation therefore does not yet provide a complete daily
+restart workflow; qualified whole-database checks are still required. The separate prepared-runtime operator binding
+retains its existing contract and is not evidence that the managed database is compatible.
+
+## Startup and connection handoff
+
+Resource integrity, configuration validity, service registration, process liveness, and readiness are separate facts.
+For an approved first startup, the shared service controller performs bounded readiness verification and protects and
+stops a newly started owned target when startup fails. A completed installation result is historical evidence; ordinary
+status does not rerun readiness checks. Cancellation takes effect at supported safe boundaries and does not promise
+rollback.
+
+If first registration fails before creating a service, release the conflicting port or resolve the reported failure,
+then confirm a fresh install plan and resume the recorded operation. The installation identity and owned configuration
+are retained. A dispatch checkpoint alone does not establish that registration existed. Matching-version CLI and Ops
+removal persist a private removal identity before native changes; an older install operation cannot undo that removal,
+even when no registration existed yet. Pending records without this identity remain readable, but a legacy dispatch
+checkpoint without registration evidence requires inspection rather than automatic replay.
+
+A cancelled installation can reuse verified staging. If regular staged files are corrupt, resume or a new approved
+install operation verifies the recorded directory ownership, discards that exact staging tree and prepares the fixed
+resource again. Replaced directories, links and unsafe ownership are rejected and preserved.
+
+The installer returns its actual endpoint and installation/resource identities. These are not Server deployment or
+Principal identities. The connection layer must validate the actual endpoint and supported public identity and
+compatibility contract before activating a connection or obtaining its default Scope. Installation does not invent a
+Scope ID, select an arbitrary Scope, or prove that a Memory operation has succeeded.
+
+## Release and platform acceptance
+
+This implementation requires producer-supplied, fixed resources. The formal platform resource catalog and qualified
+artifacts belong to [#2112](https://github.com/oceanbase/powercontext/issues/2112); the implementation does not supply a
+public production download URL or infer one from a version string. Development fixtures and locally built bundles
+verify implementation behavior, not production distribution trust.
+
+On Windows, preflight checks the producer's file layout against the actual final directory and the fixed staging
+budget. Acquisition checks its exact staging directory again before downloading. Ordinary paths must fit the Windows
+file and directory limits; unsupported layouts return `resource_path_unsupported`. Ops does not enable system-wide
+long paths or assume Task Scheduler supports extended-path executable names. The producer must qualify a layout that
+fits the intended user directories. A complete development bundle that starts from a shorter test directory does not
+establish that the default installation layout works.
+
+Release acceptance must use the exact downloaded artifacts on clean standard-user Windows 11 x64, macOS arm64, and
+macOS x86_64 machines without preinstalled Python, uv, Git, or build tools. Independently verify signatures and macOS
+notarization, independent Ops startup, actual Task Scheduler or LaunchAgent behavior, login/restart handling, and
+preservation of configuration and data through repair and removal. Fake service adapters and repository-runtime
+SQLite tests do not establish those platform results.

docs/en/docs/operate/meta.json

@@ -4,6 +4,7 @@
     "index",
     "deploy-server",
     "local-server-ops",
+    "managed-local-server",
     "connect-remote-server",
     "database-migrations",
     "artifact-processing-migration",

docs/en/rfcs/1455-desktop-control-center.md

@@ -358,11 +358,12 @@ identity resolution; `multi_principal` alone does not prove a supported login fl
 Generic `401 unauthorized` means valid credentials are needed, not necessarily expired. Show expiry only when a supported
 contract supplies it; distinguish `403` denial and `503 authentication_unavailable`. Stop protected loops on rejection.
 
-New managed local setup enables enforced authentication by default; unauthenticated attachment remains an explicit
-existing-installation mode. The configuration producer generates the credential in a protected Server environment. After
-explicit setup approval, a secure machine interface provisions the desktop OS-store entry and selected hosts through
-existing URL-bound authorization adapters, without returning secrets through page data. Server/Agents must work without
-the desktop or its unlocked vault.
+New managed personal setup explicitly binds loopback, enables Dashboard, and uses `access.mode=disabled` with
+`auth.enabled=false`; HTTP and MCP share this local tokenless mode. It does not generate a token or background Principal
+and does not configure models. This policy applies to new configuration only: existing and remote authentication choices
+remain authoritative, and repair preserves their protected configuration. Authenticated installations continue to use
+the OS credential store and existing URL-bound authorization adapters without returning secrets through page data.
+Server/Agents must work without the desktop or its unlocked vault.
 
 Rotation is a producer plan: check ownership/consumers, stage protected configuration, reconcile the service, replace
 desktop and selected-host credentials, then verify each consumer. Static Bearer has no assumed old/new overlap;

docs/zh/docs/operate/local-server-ops.md

@@ -8,8 +8,9 @@ description: 使用独立 Ops 工具配置和管理已准备好的个人 Server
 Ops 为个人 Server 提供非交互的配置和服务管理入口，复用 `powercontext service` 使用的当前用户服务控制器，调用时不需要已有的 Server HTTP 会话。
 Ops 自带的 Python 与依赖必须和受管 Server 的运行环境分开分发。因此，Server 解释器缺失不会妨碍工具自身启动和检查服务注册。
 
-此入口管理已准备好的 Server 环境。下载和修复受管环境、Desktop 原生桥接以及安装界面是另外的能力。原有的人用 CLI 命令继续可用。
+此服务入口管理已准备好的 Server 环境。固定受管资源及安装、修复策略见[受管本地 Server 安装](managed-local-server.md)。Desktop 原生桥接和安装界面是另外的能力，原有的人用 CLI 命令继续可用。
 Ops 不是 HTTP API，也不新增常驻进程。
+包含 `isolated_runtime=true` 的受管注册需使用随包 Ops 或匹配版本的服务工具；不支持该定义字段的旧 CLI 会拒绝它，不再继续管理该注册。
 
 ## 绑定目标与启动