From 9fbc2fd2ae2e915f9521ae2e4b110befc79026d7 Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 12:28:40 +0800
Subject: [PATCH 01/11] feat(app): add independent local OPC control plane

---
 README.md                                     |   21 +-
 README.zh-CN.md                               |   19 +-
 ...independent-local-opc-app-control-plane.md |   88 +
 docs/adr/README.md                            |    1 +
 docs/architecture.md                          |    4 +
 docs/installation-and-distribution.md         |   20 +
 docs/opc-app.en.md                            |  130 ++
 docs/opc-app.md                               |  130 ++
 docs/opc-dashboard.md                         |    5 +
 docs/roadmap.md                               |    2 +-
 docs/testing-and-acceptance.md                |   13 +
 .../v0.2-public-synthetic-evidence.v1.json    |    2 +-
 .../codex-opc-team/assets/app/dashboard.css   | 1725 +++++++++++++++++
 .../codex-opc-team/assets/app/dashboard.js    |  835 ++++++++
 plugins/codex-opc-team/assets/app/index.html  |  215 ++
 plugins/codex-opc-team/scripts/opc_app.py     |  635 ++++++
 .../codex-opc-team/scripts/opc_dashboard.py   |   29 +-
 .../scripts/opc_snapshot_service.py           |   60 +
 scripts/opc_app_admin.py                      |  438 +++++
 tests/integration/test_opc_app_lifecycle.py   |  253 +++
 tests/unit/test_opc_app.py                    |  333 ++++
 21 files changed, 4944 insertions(+), 14 deletions(-)
 create mode 100644 docs/adr/0017-independent-local-opc-app-control-plane.md
 create mode 100644 docs/opc-app.en.md
 create mode 100644 docs/opc-app.md
 create mode 100644 plugins/codex-opc-team/assets/app/dashboard.css
 create mode 100644 plugins/codex-opc-team/assets/app/dashboard.js
 create mode 100644 plugins/codex-opc-team/assets/app/index.html
 create mode 100644 plugins/codex-opc-team/scripts/opc_app.py
 create mode 100644 plugins/codex-opc-team/scripts/opc_snapshot_service.py
 create mode 100644 scripts/opc_app_admin.py
 create mode 100644 tests/integration/test_opc_app_lifecycle.py
 create mode 100644 tests/unit/test_opc_app.py

diff --git a/README.md b/README.md
index 05924f9..f7e8217 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,25 @@ After installing, upgrading, or rolling back the plugin, start a new Codex task
 
 The first `$opc-manager` run performs a Doctor check. If the private File/Git knowledge repository is not initialized, it shows the target directory and explains that initialization creates an independent private Git repository with a baseline commit. Nothing is written until you explicitly confirm, and Mem0 is not enabled as part of that initialization.
 
-### Development-only local Dashboard
+### Development-only independent OPC App
+
+The `main` branch includes an independently installable, explicitly started,
+loopback-only OPC App. It can run without an active Agent session, but it is a
+read-only control plane rather than an Agent harness. It never scans for
+projects and writes only its own explicit-project registry:
+
+```text
+python plugins/codex-opc-team/scripts/opc_app.py --demo
+python scripts/opc_app_admin.py install
+```
+
+Administration previews by default. After an explicit `--apply`, launch from
+the reported Windows or Linux entry. App update, rollback, and uninstall
+preserve project `.opc`, File/Git knowledge, Git history, user configuration,
+and Mem0 data. See [OPC App](docs/opc-app.en.md) for the product, installation,
+privacy, and recovery contract.
+
+### Compatible local Dashboard
 
 The `main` branch includes an explicitly started, loopback-only, read-only Dashboard for manager visibility. It is not part of stable `v0.1.0`, does not scan for projects, and has no approval or promotion actions:
 
@@ -174,6 +192,7 @@ Capability evolution is an evidence-gated private lifecycle for versioned roles,
 | [Knowledge lineage](docs/knowledge-lineage.md) | Private role/step knowledge states, portable outcome links, current-HEAD revalidation, and non-causal reports |
 | [Capability evolution](docs/capability-evolution.md) | Versioned role/Skill/policy pilots, evidence gates, one-path Git handoff, observation, and rollback |
 | [OPC Dashboard](docs/opc-dashboard.md) | Explicitly started local read-only manager view, data semantics, security boundaries, and limitations |
+| [OPC App](docs/opc-app.en.md) | Independent local control plane, App-owned settings, install lifecycle, privacy, and Dashboard compatibility |
 | [v0.2 release readiness](docs/release-readiness-v0.2.0.md) | Public synthetic evidence, private 3–5 task pilot protocol, exact-commit gates, blockers, and non-claims |
 | [Roadmap](docs/roadmap.md) | Planned delivery stages |
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 2d4c202..5d97bd7 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -81,7 +81,23 @@ codex plugin add codex-opc-team@opc
 
 首次运行 `$opc-manager` 会执行 Doctor。如果私人 File/Git 知识库尚未初始化，它会展示目标目录，并说明初始化将创建一个独立的私有 Git 仓库和基线 Commit；只有得到你的明确确认后才会写入，且不会同时启用 Mem0。
 
-### `main` 开发版本地 Dashboard
+### `main` 开发版独立 OPC App
+
+`main` 提供一个可独立安装、显式启动、仅本机访问的 OPC App。它不需要 Agent
+会话正在运行，但只是治理只读的控制平面，不是新的 Agent Harness。它不会扫描
+磁盘，只写入 App 自有的显式项目接入清单：
+
+```powershell
+python plugins/codex-opc-team/scripts/opc_app.py --demo
+python scripts/opc_app_admin.py install
+```
+
+管理命令默认只预览；显式 `--apply` 后，从输出的 Windows 或 Linux 入口启动。
+App 的更新、回滚与卸载不会删除项目 `.opc`、File/Git knowledge、Git 历史、
+用户配置或 Mem0 数据。产品边界、安装、隐私与恢复契约见
+[OPC App](docs/opc-app.md)。
+
+### 兼容的本地 Dashboard
 
 `main` 提供一个显式启动、仅本机访问、只读的经理 Dashboard。它不属于稳定版 `v0.1.0`，不会扫描磁盘发现项目，也没有批准或晋升操作：
 
@@ -191,6 +207,7 @@ Hook/运行事件只进入私有 `PLUGIN_DATA` 或项目 `.opc` 回退，绝不
 | [知识使用链路](docs/knowledge-lineage.md) | 私有角色/步骤状态、portable 结果关联、current-HEAD 重验与非因果报告 |
 | [受控能力进化](docs/capability-evolution.md) | 角色/Skill/策略版本、证据门禁、单路径 Git 交接、观察与回滚 |
 | [OPC Dashboard](docs/opc-dashboard.md) | 显式启动的本地只读经理视图、数据语义、安全边界与已知限制 |
+| [OPC App](docs/opc-app.md) | 独立本地控制平面、App 自有设置、安装生命周期、隐私与 Dashboard 兼容性 |
 | [v0.2 发布就绪度](docs/release-readiness-v0.2.0.md) | 公开 synthetic 证据、私有 3–5 task 协议、exact-commit Gate、阻断项与非主张 |
 | [路线图](docs/roadmap.md) | 分阶段交付计划 |
 
diff --git a/docs/adr/0017-independent-local-opc-app-control-plane.md b/docs/adr/0017-independent-local-opc-app-control-plane.md
new file mode 100644
index 0000000..f6c3aeb
--- /dev/null
+++ b/docs/adr/0017-independent-local-opc-app-control-plane.md
@@ -0,0 +1,88 @@
+# ADR 0017：独立本地 OPC App 是控制平面，不是 Agent Harness
+
+- 状态：Accepted
+- 日期：2026-07-25
+
+## 背景
+
+ADR-0016 的本地只读 Dashboard 已验证固定 DTO、服务端脱敏和
+loopback-only 浏览器视图可以安全降低经理理解 OPC 状态的成本，但旧入口仍需
+用户从仓库或插件目录显式执行 `opc_dashboard.py`，且只能读取启动命令传入的
+项目。
+
+用户需要一个不依赖 Codex、Claude 或 Kimi 会话生命周期的稳定产品入口，同时
+必须继续遵守 ADR-0001：OPC 不重复建设模型循环、工具运行时、权限层和 Agent
+编排 Harness。独立 App 也不能把 File/Git 权威状态复制进第二个数据库，或绕过
+现有批准、晋升、提交和发布门禁。
+
+## 决策
+
+提供独立安装和显式启动的本地 OPC App，并保持以下边界：
+
+1. **独立的是控制平面生命周期，不是执行 Harness。** App 只负责可视化、
+   显式项目接入和 App 自有偏好；Agent 继续负责模型与工具执行。
+2. **一个 Snapshot 语义来源。** `opc_snapshot_service.py` 是旧 Dashboard 和
+   新 App 共用的应用服务边界，实际聚合、状态判断、固定 DTO 与脱敏仍只由
+   `opc_dashboard.py` 的既有实现提供。App 不复制治理规则。
+3. **File/Git authoritative。** App 不持久化 OPC 业务事实。Mem0 仍是可选、
+   可删除重建的 Provider；缺失或故障时准确降级。
+4. **App 状态与业务状态隔离。** 项目接入清单和当前项目选择位于
+   `OPC_APP_HOME` 或平台文档化的用户状态目录，不在 checkout、插件安装目录、
+   项目 `.opc` 或知识根内。清单可删除重建。
+5. **显式接入，不扫描。** 用户提交一个绝对项目目录；服务端只验证该目录的
+   `.opc/project.json`。响应仅返回 `显式目录 N`、安全项目名和 portable ID，
+   不回传绝对路径。
+6. **治理 API 只读。** `/api/snapshot` 继续只读。唯一写路由只管理 App
+   接入清单和选择状态；使用精确 Host/Origin、每进程 CSRF token、固定 JSON
+   大小、方法与路由白名单。
+7. **本地网络边界不变。** 默认只绑定 `127.0.0.1`，也只允许显式 `::1`；
+   无 CORS、远程资源、遥测、默认远程监听和常驻 Agent 进程。
+8. **无大型构建链。** 延续 Python 标准库服务和无构建步骤的 HTML/CSS/JS。
+   当前交互规模没有足够证据引入 Electron、Tauri、React 或 Node 供应链。
+9. **独立可回滚分发。** App 安装器把公开插件快照复制到用户级 runtime，
+   用内容哈希 release 与原子 current pointer 支持安装、升级和回滚。卸载只删除
+   runtime；App 状态、项目、File/Git knowledge、Git 历史、用户配置和 Mem0
+   数据全部保留。
+10. **旧入口兼容。** 不安装或不启动 App 时，Codex Plugin、Skills、Hook、
+    脚本和 `opc_dashboard.py` 的行为与生命周期 Gate 不变。
+
+## API 与状态
+
+| 路由 | 方法 | 权限 |
+|---|---|---|
+| `/api/snapshot` | `GET`, `HEAD` | 共享、脱敏、治理只读 |
+| `/api/app-context` | `GET`, `HEAD` | 返回脱敏接入清单和进程级 CSRF |
+| `/api/projects` | `POST` | 只新增 App 接入记录 |
+| `/api/projects/<app-id>` | `DELETE` | 只移除 App 接入记录 |
+| `/api/selection` | `POST` | 只更新 App 当前项目 |
+
+所有其他路由和方法拒绝。未来远程、多用户、治理写操作或完整历史数据库必须
+另立 ADR，不能从这些 App 设置路由扩权。
+
+## 结果
+
+正面结果：
+
+- App 可在没有 Agent 会话时启动，关闭前台进程即停止；
+- 旧 Dashboard 与 App 对同一项目使用相同 snapshot schema 和状态语义；
+- UI 更适合筛选、切换、钻取和理解降级，但不获得治理写权限；
+- 安装、升级、回滚和卸载与私人数据生命周期分离。
+
+代价：
+
+- 仍需要本机 Python 3.10+；
+- 当前是本地 Web App，不是原生桌面壳或移动客户端；
+- App 接入清单损坏时会拒绝覆盖并降级为空清单，需要用户删除或修复 App 自有
+  状态文件；
+- 没有持久化完整运行历史，不能把 sidecar 推断成历史数据库。
+
+## 未采用方案
+
+| 方案 | 原因 |
+|---|---|
+| 独立 Agent 平台或聊天界面 | 重复 Harness，违反 ADR-0001 |
+| Electron/Tauri/React 首版 | 当前没有足够交互或分发证据承担额外构建链 |
+| 自动扫描 Home/磁盘 | 扩大隐私范围，项目边界不可预测 |
+| SQLite/搜索数据库 | 形成第二事实来源和新的迁移生命周期 |
+| 在 App 内批准、晋升或提交 | 绕过现有确认与独立 QA 门禁 |
+| 在本 Issue 安装 Codex/Claude/Kimi Adapter | 属于后续 Issue #26 |
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 46ddc34..673ecab 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -20,5 +20,6 @@ ADR 用于保存影响长期架构、安全边界或用户数据的决策。每
 | [0014](0014-evidence-gated-capability-evolution.md) | Accepted | 能力版本通过证据门禁、bounded pilot 与单路径 Git 交接晋升或回滚 |
 | [0015](0015-release-evidence-separates-public-fixtures-and-private-pilots.md) | Accepted | v0.2 发布证据严格分离公开 fixture、私有 pilot 与 exact-commit Gate |
 | [0016](0016-local-read-only-opc-dashboard.md) | Accepted | OPC Dashboard 采用显式启动、loopback-only、固定字段投影的本地只读架构 |
+| [0017](0017-independent-local-opc-app-control-plane.md) | Accepted | 独立 OPC App 只扩展本地控制平面，不成为 Agent Harness 或第二事实来源 |
 
 新 ADR 使用递增四位编号，至少包含：Status、Date、Context、Decision、Consequences、Rejected Alternatives。
diff --git a/docs/architecture.md b/docs/architecture.md
index ea4963b..b633eff 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -144,6 +144,8 @@ sequenceDiagram
 | 组织知识 | 用户配置的 `OPC_KNOWLEDGE_HOME` | 独立于插件，用户拥有 |
 | Mem0 索引 | 用户私有数据目录 | 可删除、可重建，不是权威源 |
 | Dashboard 展示状态 | 进程内即时只读投影，不持久化 | 关闭本地进程即消失，不成为事实来源 |
+| OPC App 接入清单与偏好 | `OPC_APP_HOME` 或平台用户状态目录 | 独立于 runtime、checkout、项目和知识；可删除重建 |
+| OPC App runtime releases | 平台用户数据目录 | 内容哈希版本可升级/回滚；卸载不触碰 App 状态或业务数据 |
 | 原始运行日志 | 默认最小化并设置保留策略 | 不进入公共仓库和知识层 |
 
 具体路径应由安装器和环境解析，代码和文档示例不得硬编码作者本机路径。
@@ -186,6 +188,8 @@ v0.1 以 `plugins/codex-opc-team/scripts/opc_memory.py` 为真实可调用契约
 | 显式索引计划和写入 | `MemoryService.reindex_plan(...)` / `reindex_apply(...)` |
 | 健康与运行状态 | `MemoryService.status()` / `doctor()` |
 | 本地只读经理视图 | `opc_dashboard.py` 的固定字段 `/api/snapshot`；loopback-only，不提供治理写操作 |
+| 共享本地投影服务 | `opc_snapshot_service.py`；旧 Dashboard 与 OPC App 使用同一 snapshot builder、DTO 和脱敏器 |
+| 独立本地控制平面 | `opc_app.py`；治理 API 只读，唯一写状态为显式项目清单与当前选择，不承担 Agent Harness |
 | 候选只读回放与 control/treatment 证据 | `opc_shadow.py preview` / `evaluate` / `report`；不属于 `MemoryService` 状态迁移 |
 | 角色/Skill/组织策略版本生命周期 | `opc_evolution.py` 的 private proposal/pilot/evaluate/transition/confirm；只产生一个 unstaged allowlisted diff，不修改全局 Codex 配置 |
 
diff --git a/docs/installation-and-distribution.md b/docs/installation-and-distribution.md
index 4a97211..513b284 100644
--- a/docs/installation-and-distribution.md
+++ b/docs/installation-and-distribution.md
@@ -149,6 +149,26 @@ python plugins/codex-opc-team/scripts/opc_dashboard.py --project-root .
 
 关闭进程即可停止。它不写入项目或私人知识；卸载插件前应先停止正在运行的 Dashboard 进程。完整边界见 [OPC Dashboard](opc-dashboard.md)。
 
+## 10.1 独立本地 OPC App
+
+`main` 同时提供与 Agent 会话生命周期分离的本地 OPC App。它不是 Agent
+Harness，也不替代 Marketplace 插件。App 管理器默认只预览：
+
+```powershell
+python scripts/opc_app_admin.py install
+python scripts/opc_app_admin.py install --apply
+python scripts/opc_app_admin.py status
+```
+
+安装结果会打印 Windows 和 Linux 可用的本地 launcher。更新、回滚和卸载也分别
+使用 `update`、`rollback`、`uninstall` 子命令并坚持 preview → `--apply`。
+runtime release 使用内容哈希与原子 pointer；App 状态位于独立用户状态目录。
+
+App 卸载不删除 App 接入清单、项目 `.opc`、File/Git knowledge、Git 历史、
+用户配置或 Mem0 数据。它不安装或管理 Codex、Claude、Kimi 本体，也不写这些
+宿主的全局配置；宿主 Adapters 属于 Issue #26。完整边界与恢复说明见
+[OPC App](opc-app.md)。
+
 ## 11. 卸载
 
 卸载分成三个明确范围：
diff --git a/docs/opc-app.en.md b/docs/opc-app.en.md
new file mode 100644
index 0000000..3e5553e
--- /dev/null
+++ b/docs/opc-app.en.md
@@ -0,0 +1,130 @@
+# OPC App
+
+OPC App is an independently installable, explicitly started, loopback-only
+private OPC console. It can run without an active Codex, Claude, or Kimi
+session, but it is not another Agent harness: it does not run model loops,
+tools, logins, keys, proxies, or Agent orchestration.
+
+## 1. Responsibility boundaries
+
+| Component | Owns | Does not own |
+|---|---|---|
+| OPC App | Visualization, filters, drill-down, explicit projects, App settings | Approval, promotion, commits, deletion, deployment |
+| Legacy Dashboard | Compatible read-only view for CLI-supplied projects | Installed App registry or lifecycle |
+| Agent harness | Model loop, tools, permissions, and task sessions | OPC App local state |
+| Future Adapters (#26) | OPC integration lifecycle in supported hosts | Agent applications, accounts, models, or keys |
+| File/Git knowledge | Authoritative knowledge and provenance | UI caches or optional indexes |
+
+The legacy Dashboard and OPC App use `opc_snapshot_service.py` and the same
+`opc-dashboard.snapshot.v1` aggregation and redaction contract. There is no
+second status implementation.
+
+## 2. Run from a checkout
+
+Synthetic mode reads and writes no private directory:
+
+```text
+python plugins/codex-opc-team/scripts/opc_app.py --demo
+```
+
+Live mode can start with an empty registry. Use the Projects screen to enter
+one absolute directory containing a valid `.opc/project.json`:
+
+```text
+python plugins/codex-opc-team/scripts/opc_app.py
+```
+
+The authoritative knowledge root and rebuildable data root are never found by
+disk scanning. Stop the App and pass both explicitly when switching roots;
+remove the overrides to return to the existing OPC environment variables or
+platform defaults:
+
+```text
+python plugins/codex-opc-team/scripts/opc_app.py \
+  --knowledge-root /absolute/path/to/opc-knowledge \
+  --data-root /absolute/path/to/opc-private-data
+```
+
+The browser receives only redacted knowledge status, never either root path.
+
+The default URL is `http://127.0.0.1:8570/`. Press `Ctrl+C` to stop it; no
+Agent process must remain resident. Use `--port` for an explicit alternate
+port and `--no-open` for automation.
+
+## 3. Independent install, update, and rollback
+
+Administration defaults to a preview. Only `--apply` writes the App runtime:
+
+```text
+python scripts/opc_app_admin.py install
+python scripts/opc_app_admin.py install --apply
+python scripts/opc_app_admin.py status
+```
+
+Launch with `bin\opc-app.cmd` on Windows or `bin/opc-app` on Linux. Both use
+the same atomic content-addressed release pointer.
+
+Updates and rollback also preview first:
+
+```text
+python scripts/opc_app_admin.py update
+python scripts/opc_app_admin.py update --apply
+python scripts/opc_app_admin.py rollback
+python scripts/opc_app_admin.py rollback --apply
+```
+
+The runtime and App state are separate. The default state root is
+`%LOCALAPPDATA%\OPC\App` on Windows and
+`${XDG_STATE_HOME:-$HOME/.local/state}/opc-app` on Linux. `OPC_APP_HOME`
+overrides it. This registry and current-project preference are rebuildable App
+settings, not OPC facts.
+
+Uninstall removes only the runtime:
+
+```text
+python scripts/opc_app_admin.py uninstall
+python scripts/opc_app_admin.py uninstall --apply
+```
+
+App state, project `.opc`, File/Git knowledge, Git history, existing user
+configuration, and Mem0 data are preserved. This installer does not install
+Codex, Claude, or Kimi and does not edit Agent global configuration.
+
+## 4. Project and privacy boundary
+
+The user submits one absolute directory. The server checks only that directory
+and `.opc/project.json`, atomically updates App-owned settings, and returns
+only a safe project name, portable ID, and `Explicit directory N`. It never
+scans the disk.
+
+Responses contain no absolute paths, private bodies, credentials,
+session/turn identifiers, Hook payloads, or raw logs. Unreadable projects,
+corrupt App settings, incomplete history, and missing/disabled/failing Mem0
+are reported as degradation; demo data is never substituted.
+
+## 5. Network and mutation boundary
+
+- Binding is limited to `127.0.0.1` or explicit `::1`.
+- Host must exactly match the active loopback authority.
+- Origin must be absent or exactly same-origin.
+- There is no CORS, remote asset, telemetry, response cache, or default remote
+  listener.
+- `/api/snapshot` and every governance object remain read-only.
+- `POST`/`DELETE` are limited to the App project registry and selection, with
+  a same-origin per-process CSRF token.
+- Every other method and route is rejected.
+
+Remote access, multi-user identity, governance writes, a complete history
+database, and advanced analytics require separate ADRs and acceptance.
+
+## 6. Legacy Dashboard compatibility
+
+The original command and security contract remain available:
+
+```text
+python plugins/codex-opc-team/scripts/opc_dashboard.py --project-root .
+```
+
+Not installing, not starting, or uninstalling OPC App does not change the
+Codex Plugin, Skills, Hook, scripts, legacy Dashboard, or installed-lifecycle
+gates.
diff --git a/docs/opc-app.md b/docs/opc-app.md
new file mode 100644
index 0000000..286eaa3
--- /dev/null
+++ b/docs/opc-app.md
@@ -0,0 +1,130 @@
+# OPC App
+
+OPC App 是一个可独立安装、显式启动、只在本机访问的私人 OPC 控制台。它不需要
+Codex、Claude 或 Kimi 会话正在运行，但它也不是新的 Agent Harness：不运行
+模型循环、工具、登录、Key、代理或 Agent 编排。
+
+## 1. 能力边界
+
+| 组件 | 负责 | 不负责 |
+|---|---|---|
+| OPC App | 可视化、筛选、钻取、显式项目接入、App 自有偏好 | 批准、晋升、提交、删除、部署 |
+| 旧 Dashboard | 从启动参数读取显式项目的兼容只读视图 | 安装态 App 状态和项目清单 |
+| Agent Harness | 模型循环、工具、权限和任务会话 | OPC App 本地状态 |
+| 后续 Adapters（#26） | 宿主 OPC 集成物的安装生命周期 | Agent 本体、账号、模型和 Key |
+| File/Git knowledge | 唯一权威知识与 provenance | UI 缓存或可选索引 |
+
+旧 Dashboard 与 App 通过 `opc_snapshot_service.py` 使用同一个
+`opc-dashboard.snapshot.v1` 聚合和脱敏契约，不存在两套状态判断。
+
+## 2. 从 checkout 体验
+
+合成数据不会读取或写入私人目录：
+
+```powershell
+python plugins/codex-opc-team/scripts/opc_app.py --demo
+```
+
+真实模式允许空项目清单启动；在“项目”页面明确输入一个包含有效
+`.opc/project.json` 的绝对目录：
+
+```powershell
+python plugins/codex-opc-team/scripts/opc_app.py
+```
+
+权威知识根和可重建数据根不会通过磁盘扫描发现。需要切换时，停止 App 后从启动
+入口显式传入；移除覆盖参数即可回到既有 OPC 环境变量或平台默认根：
+
+```powershell
+python plugins/codex-opc-team/scripts/opc_app.py `
+  --knowledge-root C:\path\to\opc-knowledge `
+  --data-root C:\path\to\opc-private-data
+```
+
+Linux 使用对应的绝对路径。浏览器只收到脱敏后的知识状态，不会收到这些根路径。
+
+默认 URL 是 `http://127.0.0.1:8570/`。按 `Ctrl+C` 停止；关闭后没有必须常驻
+的 Agent 进程。端口冲突时可显式使用 `--port`，自动化可加 `--no-open`。
+
+## 3. 独立安装、升级和回滚
+
+管理脚本默认只输出计划；只有 `--apply` 才写 App runtime：
+
+```powershell
+python scripts/opc_app_admin.py install --dry-run
+python scripts/opc_app_admin.py install --apply
+python scripts/opc_app_admin.py status
+```
+
+Windows 从安装结果中的 `bin\opc-app.cmd` 启动，Linux 从 `bin/opc-app` 启动。
+安装器同时生成 Python launcher；三个入口读取同一个原子 release pointer。
+
+更新和回滚同样先预览：
+
+```powershell
+python scripts/opc_app_admin.py update --dry-run
+python scripts/opc_app_admin.py update --apply
+python scripts/opc_app_admin.py rollback
+python scripts/opc_app_admin.py rollback --apply
+```
+
+App runtime 默认位于平台用户数据目录；App 状态与 runtime 分开：
+
+| 平台 | 默认 App 状态根 |
+|---|---|
+| Windows | `%LOCALAPPDATA%\OPC\App` |
+| Linux | `${XDG_STATE_HOME:-$HOME/.local/state}/opc-app` |
+
+可用 `OPC_APP_HOME` 显式覆盖状态根。状态根保存项目接入清单和当前项目选择，
+可以删除重建，但不是 OPC 业务事实来源。
+
+卸载只删除 App runtime：
+
+```powershell
+python scripts/opc_app_admin.py uninstall
+python scripts/opc_app_admin.py uninstall --apply
+```
+
+App 状态、项目 `.opc`、File/Git knowledge、Git 历史、用户配置和 Mem0 数据均
+保留。安装器不安装 Codex、Claude、Kimi，也不编辑任何 Agent 全局配置。
+
+## 4. 项目接入与隐私
+
+接入流程固定为：
+
+```text
+用户输入一个绝对目录
+  → 服务端只检查该目录和 .opc/project.json
+  → 原子更新 App 自有 settings.json
+  → 浏览器只收到项目安全名称、portable ID 和“显式目录 N”
+```
+
+App 不扫描磁盘，不把绝对路径、私人正文、凭据、session/turn、Hook Payload 或
+原始日志放入响应。项目不可读、App 设置损坏、历史不完整、Mem0 缺失/禁用/故障
+时会显示明确降级，不用演示数据填充。
+
+如果 App 接入清单损坏，服务会拒绝覆盖并以空清单降级。先停止 App，保留一份
+`settings.json` 备份，再移走该 App 自有文件即可重建；不要删除项目或知识目录。
+
+## 5. 网络与写入边界
+
+- 只允许 `127.0.0.1` 或显式 `::1`；
+- Host 必须与实际 loopback authority 精确一致；
+- Origin 必须缺失或与当前本地 URL 精确同源；
+- 无 CORS、远程资源、遥测、响应缓存和默认远程监听；
+- `/api/snapshot` 与所有 OPC 治理数据保持只读；
+- `POST`/`DELETE` 只用于 App 项目清单和当前选择，必须携带同源进程级 CSRF；
+- 所有其他方法和路由拒绝。
+
+远程、多用户、治理写操作、完整历史数据库或高级分析需要独立 ADR 和验收。
+
+## 6. 与旧 Dashboard 的关系
+
+`opc_dashboard.py` 继续支持原命令和安全契约：
+
+```powershell
+python plugins/codex-opc-team/scripts/opc_dashboard.py --project-root .
+```
+
+不安装、不启动或卸载 OPC App 都不会改变 Codex Plugin、Skills、Hook、脚本、
+旧 Dashboard 或安装态生命周期 Gate。
diff --git a/docs/opc-dashboard.md b/docs/opc-dashboard.md
index 3058968..4fc86aa 100644
--- a/docs/opc-dashboard.md
+++ b/docs/opc-dashboard.md
@@ -4,6 +4,11 @@ OPC Dashboard 是一个显式启动、本机访问、只读的经理视图。它
 
 它不是稳定版 `v0.1.0` 的能力，也不是常驻服务。当前实现位于 `main`，必须由用户在需要时启动，关闭进程后即停止。
 
+独立 OPC App 已在 `main` 作为另一个可选入口提供。旧 Dashboard 继续接收命令行
+传入的项目根并保持原安全契约；OPC App 额外管理 App 自有的显式项目清单和安装
+生命周期。两者共用相同 snapshot 聚合、状态语义和脱敏逻辑。区别与安装方式见
+[OPC App](opc-app.md)。
+
 ## 1. 最短体验路径
 
 从仓库根目录运行：
diff --git a/docs/roadmap.md b/docs/roadmap.md
index e5df990..3699f1b 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -75,7 +75,7 @@
 - 经理反馈与真实产品指标的结构化关联，以及角色/步骤知识使用链路（v1 已实现；仅 association/evidence，不证明因果）；
 - 角色、Skill 与组织策略的版本化候选、同合同 paired pilot、经理/独立 QA 门禁、单路径 Git 晋升、观察与回滚（v1 已实现；不自动 stage/commit，不改全局 Codex 配置）；
 
-v0.2 release-level contract、公开 synthetic runner 和严格私有 aggregate/envelope Gate 已实现，当前状态明确为 `BLOCKED`。退出 R4 还必须完成[代表性私有 3–5 task pilot 与 exact release commit 验证](release-readiness-v0.2.0.md)；公开 fixture、模板、Developer 自测或单项 token/latency 改善都不能替代。`main` 已提供显式启动的本地只读 OPC Dashboard，但写操作、知识导出、合并和远程访问仍是后续候选，不属于 v0.2 发布阻断项。
+v0.2 release-level contract、公开 synthetic runner 和严格私有 aggregate/envelope Gate 已实现，当前状态明确为 `BLOCKED`。退出 R4 还必须完成[代表性私有 3–5 task pilot 与 exact release commit 验证](release-readiness-v0.2.0.md)；公开 fixture、模板、Developer 自测或单项 token/latency 改善都不能替代。`main` 已提供兼容的本地只读 Dashboard，以及可独立安装、只写 App 自有项目清单的本地 OPC App；二者共用固定 snapshot 语义。治理写操作、知识导出、合并、远程访问和宿主 Adapters 仍是后续候选，不属于 v0.2 发布阻断项。
 
 这些能力仍遵守“不得自动晋升”的基础决策。任何自动化批准提议都需要新的 ADR 和安全评估。
 
diff --git a/docs/testing-and-acceptance.md b/docs/testing-and-acceptance.md
index f167ae0..2b76b87 100644
--- a/docs/testing-and-acceptance.md
+++ b/docs/testing-and-acceptance.md
@@ -146,6 +146,19 @@ G5/G7 的发布证据必须使用两个不同的固定 Ref；本地路径对同
 | 体验 | 原生桌面视口与窄屏可读；键盘可操作；经理队列说明下一步但不执行写操作 |
 | 证据 | 单元测试、完整仓库门禁、官方 Plugin/Skill 校验、真实浏览器截图与独立 QA 全部通过 |
 
+### OPC App 增量验收
+
+| 维度 | 通过条件 |
+|---|---|
+| 独立生命周期 | 从安装后的 Windows/Linux 入口启动；不要求 Agent 会话；停止后没有必须常驻 Agent 进程 |
+| 旧入口兼容 | 不安装/不启动 App 时 Plugin、Skills、Hook、脚本和旧 Dashboard 的测试与 Gate 不回退 |
+| 单一语义 | Dashboard 与 App 共用 `opc_snapshot_service.py` 和同一 DTO/脱敏实现 |
+| App 状态 | 只保存显式项目清单与选择；位于 runtime/checkout/项目/知识之外，损坏时拒绝覆盖并降级 |
+| 隐私与网络 | 响应无路径/正文/凭据/运行标识/Hook 原文；loopback、Host、Origin、CSRF、方法和路由 fail closed |
+| 安装数据保留 | install/update/rollback/uninstall 不覆盖或删除 `.opc`、File/Git、Git 历史、用户配置、App 状态或 Mem0 |
+| 体验 | 桌面、小窗口、移动、键盘、刷新上下文、无横向溢出、文本状态与零 console error |
+| 证据 | unit、clean-room lifecycle、仓库三项门禁、官方 Plugin/全部 Skill validators、浏览器对比和独立 QA |
+
 Private verdict 的路径输出仅支持 Windows，并且必须位于已批准的 private root 内。POSIX runner 为 stdout-only，传入 `--output` 必须在创建任何目录项前失败；若调用者捕获 stdout，目标必须由调用者置于已批准的私有边界，且不得位于本公开仓库或公开 CI Artifact。
 
 ## 10. 验收证据格式
diff --git a/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json b/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json
index 508ca26..bea3dcd 100644
--- a/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json
+++ b/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json
@@ -7,7 +7,7 @@
     {
       "issue": 2,
       "path": "docs/installation-and-distribution.md",
-      "sha256": "8652ed095a63ca14b60bbfb1388b02c641c38cb9645d2d4dbbe7ee5582ac3c58"
+      "sha256": "204e7c030954d11e9b4b3e4e3a4d6676ae773703da58041ea7711e205f0a4593"
     },
     {
       "issue": 3,
diff --git a/plugins/codex-opc-team/assets/app/dashboard.css b/plugins/codex-opc-team/assets/app/dashboard.css
new file mode 100644
index 0000000..f10f902
--- /dev/null
+++ b/plugins/codex-opc-team/assets/app/dashboard.css
@@ -0,0 +1,1725 @@
+:root {
+  --ink-950: #071b2d;
+  --ink-900: #0b2942;
+  --text-950: #071426;
+  --text-700: #34465c;
+  --text-500: #718096;
+  --canvas: #ffffff;
+  --surface: #ffffff;
+  --surface-muted: #f7fafc;
+  --line: #dbe3ec;
+  --cyan-600: #087ad8;
+  --cyan-400: #21b8ef;
+  --green-600: #2f9b4b;
+  --amber-600: #d88700;
+  --red-600: #d83b31;
+  --shadow-panel: 0 10px 30px rgba(7, 27, 45, .06);
+  --sidebar-width: 220px;
+  --radius: 10px;
+  color: var(--text-950);
+  font-family: "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+  font-synthesis: none;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  min-width: 320px;
+  background: var(--canvas);
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  min-height: 100vh;
+  overflow-x: hidden;
+  background: var(--canvas);
+  color: var(--text-950);
+  font-size: 14px;
+  line-height: 1.55;
+}
+
+button,
+input,
+select {
+  font: 600 14px/1.4 inherit;
+}
+
+button,
+select {
+  cursor: pointer;
+}
+
+button:focus-visible,
+input:focus-visible,
+select:focus-visible,
+a:focus-visible,
+[tabindex]:focus-visible {
+  outline: 3px solid rgba(8, 122, 216, .24);
+  outline-offset: 2px;
+}
+
+.icon-sprite {
+  position: absolute;
+  width: 0;
+  height: 0;
+  overflow: hidden;
+}
+
+.icon,
+.brand-logo {
+  width: 20px;
+  height: 20px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.75;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  flex: 0 0 auto;
+}
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.app-shell {
+  min-height: 100vh;
+}
+
+.sidebar {
+  position: fixed;
+  inset: 0 auto 0 0;
+  z-index: 20;
+  display: flex;
+  width: var(--sidebar-width);
+  flex-direction: column;
+  overflow-y: auto;
+  color: #eef7ff;
+  background: var(--ink-950);
+  box-shadow: 1px 0 0 rgba(255, 255, 255, .04);
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  min-height: 86px;
+  padding: 0 26px;
+  color: #fff;
+  font-size: 26px;
+  font-weight: 750;
+  letter-spacing: -.03em;
+}
+
+.brand-logo {
+  width: 28px;
+  height: 28px;
+  color: var(--cyan-400);
+  stroke-width: 2.6;
+}
+
+.primary-nav {
+  display: grid;
+  gap: 4px;
+  padding: 4px 10px;
+}
+
+.nav-item {
+  position: relative;
+  display: flex;
+  min-height: 54px;
+  align-items: center;
+  gap: 16px;
+  padding: 0 18px;
+  border-radius: 8px;
+  color: #d8e7f4;
+  font-size: 15px;
+  font-weight: 600;
+  text-decoration: none;
+  transition: color 160ms ease, background 160ms ease;
+}
+
+.nav-item:hover {
+  color: #fff;
+  background: rgba(255, 255, 255, .06);
+}
+
+.nav-item.is-active {
+  color: #6fd9ff;
+  background: rgba(33, 184, 239, .12);
+}
+
+.nav-item.is-active::before {
+  content: "";
+  position: absolute;
+  inset: 8px auto 8px -10px;
+  width: 3px;
+  border-radius: 0 3px 3px 0;
+  background: var(--cyan-400);
+}
+
+.utility-nav {
+  margin: auto 10px 0;
+}
+
+.privacy-note {
+  display: grid;
+  gap: 6px;
+  padding: 20px 26px 26px;
+  border-top: 1px solid rgba(255, 255, 255, .08);
+  color: #cfe1ef;
+}
+
+.privacy-note strong {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+}
+
+.privacy-note strong .icon {
+  width: 16px;
+  height: 16px;
+}
+
+.privacy-note span {
+  color: #7f9bb0;
+  font-size: 11px;
+}
+
+.main-content {
+  min-height: 100vh;
+  margin-left: var(--sidebar-width);
+  background: var(--canvas);
+}
+
+.topbar {
+  position: sticky;
+  top: 0;
+  z-index: 12;
+  display: grid;
+  min-height: 78px;
+  grid-template-columns: max-content minmax(190px, 300px) minmax(220px, 1fr) max-content max-content 44px;
+  align-items: center;
+  gap: 16px;
+  padding: 12px 28px;
+  border-bottom: 1px solid var(--line);
+  background: rgba(255, 255, 255, .97);
+}
+
+.topbar h1 {
+  margin: 0;
+  font-size: 28px;
+  line-height: 36px;
+  letter-spacing: -.04em;
+}
+
+.project-context,
+.search-control,
+.readonly-state {
+  display: flex;
+  min-height: 44px;
+  align-items: center;
+  gap: 10px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: #fff;
+}
+
+.project-context {
+  padding: 0 10px 0 14px;
+}
+
+.project-context select {
+  min-width: 0;
+  width: 100%;
+  border: 0;
+  outline: 0;
+  color: var(--text-700);
+  background: transparent;
+}
+
+.search-control {
+  justify-self: end;
+  width: min(100%, 290px);
+  padding: 0 14px;
+  color: var(--text-500);
+}
+
+.search-control:focus-within,
+.project-context:focus-within {
+  border-color: var(--cyan-600);
+  box-shadow: 0 0 0 3px rgba(8, 122, 216, .12);
+}
+
+.search-control input {
+  min-width: 0;
+  width: 100%;
+  height: 42px;
+  border: 0;
+  outline: 0;
+  color: var(--text-950);
+  background: transparent;
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.readonly-state {
+  padding: 0 13px;
+  color: #267d40;
+  font-size: 13px;
+  white-space: nowrap;
+}
+
+.readonly-state .icon {
+  width: 18px;
+  height: 18px;
+}
+
+.updated-state {
+  color: var(--text-500);
+  font-size: 12px;
+  white-space: nowrap;
+}
+
+.icon-button {
+  display: inline-flex;
+  width: 44px;
+  height: 44px;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  color: var(--text-700);
+  background: transparent;
+}
+
+.icon-button:hover {
+  background: var(--surface-muted);
+}
+
+.mobile-menu {
+  display: none;
+}
+
+.status-banner {
+  margin: 20px 28px 0;
+  padding: 12px 16px;
+  border: 1px solid #f4c7c3;
+  border-radius: 8px;
+  color: #8f2f28;
+  background: #fff4f3;
+}
+
+.app-view {
+  padding: 20px 28px 28px;
+  animation: view-in 160ms ease both;
+}
+
+.app-view[hidden] {
+  display: none;
+}
+
+@keyframes view-in {
+  from { opacity: .45; transform: translateY(3px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+.status-strip {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  min-height: 138px;
+  margin-bottom: 16px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: #fff;
+}
+
+.status-strip article {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 18px;
+  min-width: 0;
+  padding: 22px 24px;
+}
+
+.status-strip article:not(:last-child)::after {
+  content: "";
+  position: absolute;
+  inset: 24px 0 24px auto;
+  width: 1px;
+  background: var(--line);
+}
+
+.summary-icon {
+  display: grid;
+  width: 56px;
+  height: 56px;
+  flex: 0 0 auto;
+  place-items: center;
+  border: 1px solid #bee6f4;
+  border-radius: 10px;
+  color: var(--cyan-600);
+  background: #eaf7fc;
+}
+
+.summary-icon.is-amber {
+  border-color: #f4deb1;
+  color: var(--amber-600);
+  background: #fff8e8;
+}
+
+.summary-icon.is-green {
+  border-color: #c8e6cf;
+  color: var(--green-600);
+  background: #eef8f0;
+}
+
+.summary-icon .icon {
+  width: 26px;
+  height: 26px;
+}
+
+.status-strip article > div {
+  display: grid;
+  min-width: 0;
+}
+
+.status-strip strong {
+  font-size: 34px;
+  line-height: 38px;
+  letter-spacing: -.04em;
+}
+
+.status-strip b {
+  margin-top: 2px;
+  font-size: 14px;
+}
+
+.status-strip small {
+  margin-top: 4px;
+  overflow: hidden;
+  color: var(--text-500);
+  font-size: 11px;
+  font-weight: 400;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.overview-workspace {
+  display: grid;
+  grid-template-columns: minmax(0, 1.8fr) minmax(290px, .95fr);
+  gap: 16px;
+  align-items: start;
+}
+
+.surface {
+  min-width: 0;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: var(--surface);
+}
+
+.surface-heading {
+  display: flex;
+  min-height: 70px;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 14px 18px;
+  border-bottom: 1px solid var(--line);
+}
+
+.surface-heading h2 {
+  margin: 0;
+  font-size: 18px;
+  line-height: 26px;
+  letter-spacing: -.02em;
+}
+
+.surface-heading p {
+  margin: 2px 0 0;
+  color: var(--text-500);
+  font-size: 12px;
+}
+
+.surface-heading > span {
+  color: var(--text-500);
+  font-size: 12px;
+}
+
+.queue-header,
+.queue-row {
+  display: grid;
+  grid-template-columns: 84px minmax(240px, 1fr) 100px 82px 28px;
+  align-items: center;
+  gap: 10px;
+}
+
+.queue-header {
+  min-height: 40px;
+  padding: 0 18px;
+  border-bottom: 1px solid var(--line);
+  color: var(--text-500);
+  font-size: 11px;
+}
+
+.queue-row {
+  min-height: 70px;
+  padding: 10px 18px;
+  border: 0;
+  border-bottom: 1px solid var(--line);
+  color: inherit;
+  text-align: left;
+  background: transparent;
+}
+
+.queue-row:hover,
+.queue-row:focus-visible {
+  background: var(--surface-muted);
+}
+
+.priority {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  font-weight: 700;
+}
+
+.priority::before,
+.status-dot {
+  content: "";
+  width: 8px;
+  height: 8px;
+  flex: 0 0 auto;
+  border-radius: 50%;
+  background: var(--text-500);
+}
+
+.priority.is-high {
+  color: var(--red-600);
+}
+
+.priority.is-high::before {
+  background: var(--red-600);
+}
+
+.priority.is-medium {
+  color: var(--amber-600);
+}
+
+.priority.is-medium::before {
+  background: var(--amber-600);
+}
+
+.queue-copy {
+  display: grid;
+  min-width: 0;
+}
+
+.queue-copy b {
+  overflow: hidden;
+  font-size: 13px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.queue-copy small {
+  overflow: hidden;
+  color: var(--text-500);
+  font-size: 11px;
+  font-weight: 400;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.queue-source {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--text-700);
+  font-size: 12px;
+}
+
+.queue-source .icon,
+.queue-row > .icon {
+  width: 17px;
+  height: 17px;
+}
+
+.queue-time {
+  color: var(--text-500);
+  font-size: 11px;
+}
+
+.empty-state {
+  display: grid;
+  min-height: 240px;
+  place-content: center;
+  justify-items: center;
+  padding: 32px;
+  color: var(--text-500);
+  text-align: center;
+}
+
+.empty-state .icon {
+  width: 32px;
+  height: 32px;
+  margin-bottom: 12px;
+}
+
+.empty-state b {
+  color: var(--text-700);
+}
+
+.operations-rail {
+  display: grid;
+  gap: 16px;
+}
+
+.compact-surface .surface-heading {
+  min-height: 56px;
+  padding: 12px 16px;
+}
+
+.compact-surface .surface-heading h2 {
+  font-size: 16px;
+}
+
+.run-summary {
+  padding: 16px;
+}
+
+.run-summary-top {
+  display: flex;
+  align-items: start;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.run-summary-top span {
+  display: grid;
+}
+
+.run-summary-top small,
+.run-next small {
+  color: var(--text-500);
+  font-size: 11px;
+}
+
+.run-summary-top b {
+  margin-top: 3px;
+}
+
+.run-status-text {
+  display: inline-flex !important;
+  grid-auto-flow: column;
+  align-items: center;
+  gap: 7px;
+  color: var(--green-600);
+}
+
+.run-status-text .status-dot {
+  background: currentColor;
+}
+
+.progress-steps {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  margin: 20px 0;
+}
+
+.progress-step {
+  position: relative;
+  display: grid;
+  justify-items: center;
+  gap: 4px;
+  color: var(--text-500);
+  font-size: 10px;
+}
+
+.progress-step:not(:last-child)::after {
+  content: "";
+  position: absolute;
+  top: 9px;
+  left: 62%;
+  width: 76%;
+  height: 1px;
+  background: var(--line);
+}
+
+.progress-step i {
+  z-index: 1;
+  display: grid;
+  width: 19px;
+  height: 19px;
+  place-items: center;
+  border: 2px solid var(--line);
+  border-radius: 50%;
+  background: #fff;
+}
+
+.progress-step.is-complete i {
+  border-color: var(--green-600);
+  color: #fff;
+  background: var(--green-600);
+}
+
+.progress-step.is-current i {
+  border-color: var(--cyan-600);
+}
+
+.progress-step b {
+  color: var(--text-700);
+  font-size: 11px;
+}
+
+.run-next {
+  padding-top: 14px;
+  border-top: 1px solid var(--line);
+}
+
+.run-next strong {
+  display: block;
+  margin-bottom: 3px;
+  font-size: 12px;
+}
+
+.metric-list {
+  display: grid;
+  gap: 9px;
+  margin: 0;
+  padding: 16px;
+}
+
+.metric-list div {
+  display: grid;
+  grid-template-columns: 1fr 1.25fr;
+  gap: 12px;
+}
+
+.metric-list dt,
+.metric-list dd {
+  margin: 0;
+  font-size: 12px;
+}
+
+.metric-list dd {
+  color: var(--text-500);
+}
+
+.section-link {
+  display: flex;
+  min-height: 44px;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0 16px;
+  border-top: 1px solid var(--line);
+  color: var(--cyan-600);
+  font-size: 12px;
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.section-link .icon {
+  width: 16px;
+  height: 16px;
+}
+
+.health-list {
+  padding: 8px 16px 14px;
+}
+
+.health-row {
+  display: grid;
+  min-height: 42px;
+  grid-template-columns: 10px minmax(80px, 1fr) minmax(100px, 1.2fr);
+  align-items: center;
+  gap: 8px;
+  border-bottom: 1px solid var(--line);
+  font-size: 11px;
+}
+
+.health-row:last-child {
+  border-bottom: 0;
+}
+
+.health-row .status-dot {
+  background: var(--text-500);
+}
+
+.health-row.is-healthy .status-dot {
+  background: var(--green-600);
+}
+
+.health-row.is-warning .status-dot {
+  background: var(--amber-600);
+}
+
+.health-row.is-blocked .status-dot {
+  background: var(--red-600);
+}
+
+.health-row span:last-child {
+  color: var(--text-500);
+}
+
+.synthetic-notice {
+  display: flex;
+  min-height: 44px;
+  align-items: center;
+  gap: 10px;
+  margin: 0 28px 28px;
+  padding: 9px 14px;
+  border: 1px solid #f3bbb6;
+  border-radius: 8px;
+  color: #9d332a;
+  background: #fff7f6;
+  font-size: 12px;
+}
+
+.synthetic-notice .icon {
+  width: 18px;
+  height: 18px;
+}
+
+.projects-workspace {
+  display: grid;
+  grid-template-columns: minmax(540px, 1.5fr) minmax(300px, .85fr);
+  gap: 16px;
+  align-items: stretch;
+  min-height: calc(100vh - 126px);
+}
+
+.project-list-surface,
+.project-inspector {
+  display: flex;
+  min-height: 620px;
+  flex-direction: column;
+}
+
+.primary-button,
+.secondary-button,
+.danger-button {
+  display: inline-flex;
+  min-height: 42px;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding: 0 16px;
+  border-radius: 8px;
+  font-size: 13px;
+  font-weight: 650;
+}
+
+.primary-button {
+  border: 1px solid var(--cyan-600);
+  color: #fff;
+  background: var(--cyan-600);
+}
+
+.primary-button:hover {
+  background: #066cbe;
+}
+
+.secondary-button {
+  border: 1px solid var(--line);
+  color: var(--text-700);
+  background: #fff;
+}
+
+.secondary-button:hover {
+  border-color: #b8c5d3;
+  background: var(--surface-muted);
+}
+
+.danger-button {
+  border: 1px solid #f3aaa5;
+  color: var(--red-600);
+  background: #fff;
+}
+
+.primary-button .icon,
+.secondary-button .icon,
+.danger-button .icon {
+  width: 17px;
+  height: 17px;
+}
+
+.project-table-head,
+.project-row {
+  display: grid;
+  grid-template-columns: minmax(170px, 1.2fr) 100px 100px 88px 72px;
+  align-items: center;
+  gap: 10px;
+}
+
+.project-table-head {
+  min-height: 42px;
+  padding: 0 16px;
+  border-bottom: 1px solid var(--line);
+  color: var(--text-500);
+  font-size: 11px;
+}
+
+.project-row {
+  width: 100%;
+  min-height: 68px;
+  padding: 10px 16px;
+  border: 0;
+  border-bottom: 1px solid var(--line);
+  color: inherit;
+  text-align: left;
+  background: #fff;
+}
+
+.project-row:hover {
+  background: var(--surface-muted);
+}
+
+.project-row[aria-current="true"] {
+  box-shadow: inset 3px 0 var(--cyan-600);
+  background: #eef7ff;
+}
+
+.project-name {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: 10px;
+}
+
+.project-name .icon {
+  color: var(--cyan-600);
+}
+
+.project-name span {
+  display: grid;
+  min-width: 0;
+}
+
+.project-name b,
+.project-name small {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.project-name small {
+  color: var(--text-500);
+  font-size: 10px;
+}
+
+.text-state {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--text-700);
+  font-size: 11px;
+}
+
+.text-state .status-dot {
+  background: var(--green-600);
+}
+
+.text-state.is-warning .status-dot {
+  background: var(--amber-600);
+}
+
+.text-state.is-blocked .status-dot {
+  background: var(--red-600);
+}
+
+.list-footer {
+  margin: auto 0 0;
+  padding: 14px 16px;
+  border-top: 1px solid var(--line);
+  color: var(--text-500);
+  font-size: 11px;
+}
+
+.project-inspector {
+  padding-bottom: 16px;
+}
+
+.inspector-header {
+  display: flex;
+  min-height: 72px;
+  align-items: center;
+  gap: 12px;
+  padding: 16px;
+  border-bottom: 1px solid var(--line);
+}
+
+.inspector-header > .icon {
+  color: var(--cyan-600);
+}
+
+.inspector-header span {
+  display: grid;
+}
+
+.inspector-header small {
+  color: var(--text-500);
+}
+
+.inspector-section {
+  padding: 18px 16px;
+  border-bottom: 1px solid var(--line);
+}
+
+.inspector-section h3 {
+  margin: 0 0 14px;
+  font-size: 15px;
+}
+
+.inspector-section dl {
+  display: grid;
+  gap: 12px;
+  margin: 0;
+}
+
+.inspector-section dl div {
+  display: grid;
+  grid-template-columns: 100px 1fr;
+  gap: 10px;
+}
+
+.inspector-section dt,
+.inspector-section dd {
+  margin: 0;
+  font-size: 12px;
+}
+
+.inspector-section dt {
+  color: var(--text-500);
+}
+
+.inspector-section p {
+  margin: 0 0 12px;
+  color: var(--text-500);
+  font-size: 12px;
+}
+
+.inspector-actions {
+  display: grid;
+  gap: 10px;
+  padding: 16px;
+}
+
+.preservation-note {
+  margin: 0 16px;
+  padding: 12px;
+  border: 1px solid #f1d28c;
+  border-radius: 8px;
+  color: #74530a;
+  background: #fffaf0;
+  font-size: 11px;
+}
+
+.full-surface,
+.settings-surface {
+  min-height: calc(100vh - 126px);
+}
+
+.run-list {
+  display: grid;
+}
+
+.run-card {
+  display: grid;
+  min-height: 80px;
+  grid-template-columns: minmax(220px, 1fr) 130px 130px 140px;
+  align-items: center;
+  gap: 16px;
+  padding: 14px 18px;
+  border-bottom: 1px solid var(--line);
+}
+
+.run-card:last-child {
+  border-bottom: 0;
+}
+
+.run-card > span {
+  display: grid;
+}
+
+.run-card small {
+  color: var(--text-500);
+  font-size: 11px;
+}
+
+.knowledge-flow {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(140px, 1fr));
+  gap: 1px;
+  margin: 24px;
+  border: 1px solid var(--line);
+  background: var(--line);
+}
+
+.knowledge-stage {
+  min-height: 180px;
+  padding: 22px;
+  background: #fff;
+}
+
+.knowledge-stage strong {
+  display: block;
+  margin-bottom: 10px;
+  font-size: 32px;
+}
+
+.knowledge-stage b {
+  display: block;
+}
+
+.knowledge-stage small {
+  color: var(--text-500);
+}
+
+.surface-note {
+  margin: 0;
+  padding: 16px 24px;
+  border-top: 1px solid var(--line);
+  color: var(--text-500);
+  font-size: 12px;
+}
+
+.lineage-timeline {
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  margin: 0;
+  padding: 54px 24px 50px;
+  list-style: none;
+}
+
+.lineage-timeline li {
+  position: relative;
+  display: grid;
+  justify-items: center;
+  gap: 10px;
+  text-align: center;
+}
+
+.lineage-timeline li:not(:last-child)::after {
+  content: "";
+  position: absolute;
+  top: 18px;
+  left: 60%;
+  width: 80%;
+  height: 2px;
+  background: var(--line);
+}
+
+.lineage-timeline li > span {
+  z-index: 1;
+  display: grid;
+  width: 38px;
+  height: 38px;
+  place-items: center;
+  border: 2px solid var(--line);
+  border-radius: 50%;
+  color: var(--text-500);
+  background: #fff;
+}
+
+.lineage-timeline li.is-recorded > span {
+  border-color: var(--green-600);
+  color: #fff;
+  background: var(--green-600);
+}
+
+.lineage-timeline li.is-warning > span {
+  border-color: var(--amber-600);
+  color: var(--amber-600);
+}
+
+.lineage-timeline li div {
+  display: grid;
+}
+
+.lineage-timeline small,
+.lineage-timeline em {
+  color: var(--text-500);
+  font-size: 11px;
+  font-style: normal;
+}
+
+.health-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(220px, 1fr));
+  gap: 16px;
+  padding: 24px;
+}
+
+.health-card {
+  min-height: 180px;
+  padding: 20px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+}
+
+.health-card header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.health-card header .icon {
+  color: var(--green-600);
+}
+
+.health-card.is-warning header .icon {
+  color: var(--amber-600);
+}
+
+.health-card.is-blocked header .icon {
+  color: var(--red-600);
+}
+
+.health-card p {
+  color: var(--text-500);
+}
+
+.boundary-list {
+  display: grid;
+  margin: 0;
+}
+
+.boundary-list div {
+  display: grid;
+  min-height: 70px;
+  grid-template-columns: minmax(140px, .35fr) 1fr;
+  align-items: center;
+  gap: 20px;
+  padding: 14px 20px;
+  border-bottom: 1px solid var(--line);
+}
+
+.boundary-list dt,
+.boundary-list dd {
+  margin: 0;
+}
+
+.boundary-list dt {
+  font-weight: 700;
+}
+
+.boundary-list dd {
+  color: var(--text-500);
+}
+
+.settings-surface > .secondary-button {
+  margin: 20px;
+}
+
+dialog {
+  color: inherit;
+  font-family: inherit;
+}
+
+dialog::backdrop {
+  background: rgba(7, 27, 45, .38);
+  backdrop-filter: blur(2px);
+}
+
+.drawer {
+  width: min(420px, 94vw);
+  max-width: none;
+  height: 100vh;
+  max-height: none;
+  margin: 0 0 0 auto;
+  padding: 0;
+  border: 0;
+  background: #fff;
+  box-shadow: -18px 0 50px rgba(7, 27, 45, .16);
+}
+
+.drawer[open] {
+  display: flex;
+  flex-direction: column;
+  animation: drawer-in 180ms ease both;
+}
+
+@keyframes drawer-in {
+  from { opacity: .6; transform: translateX(24px); }
+  to { opacity: 1; transform: translateX(0); }
+}
+
+.drawer-header {
+  display: flex;
+  min-height: 74px;
+  align-items: center;
+  justify-content: space-between;
+  padding: 14px 20px;
+  border-bottom: 1px solid var(--line);
+}
+
+.drawer-header h2 {
+  margin: 0;
+  font-size: 20px;
+}
+
+.drawer-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 22px 20px;
+}
+
+.field-label {
+  display: block;
+  margin-bottom: 8px;
+  font-size: 13px;
+  font-weight: 700;
+}
+
+.text-field {
+  width: 100%;
+  min-height: 46px;
+  padding: 0 12px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  outline: 0;
+  color: var(--text-950);
+  background: #fff;
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.text-field:focus {
+  border-color: var(--cyan-600);
+  box-shadow: 0 0 0 3px rgba(8, 122, 216, .12);
+}
+
+.field-help {
+  margin: 8px 0 20px;
+  color: var(--text-500);
+  font-size: 11px;
+}
+
+.validation-preview {
+  padding: 16px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+}
+
+.validation-preview h3 {
+  margin: 0 0 12px;
+  font-size: 13px;
+}
+
+.validation-preview p {
+  display: flex;
+  align-items: start;
+  gap: 10px;
+  margin: 14px 0 0;
+}
+
+.validation-preview p .icon {
+  width: 18px;
+  height: 18px;
+  color: var(--green-600);
+}
+
+.validation-preview p span {
+  display: grid;
+}
+
+.validation-preview p b {
+  font-size: 12px;
+}
+
+.validation-preview p small {
+  color: var(--text-500);
+  font-size: 11px;
+}
+
+.drawer-notice {
+  display: flex;
+  gap: 10px;
+  margin-top: 20px;
+  padding: 13px;
+  border: 1px solid #a9d3f7;
+  border-radius: 8px;
+  color: #22577d;
+  background: #f4f9ff;
+  font-size: 11px;
+}
+
+.field-error {
+  margin: 14px 0 0;
+  color: var(--red-600);
+  font-size: 12px;
+}
+
+.drawer-actions {
+  display: grid;
+  grid-template-columns: 1fr 1.25fr;
+  gap: 12px;
+  padding: 16px 20px;
+  border-top: 1px solid var(--line);
+}
+
+.detail-dialog {
+  width: min(540px, 94vw);
+  padding: 22px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  box-shadow: var(--shadow-panel);
+}
+
+.dialog-header {
+  display: flex;
+  align-items: start;
+  justify-content: space-between;
+}
+
+.dialog-header span {
+  color: var(--amber-600);
+  font-size: 11px;
+  font-weight: 700;
+}
+
+.dialog-header h2 {
+  margin: 4px 0 0;
+}
+
+.detail-dialog > p {
+  color: var(--text-500);
+}
+
+.next-step-box {
+  display: grid;
+  gap: 8px;
+  margin: 18px 0;
+  padding: 14px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface-muted);
+}
+
+.next-step-box code {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.sidebar-scrim {
+  display: none;
+}
+
+@media (max-width: 1180px) {
+  :root {
+    --sidebar-width: 196px;
+  }
+
+  .topbar {
+    grid-template-columns: max-content minmax(170px, 240px) 1fr max-content 44px;
+  }
+
+  .updated-state {
+    display: none;
+  }
+
+  .status-strip article {
+    padding: 18px;
+  }
+
+  .summary-icon {
+    width: 48px;
+    height: 48px;
+  }
+
+  .queue-header,
+  .queue-row {
+    grid-template-columns: 70px minmax(210px, 1fr) 80px 26px;
+  }
+
+  .queue-header span:nth-child(4),
+  .queue-time {
+    display: none;
+  }
+
+  .projects-workspace {
+    grid-template-columns: minmax(500px, 1.25fr) minmax(270px, .75fr);
+  }
+}
+
+@media (max-width: 900px) {
+  :root {
+    --sidebar-width: 0px;
+  }
+
+  .sidebar {
+    width: 220px;
+    transform: translateX(-102%);
+    transition: transform 160ms ease;
+  }
+
+  .sidebar.is-open {
+    transform: translateX(0);
+  }
+
+  .sidebar-scrim {
+    position: fixed;
+    inset: 0;
+    z-index: 19;
+    display: block;
+    width: 100%;
+    height: 100%;
+    border: 0;
+    background: rgba(7, 27, 45, .34);
+  }
+
+  .sidebar-scrim[hidden] {
+    display: none;
+  }
+
+  .main-content {
+    margin-left: 0;
+  }
+
+  .mobile-menu {
+    display: inline-flex;
+  }
+
+  .topbar {
+    grid-template-columns: 44px max-content minmax(150px, 1fr) max-content 44px;
+    padding-inline: 16px;
+  }
+
+  .search-control {
+    display: none;
+  }
+
+  .topbar h1 {
+    font-size: 23px;
+  }
+
+  .overview-workspace {
+    grid-template-columns: 1fr;
+  }
+
+  .operations-rail {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+
+  .projects-workspace {
+    grid-template-columns: 1fr;
+  }
+
+  .project-inspector {
+    min-height: 0;
+  }
+
+  .health-grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (max-width: 680px) {
+  .topbar {
+    position: static;
+    grid-template-columns: 44px 1fr max-content;
+    gap: 8px;
+    min-height: 64px;
+    padding: 8px 14px;
+  }
+
+  .topbar h1 {
+    justify-self: center;
+    font-size: 21px;
+  }
+
+  .readonly-state {
+    border: 0;
+    padding: 0;
+  }
+
+  .project-context {
+    grid-column: 1 / 3;
+    grid-row: 2;
+  }
+
+  .topbar > .icon-button:last-child {
+    grid-column: 3;
+    grid-row: 2;
+  }
+
+  .app-view {
+    padding: 12px 14px 18px;
+  }
+
+  .status-banner {
+    margin: 12px 14px 0;
+  }
+
+  .status-strip {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    margin-bottom: 12px;
+  }
+
+  .status-strip article {
+    min-height: 108px;
+    gap: 10px;
+    padding: 14px 12px;
+  }
+
+  .status-strip article:nth-child(2)::after {
+    display: none;
+  }
+
+  .status-strip article:nth-child(-n + 2) {
+    border-bottom: 1px solid var(--line);
+  }
+
+  .summary-icon {
+    width: 42px;
+    height: 42px;
+  }
+
+  .summary-icon .icon {
+    width: 22px;
+    height: 22px;
+  }
+
+  .status-strip strong {
+    font-size: 28px;
+    line-height: 30px;
+  }
+
+  .status-strip b {
+    font-size: 12px;
+  }
+
+  .status-strip small {
+    max-width: 112px;
+    white-space: normal;
+  }
+
+  .overview-workspace {
+    gap: 12px;
+  }
+
+  .surface-heading {
+    min-height: 62px;
+    padding: 12px 14px;
+  }
+
+  .surface-heading h2 {
+    font-size: 16px;
+  }
+
+  .queue-header {
+    display: none;
+  }
+
+  .queue-row {
+    grid-template-columns: 52px minmax(0, 1fr) 24px;
+    gap: 9px;
+    min-height: 86px;
+    padding: 12px 14px;
+  }
+
+  .queue-source,
+  .queue-time {
+    display: none;
+  }
+
+  .queue-copy b,
+  .queue-copy small {
+    white-space: normal;
+  }
+
+  .operations-rail {
+    grid-template-columns: 1fr;
+  }
+
+  .synthetic-notice {
+    margin: 0 14px 18px;
+  }
+
+  .project-table-head {
+    display: none;
+  }
+
+  .project-list-surface,
+  .project-inspector,
+  .full-surface,
+  .settings-surface {
+    min-height: 0;
+  }
+
+  .project-row {
+    grid-template-columns: 1fr max-content;
+    min-height: 78px;
+    padding: 12px 14px;
+  }
+
+  .project-row > :not(.project-name, .text-state:last-child) {
+    display: none;
+  }
+
+  .run-card {
+    grid-template-columns: 1fr 1fr;
+    gap: 12px;
+  }
+
+  .knowledge-flow {
+    grid-template-columns: repeat(2, 1fr);
+    margin: 14px;
+  }
+
+  .knowledge-stage {
+    min-height: 140px;
+    padding: 16px;
+  }
+
+  .lineage-timeline {
+    grid-template-columns: 1fr;
+    gap: 18px;
+    padding: 24px 18px;
+  }
+
+  .lineage-timeline li {
+    grid-template-columns: 42px 1fr max-content;
+    justify-items: start;
+    text-align: left;
+  }
+
+  .lineage-timeline li:not(:last-child)::after {
+    top: 38px;
+    bottom: -18px;
+    left: 18px;
+    width: 2px;
+    height: auto;
+  }
+
+  .boundary-list div {
+    grid-template-columns: 1fr;
+    gap: 4px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    scroll-behavior: auto !important;
+    animation-duration: .01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: .01ms !important;
+  }
+}
diff --git a/plugins/codex-opc-team/assets/app/dashboard.js b/plugins/codex-opc-team/assets/app/dashboard.js
new file mode 100644
index 0000000..02d5ef9
--- /dev/null
+++ b/plugins/codex-opc-team/assets/app/dashboard.js
@@ -0,0 +1,835 @@
+(() => {
+  "use strict";
+
+  const REFRESH_MS = 30_000;
+  const VIEWS = {
+    overview: "总览",
+    projects: "项目",
+    runs: "运行",
+    knowledge: "知识",
+    lineage: "证据链",
+    health: "系统健康",
+    settings: "设置",
+  };
+
+  const state = {
+    snapshot: null,
+    context: null,
+    csrf: "",
+    queue: new Map(),
+    refreshTimer: null,
+  };
+
+  const byId = (id) => document.getElementById(id);
+  const asObject = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const asArray = (value) => Array.isArray(value) ? value : [];
+  const finiteNumber = (value) => Number.isFinite(Number(value)) ? Number(value) : 0;
+
+  function icon(name) {
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.setAttribute("class", "icon");
+    svg.setAttribute("aria-hidden", "true");
+    const use = document.createElementNS("http://www.w3.org/2000/svg", "use");
+    use.setAttribute("href", `#icon-${name}`);
+    svg.append(use);
+    return svg;
+  }
+
+  function setText(id, value) {
+    const node = byId(id);
+    if (node) node.textContent = String(value ?? "");
+  }
+
+  function relativeTime(value) {
+    const timestamp = Date.parse(String(value || ""));
+    if (!Number.isFinite(timestamp)) return "时间未记录";
+    const seconds = Math.max(0, Math.floor((Date.now() - timestamp) / 1000));
+    if (seconds < 60) return `${Math.max(1, seconds)} 秒前`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) return `${minutes} 分钟前`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) return `${hours} 小时前`;
+    return `${Math.floor(hours / 24)} 天前`;
+  }
+
+  function statusLabel(value) {
+    const labels = {
+      aligning: "对齐中",
+      planned: "已规划",
+      implementing: "实现中",
+      validating: "验收中",
+      ready_for_manager: "待经理体验",
+      completed: "已完成",
+      paused: "已暂停",
+      failed: "失败",
+      available: "可用",
+      unavailable: "不可用",
+      degraded: "降级",
+      healthy: "健康",
+      disabled: "已禁用",
+      invalid: "无效",
+      absent: "未配置",
+      high: "高优先级",
+      medium: "中优先级",
+      low: "低优先级",
+    };
+    return labels[String(value || "").toLowerCase()] || String(value || "未知");
+  }
+
+  function tone(value) {
+    const normalized = String(value || "").toLowerCase();
+    if (["completed", "ready_for_manager", "pass", "available", "healthy", "ready", "published", "disabled"].includes(normalized)) return "healthy";
+    if (["failed", "blocked", "invalid", "error"].includes(normalized)) return "blocked";
+    if (["planned", "implementing", "validating", "aligning", "paused", "degraded", "warning", "inconclusive"].includes(normalized)) return "warning";
+    return "neutral";
+  }
+
+  function emptyState(title, description) {
+    const node = document.createElement("div");
+    node.className = "empty-state";
+    node.append(icon("project"));
+    const heading = document.createElement("b");
+    heading.textContent = title;
+    const copy = document.createElement("span");
+    copy.textContent = description;
+    node.append(heading, copy);
+    return node;
+  }
+
+  function selectedRegistryProject() {
+    const context = asObject(state.context);
+    const selected = context.selected_project_id;
+    return asArray(context.projects).find((project) => project.id === selected) || asArray(context.projects)[0] || null;
+  }
+
+  function selectedSnapshotProject() {
+    const selected = selectedRegistryProject();
+    const projects = asArray(asObject(state.snapshot).projects);
+    if (!selected) return projects[0] || null;
+    return projects.find((project) => project.id === selected.project_id) || projects[0] || null;
+  }
+
+  function renderContext() {
+    const context = asObject(state.context);
+    const projects = asArray(context.projects);
+    const select = byId("project-select");
+    select.replaceChildren();
+    if (!projects.length) {
+      const option = document.createElement("option");
+      option.value = "";
+      option.textContent = context.settings_state === "invalid" ? "接入清单不可用" : "尚未接入项目";
+      select.append(option);
+      select.disabled = true;
+    } else {
+      projects.forEach((project) => {
+        const option = document.createElement("option");
+        option.value = project.id;
+        option.textContent = project.name || project.root_label || "未命名项目";
+        option.selected = project.id === context.selected_project_id;
+        select.append(option);
+      });
+      select.disabled = context.settings_state === "demo";
+    }
+    if (context.warning && context.settings_state === "invalid") {
+      showBanner(context.warning.message || "App 接入清单不可用。");
+    }
+    byId("open-project-drawer").disabled = context.settings_state === "invalid";
+  }
+
+  function renderSummary() {
+    const snapshot = asObject(state.snapshot);
+    const summary = asObject(snapshot.summary);
+    setText("stat-projects", finiteNumber(summary.active_projects));
+    setText("stat-acceptance", finiteNumber(summary.pending_acceptance));
+    setText("stat-candidates", finiteNumber(summary.candidates));
+    setText("stat-published", finiteNumber(summary.published));
+    setText("mode-label", snapshot.mode === "demo" ? "演示数据 · 只读" : "本地只读");
+    setText("last-updated", `最后刷新：${relativeTime(snapshot.generated_at)}`);
+    byId("synthetic-notice").hidden = snapshot.mode !== "demo";
+  }
+
+  function queueSource(item) {
+    const mapping = {
+      acceptance: ["run", "运行"],
+      knowledge_publish: ["lineage", "证据链"],
+      knowledge_review: ["knowledge", "知识"],
+      system_health: ["health", "系统健康"],
+      evaluation: ["run", "评测"],
+    };
+    return mapping[item.type] || ["overview", "总览"];
+  }
+
+  function renderQueue() {
+    const queue = asArray(asObject(state.snapshot).manager_queue);
+    const target = byId("queue-list");
+    target.replaceChildren();
+    state.queue.clear();
+    setText("queue-count", `${queue.length} 项`);
+    if (!queue.length) {
+      target.append(emptyState("没有待处理项", "当前快照没有需要经理介入的验收、知识或评测事项。"));
+      return;
+    }
+    queue.forEach((item, index) => {
+      const itemId = String(item.id || `queue-${index + 1}`);
+      state.queue.set(itemId, item);
+      const row = document.createElement("button");
+      row.type = "button";
+      row.className = "queue-row filterable";
+      row.dataset.queueId = itemId;
+      row.setAttribute("aria-label", `查看 ${item.title || "待处理事项"} 的下一步`);
+
+      const priority = document.createElement("span");
+      const severity = String(item.severity || "low").toLowerCase();
+      priority.className = `priority is-${severity}`;
+      priority.textContent = severity === "high" ? "P1" : severity === "medium" ? "P2" : "P3";
+
+      const copy = document.createElement("span");
+      copy.className = "queue-copy";
+      const title = document.createElement("b");
+      title.textContent = item.title || "待处理事项";
+      const description = document.createElement("small");
+      description.textContent = item.description || "查看现有证据并决定下一步。";
+      copy.append(title, description);
+
+      const [iconName, sourceName] = queueSource(item);
+      const source = document.createElement("span");
+      source.className = "queue-source";
+      source.append(icon(iconName));
+      const sourceCopy = document.createElement("span");
+      sourceCopy.textContent = sourceName;
+      source.append(sourceCopy);
+
+      const time = document.createElement("span");
+      time.className = "queue-time";
+      time.textContent = relativeTime(asObject(state.snapshot).generated_at);
+
+      row.append(priority, copy, source, time, icon("chevron"));
+      row.addEventListener("click", () => openQueue(itemId));
+      target.append(row);
+    });
+  }
+
+  function progressStages(status) {
+    const order = ["planned", "implementing", "validating", "ready_for_manager", "completed"];
+    const index = order.indexOf(String(status || ""));
+    return [
+      ["计划", index >= 0],
+      ["执行", index >= 1],
+      ["验证", index >= 2],
+      ["记录", index >= 3],
+    ];
+  }
+
+  function renderCurrentRun() {
+    const target = byId("current-run");
+    target.replaceChildren();
+    const project = selectedSnapshotProject();
+    if (!project) {
+      target.append(emptyState("没有当前运行", "接入项目后，这里会显示其当前运行状态。"));
+      return;
+    }
+    const run = asObject(project.run);
+    const wrapper = document.createElement("div");
+    wrapper.className = "run-summary";
+    const top = document.createElement("div");
+    top.className = "run-summary-top";
+    const names = document.createElement("span");
+    const label = document.createElement("small");
+    label.textContent = "最新运行";
+    const title = document.createElement("b");
+    title.textContent = run.title || "暂无运行";
+    names.append(label, title);
+    const status = document.createElement("span");
+    status.className = `run-status-text is-${tone(run.status)}`;
+    const dot = document.createElement("i");
+    dot.className = "status-dot";
+    const statusCopy = document.createElement("b");
+    statusCopy.textContent = statusLabel(run.status);
+    status.append(dot, statusCopy);
+    top.append(names, status);
+
+    const steps = document.createElement("div");
+    steps.className = "progress-steps";
+    const stages = progressStages(run.status);
+    stages.forEach(([name, complete], index) => {
+      const step = document.createElement("span");
+      step.className = `progress-step${complete ? " is-complete" : index === stages.findIndex((entry) => !entry[1]) ? " is-current" : ""}`;
+      const marker = document.createElement("i");
+      marker.textContent = complete ? "✓" : "";
+      const stepName = document.createElement("b");
+      stepName.textContent = name;
+      const stepState = document.createElement("small");
+      stepState.textContent = complete ? "完成" : index === stages.findIndex((entry) => !entry[1]) ? "进行中" : "待开始";
+      step.append(marker, stepName, stepState);
+      steps.append(step);
+    });
+
+    const next = document.createElement("div");
+    next.className = "run-next";
+    const nextTitle = document.createElement("strong");
+    nextTitle.textContent = "下一步建议";
+    const nextCopy = document.createElement("small");
+    nextCopy.textContent = run.status === "ready_for_manager" ? "由经理体验已通过独立验收的结果。" : "继续按项目契约收集证据并完成独立验收。";
+    next.append(nextTitle, nextCopy);
+    wrapper.append(top, steps, next);
+    target.append(wrapper);
+  }
+
+  function healthEntries() {
+    const health = asObject(asObject(state.snapshot).health);
+    return [
+      ["file_git", "File/Git 权威"],
+      ["mem0", "Mem0（可选）"],
+      ["projects", "项目数据"],
+    ].map(([key, fallback]) => [key, fallback, asObject(health[key])]);
+  }
+
+  function renderOverviewHealth() {
+    const target = byId("overview-health");
+    target.replaceChildren();
+    healthEntries().slice(0, 2).forEach(([, fallback, item]) => {
+      const row = document.createElement("div");
+      row.className = `health-row is-${tone(item.state)}`;
+      const dot = document.createElement("i");
+      dot.className = "status-dot";
+      const name = document.createElement("b");
+      name.textContent = item.label || fallback;
+      const detail = document.createElement("span");
+      detail.textContent = item.detail || statusLabel(item.state);
+      row.append(dot, name, detail);
+      target.append(row);
+    });
+  }
+
+  function snapshotProjectForRegistry(registryProject) {
+    return asArray(asObject(state.snapshot).projects).find((project) => project.id === registryProject.project_id) || null;
+  }
+
+  function renderProjects() {
+    const target = byId("project-list");
+    target.replaceChildren();
+    const projects = asArray(asObject(state.context).projects);
+    setText("project-count", `共 ${projects.length} 个项目`);
+    if (!projects.length) {
+      target.append(emptyState("尚未接入项目", "使用“接入项目”明确添加一个 OPC 项目目录。App 不会扫描磁盘。"));
+      renderInspector(null);
+      return;
+    }
+    projects.forEach((registryProject) => {
+      const project = snapshotProjectForRegistry(registryProject);
+      const run = asObject(asObject(project).run);
+      const acceptance = asObject(asObject(project).acceptance);
+      const total = finiteNumber(acceptance.total);
+      const passed = finiteNumber(acceptance.passed);
+
+      const row = document.createElement("button");
+      row.type = "button";
+      row.className = "project-row filterable";
+      row.dataset.registryId = registryProject.id;
+      if (registryProject.id === asObject(state.context).selected_project_id) row.setAttribute("aria-current", "true");
+
+      const name = document.createElement("span");
+      name.className = "project-name";
+      name.append(icon("project"));
+      const nameCopy = document.createElement("span");
+      const nameStrong = document.createElement("b");
+      nameStrong.textContent = registryProject.name || asObject(project).name || "未命名项目";
+      const rootLabel = document.createElement("small");
+      rootLabel.textContent = registryProject.root_label || "显式目录";
+      nameCopy.append(nameStrong, rootLabel);
+      name.append(nameCopy);
+
+      const runState = stateText(statusLabel(run.status), tone(run.status));
+      const acceptanceText = document.createElement("span");
+      acceptanceText.className = "text-state";
+      acceptanceText.textContent = total ? `${passed} / ${total}` : "未记录";
+      const updated = document.createElement("span");
+      updated.className = "text-state";
+      updated.textContent = relativeTime(run.updated_at || asObject(state.snapshot).generated_at);
+      const sourceState = stateText(
+        registryProject.state === "available" && asObject(project).source_state !== "invalid" ? "正常" : "不可用",
+        registryProject.state === "available" && asObject(project).source_state !== "invalid" ? "healthy" : "blocked",
+      );
+      row.append(name, runState, acceptanceText, updated, sourceState);
+      row.addEventListener("click", async () => {
+        await selectProject(registryProject.id);
+      });
+      target.append(row);
+    });
+    renderInspector(selectedRegistryProject());
+    applySearch();
+  }
+
+  function stateText(label, stateTone) {
+    const node = document.createElement("span");
+    node.className = `text-state is-${stateTone}`;
+    const dot = document.createElement("i");
+    dot.className = "status-dot";
+    const copy = document.createElement("span");
+    copy.textContent = label;
+    node.append(dot, copy);
+    return node;
+  }
+
+  function renderInspector(registryProject) {
+    const target = byId("project-inspector");
+    target.replaceChildren();
+    if (!registryProject) {
+      target.append(emptyState("未选择项目", "接入并选择项目后，这里会显示脱敏状态。"));
+      return;
+    }
+    const project = snapshotProjectForRegistry(registryProject);
+    const run = asObject(asObject(project).run);
+    const acceptance = asObject(asObject(project).acceptance);
+
+    const header = document.createElement("header");
+    header.className = "inspector-header";
+    header.append(icon("project"));
+    const heading = document.createElement("span");
+    const title = document.createElement("b");
+    title.textContent = registryProject.name || "未命名项目";
+    const status = document.createElement("small");
+    status.textContent = registryProject.state === "available" ? "显式接入 · 只读" : "项目不可读 · 已降级";
+    heading.append(title, status);
+    header.append(heading);
+
+    const projectState = document.createElement("section");
+    projectState.className = "inspector-section";
+    const projectStateTitle = document.createElement("h3");
+    projectStateTitle.textContent = "项目状态";
+    const facts = document.createElement("dl");
+    [
+      ["当前运行", statusLabel(run.status)],
+      ["独立验收", acceptance.total ? `${finiteNumber(acceptance.passed)} / ${finiteNumber(acceptance.total)}` : "未记录"],
+      ["最近更新", relativeTime(run.updated_at || asObject(state.snapshot).generated_at)],
+    ].forEach(([term, description]) => {
+      const row = document.createElement("div");
+      const dt = document.createElement("dt");
+      dt.textContent = term;
+      const dd = document.createElement("dd");
+      dd.textContent = description;
+      row.append(dt, dd);
+      facts.append(row);
+    });
+    projectState.append(projectStateTitle, facts);
+
+    const boundary = document.createElement("section");
+    boundary.className = "inspector-section";
+    const boundaryTitle = document.createElement("h3");
+    boundaryTitle.textContent = "数据边界";
+    const boundaryCopy = document.createElement("p");
+    boundaryCopy.textContent = `${registryProject.root_label || "显式目录"} · 仅从此项目读取固定字段，不访问其他位置。`;
+    boundary.append(boundaryTitle, boundaryCopy);
+
+    const actions = document.createElement("div");
+    actions.className = "inspector-actions";
+    const switchButton = document.createElement("button");
+    switchButton.type = "button";
+    switchButton.className = "secondary-button";
+    switchButton.textContent = "切换到此项目";
+    switchButton.disabled = registryProject.id === asObject(state.context).selected_project_id;
+    switchButton.addEventListener("click", () => selectProject(registryProject.id));
+    const removeButton = document.createElement("button");
+    removeButton.type = "button";
+    removeButton.className = "danger-button";
+    removeButton.append(icon("trash"));
+    const removeCopy = document.createElement("span");
+    removeCopy.textContent = "移除接入";
+    removeButton.append(removeCopy);
+    removeButton.disabled = asObject(state.context).settings_state !== "ready";
+    removeButton.addEventListener("click", () => removeProject(registryProject.id));
+    actions.append(switchButton, removeButton);
+
+    const note = document.createElement("p");
+    note.className = "preservation-note";
+    note.textContent = "移除接入不会删除项目 .opc、File/Git 知识、Git 历史、用户配置或 Mem0 数据；只会从 App 清单移除此目录。";
+    target.append(header, projectState, boundary, actions, note);
+  }
+
+  function renderRuns() {
+    const target = byId("run-list");
+    target.replaceChildren();
+    const projects = asArray(asObject(state.snapshot).projects);
+    setText("run-count", `${projects.length} 个`);
+    if (!projects.length) {
+      target.append(emptyState("没有当前运行", "接入项目后，这里会显示其当前运行状态。"));
+      return;
+    }
+    projects.forEach((project) => {
+      const run = asObject(project.run);
+      const acceptance = asObject(project.acceptance);
+      const card = document.createElement("article");
+      card.className = "run-card filterable";
+      [
+        [run.title || "当前运行", project.name || project.id || "未命名项目"],
+        [statusLabel(run.status), run.active === false ? "非活动" : "活动"],
+        [acceptance.total ? `${finiteNumber(acceptance.passed)} / ${finiteNumber(acceptance.total)}` : "未记录", "独立验收"],
+        [relativeTime(run.updated_at || asObject(state.snapshot).generated_at), "最近更新"],
+      ].forEach(([primary, secondary]) => {
+        const item = document.createElement("span");
+        const strong = document.createElement("b");
+        strong.textContent = primary;
+        const small = document.createElement("small");
+        small.textContent = secondary;
+        item.append(strong, small);
+        card.append(item);
+      });
+      target.append(card);
+    });
+  }
+
+  function renderKnowledge() {
+    const target = byId("knowledge-flow");
+    target.replaceChildren();
+    const knowledge = asObject(asObject(state.snapshot).knowledge);
+    const stages = [
+      ["Candidate", finiteNumber(knowledge.candidate), "等待经理验证"],
+      ["Approved", finiteNumber(knowledge.approved_uncommitted), "尚无 current HEAD provenance"],
+      ["Published", finiteNumber(knowledge.published), "current HEAD 可验证"],
+      ["Obsolete", finiteNumber(knowledge.obsolete), "已失效但保留历史"],
+    ];
+    stages.forEach(([label, count, detail]) => {
+      const stage = document.createElement("article");
+      stage.className = "knowledge-stage filterable";
+      const value = document.createElement("strong");
+      value.textContent = count;
+      const title = document.createElement("b");
+      title.textContent = label;
+      const description = document.createElement("small");
+      description.textContent = detail;
+      stage.append(value, title, description);
+      target.append(stage);
+    });
+    setText("knowledge-candidate", `${finiteNumber(knowledge.candidate)} 条等待治理`);
+    setText("knowledge-approved", `${finiteNumber(knowledge.approved_uncommitted)} 条尚未闭环`);
+    setText("knowledge-published", `${finiteNumber(knowledge.published)} 条可验证知识`);
+  }
+
+  function renderLineage() {
+    const project = selectedSnapshotProject();
+    const stages = [...document.querySelectorAll("#lineage-timeline li")];
+    stages.forEach((stage) => {
+      stage.classList.remove("is-recorded", "is-warning");
+      stage.querySelector("em").textContent = "未记录";
+    });
+    if (!project) {
+      setText("lineage-project-label", "选择项目查看证据状态");
+      return;
+    }
+    const run = asObject(project.run);
+    const status = String(run.status || "");
+    const feedback = String(project.feedback_status || "unavailable");
+    const recorded = {
+      context: Boolean(run.title),
+      developer: ["implementing", "validating", "ready_for_manager", "completed"].includes(status),
+      qa: ["validating", "ready_for_manager", "completed"].includes(status),
+      feedback: !["unavailable", "absent", ""].includes(feedback),
+      outcome: ["ready_for_manager", "completed"].includes(status),
+    };
+    stages.forEach((stage) => {
+      const key = stage.dataset.stage;
+      if (recorded[key]) {
+        stage.classList.add("is-recorded");
+        stage.querySelector("em").textContent = "已记录";
+      } else if (key === "feedback" && feedback === "degraded") {
+        stage.classList.add("is-warning");
+        stage.querySelector("em").textContent = "已降级";
+      }
+    });
+    setText("lineage-project-label", `${project.name || project.id || "当前项目"} · ${statusLabel(project.lineage_status)}`);
+  }
+
+  function renderHealth() {
+    const target = byId("health-list");
+    target.replaceChildren();
+    healthEntries().forEach(([, fallback, item]) => {
+      const card = document.createElement("article");
+      card.className = `health-card is-${tone(item.state)} filterable`;
+      const heading = document.createElement("header");
+      heading.append(icon("health"));
+      const title = document.createElement("b");
+      title.textContent = item.label || fallback;
+      heading.append(title);
+      const status = document.createElement("p");
+      status.textContent = `状态：${statusLabel(item.state)}`;
+      const detail = document.createElement("p");
+      detail.textContent = item.detail || "未提供状态详情。";
+      card.append(heading, status, detail);
+      target.append(card);
+    });
+  }
+
+  function renderWarnings() {
+    const warnings = asArray(asObject(state.snapshot).warnings)
+      .map((item) => typeof item === "string" ? item : asObject(item).message)
+      .filter(Boolean);
+    if (warnings.length && asObject(state.snapshot).mode !== "demo") showBanner(warnings.slice(0, 3).join("；"));
+    else if (asObject(state.context).settings_state !== "invalid") hideBanner();
+  }
+
+  function renderAll() {
+    renderContext();
+    renderSummary();
+    renderQueue();
+    renderCurrentRun();
+    renderOverviewHealth();
+    renderProjects();
+    renderRuns();
+    renderKnowledge();
+    renderLineage();
+    renderHealth();
+    renderWarnings();
+    applySearch();
+    setText("live-status", "OPC App 本地状态已刷新");
+  }
+
+  async function fetchJSON(path, options = {}) {
+    const response = await fetch(path, {
+      cache: "no-store",
+      credentials: "same-origin",
+      ...options,
+      headers: {
+        Accept: "application/json",
+        ...(options.headers || {}),
+      },
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      const error = new Error(payload.error || `HTTP_${response.status}`);
+      error.code = payload.error || `HTTP_${response.status}`;
+      throw error;
+    }
+    return payload;
+  }
+
+  async function refresh() {
+    byId("refresh-button").disabled = true;
+    try {
+      const [context, snapshot] = await Promise.all([
+        fetchJSON("/api/app-context"),
+        fetchJSON("/api/snapshot"),
+      ]);
+      state.context = context;
+      state.snapshot = snapshot;
+      state.csrf = String(context.csrf_token || "");
+      renderAll();
+    } catch (error) {
+      showBanner("无法读取本地 App 状态。请查看启动终端中的安全诊断信息。");
+      setText("last-updated", "读取失败");
+      setText("live-status", "OPC App 本地状态读取失败");
+    } finally {
+      byId("refresh-button").disabled = false;
+    }
+  }
+
+  async function mutate(path, method, body) {
+    const options = {
+      method,
+      headers: {
+        "X-OPC-CSRF": state.csrf,
+      },
+    };
+    if (body !== undefined) {
+      options.headers["Content-Type"] = "application/json";
+      options.body = JSON.stringify(body);
+    }
+    const context = await fetchJSON(path, options);
+    state.context = context;
+    state.csrf = String(context.csrf_token || state.csrf);
+    await refresh();
+  }
+
+  function errorMessage(code) {
+    const mapping = {
+      ABSOLUTE_PROJECT_ROOT_REQUIRED: "请输入项目的绝对目录。",
+      PROJECT_UNAVAILABLE: "目录不可读取或不存在。",
+      UNSAFE_PROJECT_ROOT: "目录是链接或不安全的来源，已拒绝接入。",
+      INVALID_OPC_PROJECT: "目录中没有有效的 .opc/project.json。",
+      PROJECT_ALREADY_REGISTERED: "此项目已经接入。",
+      PROJECT_LIMIT_REACHED: "显式项目数量已达到上限。",
+      INVALID_SETTINGS: "App 接入清单损坏；为避免覆盖，已拒绝写入。",
+      CSRF_FORBIDDEN: "本地会话已变化，请刷新后重试。",
+      DEMO_SETTINGS_READ_ONLY: "演示模式不写入 App 设置。",
+    };
+    return mapping[code] || "操作未完成；本地设置保持不变。";
+  }
+
+  async function selectProject(itemId) {
+    if (!itemId || asObject(state.context).settings_state !== "ready") return;
+    try {
+      await mutate("/api/selection", "POST", { project_id: itemId });
+    } catch (error) {
+      showBanner(errorMessage(error.code));
+    }
+  }
+
+  async function removeProject(itemId) {
+    if (!itemId) return;
+    try {
+      await mutate(`/api/projects/${encodeURIComponent(itemId)}`, "DELETE");
+      setText("live-status", "项目已从 App 接入清单移除；项目与知识数据均未删除");
+    } catch (error) {
+      showBanner(errorMessage(error.code));
+    }
+  }
+
+  function openProjectDrawer() {
+    if (asObject(state.context).settings_state === "invalid") return;
+    const dialog = byId("project-drawer");
+    byId("project-path").value = "";
+    byId("project-form-error").hidden = true;
+    dialog.showModal();
+    byId("project-path").focus();
+  }
+
+  function closeProjectDrawer() {
+    byId("project-drawer").close();
+  }
+
+  async function saveProject() {
+    const path = byId("project-path").value.trim();
+    const errorNode = byId("project-form-error");
+    errorNode.hidden = true;
+    byId("save-project").disabled = true;
+    try {
+      await mutate("/api/projects", "POST", { path });
+      closeProjectDrawer();
+      window.location.hash = "#projects";
+      setText("live-status", "项目已显式接入 OPC App");
+    } catch (error) {
+      errorNode.textContent = errorMessage(error.code);
+      errorNode.hidden = false;
+    } finally {
+      byId("save-project").disabled = false;
+    }
+  }
+
+  function openQueue(itemId) {
+    const item = state.queue.get(itemId);
+    if (!item) return;
+    setText("queue-dialog-severity", statusLabel(item.severity || "medium"));
+    setText("queue-dialog-title", item.title || "下一步");
+    setText("queue-dialog-description", item.description || "请查看现有证据后决定下一步。");
+    setText("queue-dialog-next-step", item.next_step || "使用对应 OPC Skill 查看详情。");
+    byId("queue-dialog").showModal();
+  }
+
+  function resolveView(value) {
+    const candidate = String(value || "").replace(/^#/, "");
+    return Object.prototype.hasOwnProperty.call(VIEWS, candidate) ? candidate : "overview";
+  }
+
+  function activateView(value) {
+    const viewName = resolveView(value);
+    document.querySelectorAll(".app-view").forEach((view) => {
+      const selected = view.dataset.view === viewName;
+      view.hidden = !selected;
+      view.classList.toggle("is-active", selected);
+    });
+    document.querySelectorAll(".nav-item[data-nav]").forEach((item) => {
+      const selected = item.dataset.nav === viewName;
+      item.classList.toggle("is-active", selected);
+      if (selected) item.setAttribute("aria-current", "page");
+      else item.removeAttribute("aria-current");
+    });
+    setText("view-title", VIEWS[viewName]);
+    document.title = `${VIEWS[viewName]} · OPC`;
+    closeMobileMenu();
+    applySearch();
+    window.scrollTo({ top: 0, behavior: "auto" });
+  }
+
+  function applySearch() {
+    const query = byId("global-search").value.trim().toLocaleLowerCase("zh-CN");
+    const active = document.querySelector(".app-view:not([hidden])");
+    if (!active) return;
+    active.querySelectorAll(".filterable").forEach((node) => {
+      node.hidden = Boolean(query) && !node.textContent.toLocaleLowerCase("zh-CN").includes(query);
+    });
+  }
+
+  function openMobileMenu() {
+    byId("sidebar").classList.add("is-open");
+    byId("sidebar-scrim").hidden = false;
+    byId("mobile-menu").setAttribute("aria-expanded", "true");
+  }
+
+  function closeMobileMenu() {
+    byId("sidebar").classList.remove("is-open");
+    byId("sidebar-scrim").hidden = true;
+    byId("mobile-menu").setAttribute("aria-expanded", "false");
+  }
+
+  function showBanner(message) {
+    const banner = byId("error-banner");
+    banner.textContent = message;
+    banner.hidden = false;
+  }
+
+  function hideBanner() {
+    const banner = byId("error-banner");
+    banner.hidden = true;
+    banner.textContent = "";
+  }
+
+  function setupEvents() {
+    document.querySelectorAll(".nav-item[data-nav]").forEach((item) => {
+      item.addEventListener("click", (event) => {
+        event.preventDefault();
+        const hash = `#${item.dataset.nav}`;
+        if (window.location.hash === hash) activateView(hash);
+        else window.location.hash = hash;
+      });
+    });
+    window.addEventListener("hashchange", () => activateView(window.location.hash));
+    byId("global-search").addEventListener("input", applySearch);
+    document.addEventListener("keydown", (event) => {
+      if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === "f") {
+        event.preventDefault();
+        byId("global-search").focus();
+      }
+      if (event.key === "Escape") closeMobileMenu();
+    });
+    byId("project-select").addEventListener("change", (event) => selectProject(event.target.value));
+    byId("refresh-button").addEventListener("click", refresh);
+    byId("mobile-menu").addEventListener("click", () => {
+      if (byId("sidebar").classList.contains("is-open")) closeMobileMenu();
+      else openMobileMenu();
+    });
+    byId("sidebar-scrim").addEventListener("click", closeMobileMenu);
+    byId("open-project-drawer").addEventListener("click", openProjectDrawer);
+    byId("manage-projects-from-settings").addEventListener("click", () => {
+      window.location.hash = "#projects";
+      openProjectDrawer();
+    });
+    byId("close-project-drawer").addEventListener("click", closeProjectDrawer);
+    byId("cancel-project").addEventListener("click", closeProjectDrawer);
+    byId("save-project").addEventListener("click", saveProject);
+    byId("project-path").addEventListener("keydown", (event) => {
+      if (event.key === "Enter") saveProject();
+    });
+    byId("close-queue-dialog").addEventListener("click", () => byId("queue-dialog").close());
+    byId("copy-next-step").addEventListener("click", async () => {
+      try {
+        await navigator.clipboard.writeText(byId("queue-dialog-next-step").textContent);
+        setText("live-status", "下一步建议已复制");
+      } catch (error) {
+        setText("live-status", "浏览器未允许复制；请手动选择文本");
+      }
+    });
+  }
+
+  function scheduleRefresh() {
+    window.clearInterval(state.refreshTimer);
+    state.refreshTimer = window.setInterval(() => {
+      if (document.visibilityState === "visible") refresh();
+    }, REFRESH_MS);
+  }
+
+  setupEvents();
+  const initialView = resolveView(window.location.hash);
+  if (window.location.hash !== `#${initialView}`) window.history.replaceState(null, "", `#${initialView}`);
+  activateView(initialView);
+  refresh();
+  scheduleRefresh();
+})();
diff --git a/plugins/codex-opc-team/assets/app/index.html b/plugins/codex-opc-team/assets/app/index.html
new file mode 100644
index 0000000..9047752
--- /dev/null
+++ b/plugins/codex-opc-team/assets/app/index.html
@@ -0,0 +1,215 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light">
+  <meta name="theme-color" content="#071b2d">
+  <title>总览 · OPC</title>
+  <link rel="stylesheet" href="/dashboard.css">
+</head>
+<body>
+  <svg class="icon-sprite" aria-hidden="true">
+    <symbol id="icon-logo" viewBox="0 0 24 24"><path d="m12 2.8 8 4.6v9.2l-8 4.6-8-4.6V7.4z"/></symbol>
+    <symbol id="icon-overview" viewBox="0 0 24 24"><path d="M4 10.5 12 4l8 6.5V20H4z"/><path d="M9 20v-6h6v6"/></symbol>
+    <symbol id="icon-project" viewBox="0 0 24 24"><path d="M3.5 6.5h6l2 2H20.5V20H3.5z"/><path d="M3.5 6.5V4h6l2 2"/></symbol>
+    <symbol id="icon-run" viewBox="0 0 24 24"><rect x="3.5" y="4" width="17" height="16" rx="2"/><path d="m8 15 3-3-3-3M13 16h4"/></symbol>
+    <symbol id="icon-knowledge" viewBox="0 0 24 24"><path d="M5 4.5h11a3 3 0 0 1 3 3V20H8a3 3 0 0 1-3-3z"/><path d="M8 4.5V20M11 8h5M11 12h5"/></symbol>
+    <symbol id="icon-lineage" viewBox="0 0 24 24"><circle cx="6" cy="12" r="2.5"/><circle cx="18" cy="6" r="2.5"/><circle cx="18" cy="18" r="2.5"/><path d="m8.5 11 7-3.5M8.5 13l7 3.5"/></symbol>
+    <symbol id="icon-health" viewBox="0 0 24 24"><path d="M12 3 20 7v5c0 5-3.4 8-8 9-4.6-1-8-4-8-9V7z"/><path d="m8.5 12 2.2 2.2L15.8 9"/></symbol>
+    <symbol id="icon-settings" viewBox="0 0 24 24"><circle cx="12" cy="12" r="3"/><path d="M19 13.5v-3l-2-.7-.8-1.8.9-1.9L15 4l-1.9.9-1.9-.8-.7-2h-3l-.7 2-1.8.8L3.1 4 1 6.1 1.9 8l-.8 1.8-2 .7v3l2 .7.8 1.8-.9 1.9L3.1 20l1.9-.9 1.8.8.7 2h3l.7-2 1.9-.8 1.9.9 2.1-2.1-.9-1.9.8-1.8z" transform="translate(2) scale(.83)"/></symbol>
+    <symbol id="icon-search" viewBox="0 0 24 24"><circle cx="10.5" cy="10.5" r="6.5"/><path d="m15.5 15.5 5 5"/></symbol>
+    <symbol id="icon-refresh" viewBox="0 0 24 24"><path d="M20 7v5h-5"/><path d="M18.5 16a8 8 0 1 1 1.1-8.2L20 12"/></symbol>
+    <symbol id="icon-clock" viewBox="0 0 24 24"><circle cx="12" cy="12" r="8.5"/><path d="M12 7v5l3 2"/></symbol>
+    <symbol id="icon-check" viewBox="0 0 24 24"><circle cx="12" cy="12" r="8.5"/><path d="m8 12 2.5 2.5L16 9"/></symbol>
+    <symbol id="icon-alert" viewBox="0 0 24 24"><path d="M12 4 21 20H3z"/><path d="M12 9v5M12 17.5v.1"/></symbol>
+    <symbol id="icon-copy" viewBox="0 0 24 24"><rect x="8" y="8" width="11" height="12" rx="2"/><path d="M16 8V5a2 2 0 0 0-2-2H5a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h3"/></symbol>
+    <symbol id="icon-plus" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9"/><path d="M12 8v8M8 12h8"/></symbol>
+    <symbol id="icon-close" viewBox="0 0 24 24"><path d="m6 6 12 12M18 6 6 18"/></symbol>
+    <symbol id="icon-chevron" viewBox="0 0 24 24"><path d="m9 5 7 7-7 7"/></symbol>
+    <symbol id="icon-menu" viewBox="0 0 24 24"><path d="M4 6h16M4 12h16M4 18h16"/></symbol>
+    <symbol id="icon-trash" viewBox="0 0 24 24"><path d="M4 7h16M9 7V4h6v3M7 7l1 14h8l1-14M10 11v6M14 11v6"/></symbol>
+  </svg>
+
+  <div class="app-shell">
+    <aside class="sidebar" id="sidebar">
+      <div class="brand"><svg class="brand-logo" aria-hidden="true"><use href="#icon-logo"></use></svg><span>OPC</span></div>
+      <nav class="primary-nav" aria-label="主要导航">
+        <a class="nav-item is-active" href="#overview" data-nav="overview"><svg class="icon" aria-hidden="true"><use href="#icon-overview"></use></svg><span>总览</span></a>
+        <a class="nav-item" href="#projects" data-nav="projects"><svg class="icon" aria-hidden="true"><use href="#icon-project"></use></svg><span>项目</span></a>
+        <a class="nav-item" href="#runs" data-nav="runs"><svg class="icon" aria-hidden="true"><use href="#icon-run"></use></svg><span>运行</span></a>
+        <a class="nav-item" href="#knowledge" data-nav="knowledge"><svg class="icon" aria-hidden="true"><use href="#icon-knowledge"></use></svg><span>知识</span></a>
+        <a class="nav-item" href="#lineage" data-nav="lineage"><svg class="icon" aria-hidden="true"><use href="#icon-lineage"></use></svg><span>证据链</span></a>
+        <a class="nav-item" href="#health" data-nav="health"><svg class="icon" aria-hidden="true"><use href="#icon-health"></use></svg><span>系统健康</span></a>
+      </nav>
+      <a class="nav-item utility-nav" href="#settings" data-nav="settings"><svg class="icon" aria-hidden="true"><use href="#icon-settings"></use></svg><span>设置</span></a>
+      <div class="privacy-note">
+        <strong><svg class="icon" aria-hidden="true"><use href="#icon-health"></use></svg>本地优先 · 隐私安全</strong>
+        <span>所有数据仅保留在本地环境</span>
+      </div>
+    </aside>
+    <button class="sidebar-scrim" id="sidebar-scrim" type="button" aria-label="关闭导航" hidden></button>
+
+    <main class="main-content">
+      <header class="topbar">
+        <button class="icon-button mobile-menu" id="mobile-menu" type="button" aria-label="打开导航" aria-controls="sidebar" aria-expanded="false">
+          <svg class="icon" aria-hidden="true"><use href="#icon-menu"></use></svg>
+        </button>
+        <h1 id="view-title">总览</h1>
+        <label class="project-context">
+          <span class="sr-only">当前项目</span>
+          <svg class="icon" aria-hidden="true"><use href="#icon-project"></use></svg>
+          <select id="project-select" aria-label="当前项目">
+            <option value="">尚未接入项目</option>
+          </select>
+        </label>
+        <label class="search-control">
+          <svg class="icon" aria-hidden="true"><use href="#icon-search"></use></svg>
+          <input id="global-search" type="search" placeholder="搜索或筛选…（Ctrl+F）" autocomplete="off">
+        </label>
+        <div class="readonly-state"><svg class="icon" aria-hidden="true"><use href="#icon-health"></use></svg><span id="mode-label">本地只读</span></div>
+        <span class="updated-state" id="last-updated">正在读取…</span>
+        <button class="icon-button" id="refresh-button" type="button" aria-label="刷新本地状态">
+          <svg class="icon" aria-hidden="true"><use href="#icon-refresh"></use></svg>
+        </button>
+      </header>
+
+      <div class="status-banner" id="error-banner" role="alert" hidden></div>
+
+      <section class="app-view is-active" id="overview" data-view="overview" aria-labelledby="view-title">
+        <section class="status-strip" aria-label="关键状态">
+          <article><span class="summary-icon is-cyan"><svg class="icon" aria-hidden="true"><use href="#icon-project"></use></svg></span><div><strong id="stat-projects">—</strong><b>活动项目</b><small>正在投入的进行中项目</small></div></article>
+          <article><span class="summary-icon is-amber"><svg class="icon" aria-hidden="true"><use href="#icon-run"></use></svg></span><div><strong id="stat-acceptance">—</strong><b>待独立验收</b><small>尚未闭环的验收项</small></div></article>
+          <article><span class="summary-icon is-cyan"><svg class="icon" aria-hidden="true"><use href="#icon-knowledge"></use></svg></span><div><strong id="stat-candidates">—</strong><b>知识候选</b><small>等待治理的记录</small></div></article>
+          <article><span class="summary-icon is-green"><svg class="icon" aria-hidden="true"><use href="#icon-check"></use></svg></span><div><strong id="stat-published">—</strong><b>Published</b><small>current-HEAD 可验证知识</small></div></article>
+        </section>
+
+        <div class="overview-workspace">
+          <section class="surface queue-surface" aria-labelledby="queue-heading">
+            <header class="surface-heading"><div><h2 id="queue-heading">待经理处理</h2><p>只读视图下一步，不代替独立决策</p></div><span id="queue-count">0 项</span></header>
+            <div class="queue-header" aria-hidden="true"><span>优先级</span><span>事项与下一步建议</span><span>来源</span><span>检测时间</span><span></span></div>
+            <div class="queue-list" id="queue-list" aria-live="polite"></div>
+          </section>
+
+          <aside class="operations-rail">
+            <section class="surface compact-surface" aria-labelledby="current-run-heading">
+              <header class="surface-heading"><h2 id="current-run-heading">当前运行状态</h2></header>
+              <div id="current-run"></div>
+            </section>
+            <section class="surface compact-surface" aria-labelledby="governance-heading">
+              <header class="surface-heading"><h2 id="governance-heading">知识治理状态</h2></header>
+              <dl class="metric-list">
+                <div><dt>知识候选</dt><dd id="knowledge-candidate">0 条等待治理</dd></div>
+                <div><dt>待独立验收</dt><dd id="knowledge-approved">0 条尚未闭环</dd></div>
+                <div><dt>已 Published</dt><dd id="knowledge-published">0 条可验证知识</dd></div>
+              </dl>
+              <a class="section-link" href="#knowledge">查看知识<svg class="icon" aria-hidden="true"><use href="#icon-chevron"></use></svg></a>
+            </section>
+            <section class="surface compact-surface" aria-labelledby="local-health-heading">
+              <header class="surface-heading"><h2 id="local-health-heading">本地运行环境健康</h2></header>
+              <div class="health-list" id="overview-health"></div>
+            </section>
+          </aside>
+        </div>
+      </section>
+
+      <section class="app-view" id="projects" data-view="projects" aria-labelledby="view-title" hidden>
+        <div class="projects-workspace">
+          <section class="surface project-list-surface">
+            <header class="surface-heading">
+              <div><h2>显式接入的项目</h2><p>只读取你明确接入的目录，不扫描磁盘</p></div>
+              <button class="primary-button" id="open-project-drawer" type="button"><svg class="icon" aria-hidden="true"><use href="#icon-plus"></use></svg>接入项目</button>
+            </header>
+            <div class="project-table-head" aria-hidden="true"><span>项目</span><span>当前运行</span><span>独立验收</span><span>最近更新</span><span>状态</span></div>
+            <div class="project-list" id="project-list" aria-live="polite"></div>
+            <p class="list-footer" id="project-count">共 0 个项目</p>
+          </section>
+          <aside class="surface project-inspector" id="project-inspector" aria-live="polite"></aside>
+        </div>
+      </section>
+
+      <section class="app-view" id="runs" data-view="runs" aria-labelledby="view-title" hidden>
+        <section class="surface full-surface">
+          <header class="surface-heading"><div><h2>当前运行</h2><p>只显示显式接入项目的当前运行，不推断完整历史</p></div><span id="run-count">0 个</span></header>
+          <div class="run-list" id="run-list"></div>
+        </section>
+      </section>
+
+      <section class="app-view" id="knowledge" data-view="knowledge" aria-labelledby="view-title" hidden>
+        <section class="surface full-surface">
+          <header class="surface-heading"><div><h2>知识治理</h2><p>状态与 Git provenance 分开呈现</p></div></header>
+          <div class="knowledge-flow" id="knowledge-flow"></div>
+          <p class="surface-note">Candidate 不会自动晋升；只有 current File/Git HEAD 可验证的 approved 条目才是 Published。</p>
+        </section>
+      </section>
+
+      <section class="app-view" id="lineage" data-view="lineage" aria-labelledby="view-title" hidden>
+        <section class="surface full-surface">
+          <header class="surface-heading"><div><h2>知识使用证据链</h2><p id="lineage-project-label">选择项目查看证据状态</p></div><span>association / evidence only</span></header>
+          <ol class="lineage-timeline" id="lineage-timeline">
+            <li data-stage="context"><span>1</span><div><b>Context</b><small>上下文与召回证据</small></div><em>未记录</em></li>
+            <li data-stage="developer"><span>2</span><div><b>Developer</b><small>实现阶段</small></div><em>未记录</em></li>
+            <li data-stage="qa"><span>3</span><div><b>Independent QA</b><small>独立验收</small></div><em>未记录</em></li>
+            <li data-stage="feedback"><span>4</span><div><b>Feedback</b><small>结构化反馈</small></div><em>未记录</em></li>
+            <li data-stage="outcome"><span>5</span><div><b>Outcome</b><small>结果关联</small></div><em>未记录</em></li>
+          </ol>
+          <p class="surface-note">链路只证明可验证关联，不证明知识被采用或造成结果。</p>
+        </section>
+      </section>
+
+      <section class="app-view" id="health" data-view="health" aria-labelledby="view-title" hidden>
+        <section class="surface full-surface">
+          <header class="surface-heading"><div><h2>系统健康</h2><p>File/Git 为权威；可选 Provider 故障时安全降级</p></div></header>
+          <div class="health-grid" id="health-list"></div>
+        </section>
+      </section>
+
+      <section class="app-view" id="settings" data-view="settings" aria-labelledby="view-title" hidden>
+        <section class="surface settings-surface">
+          <header class="surface-heading"><div><h2>App 设置</h2><p>这里只管理 OPC App 自有、可删除重建的本地状态</p></div></header>
+          <dl class="boundary-list">
+            <div><dt>项目接入</dt><dd>仅显式目录；不会扫描磁盘</dd></div>
+            <div><dt>治理业务 API</dt><dd>只读；批准、晋升、提交、删除与部署仍走现有流程</dd></div>
+            <div><dt>事实来源</dt><dd>File/Git authoritative；App 设置不是组织知识</dd></div>
+            <div><dt>Agent Harness</dt><dd>不在 App 内运行模型、工具或 Agent 会话</dd></div>
+          </dl>
+          <button class="secondary-button" id="manage-projects-from-settings" type="button">管理显式项目</button>
+        </section>
+      </section>
+
+      <div class="synthetic-notice" id="synthetic-notice" hidden>
+        <svg class="icon" aria-hidden="true"><use href="#icon-alert"></use></svg>
+        <span>本地状态提示：当前为合成演示数据，不代表真实组织状态。</span>
+      </div>
+      <p class="live-status sr-only" id="live-status" aria-live="polite"></p>
+    </main>
+  </div>
+
+  <dialog class="drawer" id="project-drawer" aria-labelledby="project-drawer-title">
+    <div class="drawer-header"><h2 id="project-drawer-title">接入本地项目</h2><button class="icon-button" id="close-project-drawer" type="button" aria-label="关闭接入项目"><svg class="icon" aria-hidden="true"><use href="#icon-close"></use></svg></button></div>
+    <div class="drawer-body">
+      <label class="field-label" for="project-path">项目目录</label>
+      <input class="text-field" id="project-path" type="text" autocomplete="off" placeholder="输入项目的绝对目录">
+      <p class="field-help">仅添加此目录，不扫描其他位置。目录必须包含有效的 <code>.opc/project.json</code>。</p>
+      <section class="validation-preview" aria-label="验证预期">
+        <h3>验证预览（只读检查）</h3>
+        <p><svg class="icon" aria-hidden="true"><use href="#icon-check"></use></svg><span><b>可读取</b><small>仅验证输入的目录</small></span></p>
+        <p><svg class="icon" aria-hidden="true"><use href="#icon-check"></use></svg><span><b>OPC 契约已识别</b><small>校验项目 ID 与名称</small></span></p>
+        <p><svg class="icon" aria-hidden="true"><use href="#icon-check"></use></svg><span><b>不会写入项目</b><small>只更新 App 自有接入清单</small></span></p>
+      </section>
+      <div class="drawer-notice"><svg class="icon" aria-hidden="true"><use href="#icon-health"></use></svg><span>接入是 App 级设置，也不会修改项目内容。</span></div>
+      <p class="field-error" id="project-form-error" role="alert" hidden></p>
+    </div>
+    <div class="drawer-actions"><button class="secondary-button" id="cancel-project" type="button">取消</button><button class="primary-button" id="save-project" type="button">验证并接入</button></div>
+  </dialog>
+
+  <dialog class="detail-dialog" id="queue-dialog" aria-labelledby="queue-dialog-title">
+    <div class="dialog-header"><div><span id="queue-dialog-severity">待处理</span><h2 id="queue-dialog-title">下一步</h2></div><button class="icon-button" id="close-queue-dialog" type="button" aria-label="关闭详情"><svg class="icon" aria-hidden="true"><use href="#icon-close"></use></svg></button></div>
+    <p id="queue-dialog-description"></p>
+    <div class="next-step-box"><strong>受控下一步</strong><code id="queue-dialog-next-step"></code></div>
+    <button class="secondary-button" id="copy-next-step" type="button"><svg class="icon" aria-hidden="true"><use href="#icon-copy"></use></svg>复制下一步建议</button>
+  </dialog>
+
+  <script src="/dashboard.js" defer></script>
+</body>
+</html>
diff --git a/plugins/codex-opc-team/scripts/opc_app.py b/plugins/codex-opc-team/scripts/opc_app.py
new file mode 100644
index 0000000..2cd2343
--- /dev/null
+++ b/plugins/codex-opc-team/scripts/opc_app.py
@@ -0,0 +1,635 @@
+#!/usr/bin/env python3
+"""Run the independent, local-only OPC App control plane.
+
+The App is not an Agent harness. It reuses the Dashboard snapshot contract,
+writes only its own explicit-project registry, and never mutates project or
+knowledge state.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import secrets
+import socket
+import stat
+import sys
+import threading
+import uuid
+import webbrowser
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+from urllib.parse import unquote, urlsplit
+
+from opc_dashboard import (
+    DashboardError,
+    DashboardHTTPServer,
+    DashboardRequestHandler,
+    IPv6DashboardHTTPServer,
+    PORTABLE_ID,
+    _assert_redacted,
+    _authority,
+    _read_json,
+    _safe_text,
+    aggregate_snapshot,
+    load_demo_snapshot,
+    utc_now,
+    validate_bind_host,
+)
+from opc_memory import resolve_data_root, resolve_knowledge_root
+from opc_snapshot_service import SnapshotService
+
+
+APP_CONTEXT_SCHEMA = "opc-app.context.v1"
+APP_SETTINGS_SCHEMA = "opc-app.settings.v1"
+MAX_SETTINGS_BYTES = 256 * 1024
+MAX_REQUEST_BYTES = 16 * 1024
+MAX_PROJECTS = 64
+APP_ASSET_ROOT = Path(__file__).resolve().parents[1] / "assets" / "app"
+
+
+class AppSettingsError(RuntimeError):
+    """An App-owned settings error safe to expose by code only."""
+
+    def __init__(self, code: str):
+        super().__init__(code)
+        self.code = code
+
+
+def resolve_app_state_root(value: str | None = None) -> Path:
+    configured = value or os.environ.get("OPC_APP_HOME")
+    if configured:
+        return Path(os.path.abspath(Path(configured).expanduser()))
+    if os.name == "nt":
+        local = os.environ.get("LOCALAPPDATA")
+        base = Path(local) if local else Path.home() / "AppData" / "Local"
+        return base / "OPC" / "App"
+    state_home = os.environ.get("XDG_STATE_HOME")
+    base = Path(state_home) if state_home else Path.home() / ".local" / "state"
+    return base / "opc-app"
+
+
+def _is_link(metadata: os.stat_result) -> bool:
+    if stat.S_ISLNK(metadata.st_mode):
+        return True
+    attributes = getattr(metadata, "st_file_attributes", 0)
+    reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    return bool(reparse and attributes & reparse)
+
+
+def _safe_state_root(path: Path) -> Path:
+    root = Path(os.path.abspath(path))
+    plugin_root = Path(__file__).resolve().parents[1]
+    try:
+        root.relative_to(plugin_root)
+    except ValueError:
+        pass
+    else:
+        raise AppSettingsError("STATE_INSIDE_PLUGIN")
+    root.mkdir(parents=True, exist_ok=True)
+    try:
+        metadata = root.lstat()
+    except OSError as exc:
+        raise AppSettingsError("STATE_UNAVAILABLE") from exc
+    if _is_link(metadata) or not stat.S_ISDIR(metadata.st_mode):
+        raise AppSettingsError("UNSAFE_STATE_ROOT")
+    return root
+
+
+def _default_settings() -> dict[str, Any]:
+    return {
+        "schema_version": APP_SETTINGS_SCHEMA,
+        "projects": [],
+        "selected_project_id": None,
+    }
+
+
+class AppSettingsStore:
+    """Atomic App-owned registry; project paths never leave this process."""
+
+    def __init__(self, state_root: Path | str):
+        self.root = _safe_state_root(Path(state_root))
+        self.path = self.root / "settings.json"
+        self._lock = threading.RLock()
+
+    def _load_strict(self) -> dict[str, Any]:
+        if not os.path.lexists(self.path):
+            return _default_settings()
+        try:
+            payload = _read_json(
+                self.path,
+                root=self.root,
+                maximum=MAX_SETTINGS_BYTES,
+            )
+        except DashboardError as exc:
+            raise AppSettingsError("INVALID_SETTINGS") from exc
+        if (
+            payload.get("schema_version") != APP_SETTINGS_SCHEMA
+            or set(payload) != {"schema_version", "projects", "selected_project_id"}
+            or not isinstance(payload.get("projects"), list)
+            or len(payload["projects"]) > MAX_PROJECTS
+        ):
+            raise AppSettingsError("INVALID_SETTINGS")
+        seen_ids: set[str] = set()
+        seen_paths: set[str] = set()
+        for item in payload["projects"]:
+            if not isinstance(item, dict) or set(item) != {"id", "path", "added_at"}:
+                raise AppSettingsError("INVALID_SETTINGS")
+            item_id = item.get("id")
+            raw_path = item.get("path")
+            if (
+                not isinstance(item_id, str)
+                or not item_id.startswith("project-")
+                or len(item_id) > 64
+                or not isinstance(raw_path, str)
+                or not raw_path
+                or len(raw_path) > 4096
+                or not isinstance(item.get("added_at"), str)
+            ):
+                raise AppSettingsError("INVALID_SETTINGS")
+            normalized = os.path.normcase(os.path.abspath(raw_path))
+            if item_id in seen_ids or normalized in seen_paths:
+                raise AppSettingsError("INVALID_SETTINGS")
+            seen_ids.add(item_id)
+            seen_paths.add(normalized)
+        selected = payload.get("selected_project_id")
+        if selected is not None and selected not in seen_ids:
+            raise AppSettingsError("INVALID_SETTINGS")
+        return payload
+
+    def _write(self, payload: Mapping[str, Any]) -> None:
+        root = _safe_state_root(self.root)
+        if os.path.lexists(self.path):
+            metadata = self.path.lstat()
+            if (
+                _is_link(metadata)
+                or not stat.S_ISREG(metadata.st_mode)
+                or metadata.st_nlink != 1
+            ):
+                raise AppSettingsError("UNSAFE_SETTINGS_FILE")
+        encoded = json.dumps(
+            payload,
+            ensure_ascii=False,
+            separators=(",", ":"),
+        ).encode("utf-8")
+        if len(encoded) > MAX_SETTINGS_BYTES:
+            raise AppSettingsError("SETTINGS_TOO_LARGE")
+        temporary = root / f".settings-{secrets.token_hex(8)}.tmp"
+        descriptor: int | None = None
+        try:
+            flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
+            descriptor = os.open(temporary, flags, 0o600)
+            remaining = memoryview(encoded)
+            while remaining:
+                written = os.write(descriptor, remaining)
+                if written <= 0:
+                    raise OSError("short settings write")
+                remaining = remaining[written:]
+            os.fsync(descriptor)
+            os.close(descriptor)
+            descriptor = None
+            os.replace(temporary, self.path)
+            try:
+                os.chmod(self.path, 0o600)
+            except OSError:
+                pass
+        except OSError as exc:
+            raise AppSettingsError("SETTINGS_WRITE_FAILED") from exc
+        finally:
+            if descriptor is not None:
+                os.close(descriptor)
+            try:
+                temporary.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+    @staticmethod
+    def _normalize_project_root(value: str) -> Path:
+        if not isinstance(value, str) or not value.strip() or len(value) > 4096:
+            raise AppSettingsError("INVALID_PROJECT_ROOT")
+        expanded = Path(value.strip()).expanduser()
+        if not expanded.is_absolute():
+            raise AppSettingsError("ABSOLUTE_PROJECT_ROOT_REQUIRED")
+        root = Path(os.path.abspath(expanded))
+        try:
+            metadata = root.lstat()
+        except OSError as exc:
+            raise AppSettingsError("PROJECT_UNAVAILABLE") from exc
+        if _is_link(metadata) or not stat.S_ISDIR(metadata.st_mode):
+            raise AppSettingsError("UNSAFE_PROJECT_ROOT")
+        try:
+            project = _read_json(root / ".opc" / "project.json", root=root)
+        except DashboardError as exc:
+            raise AppSettingsError("INVALID_OPC_PROJECT") from exc
+        project_id = _safe_text(project.get("project_id"), maximum=128)
+        name = _safe_text(project.get("name"), maximum=160)
+        if project_id is None or PORTABLE_ID.fullmatch(project_id) is None or name is None:
+            raise AppSettingsError("INVALID_OPC_PROJECT")
+        return root
+
+    def read_state(self) -> tuple[str, dict[str, Any]]:
+        with self._lock:
+            try:
+                return "ready", self._load_strict()
+            except AppSettingsError:
+                return "invalid", _default_settings()
+
+    def project_roots(self) -> tuple[Path, ...]:
+        state, payload = self.read_state()
+        if state != "ready":
+            return ()
+        return tuple(Path(item["path"]) for item in payload["projects"])
+
+    def context(self) -> dict[str, Any]:
+        state, payload = self.read_state()
+        projects: list[dict[str, Any]] = []
+        if state == "ready":
+            for index, item in enumerate(payload["projects"]):
+                root = Path(item["path"])
+                project_state = "available"
+                project_id: str | None = None
+                name = f"项目 {index + 1}"
+                try:
+                    raw = _read_json(root / ".opc" / "project.json", root=root)
+                    candidate_id = _safe_text(raw.get("project_id"), maximum=128)
+                    candidate_name = _safe_text(raw.get("name"), maximum=160)
+                    if (
+                        candidate_id is None
+                        or PORTABLE_ID.fullmatch(candidate_id) is None
+                        or candidate_name is None
+                    ):
+                        raise DashboardError("INVALID_PROJECT")
+                    project_id = candidate_id
+                    name = candidate_name
+                except DashboardError:
+                    project_state = "unavailable"
+                projects.append(
+                    {
+                        "id": item["id"],
+                        "project_id": project_id,
+                        "name": name,
+                        "root_label": f"显式目录 {index + 1}",
+                        "state": project_state,
+                    }
+                )
+        context = {
+            "schema_version": APP_CONTEXT_SCHEMA,
+            "settings_state": state,
+            "projects": projects,
+            "selected_project_id": payload.get("selected_project_id"),
+            "warning": (
+                None
+                if state == "ready"
+                else {
+                    "code": "INVALID_APP_SETTINGS",
+                    "message": "App 接入清单不可读；未扫描磁盘，也未推测项目。",
+                }
+            ),
+        }
+        _assert_redacted(context)
+        return context
+
+    def add_project(self, value: str) -> None:
+        with self._lock:
+            payload = self._load_strict()
+            root = self._normalize_project_root(value)
+            normalized = os.path.normcase(str(root))
+            if any(
+                os.path.normcase(os.path.abspath(item["path"])) == normalized
+                for item in payload["projects"]
+            ):
+                raise AppSettingsError("PROJECT_ALREADY_REGISTERED")
+            if len(payload["projects"]) >= MAX_PROJECTS:
+                raise AppSettingsError("PROJECT_LIMIT_REACHED")
+            item_id = f"project-{uuid.uuid4().hex[:16]}"
+            payload["projects"].append(
+                {"id": item_id, "path": str(root), "added_at": utc_now()}
+            )
+            if payload["selected_project_id"] is None:
+                payload["selected_project_id"] = item_id
+            self._write(payload)
+
+    def select_project(self, item_id: str) -> None:
+        if not isinstance(item_id, str):
+            raise AppSettingsError("INVALID_PROJECT_SELECTION")
+        with self._lock:
+            payload = self._load_strict()
+            if item_id not in {item["id"] for item in payload["projects"]}:
+                raise AppSettingsError("PROJECT_NOT_REGISTERED")
+            payload["selected_project_id"] = item_id
+            self._write(payload)
+
+    def remove_project(self, item_id: str) -> None:
+        if not isinstance(item_id, str):
+            raise AppSettingsError("INVALID_PROJECT_SELECTION")
+        with self._lock:
+            payload = self._load_strict()
+            remaining = [item for item in payload["projects"] if item["id"] != item_id]
+            if len(remaining) == len(payload["projects"]):
+                raise AppSettingsError("PROJECT_NOT_REGISTERED")
+            payload["projects"] = remaining
+            if payload["selected_project_id"] == item_id:
+                payload["selected_project_id"] = remaining[0]["id"] if remaining else None
+            self._write(payload)
+
+
+class DemoSettingsStore:
+    def project_roots(self) -> tuple[Path, ...]:
+        return ()
+
+    def context(self) -> dict[str, Any]:
+        context = {
+            "schema_version": APP_CONTEXT_SCHEMA,
+            "settings_state": "demo",
+            "projects": [
+                {
+                    "id": "project-demo-primary",
+                    "project_id": "synthetic-dashboard",
+                    "name": "本地 OPC Dashboard",
+                    "root_label": "合成目录 1",
+                    "state": "available",
+                },
+                {
+                    "id": "project-demo-secondary",
+                    "project_id": "synthetic-memory",
+                    "name": "组织知识治理",
+                    "root_label": "合成目录 2",
+                    "state": "available",
+                },
+            ],
+            "selected_project_id": "project-demo-primary",
+            "warning": {
+                "code": "SYNTHETIC_DEMO",
+                "message": "当前为合成演示数据，不代表真实组织状态。",
+            },
+        }
+        _assert_redacted(context)
+        return context
+
+
+class OPCAppHTTPServer(DashboardHTTPServer):
+    def __init__(
+        self,
+        address: tuple[str, int],
+        handler: type[DashboardRequestHandler],
+        *,
+        snapshot_provider: Any,
+        asset_root: Path,
+        settings_store: AppSettingsStore | DemoSettingsStore,
+        demo: bool,
+    ) -> None:
+        self.settings_store = settings_store
+        self.demo = demo
+        self.csrf_token = secrets.token_urlsafe(32)
+        super().__init__(
+            address,
+            handler,
+            snapshot_provider=snapshot_provider,
+            asset_root=asset_root,
+        )
+
+
+class IPv6OPCAppHTTPServer(OPCAppHTTPServer):
+    address_family = socket.AF_INET6
+
+
+class OPCAppRequestHandler(DashboardRequestHandler):
+    server_version = "OPCApp/1"
+
+    @property
+    def app_server(self) -> OPCAppHTTPServer:
+        return self.server  # type: ignore[return-value]
+
+    def _send_json(
+        self,
+        status_code: int,
+        value: Mapping[str, Any],
+        *,
+        head_only: bool = False,
+    ) -> None:
+        _assert_redacted(value)
+        payload = json.dumps(
+            value,
+            ensure_ascii=False,
+            separators=(",", ":"),
+        ).encode("utf-8")
+        self._send(
+            status_code,
+            payload,
+            "application/json; charset=utf-8",
+            head_only=head_only,
+        )
+
+    def _context_payload(self) -> dict[str, Any]:
+        payload = self.app_server.settings_store.context()
+        payload["csrf_token"] = self.app_server.csrf_token
+        _assert_redacted(payload)
+        return payload
+
+    def _handle_read(self, *, head_only: bool) -> None:
+        parsed = urlsplit(self.path)
+        if parsed.path != "/api/app-context":
+            super()._handle_read(head_only=head_only)
+            return
+        if not self._valid_host():
+            self._json_error(400, "INVALID_HOST", head_only=head_only)
+            return
+        if not self._valid_origin():
+            self._json_error(403, "ORIGIN_FORBIDDEN", head_only=head_only)
+            return
+        if parsed.query or parsed.fragment:
+            self._json_error(404, "NOT_FOUND", head_only=head_only)
+            return
+        self._send_json(200, self._context_payload(), head_only=head_only)
+
+    def _valid_csrf(self) -> bool:
+        values = self.headers.get_all("X-OPC-CSRF", [])
+        return (
+            len(values) == 1
+            and secrets.compare_digest(values[0], self.app_server.csrf_token)
+        )
+
+    def _read_request_json(self) -> dict[str, Any]:
+        if self.headers.get("Transfer-Encoding") is not None:
+            raise AppSettingsError("INVALID_REQUEST")
+        lengths = self.headers.get_all("Content-Length", [])
+        if len(lengths) != 1:
+            raise AppSettingsError("INVALID_REQUEST")
+        try:
+            length = int(lengths[0])
+        except (TypeError, ValueError) as exc:
+            raise AppSettingsError("INVALID_REQUEST") from exc
+        if length < 2 or length > MAX_REQUEST_BYTES:
+            raise AppSettingsError("INVALID_REQUEST")
+        media_type = self.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+        if media_type != "application/json":
+            raise AppSettingsError("INVALID_CONTENT_TYPE")
+        try:
+            payload = json.loads(self.rfile.read(length).decode("utf-8"))
+        except (UnicodeError, ValueError, json.JSONDecodeError) as exc:
+            raise AppSettingsError("INVALID_REQUEST") from exc
+        if not isinstance(payload, dict):
+            raise AppSettingsError("INVALID_REQUEST")
+        return payload
+
+    def _prepare_mutation(self) -> bool:
+        if not self._valid_host():
+            self._json_error(400, "INVALID_HOST")
+            return False
+        if not self._valid_origin():
+            self._json_error(403, "ORIGIN_FORBIDDEN")
+            return False
+        if not self._valid_csrf():
+            self._json_error(403, "CSRF_FORBIDDEN")
+            return False
+        if self.app_server.demo:
+            self._json_error(409, "DEMO_SETTINGS_READ_ONLY")
+            return False
+        return True
+
+    def do_POST(self) -> None:
+        if not self._prepare_mutation():
+            return
+        parsed = urlsplit(self.path)
+        if parsed.query or parsed.fragment:
+            self._json_error(404, "NOT_FOUND")
+            return
+        try:
+            payload = self._read_request_json()
+            store = self.app_server.settings_store
+            if not isinstance(store, AppSettingsStore):
+                raise AppSettingsError("SETTINGS_UNAVAILABLE")
+            if parsed.path == "/api/projects" and set(payload) == {"path"}:
+                store.add_project(payload["path"])
+                status = 201
+            elif parsed.path == "/api/selection" and set(payload) == {"project_id"}:
+                store.select_project(payload["project_id"])
+                status = 200
+            else:
+                self._json_error(404, "NOT_FOUND")
+                return
+            self._send_json(status, self._context_payload())
+        except AppSettingsError as exc:
+            self._json_error(400, exc.code)
+
+    def do_DELETE(self) -> None:
+        if not self._prepare_mutation():
+            return
+        if (
+            self.headers.get("Transfer-Encoding") is not None
+            or self.headers.get_all("Content-Length", []) not in ([], ["0"])
+        ):
+            self._json_error(400, "INVALID_REQUEST")
+            return
+        parsed = urlsplit(self.path)
+        prefix = "/api/projects/"
+        if parsed.query or parsed.fragment or not parsed.path.startswith(prefix):
+            self._json_error(404, "NOT_FOUND")
+            return
+        item_id = unquote(parsed.path[len(prefix) :])
+        if not item_id or "/" in item_id or len(item_id) > 64:
+            self._json_error(404, "NOT_FOUND")
+            return
+        try:
+            store = self.app_server.settings_store
+            if not isinstance(store, AppSettingsStore):
+                raise AppSettingsError("SETTINGS_UNAVAILABLE")
+            store.remove_project(item_id)
+            self._send_json(200, self._context_payload())
+        except AppSettingsError as exc:
+            self._json_error(400, exc.code)
+
+
+def create_app_server(
+    *,
+    host: str,
+    port: int,
+    snapshot_provider: Any,
+    settings_store: AppSettingsStore | DemoSettingsStore,
+    demo: bool = False,
+    asset_root: Path | str | None = None,
+) -> OPCAppHTTPServer:
+    validate_bind_host(host)
+    if isinstance(port, bool) or not isinstance(port, int) or not 0 <= port <= 65535:
+        raise DashboardError("INVALID_PORT")
+    root = Path(asset_root) if asset_root is not None else APP_ASSET_ROOT
+    server_type = IPv6OPCAppHTTPServer if host == "::1" else OPCAppHTTPServer
+    try:
+        return server_type(
+            (host, port),
+            OPCAppRequestHandler,
+            snapshot_provider=snapshot_provider,
+            asset_root=root,
+            settings_store=settings_store,
+            demo=demo,
+        )
+    except OSError as exc:
+        raise DashboardError("PORT_UNAVAILABLE") from exc
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--state-root")
+    parser.add_argument("--knowledge-root")
+    parser.add_argument("--data-root")
+    parser.add_argument("--demo", action="store_true")
+    parser.add_argument("--host", "--bind", dest="host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8570)
+    parser.add_argument("--no-open", action="store_true")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        validate_bind_host(args.host)
+        if args.demo:
+            if args.knowledge_root or args.data_root or args.state_root:
+                parser.error("--demo 不能与真实数据根或 App 状态根参数同时使用")
+            settings_store: AppSettingsStore | DemoSettingsStore = DemoSettingsStore()
+            service = SnapshotService(
+                project_roots_provider=settings_store.project_roots,
+                snapshot_builder=aggregate_snapshot,
+                demo_loader=load_demo_snapshot,
+                snapshot_validator=_assert_redacted,
+                demo=True,
+            )
+        else:
+            settings_store = AppSettingsStore(resolve_app_state_root(args.state_root))
+            service = SnapshotService(
+                project_roots_provider=settings_store.project_roots,
+                snapshot_builder=aggregate_snapshot,
+                demo_loader=load_demo_snapshot,
+                snapshot_validator=_assert_redacted,
+                knowledge_root=resolve_knowledge_root(args.knowledge_root),
+                data_root=resolve_data_root(args.data_root),
+                allow_empty=True,
+            )
+        server = create_app_server(
+            host=args.host,
+            port=args.port,
+            snapshot_provider=service.snapshot,
+            settings_store=settings_store,
+            demo=args.demo,
+        )
+    except (DashboardError, AppSettingsError) as exc:
+        code = exc.code
+        print(f"OPC_APP_ERROR: {code}", file=sys.stderr)
+        return 2
+    url = f"http://{_authority(args.host, int(server.server_address[1]))}/"
+    print(f"OPC App: {url}", flush=True)
+    if not args.no_open:
+        webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/plugins/codex-opc-team/scripts/opc_dashboard.py b/plugins/codex-opc-team/scripts/opc_dashboard.py
index db09195..6323a8b 100644
--- a/plugins/codex-opc-team/scripts/opc_dashboard.py
+++ b/plugins/codex-opc-team/scripts/opc_dashboard.py
@@ -30,6 +30,7 @@
     resolve_data_root,
     resolve_knowledge_root,
 )
+from opc_snapshot_service import SnapshotService
 
 
 SCHEMA_VERSION = "opc-dashboard.snapshot.v1"
@@ -636,8 +637,9 @@ def aggregate_snapshot(
     knowledge_root: Path | str,
     data_root: Path | str,
     now: Callable[[], str] = utc_now,
+    allow_empty: bool = False,
 ) -> dict[str, Any]:
-    if not project_roots or len(project_roots) > MAX_PROJECTS:
+    if (not project_roots and not allow_empty) or len(project_roots) > MAX_PROJECTS:
         raise DashboardError("INVALID_PROJECT_ROOT_COUNT")
     knowledge_path = Path(knowledge_root)
     data_path = Path(data_root)
@@ -951,24 +953,31 @@ def main(argv: Sequence[str] | None = None) -> int:
         if args.demo:
             if args.project_root or args.knowledge_root or args.data_root:
                 parser.error("--demo 不能与真实数据根参数同时使用")
-            provider = load_demo_snapshot
+            service = SnapshotService(
+                project_roots_provider=tuple,
+                snapshot_builder=aggregate_snapshot,
+                demo_loader=load_demo_snapshot,
+                snapshot_validator=_assert_redacted,
+                demo=True,
+            )
         else:
             if not args.project_root:
                 parser.error("真实模式需要至少一个 --project-root")
             knowledge_root = resolve_knowledge_root(args.knowledge_root)
             data_root = resolve_data_root(args.data_root)
-
-            def provider() -> dict[str, Any]:
-                return aggregate_snapshot(
-                    args.project_root,
-                    knowledge_root=knowledge_root,
-                    data_root=data_root,
-                )
+            service = SnapshotService(
+                project_roots_provider=lambda: args.project_root,
+                snapshot_builder=aggregate_snapshot,
+                demo_loader=load_demo_snapshot,
+                snapshot_validator=_assert_redacted,
+                knowledge_root=knowledge_root,
+                data_root=data_root,
+            )
 
         server = create_server(
             host=args.host,
             port=args.port,
-            snapshot_provider=provider,
+            snapshot_provider=service.snapshot,
         )
     except DashboardError as exc:
         print(f"OPC_DASHBOARD_ERROR: {exc.code}", file=sys.stderr)
diff --git a/plugins/codex-opc-team/scripts/opc_snapshot_service.py b/plugins/codex-opc-team/scripts/opc_snapshot_service.py
new file mode 100644
index 0000000..55bac07
--- /dev/null
+++ b/plugins/codex-opc-team/scripts/opc_snapshot_service.py
@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Shared, read-only snapshot application service for OPC visual surfaces."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Mapping, Sequence
+
+
+Snapshot = dict[str, Any]
+ProjectRootsProvider = Callable[[], Sequence[Path | str]]
+SnapshotBuilder = Callable[..., Snapshot]
+DemoLoader = Callable[[], Snapshot]
+SnapshotValidator = Callable[[Any], None]
+
+
+class SnapshotService:
+    """Keep Dashboard and OPC App on one aggregation/redaction contract."""
+
+    def __init__(
+        self,
+        *,
+        project_roots_provider: ProjectRootsProvider,
+        snapshot_builder: SnapshotBuilder,
+        demo_loader: DemoLoader,
+        snapshot_validator: SnapshotValidator,
+        knowledge_root: Path | str | None = None,
+        data_root: Path | str | None = None,
+        demo: bool = False,
+        allow_empty: bool = False,
+    ) -> None:
+        self._project_roots_provider = project_roots_provider
+        self._snapshot_builder = snapshot_builder
+        self._demo_loader = demo_loader
+        self._snapshot_validator = snapshot_validator
+        self._knowledge_root = knowledge_root
+        self._data_root = data_root
+        self._demo = demo
+        self._allow_empty = allow_empty
+
+    def snapshot(self) -> Snapshot:
+        if self._demo:
+            snapshot = self._demo_loader()
+        else:
+            if self._knowledge_root is None or self._data_root is None:
+                raise RuntimeError("live snapshot roots are required")
+            arguments: dict[str, Any] = {
+                "knowledge_root": self._knowledge_root,
+                "data_root": self._data_root,
+            }
+            if self._allow_empty:
+                arguments["allow_empty"] = True
+            snapshot = self._snapshot_builder(
+                self._project_roots_provider(),
+                **arguments,
+            )
+        if not isinstance(snapshot, Mapping):
+            raise RuntimeError("snapshot builder returned an invalid value")
+        self._snapshot_validator(snapshot)
+        return dict(snapshot)
diff --git a/scripts/opc_app_admin.py b/scripts/opc_app_admin.py
new file mode 100644
index 0000000..8505316
--- /dev/null
+++ b/scripts/opc_app_admin.py
@@ -0,0 +1,438 @@
+#!/usr/bin/env python3
+"""Install, update, roll back, inspect, or uninstall the local OPC App.
+
+This manages only the independent App runtime. It does not install an Agent,
+register an OPC host Adapter, edit global configuration, or delete App state,
+project data, knowledge, Git history, or Mem0 data.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import shutil
+import stat
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+MAX_MANIFEST_BYTES = 64 * 1024
+POINTER_SCHEMA = "opc-app.install.v1"
+OWNER_SCHEMA = "opc-app.runtime-owner.v1"
+
+
+class AppInstallError(RuntimeError):
+    pass
+
+
+def default_install_root() -> Path:
+    if os.name == "nt":
+        local = os.environ.get("LOCALAPPDATA")
+        base = Path(local) if local else Path.home() / "AppData" / "Local"
+        return base / "OPC" / "AppRuntime"
+    data_home = os.environ.get("XDG_DATA_HOME")
+    base = Path(data_home) if data_home else Path.home() / ".local" / "share"
+    return base / "opc-app"
+
+
+def default_state_root() -> Path:
+    configured = os.environ.get("OPC_APP_HOME")
+    if configured:
+        return Path(os.path.abspath(Path(configured).expanduser()))
+    if os.name == "nt":
+        local = os.environ.get("LOCALAPPDATA")
+        base = Path(local) if local else Path.home() / "AppData" / "Local"
+        return base / "OPC" / "App"
+    state_home = os.environ.get("XDG_STATE_HOME")
+    base = Path(state_home) if state_home else Path.home() / ".local" / "state"
+    return base / "opc-app"
+
+
+def _is_link(path: Path) -> bool:
+    try:
+        metadata = path.lstat()
+    except OSError:
+        return False
+    if stat.S_ISLNK(metadata.st_mode):
+        return True
+    attributes = getattr(metadata, "st_file_attributes", 0)
+    reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    return bool(reparse and attributes & reparse)
+
+
+def _safe_install_root(value: str | Path) -> Path:
+    root = Path(os.path.abspath(Path(value).expanduser()))
+    home = Path(os.path.abspath(Path.home()))
+    source = Path(os.path.abspath(ROOT))
+    anchor = Path(root.anchor) if root.anchor else None
+    if root == home or root == source or anchor is None or root == anchor:
+        raise AppInstallError("refusing broad or source install root")
+    try:
+        source.relative_to(root)
+    except ValueError:
+        pass
+    else:
+        raise AppInstallError("install root cannot contain the source checkout")
+    try:
+        root.relative_to(source)
+    except ValueError:
+        pass
+    else:
+        raise AppInstallError("install root cannot be inside the source checkout")
+    if root.exists() and (_is_link(root) or not root.is_dir()):
+        raise AppInstallError("install root is not a safe directory")
+    return root
+
+
+def _plugin_source(source: Path) -> Path:
+    plugin = source / "plugins" / "codex-opc-team"
+    required = (
+        plugin / ".codex-plugin" / "plugin.json",
+        plugin / "scripts" / "opc_app.py",
+        plugin / "scripts" / "opc_dashboard.py",
+        plugin / "scripts" / "opc_snapshot_service.py",
+        plugin / "assets" / "app" / "index.html",
+        plugin / "assets" / "app" / "dashboard.css",
+        plugin / "assets" / "app" / "dashboard.js",
+    )
+    if any(not path.is_file() for path in required):
+        raise AppInstallError("source does not contain a complete OPC App")
+    if any(_is_link(path) for path in plugin.rglob("*")):
+        raise AppInstallError("source contains linked content")
+    return plugin
+
+
+def _manifest(plugin: Path) -> dict[str, Any]:
+    path = plugin / ".codex-plugin" / "plugin.json"
+    raw = path.read_bytes()
+    if len(raw) > MAX_MANIFEST_BYTES:
+        raise AppInstallError("plugin manifest is too large")
+    try:
+        payload = json.loads(raw.decode("utf-8"))
+    except (UnicodeError, ValueError, json.JSONDecodeError) as exc:
+        raise AppInstallError("plugin manifest is invalid") from exc
+    version = payload.get("version")
+    if not isinstance(version, str) or not version or len(version) > 64:
+        raise AppInstallError("plugin version is invalid")
+    return payload
+
+
+def _source_files(plugin: Path) -> list[Path]:
+    files: list[Path] = []
+    for path in plugin.rglob("*"):
+        if not path.is_file() or _is_link(path):
+            continue
+        relative = path.relative_to(plugin)
+        if "__pycache__" in relative.parts or path.suffix in {".pyc", ".pyo"}:
+            continue
+        files.append(path)
+    return sorted(files, key=lambda item: item.relative_to(plugin).as_posix())
+
+
+def _release_id(plugin: Path, version: str) -> str:
+    digest = hashlib.sha256()
+    for path in _source_files(plugin):
+        relative = path.relative_to(plugin).as_posix().encode("utf-8")
+        digest.update(len(relative).to_bytes(4, "big"))
+        digest.update(relative)
+        payload = path.read_bytes()
+        digest.update(len(payload).to_bytes(8, "big"))
+        digest.update(payload)
+    safe_version = "".join(char if char.isalnum() or char in ".-" else "-" for char in version)
+    return f"v{safe_version}-{digest.hexdigest()[:12]}"
+
+
+def _read_pointer(root: Path) -> dict[str, Any]:
+    path = root / "current.json"
+    if not path.is_file() or _is_link(path):
+        return {"schema_version": POINTER_SCHEMA, "current": None, "previous": None}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError, json.JSONDecodeError) as exc:
+        raise AppInstallError("installed release pointer is invalid") from exc
+    if (
+        payload.get("schema_version") != POINTER_SCHEMA
+        or set(payload) != {"schema_version", "current", "previous"}
+        or any(
+            value is not None and (not isinstance(value, str) or len(value) > 128)
+            for value in (payload.get("current"), payload.get("previous"))
+        )
+    ):
+        raise AppInstallError("installed release pointer is invalid")
+    return payload
+
+
+def _owned_root(root: Path) -> bool:
+    owner = root / ".opc-app-owned.json"
+    if not owner.is_file() or _is_link(owner):
+        return False
+    try:
+        payload = json.loads(owner.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError, json.JSONDecodeError):
+        return False
+    return payload == {
+        "schema_version": OWNER_SCHEMA,
+        "owner": "coconilu/codex-opc-team:opc-app",
+    }
+
+
+def _atomic_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{path.name}-",
+        suffix=".tmp",
+        dir=path.parent,
+    )
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as stream:
+            json.dump(payload, stream, ensure_ascii=False, separators=(",", ":"))
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+    except OSError as exc:
+        raise AppInstallError("failed to update installed release pointer") from exc
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+LAUNCHER = """#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import runpy
+import sys
+from pathlib import Path
+
+root = Path(__file__).resolve().parents[1]
+pointer = json.loads((root / "current.json").read_text(encoding="utf-8"))
+release = pointer.get("current")
+if not isinstance(release, str) or not release:
+    raise SystemExit("OPC_APP_LAUNCH_FAILED: no active release")
+script = root / "releases" / release / "plugin" / "scripts" / "opc_app.py"
+if not script.is_file():
+    raise SystemExit("OPC_APP_LAUNCH_FAILED: active release is incomplete")
+sys.path.insert(0, str(script.parent))
+sys.argv = [str(script), *sys.argv[1:]]
+runpy.run_path(str(script), run_name="__main__")
+"""
+
+
+def _write_launchers(root: Path) -> None:
+    target = root / "bin"
+    target.mkdir(parents=True, exist_ok=True)
+    (target / "opc-app.py").write_text(LAUNCHER, encoding="utf-8", newline="\n")
+    (target / "opc-app.cmd").write_text(
+        '@echo off\r\npython "%~dp0opc-app.py" %*\r\n',
+        encoding="utf-8",
+        newline="",
+    )
+    shell = target / "opc-app"
+    shell.write_text(
+        '#!/usr/bin/env sh\nexec python3 "$(dirname "$0")/opc-app.py" "$@"\n',
+        encoding="utf-8",
+        newline="\n",
+    )
+    try:
+        shell.chmod(0o755)
+    except OSError:
+        pass
+
+
+def install_or_update(args: argparse.Namespace) -> int:
+    source = Path(os.path.abspath(Path(args.source).expanduser())) if args.source else ROOT
+    plugin = _plugin_source(source)
+    manifest = _manifest(plugin)
+    release = _release_id(plugin, manifest["version"])
+    root = _safe_install_root(args.install_root or default_install_root())
+    if root.exists() and any(root.iterdir()) and not _owned_root(root):
+        raise AppInstallError("non-empty install root is not owned by OPC App")
+    pointer = _read_pointer(root) if root.exists() else {
+        "schema_version": POINTER_SCHEMA,
+        "current": None,
+        "previous": None,
+    }
+    action = "keep" if pointer["current"] == release else "install"
+    plan = {
+        "dry_run": not args.apply,
+        "action": action,
+        "version": manifest["version"],
+        "release": release,
+        "install_root": str(root),
+        "launcher": str(root / "bin" / ("opc-app.cmd" if os.name == "nt" else "opc-app")),
+        "app_state_root": str(default_state_root()),
+        "project_and_knowledge_action": "preserve",
+        "agent_adapter_action": "none",
+        "global_config_action": "none",
+    }
+    print(json.dumps(plan, ensure_ascii=False, indent=2))
+    if not args.apply:
+        print("Dry run only. Re-run with --apply after reviewing this plan.")
+        return 0
+    root.mkdir(parents=True, exist_ok=True)
+    _atomic_json(
+        root / ".opc-app-owned.json",
+        {
+            "schema_version": OWNER_SCHEMA,
+            "owner": "coconilu/codex-opc-team:opc-app",
+        },
+    )
+    releases = root / "releases"
+    releases.mkdir(exist_ok=True)
+    release_root = releases / release
+    if not release_root.exists():
+        stage = root / f".stage-{release}"
+        if stage.exists():
+            shutil.rmtree(stage)
+        stage.mkdir()
+        try:
+            shutil.copytree(
+                plugin,
+                stage / "plugin",
+                ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"),
+            )
+            os.replace(stage, release_root)
+        except OSError as exc:
+            shutil.rmtree(stage, ignore_errors=True)
+            raise AppInstallError("failed to install OPC App release") from exc
+    if pointer["current"] != release:
+        pointer = {
+            "schema_version": POINTER_SCHEMA,
+            "current": release,
+            "previous": pointer["current"],
+        }
+        _atomic_json(root / "current.json", pointer)
+    _write_launchers(root)
+    print(f"OPC App ready: {plan['launcher']}")
+    print(f"App state remains separate: {plan['app_state_root']}")
+    return 0
+
+
+def rollback(args: argparse.Namespace) -> int:
+    root = _safe_install_root(args.install_root or default_install_root())
+    if not root.exists() or not _owned_root(root):
+        raise AppInstallError("install root is not owned by OPC App")
+    pointer = _read_pointer(root)
+    previous = pointer.get("previous")
+    if not previous or not (root / "releases" / previous / "plugin").is_dir():
+        raise AppInstallError("no complete previous release is available")
+    plan = {
+        "dry_run": not args.apply,
+        "action": "rollback",
+        "from_release": pointer["current"],
+        "to_release": previous,
+        "app_state_root": str(default_state_root()),
+        "project_and_knowledge_action": "preserve",
+    }
+    print(json.dumps(plan, ensure_ascii=False, indent=2))
+    if not args.apply:
+        print("Dry run only. Re-run with --apply after reviewing this plan.")
+        return 0
+    _atomic_json(
+        root / "current.json",
+        {
+            "schema_version": POINTER_SCHEMA,
+            "current": previous,
+            "previous": pointer["current"],
+        },
+    )
+    print(f"OPC App rolled back to {previous}")
+    return 0
+
+
+def uninstall(args: argparse.Namespace) -> int:
+    root = _safe_install_root(args.install_root or default_install_root())
+    if root.exists() and not _owned_root(root):
+        raise AppInstallError("install root is not owned by OPC App")
+    plan = {
+        "dry_run": not args.apply,
+        "action": "remove-runtime" if root.exists() else "none",
+        "install_root": str(root),
+        "app_state_root": str(default_state_root()),
+        "app_state_action": "preserve",
+        "project_and_knowledge_action": "preserve",
+        "agent_adapter_action": "none",
+    }
+    print(json.dumps(plan, ensure_ascii=False, indent=2))
+    if not args.apply:
+        print("Dry run only. Re-run with --apply after reviewing this plan.")
+        return 0
+    if root.exists():
+        if _is_link(root) or not _owned_root(root):
+            raise AppInstallError("refusing unowned or linked install root")
+        shutil.rmtree(root)
+    print(f"OPC App runtime removed: {root}")
+    print(f"App state preserved: {plan['app_state_root']}")
+    print("Project .opc, File/Git knowledge, Git history, user config, and Mem0 data were not touched.")
+    return 0
+
+
+def status(args: argparse.Namespace) -> int:
+    root = _safe_install_root(args.install_root or default_install_root())
+    pointer = _read_pointer(root) if root.exists() else {
+        "schema_version": POINTER_SCHEMA,
+        "current": None,
+        "previous": None,
+    }
+    print(
+        json.dumps(
+            {
+                "install_root": str(root),
+                "installed": bool(pointer["current"]),
+                "current_release": pointer["current"],
+                "previous_release": pointer["previous"],
+                "launcher": str(root / "bin" / ("opc-app.cmd" if os.name == "nt" else "opc-app")),
+                "app_state_root": str(default_state_root()),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(description=__doc__)
+    commands = root.add_subparsers(dest="command", required=True)
+    for name in ("install", "update"):
+        command = commands.add_parser(name)
+        command.add_argument("--source")
+        command.add_argument("--install-root")
+        mode = command.add_mutually_exclusive_group()
+        mode.add_argument("--apply", action="store_true")
+        mode.add_argument("--dry-run", action="store_true")
+        command.set_defaults(handler=install_or_update)
+    rollback_command = commands.add_parser("rollback")
+    rollback_command.add_argument("--install-root")
+    rollback_mode = rollback_command.add_mutually_exclusive_group()
+    rollback_mode.add_argument("--apply", action="store_true")
+    rollback_mode.add_argument("--dry-run", action="store_true")
+    rollback_command.set_defaults(handler=rollback)
+    uninstall_command = commands.add_parser("uninstall")
+    uninstall_command.add_argument("--install-root")
+    uninstall_mode = uninstall_command.add_mutually_exclusive_group()
+    uninstall_mode.add_argument("--apply", action="store_true")
+    uninstall_mode.add_argument("--dry-run", action="store_true")
+    uninstall_command.set_defaults(handler=uninstall)
+    status_command = commands.add_parser("status")
+    status_command.add_argument("--install-root")
+    status_command.set_defaults(handler=status)
+    return root
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        return int(args.handler(args))
+    except (AppInstallError, OSError, ValueError) as exc:
+        print(f"OPC_APP_ADMIN_FAILED: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tests/integration/test_opc_app_lifecycle.py b/tests/integration/test_opc_app_lifecycle.py
new file mode 100644
index 0000000..2e0bd57
--- /dev/null
+++ b/tests/integration/test_opc_app_lifecycle.py
@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+import urllib.request
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+ADMIN = ROOT / "scripts" / "opc_app_admin.py"
+
+
+def clean_environment(home: Path, state_root: Path) -> dict[str, str]:
+    environment = os.environ.copy()
+    environment.update(
+        {
+            "HOME": str(home),
+            "USERPROFILE": str(home),
+            "LOCALAPPDATA": str(home / "local"),
+            "XDG_DATA_HOME": str(home / "share"),
+            "XDG_STATE_HOME": str(home / "state"),
+            "OPC_APP_HOME": str(state_root),
+        }
+    )
+    return environment
+
+
+def run_admin(
+    *arguments: str,
+    environment: dict[str, str],
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(ADMIN), *arguments],
+        cwd=ROOT,
+        env=environment,
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=90,
+    )
+
+
+class OPCAppLifecycleTests(unittest.TestCase):
+    def test_uninstall_refuses_an_unowned_directory(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            state_root = base / "state"
+            unowned = base / "unowned"
+            unowned.mkdir()
+            marker = unowned / "user-file.txt"
+            marker.write_text("preserve", encoding="utf-8")
+            environment = clean_environment(home, state_root)
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(ADMIN),
+                    "uninstall",
+                    "--install-root",
+                    str(unowned),
+                    "--apply",
+                ],
+                cwd=ROOT,
+                env=environment,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            self.assertEqual(result.returncode, 1)
+            self.assertTrue(marker.is_file())
+
+    def test_clean_room_install_launch_stop_uninstall_preserves_all_private_state(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            install_root = base / "runtime"
+            state_root = base / "app-state"
+            state_root.mkdir()
+            state_marker = state_root / "preference.json"
+            state_marker.write_text('{"theme":"system"}', encoding="utf-8")
+            project_root = base / "project"
+            (project_root / ".opc").mkdir(parents=True)
+            project_marker = project_root / ".opc" / "project.json"
+            project_marker.write_text('{"project_id":"preserved"}', encoding="utf-8")
+            knowledge_root = base / "knowledge"
+            (knowledge_root / ".git").mkdir(parents=True)
+            knowledge_marker = knowledge_root / "catalog.json"
+            knowledge_marker.write_text('{"schema_version":2}', encoding="utf-8")
+            mem0_root = base / "mem0"
+            mem0_root.mkdir()
+            mem0_marker = mem0_root / "index.bin"
+            mem0_marker.write_bytes(b"preserve")
+            environment = clean_environment(home, state_root)
+
+            preview = run_admin(
+                "install",
+                "--source",
+                str(ROOT),
+                "--install-root",
+                str(install_root),
+                environment=environment,
+            )
+            self.assertIn('"dry_run": true', preview.stdout)
+            self.assertFalse(install_root.exists())
+
+            run_admin(
+                "install",
+                "--source",
+                str(ROOT),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            python_launcher = install_root / "bin" / "opc-app.py"
+            self.assertTrue(python_launcher.is_file())
+            self.assertTrue((install_root / "bin" / "opc-app.cmd").is_file())
+            self.assertTrue((install_root / "bin" / "opc-app").is_file())
+
+            process = subprocess.Popen(
+                [
+                    sys.executable,
+                    str(python_launcher),
+                    "--demo",
+                    "--host",
+                    "127.0.0.1",
+                    "--port",
+                    "0",
+                    "--no-open",
+                ],
+                cwd=base,
+                env=environment,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+            try:
+                assert process.stdout is not None
+                line = process.stdout.readline().strip()
+                self.assertTrue(line.startswith("OPC App: http://127.0.0.1:"), line)
+                url = line.removeprefix("OPC App: ")
+                with urllib.request.urlopen(url + "api/app-context", timeout=5) as response:
+                    context = json.loads(response.read())
+                self.assertEqual(context["schema_version"], "opc-app.context.v1")
+                self.assertEqual(process.poll(), None)
+            finally:
+                process.terminate()
+                process.wait(timeout=10)
+                if process.stdout is not None:
+                    process.stdout.close()
+                if process.stderr is not None:
+                    process.stderr.close()
+            self.assertIsNotNone(process.returncode)
+
+            run_admin(
+                "uninstall",
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            self.assertFalse(install_root.exists())
+            self.assertEqual(state_marker.read_text(encoding="utf-8"), '{"theme":"system"}')
+            self.assertTrue(project_marker.is_file())
+            self.assertTrue(knowledge_marker.is_file())
+            self.assertEqual(mem0_marker.read_bytes(), b"preserve")
+
+    def test_update_and_rollback_switch_release_pointer_without_touching_state(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            state_root = base / "app-state"
+            state_root.mkdir()
+            state_marker = state_root / "settings.json"
+            state_marker.write_text('{"private":"preserve"}', encoding="utf-8")
+            install_root = base / "runtime"
+            environment = clean_environment(home, state_root)
+
+            sources: list[Path] = []
+            for version in ("9.0.0-test", "9.0.1-test"):
+                source = base / f"source-{version}"
+                plugin_target = source / "plugins" / "codex-opc-team"
+                shutil.copytree(
+                    ROOT / "plugins" / "codex-opc-team",
+                    plugin_target,
+                    ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"),
+                )
+                manifest_path = plugin_target / ".codex-plugin" / "plugin.json"
+                manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+                manifest["version"] = version
+                manifest_path.write_text(
+                    json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
+                    encoding="utf-8",
+                )
+                sources.append(source)
+
+            run_admin(
+                "install",
+                "--source",
+                str(sources[0]),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            first = json.loads((install_root / "current.json").read_text(encoding="utf-8"))
+            run_admin(
+                "update",
+                "--source",
+                str(sources[1]),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            second = json.loads((install_root / "current.json").read_text(encoding="utf-8"))
+            self.assertNotEqual(first["current"], second["current"])
+            self.assertEqual(second["previous"], first["current"])
+
+            preview = run_admin(
+                "rollback",
+                "--install-root",
+                str(install_root),
+                environment=environment,
+            )
+            self.assertIn('"dry_run": true', preview.stdout)
+            unchanged = json.loads((install_root / "current.json").read_text(encoding="utf-8"))
+            self.assertEqual(unchanged, second)
+
+            run_admin(
+                "rollback",
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            rolled_back = json.loads((install_root / "current.json").read_text(encoding="utf-8"))
+            self.assertEqual(rolled_back["current"], first["current"])
+            self.assertEqual(state_marker.read_text(encoding="utf-8"), '{"private":"preserve"}')
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_opc_app.py b/tests/unit/test_opc_app.py
new file mode 100644
index 0000000..5fc04df
--- /dev/null
+++ b/tests/unit/test_opc_app.py
@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+import contextlib
+import http.client
+import json
+import os
+import socket
+import sys
+import tempfile
+import threading
+import unittest
+from html.parser import HTMLParser
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SCRIPTS = ROOT / "plugins" / "codex-opc-team" / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+
+import opc_app  # noqa: E402
+import opc_dashboard  # noqa: E402
+from opc_snapshot_service import SnapshotService  # noqa: E402
+
+
+class AppMarkupParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.navigation: list[dict[str, str | None]] = []
+        self.views: list[dict[str, str | None]] = []
+        self.remote_resources: list[str] = []
+
+    def handle_starttag(self, tag, attrs):
+        attributes = dict(attrs)
+        classes = set((attributes.get("class") or "").split())
+        if tag == "a" and "nav-item" in classes:
+            self.navigation.append(attributes)
+        if tag == "section" and "app-view" in classes:
+            self.views.append(attributes)
+        if tag in {"link", "script", "img"}:
+            value = attributes.get("href") or attributes.get("src")
+            if value and value.startswith(("http://", "https://", "//")):
+                self.remote_resources.append(value)
+
+
+def project_fixture(root: Path, project_id: str = "sample-project") -> Path:
+    opc = root / ".opc"
+    opc.mkdir(parents=True)
+    (opc / "project.json").write_text(
+        json.dumps(
+            {
+                "schema_version": 1,
+                "project_id": project_id,
+                "name": "Synthetic Project",
+                "created_at": "2026-07-25T00:00:00Z",
+                "updated_at": "2026-07-25T00:00:00Z",
+            }
+        ),
+        encoding="utf-8",
+    )
+    marker = root / "must-survive.txt"
+    marker.write_text("preserve", encoding="utf-8")
+    return root
+
+
+@contextlib.contextmanager
+def running_server(*, store, demo=False, provider=None):
+    server = opc_app.create_app_server(
+        host="127.0.0.1",
+        port=0,
+        snapshot_provider=provider or opc_dashboard.load_demo_snapshot,
+        settings_store=store,
+        demo=demo,
+    )
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield server
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+
+def request(
+    server,
+    method: str,
+    path: str,
+    *,
+    headers: dict[str, str] | None = None,
+    payload: dict | None = None,
+):
+    host, port = server.server_address[:2]
+    body = None if payload is None else json.dumps(payload).encode("utf-8")
+    request_headers = dict(headers or {})
+    if body is not None:
+        request_headers.setdefault("Content-Type", "application/json")
+        request_headers["Content-Length"] = str(len(body))
+    connection = http.client.HTTPConnection(host, port, timeout=5)
+    connection.request(method, path, body=body, headers=request_headers)
+    response = connection.getresponse()
+    content = response.read()
+    response_headers = dict(response.getheaders())
+    connection.close()
+    decoded = json.loads(content) if content else None
+    return response.status, decoded, response_headers, content
+
+
+class SettingsStoreTests(unittest.TestCase):
+    def test_registry_is_app_owned_redacted_and_removal_preserves_project(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            state_root = base / "state"
+            project = project_fixture(base / "project")
+            store = opc_app.AppSettingsStore(state_root)
+
+            store.add_project(str(project))
+            context = store.context()
+            serialized = json.dumps(context)
+            settings = json.loads((state_root / "settings.json").read_text(encoding="utf-8"))
+
+            self.assertEqual(context["settings_state"], "ready")
+            self.assertEqual(context["projects"][0]["name"], "Synthetic Project")
+            self.assertEqual(context["projects"][0]["root_label"], "显式目录 1")
+            self.assertNotIn(str(project), serialized)
+            self.assertEqual(settings["projects"][0]["path"], str(project))
+
+            item_id = context["projects"][0]["id"]
+            store.remove_project(item_id)
+            self.assertEqual(store.project_roots(), ())
+            self.assertTrue((project / ".opc" / "project.json").is_file())
+            self.assertEqual((project / "must-survive.txt").read_text(encoding="utf-8"), "preserve")
+
+    def test_corrupt_registry_degrades_without_overwrite(self):
+        with tempfile.TemporaryDirectory() as directory:
+            state_root = Path(directory) / "state"
+            state_root.mkdir()
+            settings = state_root / "settings.json"
+            settings.write_text("{invalid", encoding="utf-8")
+            store = opc_app.AppSettingsStore(state_root)
+
+            self.assertEqual(store.project_roots(), ())
+            self.assertEqual(store.context()["settings_state"], "invalid")
+            with self.assertRaises(opc_app.AppSettingsError) as caught:
+                store.add_project(str(Path(directory) / "missing"))
+            self.assertEqual(caught.exception.code, "INVALID_SETTINGS")
+            self.assertEqual(settings.read_text(encoding="utf-8"), "{invalid")
+
+    def test_project_must_be_absolute_valid_and_unique(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            project = project_fixture(base / "project")
+            store = opc_app.AppSettingsStore(base / "state")
+            with self.assertRaises(opc_app.AppSettingsError) as relative:
+                store.add_project("relative/project")
+            self.assertEqual(relative.exception.code, "ABSOLUTE_PROJECT_ROOT_REQUIRED")
+            store.add_project(str(project))
+            with self.assertRaises(opc_app.AppSettingsError) as duplicate:
+                store.add_project(str(project))
+            self.assertEqual(duplicate.exception.code, "PROJECT_ALREADY_REGISTERED")
+
+    def test_linked_state_file_is_never_followed(self):
+        if not hasattr(os, "symlink"):
+            self.skipTest("symlink is unavailable")
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            state_root = base / "state"
+            state_root.mkdir()
+            outside = base / "outside.json"
+            outside.write_text(json.dumps(opc_app._default_settings()), encoding="utf-8")
+            try:
+                os.symlink(outside, state_root / "settings.json")
+            except (OSError, NotImplementedError):
+                self.skipTest("symlink creation is not permitted")
+            store = opc_app.AppSettingsStore(state_root)
+            self.assertEqual(store.context()["settings_state"], "invalid")
+            self.assertEqual(outside.read_text(encoding="utf-8"), json.dumps(opc_app._default_settings()))
+
+
+class SnapshotServiceTests(unittest.TestCase):
+    def test_app_allows_empty_registry_without_changing_dashboard_default(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            with self.assertRaises(opc_dashboard.DashboardError):
+                opc_dashboard.aggregate_snapshot(
+                    [],
+                    knowledge_root=base / "knowledge",
+                    data_root=base / "data",
+                )
+            snapshot = opc_dashboard.aggregate_snapshot(
+                [],
+                knowledge_root=base / "knowledge",
+                data_root=base / "data",
+                allow_empty=True,
+            )
+            self.assertEqual(snapshot["projects"], [])
+            self.assertEqual(snapshot["summary"]["active_projects"], 0)
+            self.assertNotEqual(snapshot["mode"], "demo")
+
+    def test_shared_service_validates_the_same_snapshot_contract(self):
+        expected = opc_dashboard.load_demo_snapshot()
+        service = SnapshotService(
+            project_roots_provider=tuple,
+            snapshot_builder=opc_dashboard.aggregate_snapshot,
+            demo_loader=opc_dashboard.load_demo_snapshot,
+            snapshot_validator=opc_dashboard._assert_redacted,
+            demo=True,
+        )
+        self.assertEqual(service.snapshot(), expected)
+
+
+class HTTPTests(unittest.TestCase):
+    def test_context_is_redacted_and_security_boundaries_are_enforced(self):
+        store = opc_app.DemoSettingsStore()
+        with running_server(store=store, demo=True) as server:
+            authority = f"http://127.0.0.1:{server.server_address[1]}"
+            status, context, headers, _ = request(server, "GET", "/api/app-context")
+            token = context["csrf_token"]
+            self.assertEqual(status, 200)
+            self.assertEqual(context["schema_version"], "opc-app.context.v1")
+            serialized = json.dumps(context, ensure_ascii=False)
+            self.assertNotRegex(serialized, r"[A-Za-z]:[\\/]")
+            self.assertNotIn("/home/", serialized)
+            self.assertIn("default-src 'self'", headers["Content-Security-Policy"])
+            self.assertEqual(headers["Cache-Control"], "no-store")
+
+            status, _, _, _ = request(
+                server,
+                "GET",
+                "/api/app-context",
+                headers={"Host": "remote.example"},
+            )
+            self.assertEqual(status, 400)
+            status, _, _, _ = request(
+                server,
+                "GET",
+                "/api/app-context",
+                headers={"Origin": "http://remote.example"},
+            )
+            self.assertEqual(status, 403)
+            status, _, _, _ = request(
+                server,
+                "POST",
+                "/api/selection",
+                payload={"project_id": "project-demo-primary"},
+            )
+            self.assertEqual(status, 403)
+            status, error, _, _ = request(
+                server,
+                "POST",
+                "/api/selection",
+                headers={"Origin": authority, "X-OPC-CSRF": token},
+                payload={"project_id": "project-demo-primary"},
+            )
+            self.assertEqual(status, 409)
+            self.assertEqual(error["error"], "DEMO_SETTINGS_READ_ONLY")
+            self.assertEqual(request(server, "PUT", "/api/snapshot")[0], 405)
+            self.assertEqual(request(server, "GET", "/api/app-context?raw=1")[0], 404)
+
+    def test_only_app_settings_routes_write_and_never_return_the_input_path(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            project = project_fixture(base / "project")
+            store = opc_app.AppSettingsStore(base / "state")
+            with running_server(store=store) as server:
+                authority = f"http://127.0.0.1:{server.server_address[1]}"
+                _, context, _, _ = request(server, "GET", "/api/app-context")
+                headers = {"Origin": authority, "X-OPC-CSRF": context["csrf_token"]}
+                status, context, _, raw = request(
+                    server,
+                    "POST",
+                    "/api/projects",
+                    headers=headers,
+                    payload={"path": str(project)},
+                )
+                self.assertEqual(status, 201)
+                self.assertNotIn(str(project).encode("utf-8"), raw)
+                self.assertTrue((project / "must-survive.txt").is_file())
+
+                item_id = context["projects"][0]["id"]
+                status, error, _, _ = request(
+                    server,
+                    "DELETE",
+                    f"/api/projects/{item_id}",
+                    headers=headers,
+                    payload={"unexpected": True},
+                )
+                self.assertEqual(status, 400)
+                self.assertEqual(error["error"], "INVALID_REQUEST")
+                self.assertTrue((project / "must-survive.txt").is_file())
+
+                status, context, _, raw = request(
+                    server,
+                    "DELETE",
+                    f"/api/projects/{item_id}",
+                    headers=headers,
+                )
+                self.assertEqual(status, 200)
+                self.assertEqual(context["projects"], [])
+                self.assertNotIn(str(project).encode("utf-8"), raw)
+                self.assertTrue((project / "must-survive.txt").is_file())
+
+                status, _, _, _ = request(
+                    server,
+                    "POST",
+                    "/api/snapshot",
+                    headers=headers,
+                    payload={"path": str(project)},
+                )
+                self.assertEqual(status, 404)
+
+
+class AssetContractTests(unittest.TestCase):
+    def test_complete_app_surface_is_local_and_has_distinct_views(self):
+        asset_root = ROOT / "plugins" / "codex-opc-team" / "assets" / "app"
+        parser = AppMarkupParser()
+        parser.feed((asset_root / "index.html").read_text(encoding="utf-8"))
+        self.assertEqual(
+            [item["data-nav"] for item in parser.navigation],
+            ["overview", "projects", "runs", "knowledge", "lineage", "health", "settings"],
+        )
+        self.assertEqual(
+            [item["data-view"] for item in parser.views],
+            ["overview", "projects", "runs", "knowledge", "lineage", "health", "settings"],
+        )
+        self.assertEqual(parser.remote_resources, [])
+        javascript = (asset_root / "dashboard.js").read_text(encoding="utf-8")
+        self.assertIn('fetchJSON("/api/app-context")', javascript)
+        self.assertIn('fetchJSON("/api/snapshot")', javascript)
+        self.assertNotIn("innerHTML", javascript)
+
+
+if __name__ == "__main__":
+    unittest.main()

From f95910d28733669f2081a9fbbfc7960b25576bd5 Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 13:30:36 +0800
Subject: [PATCH 02/11] fix(app): harden local control plane boundaries

---
 ...independent-local-opc-app-control-plane.md |  16 +-
 docs/installation-and-distribution.md         |   5 +-
 docs/opc-app.en.md                            |  12 +
 docs/opc-app.md                               |   9 +
 .../v0.2-public-synthetic-evidence.v1.json    |   2 +-
 .../codex-opc-team/assets/app/dashboard.css   |   4 +
 plugins/codex-opc-team/scripts/opc_app.py     | 153 ++-
 .../codex-opc-team/scripts/opc_dashboard.py   | 972 +-----------------
 .../scripts/opc_snapshot_service.py           | 959 ++++++++++++++++-
 scripts/opc_app_admin.py                      | 380 ++++++-
 tests/integration/test_opc_app_lifecycle.py   | 310 ++++++
 tests/unit/test_opc_app.py                    |  93 +-
 tests/unit/test_opc_dashboard.py              |  29 +-
 tests/unit/test_opc_snapshot_service.py       |  83 ++
 14 files changed, 1994 insertions(+), 1033 deletions(-)
 create mode 100644 tests/unit/test_opc_snapshot_service.py

diff --git a/docs/adr/0017-independent-local-opc-app-control-plane.md b/docs/adr/0017-independent-local-opc-app-control-plane.md
index f6c3aeb..8d1d8f0 100644
--- a/docs/adr/0017-independent-local-opc-app-control-plane.md
+++ b/docs/adr/0017-independent-local-opc-app-control-plane.md
@@ -22,13 +22,16 @@ loopback-only 浏览器视图可以安全降低经理理解 OPC 状态的成本
 1. **独立的是控制平面生命周期，不是执行 Harness。** App 只负责可视化、
    显式项目接入和 App 自有偏好；Agent 继续负责模型与工具执行。
 2. **一个 Snapshot 语义来源。** `opc_snapshot_service.py` 是旧 Dashboard 和
-   新 App 共用的应用服务边界，实际聚合、状态判断、固定 DTO 与脱敏仍只由
-   `opc_dashboard.py` 的既有实现提供。App 不复制治理规则。
+   新 App 共用的 core/service，实际聚合、状态判断、固定 DTO、脱敏、demo
+   校验与稳定读取均位于该模块。`opc_dashboard.py` 和 `opc_app.py` 只是入口
+   adapter，不互相 import，也不复制治理规则。
 3. **File/Git authoritative。** App 不持久化 OPC 业务事实。Mem0 仍是可选、
    可删除重建的 Provider；缺失或故障时准确降级。
 4. **App 状态与业务状态隔离。** 项目接入清单和当前项目选择位于
    `OPC_APP_HOME` 或平台文档化的用户状态目录，不在 checkout、插件安装目录、
-   项目 `.opc` 或知识根内。清单可删除重建。
+   runtime、项目/`.opc`、知识根或可重建数据根内。服务在创建目录或写入前，
+   对 lexical path 与 canonical realpath 执行双向 overlap 检查，并拒绝
+   symlink/junction ancestor；已有恶意清单也不能绕过。清单可删除重建。
 5. **显式接入，不扫描。** 用户提交一个绝对项目目录；服务端只验证该目录的
    `.opc/project.json`。响应仅返回 `显式目录 N`、安全项目名和 portable ID，
    不回传绝对路径。
@@ -40,9 +43,10 @@ loopback-only 浏览器视图可以安全降低经理理解 OPC 状态的成本
 8. **无大型构建链。** 延续 Python 标准库服务和无构建步骤的 HTML/CSS/JS。
    当前交互规模没有足够证据引入 Electron、Tauri、React 或 Node 供应链。
 9. **独立可回滚分发。** App 安装器把公开插件快照复制到用户级 runtime，
-   用内容哈希 release 与原子 current pointer 支持安装、升级和回滚。卸载只删除
-   runtime；App 状态、项目、File/Git knowledge、Git 历史、用户配置和 Mem0
-   数据全部保留。
+   为每个 release 持久化完整文件清单、大小与 SHA-256，用内容哈希 release
+   与原子 current pointer 支持安装、升级和回滚。staging、激活、启动、状态检查
+   和回滚前都会复验完整性；损坏 release 不会被激活。卸载只删除 runtime；
+   App 状态、项目、File/Git knowledge、Git 历史、用户配置和 Mem0 数据全部保留。
 10. **旧入口兼容。** 不安装或不启动 App 时，Codex Plugin、Skills、Hook、
     脚本和 `opc_dashboard.py` 的行为与生命周期 Gate 不变。
 
diff --git a/docs/installation-and-distribution.md b/docs/installation-and-distribution.md
index 513b284..9c962a6 100644
--- a/docs/installation-and-distribution.md
+++ b/docs/installation-and-distribution.md
@@ -162,7 +162,10 @@ python scripts/opc_app_admin.py status
 
 安装结果会打印 Windows 和 Linux 可用的本地 launcher。更新、回滚和卸载也分别
 使用 `update`、`rollback`、`uninstall` 子命令并坚持 preview → `--apply`。
-runtime release 使用内容哈希与原子 pointer；App 状态位于独立用户状态目录。
+runtime release 使用完整文件 manifest、逐文件 SHA-256、内容哈希 ID 与原子
+pointer；staging、激活、status、launcher 和 rollback 均复验完整性。App 状态
+位于独立用户状态目录，并拒绝与 checkout、plugin/runtime、项目/`.opc`、
+knowledge/data root 的 lexical 或 canonical 双向重叠。
 
 App 卸载不删除 App 接入清单、项目 `.opc`、File/Git knowledge、Git 历史、
 用户配置或 Mem0 数据。它不安装或管理 Codex、Claude、Kimi 本体，也不写这些
diff --git a/docs/opc-app.en.md b/docs/opc-app.en.md
index 3e5553e..1b7451b 100644
--- a/docs/opc-app.en.md
+++ b/docs/opc-app.en.md
@@ -79,6 +79,12 @@ The runtime and App state are separate. The default state root is
 overrides it. This registry and current-project preference are rebuildable App
 settings, not OPC facts.
 
+The state root must not overlap the source checkout, plugin/runtime, any
+explicit project or `.opc`, the knowledge root, or the rebuildable data root
+in either direction. Lexical and canonical real paths are checked before
+directory creation or settings writes, and symlink/junction parents are
+rejected.
+
 Uninstall removes only the runtime:
 
 ```text
@@ -90,6 +96,12 @@ App state, project `.opc`, File/Git knowledge, Git history, existing user
 configuration, and Mem0 data are preserved. This installer does not install
 Codex, Claude, or Kimi and does not edit Agent global configuration.
 
+Every runtime release carries a complete file manifest with sizes and SHA-256
+digests. Staging, activation, `status`, the launcher, and rollback all verify
+it. Missing, modified, extra, linked, or unreadable content fails closed. A
+trusted `update --apply` can repair the same damaged release, and the current
+pointer changes only after successful verification.
+
 ## 4. Project and privacy boundary
 
 The user submits one absolute directory. The server checks only that directory
diff --git a/docs/opc-app.md b/docs/opc-app.md
index 286eaa3..c1c4f45 100644
--- a/docs/opc-app.md
+++ b/docs/opc-app.md
@@ -78,6 +78,10 @@ App runtime 默认位于平台用户数据目录；App 状态与 runtime 分开
 可用 `OPC_APP_HOME` 显式覆盖状态根。状态根保存项目接入清单和当前项目选择，
 可以删除重建，但不是 OPC 业务事实来源。
 
+状态根不能与源码 checkout、插件/runtime、任何显式项目或 `.opc`、知识根、数据
+根存在父子重叠，也不能经过 symlink/junction parent。检查同时比较 lexical path
+和 canonical realpath，并且发生在目录创建与 settings 写入之前。
+
 卸载只删除 App runtime：
 
 ```powershell
@@ -88,6 +92,11 @@ python scripts/opc_app_admin.py uninstall --apply
 App 状态、项目 `.opc`、File/Git knowledge、Git 历史、用户配置和 Mem0 数据均
 保留。安装器不安装 Codex、Claude、Kimi，也不编辑任何 Agent 全局配置。
 
+每个 runtime release 都携带完整文件 manifest、文件大小和 SHA-256。安装 staging、
+激活、`status`、launcher 和 rollback 都会复验清单；缺失、篡改、额外文件、内部
+链接或不可读内容会 fail closed。对同一可信源码再次执行 `update --apply` 可修复
+损坏 release，current pointer 只在复验成功后原子切换。
+
 ## 4. 项目接入与隐私
 
 接入流程固定为：
diff --git a/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json b/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json
index bea3dcd..2f7db1e 100644
--- a/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json
+++ b/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json
@@ -7,7 +7,7 @@
     {
       "issue": 2,
       "path": "docs/installation-and-distribution.md",
-      "sha256": "204e7c030954d11e9b4b3e4e3a4d6676ae773703da58041ea7711e205f0a4593"
+      "sha256": "90c8c870053666e971ebf9a0887c2a6fe103580809b1a87f7220267362a91d85"
     },
     {
       "issue": 3,
diff --git a/plugins/codex-opc-team/assets/app/dashboard.css b/plugins/codex-opc-team/assets/app/dashboard.css
index f10f902..f717f40 100644
--- a/plugins/codex-opc-team/assets/app/dashboard.css
+++ b/plugins/codex-opc-team/assets/app/dashboard.css
@@ -25,6 +25,10 @@
   box-sizing: border-box;
 }
 
+.filterable[hidden] {
+  display: none !important;
+}
+
 html {
   min-width: 320px;
   background: var(--canvas);
diff --git a/plugins/codex-opc-team/scripts/opc_app.py b/plugins/codex-opc-team/scripts/opc_app.py
index 2cd2343..d557ea0 100644
--- a/plugins/codex-opc-team/scripts/opc_app.py
+++ b/plugins/codex-opc-team/scripts/opc_app.py
@@ -22,7 +22,7 @@
 from typing import Any, Mapping, Sequence
 from urllib.parse import unquote, urlsplit
 
-from opc_dashboard import (
+from opc_snapshot_service import (
     DashboardError,
     DashboardHTTPServer,
     DashboardRequestHandler,
@@ -32,13 +32,11 @@
     _authority,
     _read_json,
     _safe_text,
-    aggregate_snapshot,
-    load_demo_snapshot,
     utc_now,
     validate_bind_host,
+    SnapshotService,
 )
 from opc_memory import resolve_data_root, resolve_knowledge_root
-from opc_snapshot_service import SnapshotService
 
 
 APP_CONTEXT_SCHEMA = "opc-app.context.v1"
@@ -46,7 +44,9 @@
 MAX_SETTINGS_BYTES = 256 * 1024
 MAX_REQUEST_BYTES = 16 * 1024
 MAX_PROJECTS = 64
-APP_ASSET_ROOT = Path(__file__).resolve().parents[1] / "assets" / "app"
+PLUGIN_ROOT = Path(__file__).resolve().parents[1]
+SOURCE_CONTAINER_ROOT = Path(__file__).resolve().parents[3]
+APP_ASSET_ROOT = PLUGIN_ROOT / "assets" / "app"
 
 
 class AppSettingsError(RuntimeError):
@@ -78,16 +78,87 @@ def _is_link(metadata: os.stat_result) -> bool:
     return bool(reparse and attributes & reparse)
 
 
-def _safe_state_root(path: Path) -> Path:
-    root = Path(os.path.abspath(path))
-    plugin_root = Path(__file__).resolve().parents[1]
+def _normalized_path(path: Path | str, *, canonical: bool) -> Path:
+    value = os.path.abspath(Path(path).expanduser())
+    if canonical:
+        value = os.path.realpath(value)
+    return Path(os.path.normcase(value))
+
+
+def _paths_overlap(left: Path, right: Path) -> bool:
     try:
-        root.relative_to(plugin_root)
+        left.relative_to(right)
+        return True
     except ValueError:
         pass
-    else:
-        raise AppSettingsError("STATE_INSIDE_PLUGIN")
-    root.mkdir(parents=True, exist_ok=True)
+    try:
+        right.relative_to(left)
+        return True
+    except ValueError:
+        return False
+
+
+def _runtime_root() -> Path | None:
+    for parent in (PLUGIN_ROOT, *PLUGIN_ROOT.parents):
+        if (parent / ".opc-app-owned.json").is_file():
+            return parent
+    return None
+
+
+def _assert_unlinked_ancestors(path: Path) -> None:
+    current = Path(os.path.abspath(path))
+    while True:
+        if os.path.lexists(current):
+            try:
+                metadata = current.lstat()
+            except OSError as exc:
+                raise AppSettingsError("STATE_UNAVAILABLE") from exc
+            if _is_link(metadata):
+                raise AppSettingsError("UNSAFE_STATE_ROOT")
+        parent = current.parent
+        if parent == current:
+            return
+        current = parent
+
+
+def _assert_no_root_overlap(
+    state_root: Path,
+    forbidden_roots: Sequence[Path | str],
+) -> None:
+    state_variants = (
+        _normalized_path(state_root, canonical=False),
+        _normalized_path(state_root, canonical=True),
+    )
+    for forbidden in forbidden_roots:
+        forbidden_variants = (
+            _normalized_path(forbidden, canonical=False),
+            _normalized_path(forbidden, canonical=True),
+        )
+        if any(
+            _paths_overlap(state_variant, forbidden_variant)
+            for state_variant in state_variants
+            for forbidden_variant in forbidden_variants
+        ):
+            raise AppSettingsError("STATE_ROOT_OVERLAP")
+
+
+def _safe_state_root(
+    path: Path,
+    *,
+    forbidden_roots: Sequence[Path | str] = (),
+    create: bool = False,
+) -> Path:
+    root = Path(os.path.abspath(path))
+    _assert_unlinked_ancestors(root)
+    built_in_roots: list[Path | str] = [PLUGIN_ROOT, SOURCE_CONTAINER_ROOT]
+    runtime_root = _runtime_root()
+    if runtime_root is not None:
+        built_in_roots.append(runtime_root)
+    _assert_no_root_overlap(root, (*built_in_roots, *forbidden_roots))
+    if create:
+        root.mkdir(parents=True, exist_ok=True)
+    if not os.path.lexists(root):
+        return root
     try:
         metadata = root.lstat()
     except OSError as exc:
@@ -108,11 +179,29 @@ def _default_settings() -> dict[str, Any]:
 class AppSettingsStore:
     """Atomic App-owned registry; project paths never leave this process."""
 
-    def __init__(self, state_root: Path | str):
-        self.root = _safe_state_root(Path(state_root))
+    def __init__(
+        self,
+        state_root: Path | str,
+        *,
+        forbidden_roots: Sequence[Path | str] = (),
+    ):
+        self._configured_forbidden_roots = tuple(Path(item) for item in forbidden_roots)
+        self.root = _safe_state_root(
+            Path(state_root),
+            forbidden_roots=self._configured_forbidden_roots,
+        )
         self.path = self.root / "settings.json"
         self._lock = threading.RLock()
 
+    def _assert_state_isolated(
+        self,
+        project_roots: Sequence[Path | str] = (),
+    ) -> None:
+        _assert_no_root_overlap(
+            self.root,
+            (*self._configured_forbidden_roots, *project_roots),
+        )
+
     def _load_strict(self) -> dict[str, Any]:
         if not os.path.lexists(self.path):
             return _default_settings()
@@ -156,10 +245,26 @@ def _load_strict(self) -> dict[str, Any]:
         selected = payload.get("selected_project_id")
         if selected is not None and selected not in seen_ids:
             raise AppSettingsError("INVALID_SETTINGS")
+        self._assert_state_isolated(
+            [Path(item["path"]) for item in payload["projects"]]
+        )
         return payload
 
     def _write(self, payload: Mapping[str, Any]) -> None:
-        root = _safe_state_root(self.root)
+        project_roots = [
+            Path(item["path"])
+            for item in payload.get("projects", [])
+            if isinstance(item, Mapping) and isinstance(item.get("path"), str)
+        ]
+        self._assert_state_isolated(project_roots)
+        root = _safe_state_root(
+            self.root,
+            forbidden_roots=(
+                *self._configured_forbidden_roots,
+                *project_roots,
+            ),
+            create=True,
+        )
         if os.path.lexists(self.path):
             metadata = self.path.lstat()
             if (
@@ -294,6 +399,7 @@ def add_project(self, value: str) -> None:
         with self._lock:
             payload = self._load_strict()
             root = self._normalize_project_root(value)
+            self._assert_state_isolated([root])
             normalized = os.path.normcase(str(root))
             if any(
                 os.path.normcase(os.path.abspath(item["path"])) == normalized
@@ -591,20 +697,19 @@ def main(argv: Sequence[str] | None = None) -> int:
             settings_store: AppSettingsStore | DemoSettingsStore = DemoSettingsStore()
             service = SnapshotService(
                 project_roots_provider=settings_store.project_roots,
-                snapshot_builder=aggregate_snapshot,
-                demo_loader=load_demo_snapshot,
-                snapshot_validator=_assert_redacted,
                 demo=True,
             )
         else:
-            settings_store = AppSettingsStore(resolve_app_state_root(args.state_root))
+            knowledge_root = resolve_knowledge_root(args.knowledge_root)
+            data_root = resolve_data_root(args.data_root)
+            settings_store = AppSettingsStore(
+                resolve_app_state_root(args.state_root),
+                forbidden_roots=(knowledge_root, data_root),
+            )
             service = SnapshotService(
                 project_roots_provider=settings_store.project_roots,
-                snapshot_builder=aggregate_snapshot,
-                demo_loader=load_demo_snapshot,
-                snapshot_validator=_assert_redacted,
-                knowledge_root=resolve_knowledge_root(args.knowledge_root),
-                data_root=resolve_data_root(args.data_root),
+                knowledge_root=knowledge_root,
+                data_root=data_root,
                 allow_empty=True,
             )
         server = create_app_server(
diff --git a/plugins/codex-opc-team/scripts/opc_dashboard.py b/plugins/codex-opc-team/scripts/opc_dashboard.py
index 6323a8b..0b1d7c7 100644
--- a/plugins/codex-opc-team/scripts/opc_dashboard.py
+++ b/plugins/codex-opc-team/scripts/opc_dashboard.py
@@ -1,936 +1,52 @@
 #!/usr/bin/env python3
-"""Serve a local, read-only OPC dashboard and build redacted snapshots.
-
-The dashboard is deliberately a projection over existing File/Git and project
-state.  It does not mutate OPC state and never returns knowledge bodies, raw
-feedback, filesystem paths, or run/session/thread identifiers.
-"""
+"""Serve the legacy local, read-only OPC Dashboard presentation."""
 
 from __future__ import annotations
 
 import argparse
-import json
-import os
-import re
-import socket
-import stat
 import sys
 import webbrowser
-from datetime import datetime, timezone
-from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
-from typing import Any, Callable, Mapping, Sequence
-from urllib.parse import urlsplit
-
-from opc_feedback import read_feedback
-from opc_lineage import build_view
-from opc_memory import (
-    FileGitBackend,
-    MemoryService,
-    resolve_data_root,
-    resolve_knowledge_root,
+from typing import Any, Callable, Sequence
+
+from opc_memory import resolve_data_root, resolve_knowledge_root
+from opc_snapshot_service import (
+    ASSET_ROUTES,
+    MAX_ACCEPTANCE_BYTES,
+    MAX_DEMO_BYTES,
+    MAX_JSON_BYTES,
+    MAX_PROJECTS,
+    PORTABLE_ID,
+    SCHEMA_VERSION,
+    SECURITY_HEADERS,
+    DashboardError,
+    DashboardHTTPServer,
+    DashboardRequestHandler,
+    IPv6DashboardHTTPServer,
+    SnapshotError,
+    SnapshotService,
+    _assert_redacted,
+    _authority,
+    _identity,
+    _is_link,
+    _looks_like_absolute_path,
+    _manager_queue,
+    _parse_acceptance,
+    _project_warning,
+    _read_checkpoint,
+    _read_json,
+    _read_project,
+    _read_stable_bytes,
+    _safe_text,
+    _safe_time,
+    _unavailable_acceptance,
+    _validate_demo_snapshot,
+    aggregate_snapshot,
+    create_server,
+    load_demo_snapshot,
+    utc_now,
+    validate_bind_host,
 )
-from opc_snapshot_service import SnapshotService
-
-
-SCHEMA_VERSION = "opc-dashboard.snapshot.v1"
-MAX_JSON_BYTES = 512 * 1024
-MAX_ACCEPTANCE_BYTES = 128 * 1024
-MAX_DEMO_BYTES = 512 * 1024
-MAX_PROJECTS = 64
-PORTABLE_ID = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
-RUN_STATUSES = {
-    "aligning",
-    "planned",
-    "implementing",
-    "validating",
-    "ready_for_manager",
-    "completed",
-    "paused",
-    "failed",
-}
-ASSET_ROUTES = {
-    "/": ("index.html", "text/html; charset=utf-8"),
-    "/index.html": ("index.html", "text/html; charset=utf-8"),
-    "/dashboard.css": ("dashboard.css", "text/css; charset=utf-8"),
-    "/dashboard.js": ("dashboard.js", "text/javascript; charset=utf-8"),
-}
-SECURITY_HEADERS = {
-    "Cache-Control": "no-store",
-    "Content-Security-Policy": (
-        "default-src 'self'; base-uri 'none'; object-src 'none'; "
-        "frame-ancestors 'none'; form-action 'none'; connect-src 'self'; "
-        "img-src 'self' data:; script-src 'self'; style-src 'self'"
-    ),
-    "Permissions-Policy": (
-        "camera=(), microphone=(), geolocation=(), payment=(), usb=(), "
-        "interest-cohort=()"
-    ),
-    "Referrer-Policy": "no-referrer",
-    "X-Content-Type-Options": "nosniff",
-    "X-Frame-Options": "DENY",
-}
-
-
-class DashboardError(RuntimeError):
-    """A safe dashboard error whose code is suitable for redacted output."""
-
-    def __init__(self, code: str):
-        super().__init__(code)
-        self.code = code
-
-
-def utc_now() -> str:
-    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-
-
-def _is_link(metadata: os.stat_result) -> bool:
-    if stat.S_ISLNK(metadata.st_mode):
-        return True
-    attributes = getattr(metadata, "st_file_attributes", 0)
-    reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
-    return bool(reparse and attributes & reparse)
-
-
-def _identity(metadata: os.stat_result) -> tuple[int, int, int, int, int]:
-    return (
-        int(metadata.st_dev),
-        int(metadata.st_ino),
-        int(metadata.st_size),
-        int(getattr(metadata, "st_mtime_ns", int(metadata.st_mtime * 1_000_000_000))),
-        int(metadata.st_nlink),
-    )
-
-
-def _read_checkpoint(label: str, path: Path) -> None:
-    """Test seam for simulating changes at read transaction boundaries."""
-
-
-def _assert_safe_chain(root: Path, path: Path) -> None:
-    try:
-        relative = path.relative_to(root)
-    except ValueError as exc:
-        raise DashboardError("PATH_ESCAPE") from exc
-    current = root
-    for part in (Path("."), *relative.parts):
-        if part != Path("."):
-            current = current / part
-        try:
-            metadata = current.lstat()
-        except OSError as exc:
-            raise DashboardError("SOURCE_UNAVAILABLE") from exc
-        if _is_link(metadata):
-            raise DashboardError("LINKED_SOURCE")
-
-
-def _read_stable_bytes(
-    path: Path,
-    *,
-    root: Path,
-    maximum: int,
-    label: str,
-) -> bytes:
-    """Read one bounded regular file without following links or hardlinks."""
-
-    lexical_root = Path(os.path.abspath(root))
-    lexical_path = Path(os.path.abspath(path))
-    _assert_safe_chain(lexical_root, lexical_path)
-    try:
-        before = lexical_path.lstat()
-    except OSError as exc:
-        raise DashboardError("SOURCE_UNAVAILABLE") from exc
-    if _is_link(before) or not stat.S_ISREG(before.st_mode):
-        raise DashboardError("UNSAFE_SOURCE")
-    if before.st_nlink != 1:
-        raise DashboardError("HARDLINKED_SOURCE")
-    if before.st_size > maximum:
-        raise DashboardError("SOURCE_TOO_LARGE")
-    _read_checkpoint(f"{label}:before_open", lexical_path)
-    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
-    descriptor: int | None = None
-    try:
-        descriptor = os.open(lexical_path, flags)
-        opened = os.fstat(descriptor)
-        if (
-            _is_link(opened)
-            or not stat.S_ISREG(opened.st_mode)
-            or opened.st_nlink != 1
-            or _identity(opened) != _identity(before)
-        ):
-            raise DashboardError("SOURCE_CHANGED")
-        chunks: list[bytes] = []
-        remaining = maximum + 1
-        while remaining:
-            chunk = os.read(descriptor, min(64 * 1024, remaining))
-            if not chunk:
-                break
-            chunks.append(chunk)
-            remaining -= len(chunk)
-        payload = b"".join(chunks)
-        if len(payload) > maximum:
-            raise DashboardError("SOURCE_TOO_LARGE")
-        after_descriptor = os.fstat(descriptor)
-        _read_checkpoint(f"{label}:before_verify", lexical_path)
-        after_path = lexical_path.lstat()
-        if (
-            _identity(before) != _identity(after_descriptor)
-            or _identity(before) != _identity(after_path)
-            or _is_link(after_path)
-        ):
-            raise DashboardError("SOURCE_CHANGED")
-        return payload
-    except DashboardError:
-        raise
-    except OSError as exc:
-        raise DashboardError("SOURCE_UNAVAILABLE") from exc
-    finally:
-        if descriptor is not None:
-            os.close(descriptor)
-
-
-def _read_json(path: Path, *, root: Path, maximum: int = MAX_JSON_BYTES) -> dict[str, Any]:
-    raw = _read_stable_bytes(path, root=root, maximum=maximum, label=path.name)
-    try:
-        value = json.loads(
-            raw.decode("utf-8"),
-            parse_constant=lambda token: (_ for _ in ()).throw(ValueError(token)),
-        )
-    except (UnicodeError, ValueError, json.JSONDecodeError) as exc:
-        raise DashboardError("INVALID_JSON") from exc
-    if not isinstance(value, dict):
-        raise DashboardError("INVALID_JSON")
-    return value
-
-
-def _safe_text(value: Any, *, maximum: int = 160) -> str | None:
-    if not isinstance(value, str):
-        return None
-    text = " ".join(value.split()).strip()
-    if (
-        not text
-        or len(text) > maximum
-        or any(ord(char) < 32 for char in text)
-        or _looks_like_absolute_path(text)
-    ):
-        return None
-    return text
-
-
-def _looks_like_absolute_path(value: str) -> bool:
-    posix_path = re.search(
-        r"(?:^|[\s\"'(`])/(?:home|root|etc|var|tmp|opt|usr|private|mnt|srv|workspace|workspaces)(?:/|$)",
-        value,
-    )
-    return bool(
-        re.search(r"(?:^|[\s\"'])[A-Za-z]:[\\/]", value)
-        or value.startswith("\\\\")
-        or value.startswith("/")
-        or posix_path
-    )
-
-
-def _safe_time(value: Any) -> str | None:
-    text = _safe_text(value, maximum=64)
-    if text is None:
-        return None
-    try:
-        datetime.fromisoformat(text.replace("Z", "+00:00"))
-    except ValueError:
-        return None
-    return text
-
-
-def _parse_acceptance(path: Path, project_root: Path) -> dict[str, Any]:
-    try:
-        raw = _read_stable_bytes(
-            path,
-            root=project_root,
-            maximum=MAX_ACCEPTANCE_BYTES,
-            label="acceptance",
-        )
-        text = raw.decode("utf-8")
-    except UnicodeError as exc:
-        raise DashboardError("INVALID_ACCEPTANCE") from exc
-    lines = [line.strip() for line in text.splitlines()]
-    header_index = next(
-        (
-            index
-            for index, line in enumerate(lines)
-            if line.startswith("|")
-            and "criterion" in line.lower()
-            and "status" in line.lower()
-        ),
-        None,
-    )
-    if header_index is None or header_index + 1 >= len(lines):
-        raise DashboardError("INVALID_ACCEPTANCE")
-    header = [part.strip().lower() for part in lines[header_index].strip("|").split("|")]
-    try:
-        status_index = header.index("status")
-    except ValueError as exc:
-        raise DashboardError("INVALID_ACCEPTANCE") from exc
-    separator = [part.strip() for part in lines[header_index + 1].strip("|").split("|")]
-    if len(separator) != len(header) or not all(re.fullmatch(r":?-{3,}:?", part) for part in separator):
-        raise DashboardError("INVALID_ACCEPTANCE")
-    statuses: list[str] = []
-    for line in lines[header_index + 2 :]:
-        if not line.startswith("|"):
-            break
-        cells = [part.strip() for part in line.strip("|").split("|")]
-        if len(cells) != len(header):
-            raise DashboardError("INVALID_ACCEPTANCE")
-        statuses.append(cells[status_index].lower())
-    if not statuses:
-        raise DashboardError("INVALID_ACCEPTANCE")
-    passed = sum(status in {"pass", "passed", "done", "complete", "completed"} for status in statuses)
-    return {"passed": passed, "total": len(statuses), "state": "available"}
-
-
-def _unavailable_acceptance(state: str) -> dict[str, Any]:
-    return {"passed": 0, "total": 0, "state": state}
-
-
-def _project_warning(code: str, project_id: str | None, message: str) -> dict[str, Any]:
-    out: dict[str, Any] = {"code": code, "severity": "warning", "message": message}
-    if project_id:
-        out["project_id"] = project_id
-    return out
-
-
-def _feedback_status(project_root: Path) -> str:
-    try:
-        view = read_feedback(project_root)
-        record = view.get("structured_feedback")
-        if record is None:
-            return "unavailable"
-        events = record.get("events")
-        return "available" if isinstance(events, list) else "invalid"
-    except Exception:
-        return "invalid"
-
-
-def _lineage_status(project_root: Path, knowledge_root: Path | None) -> str:
-    try:
-        view = build_view(project_root, knowledge_root=knowledge_root)
-        state = view.get("lineage_status")
-        return state if state in {"available", "degraded", "unavailable"} else "invalid"
-    except Exception:
-        return "invalid"
-
-
-def _read_project(
-    project_root: Path,
-    *,
-    index: int,
-    knowledge_root: Path | None,
-) -> tuple[dict[str, Any], list[dict[str, Any]]]:
-    fallback_id = f"project-{index + 1}"
-    fallback = {
-        "id": fallback_id,
-        "name": f"项目 {index + 1}",
-        "source_state": "invalid",
-        "run": {
-            "title": "状态不可用",
-            "status": "invalid",
-            "active": False,
-            "updated_at": None,
-        },
-        "acceptance": _unavailable_acceptance("invalid"),
-        "feedback_status": "invalid",
-        "lineage_status": "invalid",
-    }
-    warnings: list[dict[str, Any]] = []
-    lexical_root = Path(os.path.abspath(project_root))
-    try:
-        project = _read_json(lexical_root / ".opc" / "project.json", root=lexical_root)
-        project_id = _safe_text(project.get("project_id"), maximum=128)
-        name = _safe_text(project.get("name"), maximum=160)
-        if (
-            project_id is None
-            or PORTABLE_ID.fullmatch(project_id) is None
-            or name is None
-        ):
-            raise DashboardError("INVALID_PROJECT")
-    except DashboardError as exc:
-        warnings.append(
-            _project_warning(
-                exc.code,
-                None,
-                f"第 {index + 1} 个项目来源无效，已安全降级。",
-            )
-        )
-        return fallback, warnings
-
-    run_projection = {
-        "title": "暂无运行",
-        "status": "unavailable",
-        "active": False,
-        "updated_at": None,
-    }
-    source_state = "available"
-    try:
-        run = _read_json(lexical_root / ".opc" / "run.json", root=lexical_root)
-        title = _safe_text(run.get("title"), maximum=200)
-        status_value = run.get("status")
-        active = run.get("active")
-        updated_at = _safe_time(run.get("updated_at"))
-        if (
-            run.get("project_id") != project_id
-            or title is None
-            or status_value not in RUN_STATUSES
-            or not isinstance(active, bool)
-            or updated_at is None
-        ):
-            raise DashboardError("INVALID_RUN")
-        run_projection = {
-            "title": title,
-            "status": status_value,
-            "active": active,
-            "updated_at": updated_at,
-        }
-    except DashboardError as exc:
-        source_state = "degraded"
-        run_projection["status"] = "invalid" if exc.code != "SOURCE_UNAVAILABLE" else "unavailable"
-        warnings.append(
-            _project_warning(exc.code, project_id, "运行状态不可用，项目仍以只读方式展示。")
-        )
-
-    try:
-        acceptance = _parse_acceptance(lexical_root / ".opc" / "acceptance.md", lexical_root)
-    except DashboardError as exc:
-        source_state = "degraded"
-        acceptance = _unavailable_acceptance(
-            "unavailable" if exc.code == "SOURCE_UNAVAILABLE" else "invalid"
-        )
-        warnings.append(
-            _project_warning(exc.code, project_id, "验收契约不可用，未推测验收进度。")
-        )
-
-    feedback_status = _feedback_status(lexical_root)
-    lineage_status = _lineage_status(lexical_root, knowledge_root)
-    if feedback_status == "invalid" or lineage_status == "invalid":
-        source_state = "degraded"
-    return (
-        {
-            "id": project_id,
-            "name": name,
-            "source_state": source_state,
-            "run": run_projection,
-            "acceptance": acceptance,
-            "feedback_status": feedback_status,
-            "lineage_status": lineage_status,
-        },
-        warnings,
-    )
-
-
-def _knowledge_snapshot(
-    knowledge_root: Path,
-    data_root: Path,
-) -> tuple[dict[str, int | str], dict[str, Any], list[dict[str, Any]]]:
-    counts: dict[str, int | str] = {
-        "candidate": 0,
-        "approved_uncommitted": 0,
-        "published": 0,
-        "rejected": 0,
-        "obsolete": 0,
-        "state": "unavailable",
-    }
-    health = {
-        "file_git": {
-            "state": "unavailable",
-            "label": "File/Git 不可用",
-            "detail": "无法读取规范知识状态。",
-        },
-        "mem0": {
-            "state": "unavailable",
-            "label": "Mem0 不可用",
-            "detail": "可选检索索引状态不可用。",
-        },
-    }
-    warnings: list[dict[str, Any]] = []
-    try:
-        backend = FileGitBackend(knowledge_root)
-        doctor = backend.doctor()
-        if doctor.get("state") == "NOT_INITIALIZED":
-            counts["state"] = "unavailable"
-            health["file_git"] = {
-                "state": "unavailable",
-                "label": "File/Git 未初始化",
-                "detail": "规范知识仓库尚未就绪。",
-            }
-            warnings.append(
-                {
-                    "code": "KNOWLEDGE_NOT_INITIALIZED",
-                    "severity": "warning",
-                    "message": "知识仓库尚未初始化。",
-                }
-            )
-        elif not doctor.get("ok"):
-            counts["state"] = "invalid"
-            health["file_git"] = {
-                "state": "invalid",
-                "label": "File/Git 无效",
-                "detail": "知识仓库结构或记录未通过校验。",
-            }
-            warnings.append(
-                {
-                    "code": "KNOWLEDGE_INVALID",
-                    "severity": "warning",
-                    "message": "知识仓库存在无效记录，未展示推测数据。",
-                }
-            )
-        else:
-            governance = backend.governance_snapshot()
-            inventory = governance.get("inventory", {})
-            provenance = governance.get("provenance", {})
-            for record_id, metadata in inventory.items():
-                status_value = metadata.get("status")
-                if status_value == "approved":
-                    proof = provenance.get(record_id, {})
-                    if proof.get("source_commit"):
-                        counts["published"] = int(counts["published"]) + 1
-                    else:
-                        counts["approved_uncommitted"] = int(counts["approved_uncommitted"]) + 1
-                elif status_value in {"candidate", "rejected", "obsolete"}:
-                    counts[status_value] = int(counts[status_value]) + 1
-            counts["state"] = "available"
-            git_state = doctor.get("git", {})
-            degraded = not doctor.get("provenance_ready") or bool(git_state.get("authoritative_uncommitted"))
-            health["file_git"] = {
-                "state": "degraded" if degraded else "available",
-                "label": "File/Git 需关注" if degraded else "File/Git 正常",
-                "detail": (
-                    "知识可读，但 Git provenance 尚未完全就绪。"
-                    if degraded
-                    else "规范知识与 Git provenance 已就绪。"
-                ),
-            }
-        service = MemoryService.from_paths(knowledge_root, data_root)
-        memory_status = service.status()
-        mem0 = memory_status.get("mem0", {})
-        provider_health = mem0.get("health")
-        if provider_health == "disabled":
-            health["mem0"] = {
-                "state": "disabled",
-                "label": "Mem0 已停用",
-                "detail": "当前使用 File/Git 检索，功能可正常降级。",
-            }
-        elif provider_health == "configured-unverified":
-            health["mem0"] = {
-                "state": "degraded",
-                "label": "Mem0 待验证",
-                "detail": "索引已配置，但本次只读检查未调用外部 Provider。",
-            }
-        else:
-            health["mem0"] = {
-                "state": "degraded",
-                "label": "Mem0 已降级",
-                "detail": "可选索引不可用，仍使用 File/Git。",
-            }
-    except Exception:
-        warnings.append(
-            {
-                "code": "KNOWLEDGE_SOURCE_UNAVAILABLE",
-                "severity": "warning",
-                "message": "知识或检索状态不可用，未自动填充演示数据。",
-            }
-        )
-    return counts, health, warnings
-
-
-def _manager_queue(
-    projects: Sequence[Mapping[str, Any]],
-    knowledge: Mapping[str, Any],
-    health: Mapping[str, Any],
-) -> list[dict[str, Any]]:
-    queue: list[dict[str, Any]] = []
-    for project in projects:
-        project_id = str(project["id"])
-        run = project["run"]
-        acceptance = project["acceptance"]
-        if run["status"] == "ready_for_manager":
-            queue.append(
-                {
-                    "id": f"handoff-{project_id}",
-                    "type": "manager_handoff",
-                    "severity": "high",
-                    "title": f"{project['name']} 等待体验",
-                    "description": "实现与内部验证已完成，等待经理体验与方向判断。",
-                    "project_id": project_id,
-                    "next_step": "按体验路径检查结果并给出反馈。",
-                }
-            )
-        elif run["status"] in {"failed", "paused"}:
-            queue.append(
-                {
-                    "id": f"run-{project_id}",
-                    "type": "run_attention",
-                    "severity": "high",
-                    "title": f"{project['name']} 运行需处理",
-                    "description": f"当前运行状态为 {run['status']}。",
-                    "project_id": project_id,
-                    "next_step": "查看项目并决定恢复、调整或终止。",
-                }
-            )
-        if (
-            acceptance.get("state") == "available"
-            and acceptance.get("total", 0) > acceptance.get("passed", 0)
-        ):
-            pending = int(acceptance["total"]) - int(acceptance["passed"])
-            queue.append(
-                {
-                    "id": f"acceptance-{project_id}",
-                    "type": "acceptance",
-                    "severity": "medium",
-                    "title": f"{project['name']} 尚有 {pending} 项验收",
-                    "description": "验收契约仍有未通过项。",
-                    "project_id": project_id,
-                    "next_step": "查看未完成验收项并补齐证据。",
-                }
-            )
-    candidates = int(knowledge.get("candidate", 0))
-    if candidates:
-        queue.append(
-            {
-                "id": "knowledge-candidates",
-                "type": "knowledge_review",
-                "severity": "medium",
-                "title": f"{candidates} 条经验候选待审",
-                "description": "候选经验不会自动成为组织知识。",
-                "project_id": None,
-                "next_step": "核对证据、适用范围与冲突后再决定是否批准。",
-            }
-        )
-    uncommitted = int(knowledge.get("approved_uncommitted", 0))
-    if uncommitted:
-        queue.append(
-            {
-                "id": "knowledge-uncommitted",
-                "type": "knowledge_publish",
-                "severity": "high",
-                "title": f"{uncommitted} 条已批准知识尚未提交",
-                "description": "批准状态尚无当前 Git HEAD provenance。",
-                "project_id": None,
-                "next_step": "复核精确变更后提交规范知识仓库。",
-            }
-        )
-    if health.get("file_git", {}).get("state") in {"invalid", "unavailable"}:
-        queue.append(
-            {
-                "id": "file-git-health",
-                "type": "system_health",
-                "severity": "high",
-                "title": "File/Git 权威源不可用",
-                "description": "知识统计已安全降级，未使用演示数据替代。",
-                "project_id": None,
-                "next_step": "运行 OPC memory doctor 并修复报告的问题。",
-            }
-        )
-    order = {"high": 0, "medium": 1, "low": 2}
-    return sorted(queue, key=lambda item: (order[item["severity"]], item["id"]))
-
-
-def aggregate_snapshot(
-    project_roots: Sequence[Path | str],
-    *,
-    knowledge_root: Path | str,
-    data_root: Path | str,
-    now: Callable[[], str] = utc_now,
-    allow_empty: bool = False,
-) -> dict[str, Any]:
-    if (not project_roots and not allow_empty) or len(project_roots) > MAX_PROJECTS:
-        raise DashboardError("INVALID_PROJECT_ROOT_COUNT")
-    knowledge_path = Path(knowledge_root)
-    data_path = Path(data_root)
-    projects: list[dict[str, Any]] = []
-    warnings: list[dict[str, Any]] = []
-    seen: set[str] = set()
-    for index, root in enumerate(project_roots):
-        project, project_warnings = _read_project(
-            Path(root),
-            index=index,
-            knowledge_root=knowledge_path,
-        )
-        if project["id"] in seen:
-            project["source_state"] = "invalid"
-            project_warnings.append(
-                _project_warning(
-                    "DUPLICATE_PROJECT_ID",
-                    project["id"],
-                    "重复项目 ID 已标为无效。",
-                )
-            )
-        seen.add(project["id"])
-        projects.append(project)
-        warnings.extend(project_warnings)
-    knowledge, health, knowledge_warnings = _knowledge_snapshot(knowledge_path, data_path)
-    warnings.extend(knowledge_warnings)
-    active_projects = sum(
-        project["run"]["active"] is True
-        and project["run"]["status"]
-        in {"aligning", "planned", "implementing", "validating", "ready_for_manager"}
-        for project in projects
-    )
-    pending_acceptance = sum(
-        max(0, int(project["acceptance"]["total"]) - int(project["acceptance"]["passed"]))
-        for project in projects
-        if project["acceptance"]["state"] == "available"
-    )
-    snapshot = {
-        "schema_version": SCHEMA_VERSION,
-        "generated_at": now(),
-        "mode": "live",
-        "summary": {
-            "active_projects": active_projects,
-            "pending_acceptance": pending_acceptance,
-            "candidates": int(knowledge["candidate"]),
-            "published": int(knowledge["published"]),
-        },
-        "projects": projects,
-        "knowledge": knowledge,
-        "manager_queue": _manager_queue(projects, knowledge, health),
-        "health": health,
-        "warnings": warnings,
-    }
-    _assert_redacted(snapshot)
-    return snapshot
-
-
-def _assert_redacted(value: Any, *, key: str = "") -> None:
-    normalized_key = re.sub(r"[^a-z0-9]", "", key.lower())
-    if normalized_key in {"runid", "sessionid", "turnid", "threadid"}:
-        raise DashboardError("FORBIDDEN_FIELD")
-    if isinstance(value, Mapping):
-        for child_key, child in value.items():
-            if not isinstance(child_key, str):
-                raise DashboardError("INVALID_SNAPSHOT")
-            _assert_redacted(child, key=child_key)
-    elif isinstance(value, list):
-        for child in value:
-            _assert_redacted(child, key=key)
-    elif isinstance(value, str):
-        if _looks_like_absolute_path(value):
-            raise DashboardError("ABSOLUTE_PATH_REDACTED")
-
-
-def _validate_demo_snapshot(snapshot: dict[str, Any]) -> dict[str, Any]:
-    required = {
-        "schema_version",
-        "generated_at",
-        "mode",
-        "summary",
-        "projects",
-        "knowledge",
-        "manager_queue",
-        "health",
-        "warnings",
-    }
-    if set(snapshot) != required or snapshot.get("schema_version") != SCHEMA_VERSION:
-        raise DashboardError("INVALID_DEMO")
-    if snapshot.get("mode") != "demo":
-        raise DashboardError("INVALID_DEMO")
-    _assert_redacted(snapshot)
-    return snapshot
-
-
-def load_demo_snapshot(asset_root: Path | str | None = None) -> dict[str, Any]:
-    root = (
-        Path(asset_root)
-        if asset_root is not None
-        else Path(__file__).resolve().parents[1] / "assets" / "dashboard"
-    )
-    snapshot = _read_json(
-        root / "synthetic-dashboard.v1.json",
-        root=root,
-        maximum=MAX_DEMO_BYTES,
-    )
-    return _validate_demo_snapshot(snapshot)
-
-
-def validate_bind_host(host: str) -> str:
-    if host not in {"127.0.0.1", "::1"}:
-        raise DashboardError("LOOPBACK_REQUIRED")
-    return host
-
-
-def _authority(host: str, port: int) -> str:
-    return f"[{host}]:{port}" if host == "::1" else f"{host}:{port}"
-
-
-class DashboardHTTPServer(ThreadingHTTPServer):
-    daemon_threads = True
-    allow_reuse_address = False
-
-    def __init__(
-        self,
-        address: tuple[str, int],
-        handler: type[BaseHTTPRequestHandler],
-        *,
-        snapshot_provider: Callable[[], dict[str, Any]],
-        asset_root: Path,
-    ):
-        self.snapshot_provider = snapshot_provider
-        self.asset_root = Path(os.path.abspath(asset_root))
-        super().__init__(address, handler)
-        host, port = self.server_address[:2]
-        self.expected_authority = _authority(str(host), int(port))
-
-
-class IPv6DashboardHTTPServer(DashboardHTTPServer):
-    address_family = socket.AF_INET6
-
-
-class DashboardRequestHandler(BaseHTTPRequestHandler):
-    server_version = "OPCDashboard/1"
-    sys_version = ""
-
-    @property
-    def dashboard_server(self) -> DashboardHTTPServer:
-        return self.server  # type: ignore[return-value]
-
-    def log_message(self, format: str, *args: Any) -> None:
-        return
-
-    def _valid_host(self) -> bool:
-        values = self.headers.get_all("Host", [])
-        return len(values) == 1 and values[0] == self.dashboard_server.expected_authority
-
-    def _valid_origin(self) -> bool:
-        values = self.headers.get_all("Origin", [])
-        expected = f"http://{self.dashboard_server.expected_authority}"
-        return not values or (len(values) == 1 and values[0] == expected)
-
-    def _send(
-        self,
-        status_code: int,
-        payload: bytes,
-        content_type: str,
-        *,
-        head_only: bool = False,
-        extra_headers: Mapping[str, str] | None = None,
-    ) -> None:
-        self.send_response(status_code)
-        self.send_header("Content-Type", content_type)
-        self.send_header("Content-Length", str(len(payload)))
-        for name, value in SECURITY_HEADERS.items():
-            self.send_header(name, value)
-        if extra_headers:
-            for name, value in extra_headers.items():
-                self.send_header(name, value)
-        self.end_headers()
-        if not head_only:
-            self.wfile.write(payload)
-
-    def _json_error(self, status_code: int, code: str, *, head_only: bool = False) -> None:
-        payload = json.dumps({"error": code}, separators=(",", ":")).encode("utf-8")
-        self._send(status_code, payload, "application/json; charset=utf-8", head_only=head_only)
-
-    def _handle_read(self, *, head_only: bool) -> None:
-        if not self._valid_host():
-            self._json_error(400, "INVALID_HOST", head_only=head_only)
-            return
-        if not self._valid_origin():
-            self._json_error(403, "ORIGIN_FORBIDDEN", head_only=head_only)
-            return
-        parsed = urlsplit(self.path)
-        if parsed.query or parsed.fragment:
-            self._json_error(404, "NOT_FOUND", head_only=head_only)
-            return
-        if parsed.path == "/api/snapshot":
-            try:
-                snapshot = self.dashboard_server.snapshot_provider()
-                _assert_redacted(snapshot)
-                payload = json.dumps(
-                    snapshot,
-                    ensure_ascii=False,
-                    separators=(",", ":"),
-                ).encode("utf-8")
-            except Exception:
-                self._json_error(503, "SNAPSHOT_UNAVAILABLE", head_only=head_only)
-                return
-            self._send(
-                200,
-                payload,
-                "application/json; charset=utf-8",
-                head_only=head_only,
-            )
-            return
-        route = ASSET_ROUTES.get(parsed.path)
-        if route is None:
-            self._json_error(404, "NOT_FOUND", head_only=head_only)
-            return
-        filename, content_type = route
-        try:
-            payload = _read_stable_bytes(
-                self.dashboard_server.asset_root / filename,
-                root=self.dashboard_server.asset_root,
-                maximum=2 * 1024 * 1024,
-                label="dashboard_asset",
-            )
-        except DashboardError:
-            self._json_error(404, "ASSET_UNAVAILABLE", head_only=head_only)
-            return
-        self._send(200, payload, content_type, head_only=head_only)
-
-    def do_GET(self) -> None:
-        self._handle_read(head_only=False)
-
-    def do_HEAD(self) -> None:
-        self._handle_read(head_only=True)
-
-    def _method_not_allowed(self) -> None:
-        if not self._valid_host():
-            self._json_error(400, "INVALID_HOST")
-            return
-        if not self._valid_origin():
-            self._json_error(403, "ORIGIN_FORBIDDEN")
-            return
-        payload = json.dumps(
-            {"error": "METHOD_NOT_ALLOWED"},
-            separators=(",", ":"),
-        ).encode("utf-8")
-        self._send(
-            405,
-            payload,
-            "application/json; charset=utf-8",
-            extra_headers={"Allow": "GET, HEAD"},
-        )
-
-    do_POST = _method_not_allowed
-    do_PUT = _method_not_allowed
-    do_PATCH = _method_not_allowed
-    do_DELETE = _method_not_allowed
-    do_OPTIONS = _method_not_allowed
-    do_CONNECT = _method_not_allowed
-    do_TRACE = _method_not_allowed
-
-
-def create_server(
-    *,
-    host: str,
-    port: int,
-    snapshot_provider: Callable[[], dict[str, Any]],
-    asset_root: Path | str | None = None,
-) -> DashboardHTTPServer:
-    validate_bind_host(host)
-    if isinstance(port, bool) or not isinstance(port, int) or not 0 <= port <= 65535:
-        raise DashboardError("INVALID_PORT")
-    root = (
-        Path(asset_root)
-        if asset_root is not None
-        else Path(__file__).resolve().parents[1] / "assets" / "dashboard"
-    )
-    server_type = IPv6DashboardHTTPServer if host == "::1" else DashboardHTTPServer
-    try:
-        return server_type(
-            (host, port),
-            DashboardRequestHandler,
-            snapshot_provider=snapshot_provider,
-            asset_root=root,
-        )
-    except OSError as exc:
-        raise DashboardError("PORT_UNAVAILABLE") from exc
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -955,9 +71,6 @@ def main(argv: Sequence[str] | None = None) -> int:
                 parser.error("--demo 不能与真实数据根参数同时使用")
             service = SnapshotService(
                 project_roots_provider=tuple,
-                snapshot_builder=aggregate_snapshot,
-                demo_loader=load_demo_snapshot,
-                snapshot_validator=_assert_redacted,
                 demo=True,
             )
         else:
@@ -967,9 +80,6 @@ def main(argv: Sequence[str] | None = None) -> int:
             data_root = resolve_data_root(args.data_root)
             service = SnapshotService(
                 project_roots_provider=lambda: args.project_root,
-                snapshot_builder=aggregate_snapshot,
-                demo_loader=load_demo_snapshot,
-                snapshot_validator=_assert_redacted,
                 knowledge_root=knowledge_root,
                 data_root=data_root,
             )
@@ -979,7 +89,7 @@ def main(argv: Sequence[str] | None = None) -> int:
             port=args.port,
             snapshot_provider=service.snapshot,
         )
-    except DashboardError as exc:
+    except SnapshotError as exc:
         print(f"OPC_DASHBOARD_ERROR: {exc.code}", file=sys.stderr)
         return 2
     url = f"http://{_authority(args.host, int(server.server_address[1]))}/"
diff --git a/plugins/codex-opc-team/scripts/opc_snapshot_service.py b/plugins/codex-opc-team/scripts/opc_snapshot_service.py
index 55bac07..975c727 100644
--- a/plugins/codex-opc-team/scripts/opc_snapshot_service.py
+++ b/plugins/codex-opc-team/scripts/opc_snapshot_service.py
@@ -1,60 +1,975 @@
 #!/usr/bin/env python3
-"""Shared, read-only snapshot application service for OPC visual surfaces."""
+"""Shared OPC snapshot, redaction, DTO, and local read-service core.
+
+The service is deliberately a projection over existing File/Git and project
+state.  It does not mutate OPC state and never returns knowledge bodies, raw
+feedback, filesystem paths, or run/session/thread identifiers.
+"""
 
 from __future__ import annotations
 
+import json
+import os
+import re
+import socket
+import stat
+from datetime import datetime, timezone
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
+from urllib.parse import urlsplit
+
+from opc_feedback import read_feedback
+from opc_lineage import build_view
+from opc_memory import (
+    FileGitBackend,
+    MemoryService,
+    resolve_data_root,
+    resolve_knowledge_root,
+)
+SCHEMA_VERSION = "opc-dashboard.snapshot.v1"
+MAX_JSON_BYTES = 512 * 1024
+MAX_ACCEPTANCE_BYTES = 128 * 1024
+MAX_DEMO_BYTES = 512 * 1024
+MAX_PROJECTS = 64
+PORTABLE_ID = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+RUN_STATUSES = {
+    "aligning",
+    "planned",
+    "implementing",
+    "validating",
+    "ready_for_manager",
+    "completed",
+    "paused",
+    "failed",
+}
+ASSET_ROUTES = {
+    "/": ("index.html", "text/html; charset=utf-8"),
+    "/index.html": ("index.html", "text/html; charset=utf-8"),
+    "/dashboard.css": ("dashboard.css", "text/css; charset=utf-8"),
+    "/dashboard.js": ("dashboard.js", "text/javascript; charset=utf-8"),
+}
+SECURITY_HEADERS = {
+    "Cache-Control": "no-store",
+    "Content-Security-Policy": (
+        "default-src 'self'; base-uri 'none'; object-src 'none'; "
+        "frame-ancestors 'none'; form-action 'none'; connect-src 'self'; "
+        "img-src 'self' data:; script-src 'self'; style-src 'self'"
+    ),
+    "Permissions-Policy": (
+        "camera=(), microphone=(), geolocation=(), payment=(), usb=(), "
+        "interest-cohort=()"
+    ),
+    "Referrer-Policy": "no-referrer",
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+}
+
+
+class SnapshotError(RuntimeError):
+    """A safe snapshot error whose code is suitable for redacted output."""
+
+    def __init__(self, code: str):
+        super().__init__(code)
+        self.code = code
+
+
+# Preserve the old public/import contract while adapters migrate to SnapshotError.
+DashboardError = SnapshotError
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _is_link(metadata: os.stat_result) -> bool:
+    if stat.S_ISLNK(metadata.st_mode):
+        return True
+    attributes = getattr(metadata, "st_file_attributes", 0)
+    reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    return bool(reparse and attributes & reparse)
+
+
+def _identity(metadata: os.stat_result) -> tuple[int, int, int, int, int]:
+    return (
+        int(metadata.st_dev),
+        int(metadata.st_ino),
+        int(metadata.st_size),
+        int(getattr(metadata, "st_mtime_ns", int(metadata.st_mtime * 1_000_000_000))),
+        int(metadata.st_nlink),
+    )
+
+
+def _read_checkpoint(label: str, path: Path) -> None:
+    """Test seam for simulating changes at read transaction boundaries."""
+
+
+def _assert_safe_chain(root: Path, path: Path) -> None:
+    try:
+        relative = path.relative_to(root)
+    except ValueError as exc:
+        raise DashboardError("PATH_ESCAPE") from exc
+    current = root
+    for part in (Path("."), *relative.parts):
+        if part != Path("."):
+            current = current / part
+        try:
+            metadata = current.lstat()
+        except OSError as exc:
+            raise DashboardError("SOURCE_UNAVAILABLE") from exc
+        if _is_link(metadata):
+            raise DashboardError("LINKED_SOURCE")
+
+
+def _read_stable_bytes(
+    path: Path,
+    *,
+    root: Path,
+    maximum: int,
+    label: str,
+) -> bytes:
+    """Read one bounded regular file without following links or hardlinks."""
+
+    lexical_root = Path(os.path.abspath(root))
+    lexical_path = Path(os.path.abspath(path))
+    _assert_safe_chain(lexical_root, lexical_path)
+    try:
+        before = lexical_path.lstat()
+    except OSError as exc:
+        raise DashboardError("SOURCE_UNAVAILABLE") from exc
+    if _is_link(before) or not stat.S_ISREG(before.st_mode):
+        raise DashboardError("UNSAFE_SOURCE")
+    if before.st_nlink != 1:
+        raise DashboardError("HARDLINKED_SOURCE")
+    if before.st_size > maximum:
+        raise DashboardError("SOURCE_TOO_LARGE")
+    _read_checkpoint(f"{label}:before_open", lexical_path)
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    descriptor: int | None = None
+    try:
+        descriptor = os.open(lexical_path, flags)
+        opened = os.fstat(descriptor)
+        if (
+            _is_link(opened)
+            or not stat.S_ISREG(opened.st_mode)
+            or opened.st_nlink != 1
+            or _identity(opened) != _identity(before)
+        ):
+            raise DashboardError("SOURCE_CHANGED")
+        chunks: list[bytes] = []
+        remaining = maximum + 1
+        while remaining:
+            chunk = os.read(descriptor, min(64 * 1024, remaining))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        payload = b"".join(chunks)
+        if len(payload) > maximum:
+            raise DashboardError("SOURCE_TOO_LARGE")
+        after_descriptor = os.fstat(descriptor)
+        _read_checkpoint(f"{label}:before_verify", lexical_path)
+        after_path = lexical_path.lstat()
+        if (
+            _identity(before) != _identity(after_descriptor)
+            or _identity(before) != _identity(after_path)
+            or _is_link(after_path)
+        ):
+            raise DashboardError("SOURCE_CHANGED")
+        return payload
+    except DashboardError:
+        raise
+    except OSError as exc:
+        raise DashboardError("SOURCE_UNAVAILABLE") from exc
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+
+
+def _read_json(path: Path, *, root: Path, maximum: int = MAX_JSON_BYTES) -> dict[str, Any]:
+    raw = _read_stable_bytes(path, root=root, maximum=maximum, label=path.name)
+    try:
+        value = json.loads(
+            raw.decode("utf-8"),
+            parse_constant=lambda token: (_ for _ in ()).throw(ValueError(token)),
+        )
+    except (UnicodeError, ValueError, json.JSONDecodeError) as exc:
+        raise DashboardError("INVALID_JSON") from exc
+    if not isinstance(value, dict):
+        raise DashboardError("INVALID_JSON")
+    return value
+
+
+def _safe_text(value: Any, *, maximum: int = 160) -> str | None:
+    if not isinstance(value, str):
+        return None
+    text = " ".join(value.split()).strip()
+    if (
+        not text
+        or len(text) > maximum
+        or any(ord(char) < 32 for char in text)
+        or _looks_like_absolute_path(text)
+    ):
+        return None
+    return text
+
+
+def _looks_like_absolute_path(value: str) -> bool:
+    posix_path = re.search(
+        r"(?:^|[\s\"'(`])/(?:home|root|etc|var|tmp|opt|usr|private|mnt|srv|workspace|workspaces)(?:/|$)",
+        value,
+    )
+    return bool(
+        re.search(r"(?:^|[\s\"'])[A-Za-z]:[\\/]", value)
+        or value.startswith("\\\\")
+        or value.startswith("/")
+        or posix_path
+    )
+
+
+def _safe_time(value: Any) -> str | None:
+    text = _safe_text(value, maximum=64)
+    if text is None:
+        return None
+    try:
+        datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return text
+
+
+def _parse_acceptance(path: Path, project_root: Path) -> dict[str, Any]:
+    try:
+        raw = _read_stable_bytes(
+            path,
+            root=project_root,
+            maximum=MAX_ACCEPTANCE_BYTES,
+            label="acceptance",
+        )
+        text = raw.decode("utf-8")
+    except UnicodeError as exc:
+        raise DashboardError("INVALID_ACCEPTANCE") from exc
+    lines = [line.strip() for line in text.splitlines()]
+    header_index = next(
+        (
+            index
+            for index, line in enumerate(lines)
+            if line.startswith("|")
+            and "criterion" in line.lower()
+            and "status" in line.lower()
+        ),
+        None,
+    )
+    if header_index is None or header_index + 1 >= len(lines):
+        raise DashboardError("INVALID_ACCEPTANCE")
+    header = [part.strip().lower() for part in lines[header_index].strip("|").split("|")]
+    try:
+        status_index = header.index("status")
+    except ValueError as exc:
+        raise DashboardError("INVALID_ACCEPTANCE") from exc
+    separator = [part.strip() for part in lines[header_index + 1].strip("|").split("|")]
+    if len(separator) != len(header) or not all(re.fullmatch(r":?-{3,}:?", part) for part in separator):
+        raise DashboardError("INVALID_ACCEPTANCE")
+    statuses: list[str] = []
+    for line in lines[header_index + 2 :]:
+        if not line.startswith("|"):
+            break
+        cells = [part.strip() for part in line.strip("|").split("|")]
+        if len(cells) != len(header):
+            raise DashboardError("INVALID_ACCEPTANCE")
+        statuses.append(cells[status_index].lower())
+    if not statuses:
+        raise DashboardError("INVALID_ACCEPTANCE")
+    passed = sum(status in {"pass", "passed", "done", "complete", "completed"} for status in statuses)
+    return {"passed": passed, "total": len(statuses), "state": "available"}
+
+
+def _unavailable_acceptance(state: str) -> dict[str, Any]:
+    return {"passed": 0, "total": 0, "state": state}
+
+
+def _project_warning(code: str, project_id: str | None, message: str) -> dict[str, Any]:
+    out: dict[str, Any] = {"code": code, "severity": "warning", "message": message}
+    if project_id:
+        out["project_id"] = project_id
+    return out
+
+
+def _feedback_status(project_root: Path) -> str:
+    try:
+        view = read_feedback(project_root)
+        record = view.get("structured_feedback")
+        if record is None:
+            return "unavailable"
+        events = record.get("events")
+        return "available" if isinstance(events, list) else "invalid"
+    except Exception:
+        return "invalid"
+
+
+def _lineage_status(project_root: Path, knowledge_root: Path | None) -> str:
+    try:
+        view = build_view(project_root, knowledge_root=knowledge_root)
+        state = view.get("lineage_status")
+        return state if state in {"available", "degraded", "unavailable"} else "invalid"
+    except Exception:
+        return "invalid"
+
+
+def _read_project(
+    project_root: Path,
+    *,
+    index: int,
+    knowledge_root: Path | None,
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    fallback_id = f"project-{index + 1}"
+    fallback = {
+        "id": fallback_id,
+        "name": f"项目 {index + 1}",
+        "source_state": "invalid",
+        "run": {
+            "title": "状态不可用",
+            "status": "invalid",
+            "active": False,
+            "updated_at": None,
+        },
+        "acceptance": _unavailable_acceptance("invalid"),
+        "feedback_status": "invalid",
+        "lineage_status": "invalid",
+    }
+    warnings: list[dict[str, Any]] = []
+    lexical_root = Path(os.path.abspath(project_root))
+    try:
+        project = _read_json(lexical_root / ".opc" / "project.json", root=lexical_root)
+        project_id = _safe_text(project.get("project_id"), maximum=128)
+        name = _safe_text(project.get("name"), maximum=160)
+        if (
+            project_id is None
+            or PORTABLE_ID.fullmatch(project_id) is None
+            or name is None
+        ):
+            raise DashboardError("INVALID_PROJECT")
+    except DashboardError as exc:
+        warnings.append(
+            _project_warning(
+                exc.code,
+                None,
+                f"第 {index + 1} 个项目来源无效，已安全降级。",
+            )
+        )
+        return fallback, warnings
+
+    run_projection = {
+        "title": "暂无运行",
+        "status": "unavailable",
+        "active": False,
+        "updated_at": None,
+    }
+    source_state = "available"
+    try:
+        run = _read_json(lexical_root / ".opc" / "run.json", root=lexical_root)
+        title = _safe_text(run.get("title"), maximum=200)
+        status_value = run.get("status")
+        active = run.get("active")
+        updated_at = _safe_time(run.get("updated_at"))
+        if (
+            run.get("project_id") != project_id
+            or title is None
+            or status_value not in RUN_STATUSES
+            or not isinstance(active, bool)
+            or updated_at is None
+        ):
+            raise DashboardError("INVALID_RUN")
+        run_projection = {
+            "title": title,
+            "status": status_value,
+            "active": active,
+            "updated_at": updated_at,
+        }
+    except DashboardError as exc:
+        source_state = "degraded"
+        run_projection["status"] = "invalid" if exc.code != "SOURCE_UNAVAILABLE" else "unavailable"
+        warnings.append(
+            _project_warning(exc.code, project_id, "运行状态不可用，项目仍以只读方式展示。")
+        )
+
+    try:
+        acceptance = _parse_acceptance(lexical_root / ".opc" / "acceptance.md", lexical_root)
+    except DashboardError as exc:
+        source_state = "degraded"
+        acceptance = _unavailable_acceptance(
+            "unavailable" if exc.code == "SOURCE_UNAVAILABLE" else "invalid"
+        )
+        warnings.append(
+            _project_warning(exc.code, project_id, "验收契约不可用，未推测验收进度。")
+        )
+
+    feedback_status = _feedback_status(lexical_root)
+    lineage_status = _lineage_status(lexical_root, knowledge_root)
+    if feedback_status == "invalid" or lineage_status == "invalid":
+        source_state = "degraded"
+    return (
+        {
+            "id": project_id,
+            "name": name,
+            "source_state": source_state,
+            "run": run_projection,
+            "acceptance": acceptance,
+            "feedback_status": feedback_status,
+            "lineage_status": lineage_status,
+        },
+        warnings,
+    )
+
+
+def _knowledge_snapshot(
+    knowledge_root: Path,
+    data_root: Path,
+) -> tuple[dict[str, int | str], dict[str, Any], list[dict[str, Any]]]:
+    counts: dict[str, int | str] = {
+        "candidate": 0,
+        "approved_uncommitted": 0,
+        "published": 0,
+        "rejected": 0,
+        "obsolete": 0,
+        "state": "unavailable",
+    }
+    health = {
+        "file_git": {
+            "state": "unavailable",
+            "label": "File/Git 不可用",
+            "detail": "无法读取规范知识状态。",
+        },
+        "mem0": {
+            "state": "unavailable",
+            "label": "Mem0 不可用",
+            "detail": "可选检索索引状态不可用。",
+        },
+    }
+    warnings: list[dict[str, Any]] = []
+    try:
+        backend = FileGitBackend(knowledge_root)
+        doctor = backend.doctor()
+        if doctor.get("state") == "NOT_INITIALIZED":
+            counts["state"] = "unavailable"
+            health["file_git"] = {
+                "state": "unavailable",
+                "label": "File/Git 未初始化",
+                "detail": "规范知识仓库尚未就绪。",
+            }
+            warnings.append(
+                {
+                    "code": "KNOWLEDGE_NOT_INITIALIZED",
+                    "severity": "warning",
+                    "message": "知识仓库尚未初始化。",
+                }
+            )
+        elif not doctor.get("ok"):
+            counts["state"] = "invalid"
+            health["file_git"] = {
+                "state": "invalid",
+                "label": "File/Git 无效",
+                "detail": "知识仓库结构或记录未通过校验。",
+            }
+            warnings.append(
+                {
+                    "code": "KNOWLEDGE_INVALID",
+                    "severity": "warning",
+                    "message": "知识仓库存在无效记录，未展示推测数据。",
+                }
+            )
+        else:
+            governance = backend.governance_snapshot()
+            inventory = governance.get("inventory", {})
+            provenance = governance.get("provenance", {})
+            for record_id, metadata in inventory.items():
+                status_value = metadata.get("status")
+                if status_value == "approved":
+                    proof = provenance.get(record_id, {})
+                    if proof.get("source_commit"):
+                        counts["published"] = int(counts["published"]) + 1
+                    else:
+                        counts["approved_uncommitted"] = int(counts["approved_uncommitted"]) + 1
+                elif status_value in {"candidate", "rejected", "obsolete"}:
+                    counts[status_value] = int(counts[status_value]) + 1
+            counts["state"] = "available"
+            git_state = doctor.get("git", {})
+            degraded = not doctor.get("provenance_ready") or bool(git_state.get("authoritative_uncommitted"))
+            health["file_git"] = {
+                "state": "degraded" if degraded else "available",
+                "label": "File/Git 需关注" if degraded else "File/Git 正常",
+                "detail": (
+                    "知识可读，但 Git provenance 尚未完全就绪。"
+                    if degraded
+                    else "规范知识与 Git provenance 已就绪。"
+                ),
+            }
+        service = MemoryService.from_paths(knowledge_root, data_root)
+        memory_status = service.status()
+        mem0 = memory_status.get("mem0", {})
+        provider_health = mem0.get("health")
+        if provider_health == "disabled":
+            health["mem0"] = {
+                "state": "disabled",
+                "label": "Mem0 已停用",
+                "detail": "当前使用 File/Git 检索，功能可正常降级。",
+            }
+        elif provider_health == "configured-unverified":
+            health["mem0"] = {
+                "state": "degraded",
+                "label": "Mem0 待验证",
+                "detail": "索引已配置，但本次只读检查未调用外部 Provider。",
+            }
+        else:
+            health["mem0"] = {
+                "state": "degraded",
+                "label": "Mem0 已降级",
+                "detail": "可选索引不可用，仍使用 File/Git。",
+            }
+    except Exception:
+        warnings.append(
+            {
+                "code": "KNOWLEDGE_SOURCE_UNAVAILABLE",
+                "severity": "warning",
+                "message": "知识或检索状态不可用，未自动填充演示数据。",
+            }
+        )
+    return counts, health, warnings
+
+
+def _manager_queue(
+    projects: Sequence[Mapping[str, Any]],
+    knowledge: Mapping[str, Any],
+    health: Mapping[str, Any],
+) -> list[dict[str, Any]]:
+    queue: list[dict[str, Any]] = []
+    for project in projects:
+        project_id = str(project["id"])
+        run = project["run"]
+        acceptance = project["acceptance"]
+        if run["status"] == "ready_for_manager":
+            queue.append(
+                {
+                    "id": f"handoff-{project_id}",
+                    "type": "manager_handoff",
+                    "severity": "high",
+                    "title": f"{project['name']} 等待体验",
+                    "description": "实现与内部验证已完成，等待经理体验与方向判断。",
+                    "project_id": project_id,
+                    "next_step": "按体验路径检查结果并给出反馈。",
+                }
+            )
+        elif run["status"] in {"failed", "paused"}:
+            queue.append(
+                {
+                    "id": f"run-{project_id}",
+                    "type": "run_attention",
+                    "severity": "high",
+                    "title": f"{project['name']} 运行需处理",
+                    "description": f"当前运行状态为 {run['status']}。",
+                    "project_id": project_id,
+                    "next_step": "查看项目并决定恢复、调整或终止。",
+                }
+            )
+        if (
+            acceptance.get("state") == "available"
+            and acceptance.get("total", 0) > acceptance.get("passed", 0)
+        ):
+            pending = int(acceptance["total"]) - int(acceptance["passed"])
+            queue.append(
+                {
+                    "id": f"acceptance-{project_id}",
+                    "type": "acceptance",
+                    "severity": "medium",
+                    "title": f"{project['name']} 尚有 {pending} 项验收",
+                    "description": "验收契约仍有未通过项。",
+                    "project_id": project_id,
+                    "next_step": "查看未完成验收项并补齐证据。",
+                }
+            )
+    candidates = int(knowledge.get("candidate", 0))
+    if candidates:
+        queue.append(
+            {
+                "id": "knowledge-candidates",
+                "type": "knowledge_review",
+                "severity": "medium",
+                "title": f"{candidates} 条经验候选待审",
+                "description": "候选经验不会自动成为组织知识。",
+                "project_id": None,
+                "next_step": "核对证据、适用范围与冲突后再决定是否批准。",
+            }
+        )
+    uncommitted = int(knowledge.get("approved_uncommitted", 0))
+    if uncommitted:
+        queue.append(
+            {
+                "id": "knowledge-uncommitted",
+                "type": "knowledge_publish",
+                "severity": "high",
+                "title": f"{uncommitted} 条已批准知识尚未提交",
+                "description": "批准状态尚无当前 Git HEAD provenance。",
+                "project_id": None,
+                "next_step": "复核精确变更后提交规范知识仓库。",
+            }
+        )
+    if health.get("file_git", {}).get("state") in {"invalid", "unavailable"}:
+        queue.append(
+            {
+                "id": "file-git-health",
+                "type": "system_health",
+                "severity": "high",
+                "title": "File/Git 权威源不可用",
+                "description": "知识统计已安全降级，未使用演示数据替代。",
+                "project_id": None,
+                "next_step": "运行 OPC memory doctor 并修复报告的问题。",
+            }
+        )
+    order = {"high": 0, "medium": 1, "low": 2}
+    return sorted(queue, key=lambda item: (order[item["severity"]], item["id"]))
 
 
-Snapshot = dict[str, Any]
-ProjectRootsProvider = Callable[[], Sequence[Path | str]]
-SnapshotBuilder = Callable[..., Snapshot]
-DemoLoader = Callable[[], Snapshot]
-SnapshotValidator = Callable[[Any], None]
+def aggregate_snapshot(
+    project_roots: Sequence[Path | str],
+    *,
+    knowledge_root: Path | str,
+    data_root: Path | str,
+    now: Callable[[], str] = utc_now,
+    allow_empty: bool = False,
+) -> dict[str, Any]:
+    if (not project_roots and not allow_empty) or len(project_roots) > MAX_PROJECTS:
+        raise DashboardError("INVALID_PROJECT_ROOT_COUNT")
+    knowledge_path = Path(knowledge_root)
+    data_path = Path(data_root)
+    projects: list[dict[str, Any]] = []
+    warnings: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for index, root in enumerate(project_roots):
+        project, project_warnings = _read_project(
+            Path(root),
+            index=index,
+            knowledge_root=knowledge_path,
+        )
+        if project["id"] in seen:
+            project["source_state"] = "invalid"
+            project_warnings.append(
+                _project_warning(
+                    "DUPLICATE_PROJECT_ID",
+                    project["id"],
+                    "重复项目 ID 已标为无效。",
+                )
+            )
+        seen.add(project["id"])
+        projects.append(project)
+        warnings.extend(project_warnings)
+    knowledge, health, knowledge_warnings = _knowledge_snapshot(knowledge_path, data_path)
+    warnings.extend(knowledge_warnings)
+    active_projects = sum(
+        project["run"]["active"] is True
+        and project["run"]["status"]
+        in {"aligning", "planned", "implementing", "validating", "ready_for_manager"}
+        for project in projects
+    )
+    pending_acceptance = sum(
+        max(0, int(project["acceptance"]["total"]) - int(project["acceptance"]["passed"]))
+        for project in projects
+        if project["acceptance"]["state"] == "available"
+    )
+    snapshot = {
+        "schema_version": SCHEMA_VERSION,
+        "generated_at": now(),
+        "mode": "live",
+        "summary": {
+            "active_projects": active_projects,
+            "pending_acceptance": pending_acceptance,
+            "candidates": int(knowledge["candidate"]),
+            "published": int(knowledge["published"]),
+        },
+        "projects": projects,
+        "knowledge": knowledge,
+        "manager_queue": _manager_queue(projects, knowledge, health),
+        "health": health,
+        "warnings": warnings,
+    }
+    _assert_redacted(snapshot)
+    return snapshot
+
+
+def _assert_redacted(value: Any, *, key: str = "") -> None:
+    normalized_key = re.sub(r"[^a-z0-9]", "", key.lower())
+    if normalized_key in {"runid", "sessionid", "turnid", "threadid"}:
+        raise DashboardError("FORBIDDEN_FIELD")
+    if isinstance(value, Mapping):
+        for child_key, child in value.items():
+            if not isinstance(child_key, str):
+                raise DashboardError("INVALID_SNAPSHOT")
+            _assert_redacted(child, key=child_key)
+    elif isinstance(value, list):
+        for child in value:
+            _assert_redacted(child, key=key)
+    elif isinstance(value, str):
+        if _looks_like_absolute_path(value):
+            raise DashboardError("ABSOLUTE_PATH_REDACTED")
+
+
+def _validate_demo_snapshot(snapshot: dict[str, Any]) -> dict[str, Any]:
+    required = {
+        "schema_version",
+        "generated_at",
+        "mode",
+        "summary",
+        "projects",
+        "knowledge",
+        "manager_queue",
+        "health",
+        "warnings",
+    }
+    if set(snapshot) != required or snapshot.get("schema_version") != SCHEMA_VERSION:
+        raise DashboardError("INVALID_DEMO")
+    if snapshot.get("mode") != "demo":
+        raise DashboardError("INVALID_DEMO")
+    _assert_redacted(snapshot)
+    return snapshot
+
+
+def load_demo_snapshot(asset_root: Path | str | None = None) -> dict[str, Any]:
+    root = (
+        Path(asset_root)
+        if asset_root is not None
+        else Path(__file__).resolve().parents[1] / "assets" / "dashboard"
+    )
+    snapshot = _read_json(
+        root / "synthetic-dashboard.v1.json",
+        root=root,
+        maximum=MAX_DEMO_BYTES,
+    )
+    return _validate_demo_snapshot(snapshot)
 
 
 class SnapshotService:
-    """Keep Dashboard and OPC App on one aggregation/redaction contract."""
+    """One semantic source for Dashboard and OPC App snapshot projections."""
 
     def __init__(
         self,
         *,
-        project_roots_provider: ProjectRootsProvider,
-        snapshot_builder: SnapshotBuilder,
-        demo_loader: DemoLoader,
-        snapshot_validator: SnapshotValidator,
+        project_roots_provider: Callable[[], Sequence[Path | str]],
         knowledge_root: Path | str | None = None,
         data_root: Path | str | None = None,
         demo: bool = False,
         allow_empty: bool = False,
+        demo_asset_root: Path | str | None = None,
+        now_provider: Callable[[], str] | None = None,
     ) -> None:
         self._project_roots_provider = project_roots_provider
-        self._snapshot_builder = snapshot_builder
-        self._demo_loader = demo_loader
-        self._snapshot_validator = snapshot_validator
         self._knowledge_root = knowledge_root
         self._data_root = data_root
         self._demo = demo
         self._allow_empty = allow_empty
+        self._demo_asset_root = demo_asset_root
+        self._now_provider = now_provider
 
-    def snapshot(self) -> Snapshot:
+    def snapshot(self) -> dict[str, Any]:
         if self._demo:
-            snapshot = self._demo_loader()
+            snapshot = load_demo_snapshot(self._demo_asset_root)
         else:
             if self._knowledge_root is None or self._data_root is None:
-                raise RuntimeError("live snapshot roots are required")
+                raise SnapshotError("LIVE_ROOTS_REQUIRED")
             arguments: dict[str, Any] = {
                 "knowledge_root": self._knowledge_root,
                 "data_root": self._data_root,
             }
             if self._allow_empty:
                 arguments["allow_empty"] = True
-            snapshot = self._snapshot_builder(
+            if self._now_provider is not None:
+                arguments["now"] = self._now_provider
+            snapshot = aggregate_snapshot(
                 self._project_roots_provider(),
                 **arguments,
             )
-        if not isinstance(snapshot, Mapping):
-            raise RuntimeError("snapshot builder returned an invalid value")
-        self._snapshot_validator(snapshot)
-        return dict(snapshot)
+        _assert_redacted(snapshot)
+        return snapshot
+
+
+def validate_bind_host(host: str) -> str:
+    if host not in {"127.0.0.1", "::1"}:
+        raise DashboardError("LOOPBACK_REQUIRED")
+    return host
+
+
+def _authority(host: str, port: int) -> str:
+    return f"[{host}]:{port}" if host == "::1" else f"{host}:{port}"
+
+
+class DashboardHTTPServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = False
+
+    def __init__(
+        self,
+        address: tuple[str, int],
+        handler: type[BaseHTTPRequestHandler],
+        *,
+        snapshot_provider: Callable[[], dict[str, Any]],
+        asset_root: Path,
+    ):
+        self.snapshot_provider = snapshot_provider
+        self.asset_root = Path(os.path.abspath(asset_root))
+        super().__init__(address, handler)
+        host, port = self.server_address[:2]
+        self.expected_authority = _authority(str(host), int(port))
+
+
+class IPv6DashboardHTTPServer(DashboardHTTPServer):
+    address_family = socket.AF_INET6
+
+
+class DashboardRequestHandler(BaseHTTPRequestHandler):
+    server_version = "OPCDashboard/1"
+    sys_version = ""
+
+    @property
+    def dashboard_server(self) -> DashboardHTTPServer:
+        return self.server  # type: ignore[return-value]
+
+    def log_message(self, format: str, *args: Any) -> None:
+        return
+
+    def _valid_host(self) -> bool:
+        values = self.headers.get_all("Host", [])
+        return len(values) == 1 and values[0] == self.dashboard_server.expected_authority
+
+    def _valid_origin(self) -> bool:
+        values = self.headers.get_all("Origin", [])
+        expected = f"http://{self.dashboard_server.expected_authority}"
+        return not values or (len(values) == 1 and values[0] == expected)
+
+    def _send(
+        self,
+        status_code: int,
+        payload: bytes,
+        content_type: str,
+        *,
+        head_only: bool = False,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self.send_response(status_code)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(payload)))
+        for name, value in SECURITY_HEADERS.items():
+            self.send_header(name, value)
+        if extra_headers:
+            for name, value in extra_headers.items():
+                self.send_header(name, value)
+        self.end_headers()
+        if not head_only:
+            self.wfile.write(payload)
+
+    def _json_error(self, status_code: int, code: str, *, head_only: bool = False) -> None:
+        payload = json.dumps({"error": code}, separators=(",", ":")).encode("utf-8")
+        self._send(status_code, payload, "application/json; charset=utf-8", head_only=head_only)
+
+    def _handle_read(self, *, head_only: bool) -> None:
+        if not self._valid_host():
+            self._json_error(400, "INVALID_HOST", head_only=head_only)
+            return
+        if not self._valid_origin():
+            self._json_error(403, "ORIGIN_FORBIDDEN", head_only=head_only)
+            return
+        parsed = urlsplit(self.path)
+        if parsed.query or parsed.fragment:
+            self._json_error(404, "NOT_FOUND", head_only=head_only)
+            return
+        if parsed.path == "/api/snapshot":
+            try:
+                snapshot = self.dashboard_server.snapshot_provider()
+                _assert_redacted(snapshot)
+                payload = json.dumps(
+                    snapshot,
+                    ensure_ascii=False,
+                    separators=(",", ":"),
+                ).encode("utf-8")
+            except Exception:
+                self._json_error(503, "SNAPSHOT_UNAVAILABLE", head_only=head_only)
+                return
+            self._send(
+                200,
+                payload,
+                "application/json; charset=utf-8",
+                head_only=head_only,
+            )
+            return
+        route = ASSET_ROUTES.get(parsed.path)
+        if route is None:
+            self._json_error(404, "NOT_FOUND", head_only=head_only)
+            return
+        filename, content_type = route
+        try:
+            payload = _read_stable_bytes(
+                self.dashboard_server.asset_root / filename,
+                root=self.dashboard_server.asset_root,
+                maximum=2 * 1024 * 1024,
+                label="dashboard_asset",
+            )
+        except DashboardError:
+            self._json_error(404, "ASSET_UNAVAILABLE", head_only=head_only)
+            return
+        self._send(200, payload, content_type, head_only=head_only)
+
+    def do_GET(self) -> None:
+        self._handle_read(head_only=False)
+
+    def do_HEAD(self) -> None:
+        self._handle_read(head_only=True)
+
+    def _method_not_allowed(self) -> None:
+        if not self._valid_host():
+            self._json_error(400, "INVALID_HOST")
+            return
+        if not self._valid_origin():
+            self._json_error(403, "ORIGIN_FORBIDDEN")
+            return
+        payload = json.dumps(
+            {"error": "METHOD_NOT_ALLOWED"},
+            separators=(",", ":"),
+        ).encode("utf-8")
+        self._send(
+            405,
+            payload,
+            "application/json; charset=utf-8",
+            extra_headers={"Allow": "GET, HEAD"},
+        )
+
+    do_POST = _method_not_allowed
+    do_PUT = _method_not_allowed
+    do_PATCH = _method_not_allowed
+    do_DELETE = _method_not_allowed
+    do_OPTIONS = _method_not_allowed
+    do_CONNECT = _method_not_allowed
+    do_TRACE = _method_not_allowed
+
+
+def create_server(
+    *,
+    host: str,
+    port: int,
+    snapshot_provider: Callable[[], dict[str, Any]],
+    asset_root: Path | str | None = None,
+) -> DashboardHTTPServer:
+    validate_bind_host(host)
+    if isinstance(port, bool) or not isinstance(port, int) or not 0 <= port <= 65535:
+        raise DashboardError("INVALID_PORT")
+    root = (
+        Path(asset_root)
+        if asset_root is not None
+        else Path(__file__).resolve().parents[1] / "assets" / "dashboard"
+    )
+    server_type = IPv6DashboardHTTPServer if host == "::1" else DashboardHTTPServer
+    try:
+        return server_type(
+            (host, port),
+            DashboardRequestHandler,
+            snapshot_provider=snapshot_provider,
+            asset_root=root,
+        )
+    except OSError as exc:
+        raise DashboardError("PORT_UNAVAILABLE") from exc
diff --git a/scripts/opc_app_admin.py b/scripts/opc_app_admin.py
index 8505316..78e55c2 100644
--- a/scripts/opc_app_admin.py
+++ b/scripts/opc_app_admin.py
@@ -12,6 +12,8 @@
 import hashlib
 import json
 import os
+import re
+import secrets
 import shutil
 import stat
 import sys
@@ -24,6 +26,10 @@
 MAX_MANIFEST_BYTES = 64 * 1024
 POINTER_SCHEMA = "opc-app.install.v1"
 OWNER_SCHEMA = "opc-app.runtime-owner.v1"
+RELEASE_MANIFEST_SCHEMA = "opc-app.release-manifest.v1"
+RELEASE_ID = re.compile(r"^v[A-Za-z0-9.-]{1,64}-[0-9a-f]{12}$")
+HEX64 = re.compile(r"^[0-9a-f]{64}$")
+MAX_RELEASE_FILES = 4096
 
 
 class AppInstallError(RuntimeError):
@@ -147,11 +153,139 @@ def _release_id(plugin: Path, version: str) -> str:
     return f"v{safe_version}-{digest.hexdigest()[:12]}"
 
 
+def _release_manifest(plugin: Path, version: str, release: str) -> dict[str, Any]:
+    files = []
+    for path in _source_files(plugin):
+        payload = path.read_bytes()
+        files.append(
+            {
+                "path": path.relative_to(plugin).as_posix(),
+                "size": len(payload),
+                "sha256": hashlib.sha256(payload).hexdigest(),
+            }
+        )
+    return {
+        "schema_version": RELEASE_MANIFEST_SCHEMA,
+        "release": release,
+        "version": version,
+        "files": files,
+    }
+
+
+def _release_tree_files(plugin: Path) -> list[Path]:
+    files: list[Path] = []
+    try:
+        entries = list(plugin.rglob("*"))
+    except OSError as exc:
+        raise AppInstallError("installed release tree is unreadable") from exc
+    for path in entries:
+        if _is_link(path):
+            raise AppInstallError("installed release contains linked content")
+        try:
+            metadata = path.lstat()
+        except OSError as exc:
+            raise AppInstallError("installed release tree is unreadable") from exc
+        if stat.S_ISDIR(metadata.st_mode):
+            continue
+        if not stat.S_ISREG(metadata.st_mode) or metadata.st_nlink != 1:
+            raise AppInstallError("installed release contains unsafe content")
+        files.append(path)
+    return sorted(files, key=lambda item: item.relative_to(plugin).as_posix())
+
+
+def _validate_release(
+    release_root: Path,
+    *,
+    expected_release: str | None = None,
+) -> dict[str, Any]:
+    manifest_path = release_root / "release-manifest.json"
+    plugin = release_root / "plugin"
+    if _is_link(release_root) or _is_link(manifest_path) or _is_link(plugin):
+        raise AppInstallError("installed release contains linked content")
+    try:
+        manifest_metadata = manifest_path.lstat()
+    except OSError as exc:
+        raise AppInstallError("installed release manifest is missing") from exc
+    if (
+        not stat.S_ISREG(manifest_metadata.st_mode)
+        or manifest_metadata.st_nlink != 1
+        or manifest_metadata.st_size <= 0
+        or manifest_metadata.st_size > MAX_MANIFEST_BYTES * 8
+    ):
+        raise AppInstallError("installed release manifest is unsafe")
+    try:
+        payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, ValueError, json.JSONDecodeError) as exc:
+        raise AppInstallError("installed release manifest is invalid") from exc
+    if (
+        not isinstance(payload, dict)
+        or set(payload) != {"schema_version", "release", "version", "files"}
+        or payload.get("schema_version") != RELEASE_MANIFEST_SCHEMA
+        or not isinstance(payload.get("release"), str)
+        or RELEASE_ID.fullmatch(payload["release"]) is None
+        or not isinstance(payload.get("version"), str)
+        or not payload["version"]
+        or len(payload["version"]) > 64
+        or not isinstance(payload.get("files"), list)
+        or not payload["files"]
+        or len(payload["files"]) > MAX_RELEASE_FILES
+    ):
+        raise AppInstallError("installed release manifest is invalid")
+    if expected_release is not None and payload["release"] != expected_release:
+        raise AppInstallError("installed release identity mismatch")
+
+    expected_files: dict[str, tuple[int, str]] = {}
+    for item in payload["files"]:
+        if (
+            not isinstance(item, dict)
+            or set(item) != {"path", "size", "sha256"}
+            or not isinstance(item.get("path"), str)
+            or not item["path"]
+            or len(item["path"]) > 240
+            or "\\" in item["path"]
+            or item["path"].startswith("/")
+            or any(part in {"", ".", ".."} for part in item["path"].split("/"))
+            or not isinstance(item.get("size"), int)
+            or isinstance(item["size"], bool)
+            or item["size"] < 0
+            or not isinstance(item.get("sha256"), str)
+            or HEX64.fullmatch(item["sha256"]) is None
+            or item["path"] in expected_files
+        ):
+            raise AppInstallError("installed release manifest is invalid")
+        expected_files[item["path"]] = (item["size"], item["sha256"])
+
+    actual_files = _release_tree_files(plugin)
+    actual_names = [path.relative_to(plugin).as_posix() for path in actual_files]
+    if set(actual_names) != set(expected_files):
+        raise AppInstallError("installed release file inventory mismatch")
+    for path, name in zip(actual_files, actual_names):
+        try:
+            raw = path.read_bytes()
+        except OSError as exc:
+            raise AppInstallError("installed release file is unreadable") from exc
+        size, digest = expected_files[name]
+        if len(raw) != size or hashlib.sha256(raw).hexdigest() != digest:
+            raise AppInstallError("installed release content digest mismatch")
+    calculated = _release_id(plugin, payload["version"])
+    if calculated != payload["release"]:
+        raise AppInstallError("installed release content identity mismatch")
+    return payload
+
+
 def _read_pointer(root: Path) -> dict[str, Any]:
     path = root / "current.json"
     if not path.is_file() or _is_link(path):
         return {"schema_version": POINTER_SCHEMA, "current": None, "previous": None}
     try:
+        metadata = path.lstat()
+        if (
+            not stat.S_ISREG(metadata.st_mode)
+            or metadata.st_nlink != 1
+            or metadata.st_size <= 0
+            or metadata.st_size > MAX_MANIFEST_BYTES
+        ):
+            raise AppInstallError("installed release pointer is unsafe")
         payload = json.loads(path.read_text(encoding="utf-8"))
     except (OSError, UnicodeError, ValueError, json.JSONDecodeError) as exc:
         raise AppInstallError("installed release pointer is invalid") from exc
@@ -159,7 +293,11 @@ def _read_pointer(root: Path) -> dict[str, Any]:
         payload.get("schema_version") != POINTER_SCHEMA
         or set(payload) != {"schema_version", "current", "previous"}
         or any(
-            value is not None and (not isinstance(value, str) or len(value) > 128)
+            value is not None
+            and (
+                not isinstance(value, str)
+                or RELEASE_ID.fullmatch(value) is None
+            )
             for value in (payload.get("current"), payload.get("previous"))
         )
     ):
@@ -167,6 +305,23 @@ def _read_pointer(root: Path) -> dict[str, Any]:
     return payload
 
 
+def _validate_pointer_releases(
+    root: Path,
+    pointer: dict[str, Any],
+    *,
+    include_previous: bool = True,
+) -> None:
+    names = [pointer.get("current")]
+    if include_previous:
+        names.append(pointer.get("previous"))
+    for release in names:
+        if release is not None:
+            _validate_release(
+                root / "releases" / release,
+                expected_release=release,
+            )
+
+
 def _owned_root(root: Path) -> bool:
     owner = root / ".opc-app-owned.json"
     if not owner.is_file() or _is_link(owner):
@@ -196,7 +351,7 @@ def _atomic_json(path: Path, payload: dict[str, Any]) -> None:
             os.fsync(stream.fileno())
         os.replace(temporary, path)
     except OSError as exc:
-        raise AppInstallError("failed to update installed release pointer") from exc
+        raise AppInstallError("failed to atomically update OPC App metadata") from exc
     finally:
         temporary.unlink(missing_ok=True)
 
@@ -204,19 +359,107 @@ def _atomic_json(path: Path, payload: dict[str, Any]) -> None:
 LAUNCHER = """#!/usr/bin/env python3
 from __future__ import annotations
 
+import hashlib
 import json
+import os
 import runpy
+import stat
 import sys
 from pathlib import Path
 
-root = Path(__file__).resolve().parents[1]
-pointer = json.loads((root / "current.json").read_text(encoding="utf-8"))
-release = pointer.get("current")
-if not isinstance(release, str) or not release:
-    raise SystemExit("OPC_APP_LAUNCH_FAILED: no active release")
-script = root / "releases" / release / "plugin" / "scripts" / "opc_app.py"
-if not script.is_file():
-    raise SystemExit("OPC_APP_LAUNCH_FAILED: active release is incomplete")
+def linked(path: Path) -> bool:
+    metadata = path.lstat()
+    attributes = getattr(metadata, "st_file_attributes", 0)
+    reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    return stat.S_ISLNK(metadata.st_mode) or bool(reparse and attributes & reparse)
+
+try:
+    root = Path(__file__).resolve().parents[1]
+    pointer_path = root / "current.json"
+    pointer_metadata = pointer_path.lstat()
+    if linked(pointer_path) or not stat.S_ISREG(pointer_metadata.st_mode) or pointer_metadata.st_nlink != 1:
+        raise ValueError
+    pointer = json.loads(pointer_path.read_text(encoding="utf-8"))
+    release = pointer.get("current")
+    if not isinstance(release, str) or not release or "/" in release or "\\\\" in release or ".." in release:
+        raise ValueError
+    release_root = root / "releases" / release
+    plugin = release_root / "plugin"
+    manifest_path = release_root / "release-manifest.json"
+    manifest_metadata = manifest_path.lstat()
+    if (
+        linked(release_root)
+        or linked(plugin)
+        or linked(manifest_path)
+        or not stat.S_ISREG(manifest_metadata.st_mode)
+        or manifest_metadata.st_nlink != 1
+    ):
+        raise ValueError
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if (
+        set(manifest) != {"schema_version", "release", "version", "files"}
+        or manifest.get("schema_version") != "opc-app.release-manifest.v1"
+        or manifest.get("release") != release
+        or not isinstance(manifest.get("files"), list)
+        or not manifest["files"]
+    ):
+        raise ValueError
+    expected = {}
+    for item in manifest["files"]:
+        name = item.get("path")
+        digest = item.get("sha256")
+        size = item.get("size")
+        if (
+            set(item) != {"path", "size", "sha256"}
+            or not isinstance(name, str)
+            or not name
+            or "\\\\" in name
+            or name.startswith("/")
+            or any(part in {"", ".", ".."} for part in name.split("/"))
+            or not isinstance(size, int)
+            or isinstance(size, bool)
+            or size < 0
+            or not isinstance(digest, str)
+            or len(digest) != 64
+            or name in expected
+        ):
+            raise ValueError
+        expected[name] = (size, digest)
+    actual = {}
+    raw_files = {}
+    for path in plugin.rglob("*"):
+        metadata = path.lstat()
+        if linked(path):
+            raise ValueError
+        if stat.S_ISDIR(metadata.st_mode):
+            continue
+        if not stat.S_ISREG(metadata.st_mode) or metadata.st_nlink != 1:
+            raise ValueError
+        name = path.relative_to(plugin).as_posix()
+        raw = path.read_bytes()
+        actual[name] = (len(raw), hashlib.sha256(raw).hexdigest())
+        raw_files[name] = raw
+    if actual != expected:
+        raise ValueError
+    version = manifest.get("version")
+    if not isinstance(version, str) or not version:
+        raise ValueError
+    identity = hashlib.sha256()
+    for name in sorted(raw_files):
+        encoded_name = name.encode("utf-8")
+        raw = raw_files[name]
+        identity.update(len(encoded_name).to_bytes(4, "big"))
+        identity.update(encoded_name)
+        identity.update(len(raw).to_bytes(8, "big"))
+        identity.update(raw)
+    safe_version = "".join(char if char.isalnum() or char in ".-" else "-" for char in version)
+    if f"v{safe_version}-{identity.hexdigest()[:12]}" != release:
+        raise ValueError
+except Exception:
+    raise SystemExit("OPC_APP_LAUNCH_FAILED: active release failed integrity validation")
+
+script = plugin / "scripts" / "opc_app.py"
+sys.dont_write_bytecode = True
 sys.path.insert(0, str(script.parent))
 sys.argv = [str(script), *sys.argv[1:]]
 runpy.run_path(str(script), run_name="__main__")
@@ -244,6 +487,65 @@ def _write_launchers(root: Path) -> None:
         pass
 
 
+def _install_validated_release(
+    *,
+    root: Path,
+    plugin: Path,
+    version: str,
+    release: str,
+) -> None:
+    releases = root / "releases"
+    releases.mkdir(exist_ok=True)
+    release_root = releases / release
+    stage = root / f".stage-{release}-{secrets.token_hex(6)}"
+    quarantine: Path | None = None
+    replacement_installed = False
+    try:
+        stage.mkdir()
+        shutil.copytree(
+            plugin,
+            stage / "plugin",
+            ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"),
+        )
+        _atomic_json(
+            stage / "release-manifest.json",
+            _release_manifest(stage / "plugin", version, release),
+        )
+        _validate_release(stage, expected_release=release)
+
+        if release_root.exists():
+            quarantine = root / f".corrupt-{release}-{secrets.token_hex(6)}"
+            os.replace(release_root, quarantine)
+        try:
+            os.replace(stage, release_root)
+            replacement_installed = True
+        except OSError:
+            if quarantine is not None and quarantine.exists() and not release_root.exists():
+                os.replace(quarantine, release_root)
+                quarantine = None
+            raise
+        _validate_release(release_root, expected_release=release)
+        if quarantine is not None:
+            shutil.rmtree(quarantine)
+            quarantine = None
+    except (OSError, AppInstallError) as exc:
+        if replacement_installed and release_root.exists():
+            shutil.rmtree(release_root, ignore_errors=True)
+            replacement_installed = False
+        if quarantine is not None and quarantine.exists() and not release_root.exists():
+            try:
+                os.replace(quarantine, release_root)
+                quarantine = None
+            except OSError:
+                pass
+        if isinstance(exc, AppInstallError):
+            raise
+        raise AppInstallError("failed to install a verified OPC App release") from exc
+    finally:
+        if stage.exists():
+            shutil.rmtree(stage, ignore_errors=True)
+
+
 def install_or_update(args: argparse.Namespace) -> int:
     source = Path(os.path.abspath(Path(args.source).expanduser())) if args.source else ROOT
     plugin = _plugin_source(source)
@@ -257,7 +559,26 @@ def install_or_update(args: argparse.Namespace) -> int:
         "current": None,
         "previous": None,
     }
-    action = "keep" if pointer["current"] == release else "install"
+    release_root = root / "releases" / release
+    target_valid = False
+    if release_root.exists():
+        try:
+            _validate_release(release_root, expected_release=release)
+            target_valid = True
+        except AppInstallError:
+            target_valid = False
+    for referenced in (pointer.get("current"), pointer.get("previous")):
+        if referenced is not None and referenced != release:
+            _validate_release(
+                root / "releases" / referenced,
+                expected_release=referenced,
+            )
+    if pointer["current"] == release and target_valid:
+        action = "keep"
+    elif release_root.exists() and not target_valid:
+        action = "repair"
+    else:
+        action = "install"
     plan = {
         "dry_run": not args.apply,
         "action": action,
@@ -282,24 +603,15 @@ def install_or_update(args: argparse.Namespace) -> int:
             "owner": "coconilu/codex-opc-team:opc-app",
         },
     )
-    releases = root / "releases"
-    releases.mkdir(exist_ok=True)
-    release_root = releases / release
-    if not release_root.exists():
-        stage = root / f".stage-{release}"
-        if stage.exists():
-            shutil.rmtree(stage)
-        stage.mkdir()
-        try:
-            shutil.copytree(
-                plugin,
-                stage / "plugin",
-                ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"),
-            )
-            os.replace(stage, release_root)
-        except OSError as exc:
-            shutil.rmtree(stage, ignore_errors=True)
-            raise AppInstallError("failed to install OPC App release") from exc
+    if not target_valid:
+        _install_validated_release(
+            root=root,
+            plugin=plugin,
+            version=manifest["version"],
+            release=release,
+        )
+    _validate_release(release_root, expected_release=release)
+    _write_launchers(root)
     if pointer["current"] != release:
         pointer = {
             "schema_version": POINTER_SCHEMA,
@@ -307,7 +619,6 @@ def install_or_update(args: argparse.Namespace) -> int:
             "previous": pointer["current"],
         }
         _atomic_json(root / "current.json", pointer)
-    _write_launchers(root)
     print(f"OPC App ready: {plan['launcher']}")
     print(f"App state remains separate: {plan['app_state_root']}")
     return 0
@@ -318,8 +629,9 @@ def rollback(args: argparse.Namespace) -> int:
     if not root.exists() or not _owned_root(root):
         raise AppInstallError("install root is not owned by OPC App")
     pointer = _read_pointer(root)
+    _validate_pointer_releases(root, pointer)
     previous = pointer.get("previous")
-    if not previous or not (root / "releases" / previous / "plugin").is_dir():
+    if not previous:
         raise AppInstallError("no complete previous release is available")
     plan = {
         "dry_run": not args.apply,
@@ -333,6 +645,7 @@ def rollback(args: argparse.Namespace) -> int:
     if not args.apply:
         print("Dry run only. Re-run with --apply after reviewing this plan.")
         return 0
+    _validate_pointer_releases(root, pointer)
     _atomic_json(
         root / "current.json",
         {
@@ -374,11 +687,15 @@ def uninstall(args: argparse.Namespace) -> int:
 
 def status(args: argparse.Namespace) -> int:
     root = _safe_install_root(args.install_root or default_install_root())
+    if root.exists() and not _owned_root(root):
+        raise AppInstallError("install root is not owned by OPC App")
     pointer = _read_pointer(root) if root.exists() else {
         "schema_version": POINTER_SCHEMA,
         "current": None,
         "previous": None,
     }
+    if pointer["current"] is not None:
+        _validate_pointer_releases(root, pointer)
     print(
         json.dumps(
             {
@@ -386,6 +703,7 @@ def status(args: argparse.Namespace) -> int:
                 "installed": bool(pointer["current"]),
                 "current_release": pointer["current"],
                 "previous_release": pointer["previous"],
+                "integrity": "verified" if pointer["current"] else "not-installed",
                 "launcher": str(root / "bin" / ("opc-app.cmd" if os.name == "nt" else "opc-app")),
                 "app_state_root": str(default_state_root()),
             },
diff --git a/tests/integration/test_opc_app_lifecycle.py b/tests/integration/test_opc_app_lifecycle.py
index 2e0bd57..00c5191 100644
--- a/tests/integration/test_opc_app_lifecycle.py
+++ b/tests/integration/test_opc_app_lifecycle.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import importlib.util
 import json
 import os
 import shutil
@@ -10,10 +11,16 @@
 import unittest
 import urllib.request
 from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
 
 
 ROOT = Path(__file__).resolve().parents[2]
 ADMIN = ROOT / "scripts" / "opc_app_admin.py"
+ADMIN_SPEC = importlib.util.spec_from_file_location("opc_app_admin_under_test", ADMIN)
+assert ADMIN_SPEC is not None and ADMIN_SPEC.loader is not None
+opc_app_admin = importlib.util.module_from_spec(ADMIN_SPEC)
+ADMIN_SPEC.loader.exec_module(opc_app_admin)
 
 
 def clean_environment(home: Path, state_root: Path) -> dict[str, str]:
@@ -46,6 +53,38 @@ def run_admin(
     )
 
 
+def run_admin_raw(
+    *arguments: str,
+    environment: dict[str, str],
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, str(ADMIN), *arguments],
+        cwd=ROOT,
+        env=environment,
+        capture_output=True,
+        text=True,
+        timeout=90,
+    )
+
+
+def make_source(base: Path, version: str) -> Path:
+    source = base / f"source-{version}"
+    plugin_target = source / "plugins" / "codex-opc-team"
+    shutil.copytree(
+        ROOT / "plugins" / "codex-opc-team",
+        plugin_target,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"),
+    )
+    manifest_path = plugin_target / ".codex-plugin" / "plugin.json"
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    manifest["version"] = version
+    manifest_path.write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return source
+
+
 class OPCAppLifecycleTests(unittest.TestCase):
     def test_uninstall_refuses_an_unowned_directory(self):
         with tempfile.TemporaryDirectory() as directory:
@@ -227,6 +266,29 @@ def test_update_and_rollback_switch_release_pointer_without_touching_state(self)
             self.assertNotEqual(first["current"], second["current"])
             self.assertEqual(second["previous"], first["current"])
 
+            previous_manifest = (
+                install_root
+                / "releases"
+                / first["current"]
+                / "release-manifest.json"
+            )
+            previous_manifest_bytes = previous_manifest.read_bytes()
+            previous_manifest.unlink()
+            rejected = run_admin_raw(
+                "rollback",
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            self.assertEqual(rejected.returncode, 1)
+            self.assertIn("manifest is missing", rejected.stderr)
+            self.assertEqual(
+                json.loads((install_root / "current.json").read_text(encoding="utf-8")),
+                second,
+            )
+            previous_manifest.write_bytes(previous_manifest_bytes)
+
             preview = run_admin(
                 "rollback",
                 "--install-root",
@@ -248,6 +310,254 @@ def test_update_and_rollback_switch_release_pointer_without_touching_state(self)
             self.assertEqual(rolled_back["current"], first["current"])
             self.assertEqual(state_marker.read_text(encoding="utf-8"), '{"private":"preserve"}')
 
+    def test_corruption_missing_manifest_conflict_and_link_fail_closed_then_repair(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            state_root = base / "app-state"
+            install_root = base / "runtime"
+            environment = clean_environment(home, state_root)
+            source = make_source(base, "9.1.0-integrity")
+
+            run_admin(
+                "install",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            pointer = json.loads((install_root / "current.json").read_text(encoding="utf-8"))
+            release_root = install_root / "releases" / pointer["current"]
+            target = release_root / "plugin" / "assets" / "app" / "dashboard.js"
+            original = target.read_bytes()
+
+            target.write_bytes(original + b"\n// tampered")
+            status = run_admin_raw(
+                "status",
+                "--install-root",
+                str(install_root),
+                environment=environment,
+            )
+            self.assertEqual(status.returncode, 1)
+            self.assertIn("content digest mismatch", status.stderr)
+            launcher = subprocess.run(
+                [
+                    sys.executable,
+                    str(install_root / "bin" / "opc-app.py"),
+                    "--demo",
+                    "--no-open",
+                ],
+                cwd=base,
+                env=environment,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            self.assertEqual(launcher.returncode, 1)
+            self.assertIn("integrity validation", launcher.stderr)
+
+            repair = run_admin(
+                "update",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            self.assertIn('"action": "repair"', repair.stdout)
+            verified = run_admin(
+                "status",
+                "--install-root",
+                str(install_root),
+                environment=environment,
+            )
+            self.assertIn('"integrity": "verified"', verified.stdout)
+
+            extra = release_root / "plugin" / "unexpected.bin"
+            extra.write_bytes(b"conflict")
+            conflict = run_admin_raw(
+                "status",
+                "--install-root",
+                str(install_root),
+                environment=environment,
+            )
+            self.assertEqual(conflict.returncode, 1)
+            self.assertIn("file inventory mismatch", conflict.stderr)
+            run_admin(
+                "update",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+
+            manifest_path = release_root / "release-manifest.json"
+            manifest_path.unlink()
+            missing = run_admin_raw(
+                "status",
+                "--install-root",
+                str(install_root),
+                environment=environment,
+            )
+            self.assertEqual(missing.returncode, 1)
+            self.assertIn("manifest is missing", missing.stderr)
+            run_admin(
+                "update",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+
+            outside = base / "outside.js"
+            outside.write_bytes(original)
+            target = release_root / "plugin" / "assets" / "app" / "dashboard.js"
+            target.unlink()
+            try:
+                os.symlink(outside, target)
+            except (OSError, NotImplementedError):
+                self.skipTest("file symlink creation is not permitted")
+            linked = run_admin_raw(
+                "status",
+                "--install-root",
+                str(install_root),
+                environment=environment,
+            )
+            self.assertEqual(linked.returncode, 1)
+            self.assertIn("linked content", linked.stderr)
+
+    def test_permission_and_pointer_activation_failures_preserve_current_release(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            state_root = base / "app-state"
+            install_root = base / "runtime"
+            environment = clean_environment(home, state_root)
+            first_source = make_source(base, "9.2.0-first")
+            second_source = make_source(base, "9.2.1-second")
+
+            run_admin(
+                "install",
+                "--source",
+                str(first_source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            pointer_path = install_root / "current.json"
+            before = json.loads(pointer_path.read_text(encoding="utf-8"))
+            arguments = SimpleNamespace(
+                source=str(second_source),
+                install_root=str(install_root),
+                apply=True,
+                dry_run=False,
+            )
+
+            with (
+                mock.patch.object(
+                    opc_app_admin.shutil,
+                    "copytree",
+                    side_effect=PermissionError("denied"),
+                ),
+                self.assertRaises(opc_app_admin.AppInstallError),
+            ):
+                opc_app_admin.install_or_update(arguments)
+            self.assertEqual(
+                json.loads(pointer_path.read_text(encoding="utf-8")),
+                before,
+            )
+            self.assertEqual(list(install_root.glob(".stage-*")), [])
+
+            original_atomic = opc_app_admin._atomic_json
+
+            def fail_pointer(path, payload):
+                if Path(path).name == "current.json":
+                    raise opc_app_admin.AppInstallError("injected pointer failure")
+                return original_atomic(path, payload)
+
+            with (
+                mock.patch.object(
+                    opc_app_admin,
+                    "_atomic_json",
+                    side_effect=fail_pointer,
+                ),
+                self.assertRaises(opc_app_admin.AppInstallError),
+            ):
+                opc_app_admin.install_or_update(arguments)
+            self.assertEqual(
+                json.loads(pointer_path.read_text(encoding="utf-8")),
+                before,
+            )
+            opc_app_admin._validate_release(
+                install_root / "releases" / before["current"],
+                expected_release=before["current"],
+            )
+
+            second_plugin = opc_app_admin._plugin_source(second_source)
+            second_manifest = opc_app_admin._manifest(second_plugin)
+            second_release = opc_app_admin._release_id(
+                second_plugin,
+                second_manifest["version"],
+            )
+            second_root = install_root / "releases" / second_release
+            target = second_root / "plugin" / "assets" / "app" / "dashboard.js"
+            target.write_bytes(target.read_bytes() + b"\n// corrupt")
+            original_replace = opc_app_admin.os.replace
+
+            def fail_replacement_and_restore(source_path, destination_path):
+                source_path = Path(source_path)
+                destination_path = Path(destination_path)
+                if (
+                    destination_path == second_root
+                    and (
+                        source_path.name.startswith(".stage-")
+                        or source_path.name.startswith(".corrupt-")
+                    )
+                ):
+                    raise PermissionError("injected replacement failure")
+                return original_replace(source_path, destination_path)
+
+            with (
+                mock.patch.object(
+                    opc_app_admin.os,
+                    "replace",
+                    side_effect=fail_replacement_and_restore,
+                ),
+                self.assertRaises(opc_app_admin.AppInstallError),
+            ):
+                opc_app_admin._install_validated_release(
+                    root=install_root,
+                    plugin=second_plugin,
+                    version=second_manifest["version"],
+                    release=second_release,
+                )
+            quarantined = list(install_root.glob(f".corrupt-{second_release}-*"))
+            self.assertEqual(len(quarantined), 1)
+            self.assertFalse(second_root.exists())
+            self.assertTrue(
+                (
+                    quarantined[0]
+                    / "plugin"
+                    / "assets"
+                    / "app"
+                    / "dashboard.js"
+                ).is_file()
+            )
+            self.assertEqual(
+                json.loads(pointer_path.read_text(encoding="utf-8")),
+                before,
+            )
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/tests/unit/test_opc_app.py b/tests/unit/test_opc_app.py
index 5fc04df..5f6cf14 100644
--- a/tests/unit/test_opc_app.py
+++ b/tests/unit/test_opc_app.py
@@ -19,6 +19,7 @@
 
 import opc_app  # noqa: E402
 import opc_dashboard  # noqa: E402
+import opc_snapshot_service  # noqa: E402
 from opc_snapshot_service import SnapshotService  # noqa: E402
 
 
@@ -106,6 +107,92 @@ def request(
 
 
 class SettingsStoreTests(unittest.TestCase):
+    def test_state_root_rejects_checkout_before_directory_creation(self):
+        candidate = ROOT / f".opc-app-state-test-{os.getpid()}"
+        self.assertFalse(candidate.exists())
+        with self.assertRaises(opc_app.AppSettingsError) as caught:
+            opc_app.AppSettingsStore(candidate)
+        self.assertEqual(caught.exception.code, "STATE_ROOT_OVERLAP")
+        self.assertFalse(candidate.exists())
+
+    def test_state_root_rejects_project_and_dot_opc_before_write(self):
+        with tempfile.TemporaryDirectory() as directory:
+            project = project_fixture(Path(directory) / "project")
+            for candidate in (project / "app-state", project / ".opc" / "app-state"):
+                store = opc_app.AppSettingsStore(candidate)
+                with self.assertRaises(opc_app.AppSettingsError) as caught:
+                    store.add_project(str(project))
+                self.assertEqual(caught.exception.code, "STATE_ROOT_OVERLAP")
+                self.assertFalse(candidate.exists())
+
+    def test_state_root_rejects_knowledge_data_and_parent_overlap(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            knowledge = base / "knowledge"
+            data = base / "data"
+            knowledge.mkdir()
+            data.mkdir()
+            cases = (
+                knowledge / "state",
+                data / "state",
+                base,
+            )
+            for candidate in cases:
+                with self.subTest(candidate=candidate):
+                    with self.assertRaises(opc_app.AppSettingsError) as caught:
+                        opc_app.AppSettingsStore(
+                            candidate,
+                            forbidden_roots=(knowledge, data),
+                        )
+                    self.assertEqual(caught.exception.code, "STATE_ROOT_OVERLAP")
+                    if candidate != base:
+                        self.assertFalse(candidate.exists())
+
+    def test_linked_parent_is_rejected_before_target_creation(self):
+        if not hasattr(os, "symlink"):
+            self.skipTest("symlink is unavailable")
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            target = base / "target"
+            target.mkdir()
+            alias = base / "state-alias"
+            try:
+                os.symlink(target, alias, target_is_directory=True)
+            except (OSError, NotImplementedError):
+                self.skipTest("directory symlink creation is not permitted")
+            candidate = alias / "nested"
+            with self.assertRaises(opc_app.AppSettingsError) as caught:
+                opc_app.AppSettingsStore(candidate)
+            self.assertEqual(caught.exception.code, "UNSAFE_STATE_ROOT")
+            self.assertFalse((target / "nested").exists())
+
+    def test_existing_registry_cannot_hide_state_project_overlap(self):
+        with tempfile.TemporaryDirectory() as directory:
+            project = project_fixture(Path(directory) / "project")
+            state = project / ".opc" / "app-state"
+            state.mkdir()
+            settings = {
+                "schema_version": opc_app.APP_SETTINGS_SCHEMA,
+                "projects": [
+                    {
+                        "id": "project-malicious",
+                        "path": str(project),
+                        "added_at": "2026-07-25T00:00:00Z",
+                    }
+                ],
+                "selected_project_id": "project-malicious",
+            }
+            settings_path = state / "settings.json"
+            original = json.dumps(settings)
+            settings_path.write_text(original, encoding="utf-8")
+            store = opc_app.AppSettingsStore(state)
+
+            self.assertEqual(store.context()["settings_state"], "invalid")
+            with self.assertRaises(opc_app.AppSettingsError) as caught:
+                store.add_project(str(project))
+            self.assertEqual(caught.exception.code, "STATE_ROOT_OVERLAP")
+            self.assertEqual(settings_path.read_text(encoding="utf-8"), original)
+
     def test_registry_is_app_owned_redacted_and_removal_preserves_project(self):
         with tempfile.TemporaryDirectory() as directory:
             base = Path(directory)
@@ -200,9 +287,6 @@ def test_shared_service_validates_the_same_snapshot_contract(self):
         expected = opc_dashboard.load_demo_snapshot()
         service = SnapshotService(
             project_roots_provider=tuple,
-            snapshot_builder=opc_dashboard.aggregate_snapshot,
-            demo_loader=opc_dashboard.load_demo_snapshot,
-            snapshot_validator=opc_dashboard._assert_redacted,
             demo=True,
         )
         self.assertEqual(service.snapshot(), expected)
@@ -324,9 +408,12 @@ def test_complete_app_surface_is_local_and_has_distinct_views(self):
         )
         self.assertEqual(parser.remote_resources, [])
         javascript = (asset_root / "dashboard.js").read_text(encoding="utf-8")
+        stylesheet = (asset_root / "dashboard.css").read_text(encoding="utf-8")
         self.assertIn('fetchJSON("/api/app-context")', javascript)
         self.assertIn('fetchJSON("/api/snapshot")', javascript)
         self.assertNotIn("innerHTML", javascript)
+        self.assertIn(".filterable[hidden]", stylesheet)
+        self.assertIn("display: none !important", stylesheet)
 
 
 if __name__ == "__main__":
diff --git a/tests/unit/test_opc_dashboard.py b/tests/unit/test_opc_dashboard.py
index 1fc5c67..d4ded78 100644
--- a/tests/unit/test_opc_dashboard.py
+++ b/tests/unit/test_opc_dashboard.py
@@ -21,6 +21,7 @@
 opc_dashboard = importlib.util.module_from_spec(spec)
 assert spec.loader is not None
 spec.loader.exec_module(opc_dashboard)
+import opc_snapshot_service  # noqa: E402
 
 
 STAMP = "2026-07-23T05:00:00Z"
@@ -144,15 +145,15 @@ def test_aggregation_is_redacted_and_counts_publication_by_git_provenance(self):
             knowledge.mkdir()
             data.mkdir()
             with (
-                mock.patch.object(opc_dashboard, "FileGitBackend", FakeBackend),
-                mock.patch.object(opc_dashboard, "MemoryService", FakeService),
+                mock.patch.object(opc_snapshot_service, "FileGitBackend", FakeBackend),
+                mock.patch.object(opc_snapshot_service, "MemoryService", FakeService),
                 mock.patch.object(
-                    opc_dashboard,
+                    opc_snapshot_service,
                     "read_feedback",
                     return_value={"structured_feedback": {"events": []}},
                 ),
                 mock.patch.object(
-                    opc_dashboard,
+                    opc_snapshot_service,
                     "build_view",
                     return_value={"lineage_status": "available"},
                 ),
@@ -186,12 +187,12 @@ def test_missing_live_knowledge_never_falls_back_to_demo(self):
             project = ProjectFixture(base / "project")
             with (
                 mock.patch.object(
-                    opc_dashboard,
+                    opc_snapshot_service,
                     "read_feedback",
                     return_value={"structured_feedback": None},
                 ),
                 mock.patch.object(
-                    opc_dashboard,
+                    opc_snapshot_service,
                     "build_view",
                     return_value={"lineage_status": "unavailable"},
                 ),
@@ -218,8 +219,8 @@ def test_invalid_project_is_visible_as_invalid_without_path_leak(self):
             (project / ".opc").mkdir(parents=True)
             (project / ".opc" / "project.json").write_text("{bad", encoding="utf-8")
             with (
-                mock.patch.object(opc_dashboard, "FileGitBackend", FakeBackend),
-                mock.patch.object(opc_dashboard, "MemoryService", FakeService),
+                mock.patch.object(opc_snapshot_service, "FileGitBackend", FakeBackend),
+                mock.patch.object(opc_snapshot_service, "MemoryService", FakeService),
             ):
                 snapshot = opc_dashboard.aggregate_snapshot(
                     [project],
@@ -257,15 +258,15 @@ def test_inactive_run_is_not_counted_as_active(self):
             run["active"] = False
             run_path.write_text(json.dumps(run), encoding="utf-8")
             with (
-                mock.patch.object(opc_dashboard, "FileGitBackend", FakeBackend),
-                mock.patch.object(opc_dashboard, "MemoryService", FakeService),
+                mock.patch.object(opc_snapshot_service, "FileGitBackend", FakeBackend),
+                mock.patch.object(opc_snapshot_service, "MemoryService", FakeService),
                 mock.patch.object(
-                    opc_dashboard,
+                    opc_snapshot_service,
                     "read_feedback",
                     return_value={"structured_feedback": None},
                 ),
                 mock.patch.object(
-                    opc_dashboard,
+                    opc_snapshot_service,
                     "build_view",
                     return_value={"lineage_status": "unavailable"},
                 ),
@@ -385,7 +386,7 @@ def mutate(label, path):
                 os.utime(path, ns=(1_000_000_000, 1_000_000_000))
 
         with (
-            mock.patch.object(opc_dashboard, "_read_checkpoint", side_effect=mutate),
+            mock.patch.object(opc_snapshot_service, "_read_checkpoint", side_effect=mutate),
             self.assertRaises(opc_dashboard.DashboardError) as caught,
         ):
             opc_dashboard._read_stable_bytes(
@@ -558,7 +559,7 @@ def create_server(**kwargs):
                 return_value=Path("private-data"),
             ) as data_root,
             mock.patch.object(
-                opc_dashboard,
+                opc_snapshot_service,
                 "aggregate_snapshot",
                 return_value=opc_dashboard.load_demo_snapshot(),
             ) as aggregate,
diff --git a/tests/unit/test_opc_snapshot_service.py b/tests/unit/test_opc_snapshot_service.py
new file mode 100644
index 0000000..4d79694
--- /dev/null
+++ b/tests/unit/test_opc_snapshot_service.py
@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import ast
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SCRIPTS = ROOT / "plugins" / "codex-opc-team" / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+
+import opc_snapshot_service as snapshot_core  # noqa: E402
+
+
+STAMP = "2026-07-25T00:00:00Z"
+
+
+class SnapshotCoreTests(unittest.TestCase):
+    def test_core_has_no_presentation_entry_import(self):
+        source = (SCRIPTS / "opc_snapshot_service.py").read_text(encoding="utf-8")
+        tree = ast.parse(source)
+        imported = {
+            alias.name
+            for node in ast.walk(tree)
+            if isinstance(node, ast.Import)
+            for alias in node.names
+        }
+        imported.update(
+            node.module
+            for node in ast.walk(tree)
+            if isinstance(node, ast.ImportFrom) and node.module
+        )
+        self.assertNotIn("opc_dashboard", imported)
+        self.assertNotIn("opc_app", imported)
+        app_source = (SCRIPTS / "opc_app.py").read_text(encoding="utf-8")
+        self.assertNotIn("from opc_dashboard import", app_source)
+
+    def test_service_and_direct_core_are_equal_for_one_explicit_project(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            project = base / "project"
+            opc = project / ".opc"
+            opc.mkdir(parents=True)
+            (opc / "project.json").write_text(
+                json.dumps(
+                    {
+                        "schema_version": 1,
+                        "project_id": "core-equality",
+                        "name": "Core Equality",
+                        "created_at": STAMP,
+                        "updated_at": STAMP,
+                    }
+                ),
+                encoding="utf-8",
+            )
+            knowledge = base / "knowledge"
+            data = base / "data"
+            knowledge.mkdir()
+            data.mkdir()
+
+            direct = snapshot_core.aggregate_snapshot(
+                [project],
+                knowledge_root=knowledge,
+                data_root=data,
+                now=lambda: STAMP,
+            )
+            service = snapshot_core.SnapshotService(
+                project_roots_provider=lambda: [project],
+                knowledge_root=knowledge,
+                data_root=data,
+                now_provider=lambda: STAMP,
+            )
+
+            self.assertEqual(service.snapshot(), direct)
+            self.assertEqual(direct["schema_version"], snapshot_core.SCHEMA_VERSION)
+            snapshot_core._assert_redacted(direct)
+
+
+if __name__ == "__main__":
+    unittest.main()

From adb70945b733f8431169a950fb2d69561b055aad Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 14:05:37 +0800
Subject: [PATCH 03/11] fix(app): activate launcher set transactionally

---
 ...independent-local-opc-app-control-plane.md |   8 +-
 docs/installation-and-distribution.md         |   7 +
 docs/opc-app.en.md                            |  12 +
 docs/opc-app.md                               |   8 +
 .../v0.2-public-synthetic-evidence.v1.json    |   2 +-
 scripts/opc_app_admin.py                      | 346 ++++++++++++++++-
 tests/integration/test_opc_app_lifecycle.py   | 357 ++++++++++++++++++
 7 files changed, 720 insertions(+), 20 deletions(-)

diff --git a/docs/adr/0017-independent-local-opc-app-control-plane.md b/docs/adr/0017-independent-local-opc-app-control-plane.md
index 8d1d8f0..c283943 100644
--- a/docs/adr/0017-independent-local-opc-app-control-plane.md
+++ b/docs/adr/0017-independent-local-opc-app-control-plane.md
@@ -45,7 +45,13 @@ loopback-only 浏览器视图可以安全降低经理理解 OPC 状态的成本
 9. **独立可回滚分发。** App 安装器把公开插件快照复制到用户级 runtime，
    为每个 release 持久化完整文件清单、大小与 SHA-256，用内容哈希 release
    与原子 current pointer 支持安装、升级和回滚。staging、激活、启动、状态检查
-   和回滚前都会复验完整性；损坏 release 不会被激活。卸载只删除 runtime；
+   和回滚前都会复验完整性；损坏 release 不会被激活。launcher 也作为带完整
+   manifest 和 SHA-256 的独立制品集合，在 runtime 同级 staging 后以
+   `bin → backup`、`stage → bin` 的可恢复目录交换激活；Windows 不将目录交换
+   描述为原子操作。失败时先恢复完整旧集合，恢复本身失败则保留 backup 供人工
+   恢复。launcher 与 release 解耦并在运行时复验 current release，因此 launcher
+   激活完成后才切换 pointer，pointer 写失败时旧 pointer 仍可由新 launcher 安全
+   启动。卸载只删除 runtime；
    App 状态、项目、File/Git knowledge、Git 历史、用户配置和 Mem0 数据全部保留。
 10. **旧入口兼容。** 不安装或不启动 App 时，Codex Plugin、Skills、Hook、
     脚本和 `opc_dashboard.py` 的行为与生命周期 Gate 不变。
diff --git a/docs/installation-and-distribution.md b/docs/installation-and-distribution.md
index 9c962a6..4bf761d 100644
--- a/docs/installation-and-distribution.md
+++ b/docs/installation-and-distribution.md
@@ -167,6 +167,13 @@ pointer；staging、激活、status、launcher 和 rollback 均复验完整性
 位于独立用户状态目录，并拒绝与 checkout、plugin/runtime、项目/`.opc`、
 knowledge/data root 的 lexical 或 canonical 双向重叠。
 
+`bin` launcher 集合另有完整 manifest、逐文件 SHA-256 和启动时自检。安装器拒绝
+linked/reparse/unsafe `bin` 或 launcher entry，在 runtime 同级 fresh staging
+写完并复验整套文件后，才以 backup + directory swap 激活。此流程在 Windows
+明确是可恢复事务而非“目录原子替换”：激活失败会恢复旧 launcher；恢复本身失败
+会保留 `.launcher-backup-*` 供人工恢复。launcher 不绑定单个 release，并在每次
+启动时复验 current release，所以 pointer 只在 launcher 完整激活后切换。
+
 App 卸载不删除 App 接入清单、项目 `.opc`、File/Git knowledge、Git 历史、
 用户配置或 Mem0 数据。它不安装或管理 Codex、Claude、Kimi 本体，也不写这些
 宿主的全局配置；宿主 Adapters 属于 Issue #26。完整边界与恢复说明见
diff --git a/docs/opc-app.en.md b/docs/opc-app.en.md
index 1b7451b..576e3c7 100644
--- a/docs/opc-app.en.md
+++ b/docs/opc-app.en.md
@@ -102,6 +102,18 @@ it. Missing, modified, extra, linked, or unreadable content fails closed. A
 trusted `update --apply` can repair the same damaged release, and the current
 pointer changes only after successful verification.
 
+The three launchers are also one complete artifact set with their own manifest,
+sizes, and SHA-256 digests. A launcher verifies that set before it verifies the
+current release. The installer rejects linked, reparse, or unsafe `bin` and
+launcher entries, writes and flushes a fresh sibling staging directory, verifies
+it by readback, then activates it through a recoverable old-set backup and
+directory swap. On Windows this is explicitly a recoverable transaction, not a
+claim that directory replacement is atomic. Activation failure restores the old
+set; failed restoration preserves `.launcher-backup-*` for manual recovery.
+Launchers are release-agnostic, so the release pointer changes only after the
+launcher set is active and an unchanged old pointer remains safe if pointer
+activation fails.
+
 ## 4. Project and privacy boundary
 
 The user submits one absolute directory. The server checks only that directory
diff --git a/docs/opc-app.md b/docs/opc-app.md
index c1c4f45..86daa7a 100644
--- a/docs/opc-app.md
+++ b/docs/opc-app.md
@@ -97,6 +97,14 @@ App 状态、项目 `.opc`、File/Git knowledge、Git 历史、用户配置和 M
 链接或不可读内容会 fail closed。对同一可信源码再次执行 `update --apply` 可修复
 损坏 release，current pointer 只在复验成功后原子切换。
 
+三个 launcher 也组成带 manifest、文件大小和 SHA-256 的完整制品集合；launcher
+启动时先复验自身集合，再复验 current release。安装器拒绝 linked/reparse/unsafe
+的 `bin` 和 launcher entry，在同级 fresh staging 中写入、flush/fsync、readback
+验证后，以旧集合 backup + directory swap 激活。在 Windows 上这是可恢复事务，
+不宣称目录替换原子；激活失败恢复旧集合，恢复失败则保留 `.launcher-backup-*`。
+launcher 不绑定单个 release，因此只有 launcher 集合完整激活后才切换 pointer，
+pointer 写失败时旧 pointer 仍可安全使用。
+
 ## 4. 项目接入与隐私
 
 接入流程固定为：
diff --git a/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json b/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json
index 2f7db1e..ac5e1d3 100644
--- a/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json
+++ b/evaluation/baselines/v0.2-public-synthetic-evidence.v1.json
@@ -7,7 +7,7 @@
     {
       "issue": 2,
       "path": "docs/installation-and-distribution.md",
-      "sha256": "90c8c870053666e971ebf9a0887c2a6fe103580809b1a87f7220267362a91d85"
+      "sha256": "651d27891f81176590c22aeea69b711f40af30a454dc2509c93cf59d2993e902"
     },
     {
       "issue": 3,
diff --git a/scripts/opc_app_admin.py b/scripts/opc_app_admin.py
index 78e55c2..953693f 100644
--- a/scripts/opc_app_admin.py
+++ b/scripts/opc_app_admin.py
@@ -27,9 +27,11 @@
 POINTER_SCHEMA = "opc-app.install.v1"
 OWNER_SCHEMA = "opc-app.runtime-owner.v1"
 RELEASE_MANIFEST_SCHEMA = "opc-app.release-manifest.v1"
+LAUNCHER_MANIFEST_SCHEMA = "opc-app.launcher-manifest.v1"
 RELEASE_ID = re.compile(r"^v[A-Za-z0-9.-]{1,64}-[0-9a-f]{12}$")
 HEX64 = re.compile(r"^[0-9a-f]{64}$")
 MAX_RELEASE_FILES = 4096
+LAUNCHER_NAMES = ("opc-app.py", "opc-app.cmd", "opc-app")
 
 
 class AppInstallError(RuntimeError):
@@ -95,6 +97,49 @@ def _safe_install_root(value: str | Path) -> Path:
     return root
 
 
+def _assert_runtime_boundary(root: Path, candidate: Path) -> None:
+    lexical_root = Path(os.path.abspath(root))
+    lexical_candidate = Path(os.path.abspath(candidate))
+    try:
+        relative = lexical_candidate.relative_to(lexical_root)
+    except ValueError as exc:
+        raise AppInstallError("runtime artifact escapes the install root") from exc
+    if not relative.parts:
+        raise AppInstallError("runtime artifact cannot replace the install root")
+
+    canonical_root = lexical_root.resolve(strict=False)
+    canonical_candidate = lexical_candidate.resolve(strict=False)
+    try:
+        canonical_candidate.relative_to(canonical_root)
+    except ValueError as exc:
+        raise AppInstallError("runtime artifact resolves outside the install root") from exc
+
+    current = lexical_root
+    if current.exists() and _is_link(current):
+        raise AppInstallError("runtime artifact has a linked ancestor")
+    for part in relative.parts:
+        current = current / part
+        if current.exists() and _is_link(current):
+            raise AppInstallError("runtime artifact has a linked ancestor")
+
+
+def _fsync_directory(path: Path) -> None:
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        descriptor = os.open(path, flags)
+    except OSError as exc:
+        if os.name == "nt":
+            return
+        raise AppInstallError("failed to open runtime directory for synchronization") from exc
+    try:
+        os.fsync(descriptor)
+    except OSError as exc:
+        if os.name != "nt":
+            raise AppInstallError("failed to synchronize runtime directory") from exc
+    finally:
+        os.close(descriptor)
+
+
 def _plugin_source(source: Path) -> Path:
     plugin = source / "plugins" / "codex-opc-team"
     required = (
@@ -374,7 +419,61 @@ def linked(path: Path) -> bool:
     return stat.S_ISLNK(metadata.st_mode) or bool(reparse and attributes & reparse)
 
 try:
-    root = Path(__file__).resolve().parents[1]
+    launcher_path = Path(__file__).absolute()
+    launcher_root = launcher_path.parent
+    launcher_manifest_path = launcher_root / "launcher-manifest.json"
+    if linked(launcher_path) or linked(launcher_root) or linked(launcher_manifest_path):
+        raise ValueError
+    launcher_manifest_metadata = launcher_manifest_path.lstat()
+    if (
+        not stat.S_ISREG(launcher_manifest_metadata.st_mode)
+        or launcher_manifest_metadata.st_nlink != 1
+    ):
+        raise ValueError
+    launcher_manifest = json.loads(
+        launcher_manifest_path.read_text(encoding="utf-8")
+    )
+    if (
+        set(launcher_manifest) != {"schema_version", "files"}
+        or launcher_manifest.get("schema_version") != "opc-app.launcher-manifest.v1"
+        or not isinstance(launcher_manifest.get("files"), list)
+        or len(launcher_manifest["files"]) != 3
+    ):
+        raise ValueError
+    expected_launchers = {}
+    for item in launcher_manifest["files"]:
+        name = item.get("path")
+        size = item.get("size")
+        digest = item.get("sha256")
+        if (
+            set(item) != {"path", "size", "sha256"}
+            or name not in {"opc-app.py", "opc-app.cmd", "opc-app"}
+            or not isinstance(size, int)
+            or isinstance(size, bool)
+            or size < 0
+            or not isinstance(digest, str)
+            or len(digest) != 64
+            or name in expected_launchers
+        ):
+            raise ValueError
+        expected_launchers[name] = (size, digest)
+    actual_names = {path.name for path in launcher_root.iterdir()}
+    if actual_names != {*expected_launchers, "launcher-manifest.json"}:
+        raise ValueError
+    for name, expected in expected_launchers.items():
+        path = launcher_root / name
+        metadata = path.lstat()
+        if (
+            linked(path)
+            or not stat.S_ISREG(metadata.st_mode)
+            or metadata.st_nlink != 1
+        ):
+            raise ValueError
+        raw = path.read_bytes()
+        if (len(raw), hashlib.sha256(raw).hexdigest()) != expected:
+            raise ValueError
+
+    root = launcher_root.parent
     pointer_path = root / "current.json"
     pointer_metadata = pointer_path.lstat()
     if linked(pointer_path) or not stat.S_ISREG(pointer_metadata.st_mode) or pointer_metadata.st_nlink != 1:
@@ -456,7 +555,7 @@ def linked(path: Path) -> bool:
     if f"v{safe_version}-{identity.hexdigest()[:12]}" != release:
         raise ValueError
 except Exception:
-    raise SystemExit("OPC_APP_LAUNCH_FAILED: active release failed integrity validation")
+    raise SystemExit("OPC_APP_LAUNCH_FAILED: launcher or active release failed integrity validation")
 
 script = plugin / "scripts" / "opc_app.py"
 sys.dont_write_bytecode = True
@@ -466,25 +565,233 @@ def linked(path: Path) -> bool:
 """
 
 
+CMD_LAUNCHER = b'@echo off\r\npython "%~dp0opc-app.py" %*\r\n'
+SHELL_LAUNCHER = b'#!/usr/bin/env sh\nexec python3 "$(dirname "$0")/opc-app.py" "$@"\n'
+
+
+def _launcher_payloads() -> dict[str, bytes]:
+    return {
+        "opc-app.py": LAUNCHER.encode("utf-8"),
+        "opc-app.cmd": CMD_LAUNCHER,
+        "opc-app": SHELL_LAUNCHER,
+    }
+
+
+def _launcher_manifest(payloads: dict[str, bytes]) -> dict[str, Any]:
+    return {
+        "schema_version": LAUNCHER_MANIFEST_SCHEMA,
+        "files": [
+            {
+                "path": name,
+                "size": len(payloads[name]),
+                "sha256": hashlib.sha256(payloads[name]).hexdigest(),
+            }
+            for name in LAUNCHER_NAMES
+        ],
+    }
+
+
+def _launcher_manifest_bytes(payloads: dict[str, bytes]) -> bytes:
+    return (
+        json.dumps(
+            _launcher_manifest(payloads),
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+        + "\n"
+    ).encode("utf-8")
+
+
+def _write_launcher_file(path: Path, payload: bytes, *, executable: bool = False) -> None:
+    try:
+        with path.open("xb") as stream:
+            stream.write(payload)
+            stream.flush()
+            os.fsync(stream.fileno())
+    except OSError as exc:
+        raise AppInstallError("failed to write staged launcher artifact") from exc
+    if executable:
+        try:
+            path.chmod(0o755)
+        except OSError:
+            pass
+
+
+def _validate_launcher_container(root: Path, target: Path) -> set[str]:
+    _assert_runtime_boundary(root, target)
+    if _is_link(target):
+        raise AppInstallError("launcher directory contains linked content")
+    if not target.exists():
+        return set()
+    try:
+        metadata = target.lstat()
+        entries = list(target.iterdir())
+    except OSError as exc:
+        raise AppInstallError("launcher directory is unreadable") from exc
+    if not stat.S_ISDIR(metadata.st_mode):
+        raise AppInstallError("launcher path is not a safe directory")
+    names: set[str] = set()
+    for path in entries:
+        _assert_runtime_boundary(root, path)
+        if _is_link(path):
+            raise AppInstallError("launcher directory contains linked content")
+        try:
+            entry_metadata = path.lstat()
+        except OSError as exc:
+            raise AppInstallError("launcher artifact is unreadable") from exc
+        if not stat.S_ISREG(entry_metadata.st_mode) or entry_metadata.st_nlink != 1:
+            raise AppInstallError("launcher directory contains unsafe content")
+        names.add(path.name)
+    allowed = set(LAUNCHER_NAMES) | {"launcher-manifest.json"}
+    if not names.issubset(allowed):
+        raise AppInstallError("launcher directory contains unexpected content")
+    return names
+
+
+def _validate_launcher_set(root: Path, target: Path | None = None) -> dict[str, Any]:
+    target = target or root / "bin"
+    names = _validate_launcher_container(root, target)
+    if names != set(LAUNCHER_NAMES) | {"launcher-manifest.json"}:
+        raise AppInstallError("launcher artifact set is incomplete")
+    manifest_path = target / "launcher-manifest.json"
+    try:
+        metadata = manifest_path.lstat()
+        raw_manifest = manifest_path.read_bytes()
+    except OSError as exc:
+        raise AppInstallError("launcher manifest is unreadable") from exc
+    if (
+        not stat.S_ISREG(metadata.st_mode)
+        or metadata.st_nlink != 1
+        or not raw_manifest
+        or len(raw_manifest) > MAX_MANIFEST_BYTES
+    ):
+        raise AppInstallError("launcher manifest is unsafe")
+    try:
+        manifest = json.loads(raw_manifest.decode("utf-8"))
+    except (UnicodeError, ValueError, json.JSONDecodeError) as exc:
+        raise AppInstallError("launcher manifest is invalid") from exc
+    if (
+        not isinstance(manifest, dict)
+        or set(manifest) != {"schema_version", "files"}
+        or manifest.get("schema_version") != LAUNCHER_MANIFEST_SCHEMA
+        or not isinstance(manifest.get("files"), list)
+        or len(manifest["files"]) != len(LAUNCHER_NAMES)
+    ):
+        raise AppInstallError("launcher manifest is invalid")
+    expected: dict[str, tuple[int, str]] = {}
+    for item in manifest["files"]:
+        if (
+            not isinstance(item, dict)
+            or set(item) != {"path", "size", "sha256"}
+            or item.get("path") not in LAUNCHER_NAMES
+            or item["path"] in expected
+            or not isinstance(item.get("size"), int)
+            or isinstance(item["size"], bool)
+            or item["size"] < 0
+            or not isinstance(item.get("sha256"), str)
+            or HEX64.fullmatch(item["sha256"]) is None
+        ):
+            raise AppInstallError("launcher manifest is invalid")
+        expected[item["path"]] = (item["size"], item["sha256"])
+    if set(expected) != set(LAUNCHER_NAMES):
+        raise AppInstallError("launcher manifest is invalid")
+    for name in LAUNCHER_NAMES:
+        path = target / name
+        _assert_runtime_boundary(root, path)
+        try:
+            metadata = path.lstat()
+            raw = path.read_bytes()
+        except OSError as exc:
+            raise AppInstallError("launcher artifact is unreadable") from exc
+        if (
+            _is_link(path)
+            or not stat.S_ISREG(metadata.st_mode)
+            or metadata.st_nlink != 1
+            or (len(raw), hashlib.sha256(raw).hexdigest()) != expected[name]
+        ):
+            raise AppInstallError("launcher artifact failed integrity validation")
+    return manifest
+
+
 def _write_launchers(root: Path) -> None:
     target = root / "bin"
-    target.mkdir(parents=True, exist_ok=True)
-    (target / "opc-app.py").write_text(LAUNCHER, encoding="utf-8", newline="\n")
-    (target / "opc-app.cmd").write_text(
-        '@echo off\r\npython "%~dp0opc-app.py" %*\r\n',
-        encoding="utf-8",
-        newline="",
-    )
-    shell = target / "opc-app"
-    shell.write_text(
-        '#!/usr/bin/env sh\nexec python3 "$(dirname "$0")/opc-app.py" "$@"\n',
-        encoding="utf-8",
-        newline="\n",
-    )
+    stage = root / f".launcher-stage-{secrets.token_hex(6)}"
+    backup: Path | None = None
+    failed: Path | None = None
+    activated = False
+    _assert_runtime_boundary(root, target)
+    existing_names = _validate_launcher_container(root, target)
+    if existing_names and existing_names not in (
+        set(LAUNCHER_NAMES),
+        set(LAUNCHER_NAMES) | {"launcher-manifest.json"},
+    ):
+        raise AppInstallError("existing launcher artifact set is incomplete")
+
+    payloads = _launcher_payloads()
     try:
-        shell.chmod(0o755)
-    except OSError:
-        pass
+        _assert_runtime_boundary(root, stage)
+        stage.mkdir()
+        for name in LAUNCHER_NAMES:
+            _write_launcher_file(
+                stage / name,
+                payloads[name],
+                executable=name == "opc-app",
+            )
+        _write_launcher_file(
+            stage / "launcher-manifest.json",
+            _launcher_manifest_bytes(payloads),
+        )
+        _fsync_directory(stage)
+        _validate_launcher_set(root, stage)
+
+        if target.exists():
+            backup = root / f".launcher-backup-{secrets.token_hex(6)}"
+            _assert_runtime_boundary(root, backup)
+            os.replace(target, backup)
+            _fsync_directory(root)
+        try:
+            os.replace(stage, target)
+            activated = True
+            _fsync_directory(root)
+        except OSError:
+            if backup is not None and backup.exists() and not target.exists():
+                os.replace(backup, target)
+                backup = None
+                _fsync_directory(root)
+            raise
+        _validate_launcher_set(root, target)
+        if backup is not None and backup.exists():
+            # The verified active set is now the commit point. Backup cleanup
+            # is best-effort and must never roll back into a partially removed
+            # old directory.
+            shutil.rmtree(backup, ignore_errors=True)
+            backup = None
+    except (OSError, AppInstallError) as exc:
+        if activated and target.exists():
+            failed = root / f".launcher-failed-{secrets.token_hex(6)}"
+            try:
+                _assert_runtime_boundary(root, failed)
+                os.replace(target, failed)
+                activated = False
+                _fsync_directory(root)
+            except (OSError, AppInstallError):
+                failed = None
+        if backup is not None and backup.exists() and not target.exists():
+            try:
+                os.replace(backup, target)
+                backup = None
+                _fsync_directory(root)
+            except (OSError, AppInstallError):
+                pass
+        if failed is not None and failed.exists() and target.exists():
+            shutil.rmtree(failed, ignore_errors=True)
+            failed = None
+        if isinstance(exc, AppInstallError):
+            raise
+        raise AppInstallError("failed to activate verified launcher artifacts") from exc
+    finally:
+        if stage.exists():
+            shutil.rmtree(stage, ignore_errors=True)
 
 
 def _install_validated_release(
@@ -630,6 +937,7 @@ def rollback(args: argparse.Namespace) -> int:
         raise AppInstallError("install root is not owned by OPC App")
     pointer = _read_pointer(root)
     _validate_pointer_releases(root, pointer)
+    _validate_launcher_set(root)
     previous = pointer.get("previous")
     if not previous:
         raise AppInstallError("no complete previous release is available")
@@ -646,6 +954,7 @@ def rollback(args: argparse.Namespace) -> int:
         print("Dry run only. Re-run with --apply after reviewing this plan.")
         return 0
     _validate_pointer_releases(root, pointer)
+    _validate_launcher_set(root)
     _atomic_json(
         root / "current.json",
         {
@@ -696,6 +1005,7 @@ def status(args: argparse.Namespace) -> int:
     }
     if pointer["current"] is not None:
         _validate_pointer_releases(root, pointer)
+        _validate_launcher_set(root)
     print(
         json.dumps(
             {
diff --git a/tests/integration/test_opc_app_lifecycle.py b/tests/integration/test_opc_app_lifecycle.py
index 00c5191..f4e12f6 100644
--- a/tests/integration/test_opc_app_lifecycle.py
+++ b/tests/integration/test_opc_app_lifecycle.py
@@ -85,6 +85,33 @@ def make_source(base: Path, version: str) -> Path:
     return source
 
 
+def launcher_snapshot(path: Path) -> dict[str, bytes]:
+    return {
+        item.name: item.read_bytes()
+        for item in path.iterdir()
+        if item.is_file() and not item.is_symlink()
+    }
+
+
+def assert_launcher_usable(
+    testcase: unittest.TestCase,
+    launcher: Path,
+    *,
+    environment: dict[str, str],
+    cwd: Path,
+) -> None:
+    result = subprocess.run(
+        [sys.executable, str(launcher), "--help"],
+        cwd=cwd,
+        env=environment,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    testcase.assertEqual(result.returncode, 0, result.stderr)
+    testcase.assertIn("usage:", result.stdout)
+
+
 class OPCAppLifecycleTests(unittest.TestCase):
     def test_uninstall_refuses_an_unowned_directory(self):
         with tempfile.TemporaryDirectory() as directory:
@@ -434,6 +461,329 @@ def test_corruption_missing_manifest_conflict_and_link_fail_closed_then_repair(s
             self.assertEqual(linked.returncode, 1)
             self.assertIn("linked content", linked.stderr)
 
+    def test_linked_launcher_boundaries_never_modify_outside_sentinels(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            state_root = base / "app-state"
+            install_root = base / "runtime"
+            environment = clean_environment(home, state_root)
+            source = make_source(base, "9.1.1-launcher-links")
+            run_admin(
+                "install",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            pointer_before = (install_root / "current.json").read_bytes()
+            launcher_root = install_root / "bin"
+            launcher_backup = base / "safe-launchers"
+            shutil.copytree(launcher_root, launcher_backup)
+
+            outside_directory = base / "outside-bin"
+            outside_directory.mkdir()
+            outside_directory_sentinel = outside_directory / "sentinel.bin"
+            outside_directory_sentinel.write_bytes(b"outside-directory-preserve")
+            shutil.rmtree(launcher_root)
+            try:
+                os.symlink(outside_directory, launcher_root, target_is_directory=True)
+            except (OSError, NotImplementedError):
+                self.skipTest("directory symlink creation is not permitted")
+            linked_bin = run_admin_raw(
+                "update",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            self.assertEqual(linked_bin.returncode, 1)
+            self.assertIn("outside the install root", linked_bin.stderr)
+            self.assertEqual(
+                outside_directory_sentinel.read_bytes(),
+                b"outside-directory-preserve",
+            )
+            self.assertEqual((install_root / "current.json").read_bytes(), pointer_before)
+            launcher_root.unlink()
+            shutil.copytree(launcher_backup, launcher_root)
+
+            outside_file = base / "outside-launcher.cmd"
+            outside_file.write_bytes(b"outside-file-preserve")
+            linked_launcher = launcher_root / "opc-app.cmd"
+            linked_launcher.unlink()
+            try:
+                os.symlink(outside_file, linked_launcher)
+            except (OSError, NotImplementedError):
+                self.skipTest("file symlink creation is not permitted")
+            linked_entry = run_admin_raw(
+                "update",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            self.assertEqual(linked_entry.returncode, 1)
+            self.assertIn("outside the install root", linked_entry.stderr)
+            self.assertEqual(outside_file.read_bytes(), b"outside-file-preserve")
+            self.assertEqual((install_root / "current.json").read_bytes(), pointer_before)
+
+    def test_first_and_second_launcher_write_failures_preserve_old_complete_set(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            state_root = base / "app-state"
+            install_root = base / "runtime"
+            environment = clean_environment(home, state_root)
+            source = make_source(base, "9.1.2-launcher-writes")
+            run_admin(
+                "install",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            launcher_root = install_root / "bin"
+            before = launcher_snapshot(launcher_root)
+            pointer_before = (install_root / "current.json").read_bytes()
+            arguments = SimpleNamespace(
+                source=str(source),
+                install_root=str(install_root),
+                apply=True,
+                dry_run=False,
+            )
+            original_write = opc_app_admin._write_launcher_file
+
+            for fail_at in (1, 2):
+                with self.subTest(fail_at=fail_at):
+                    calls = 0
+
+                    def fail_selected_write(path, payload, *, executable=False):
+                        nonlocal calls
+                        calls += 1
+                        if calls == fail_at:
+                            raise opc_app_admin.AppInstallError(
+                                f"injected launcher write {fail_at}"
+                            )
+                        return original_write(
+                            path,
+                            payload,
+                            executable=executable,
+                        )
+
+                    with (
+                        mock.patch.object(
+                            opc_app_admin,
+                            "_write_launcher_file",
+                            side_effect=fail_selected_write,
+                        ),
+                        self.assertRaises(opc_app_admin.AppInstallError),
+                    ):
+                        opc_app_admin.install_or_update(arguments)
+                    self.assertEqual(launcher_snapshot(launcher_root), before)
+                    self.assertEqual(
+                        (install_root / "current.json").read_bytes(),
+                        pointer_before,
+                    )
+                    self.assertEqual(list(install_root.glob(".launcher-stage-*")), [])
+                    self.assertEqual(list(install_root.glob(".launcher-backup-*")), [])
+                    assert_launcher_usable(
+                        self,
+                        launcher_root / "opc-app.py",
+                        environment=environment,
+                        cwd=base,
+                    )
+
+    def test_launcher_digest_tamper_fails_status_and_launch_then_repairs(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            state_root = base / "app-state"
+            install_root = base / "runtime"
+            environment = clean_environment(home, state_root)
+            source = make_source(base, "9.1.25-launcher-integrity")
+            run_admin(
+                "install",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            command_launcher = install_root / "bin" / "opc-app.cmd"
+            command_launcher.write_bytes(command_launcher.read_bytes() + b"\r\nrem tampered")
+            status = run_admin_raw(
+                "status",
+                "--install-root",
+                str(install_root),
+                environment=environment,
+            )
+            self.assertEqual(status.returncode, 1)
+            self.assertIn("launcher artifact failed integrity", status.stderr)
+            launch = subprocess.run(
+                [
+                    sys.executable,
+                    str(install_root / "bin" / "opc-app.py"),
+                    "--help",
+                ],
+                cwd=base,
+                env=environment,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            self.assertEqual(launch.returncode, 1)
+            self.assertIn("launcher or active release", launch.stderr)
+
+            run_admin(
+                "update",
+                "--source",
+                str(source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            opc_app_admin._validate_launcher_set(install_root)
+            assert_launcher_usable(
+                self,
+                install_root / "bin" / "opc-app.py",
+                environment=environment,
+                cwd=base,
+            )
+
+    def test_launcher_activation_failure_restores_old_set_and_pointer(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            state_root = base / "app-state"
+            install_root = base / "runtime"
+            environment = clean_environment(home, state_root)
+            first_source = make_source(base, "9.1.3-launcher-old")
+            second_source = make_source(base, "9.1.4-launcher-new")
+            run_admin(
+                "install",
+                "--source",
+                str(first_source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            launcher_root = install_root / "bin"
+            before = launcher_snapshot(launcher_root)
+            pointer_before = (install_root / "current.json").read_bytes()
+            arguments = SimpleNamespace(
+                source=str(second_source),
+                install_root=str(install_root),
+                apply=True,
+                dry_run=False,
+            )
+            original_replace = opc_app_admin.os.replace
+
+            def fail_activation(source_path, destination_path):
+                source_path = Path(source_path)
+                destination_path = Path(destination_path)
+                if (
+                    source_path.name.startswith(".launcher-stage-")
+                    and destination_path == launcher_root
+                ):
+                    raise PermissionError("injected launcher activation failure")
+                return original_replace(source_path, destination_path)
+
+            with (
+                mock.patch.object(
+                    opc_app_admin.os,
+                    "replace",
+                    side_effect=fail_activation,
+                ),
+                self.assertRaises(opc_app_admin.AppInstallError),
+            ):
+                opc_app_admin.install_or_update(arguments)
+            self.assertEqual(launcher_snapshot(launcher_root), before)
+            self.assertEqual((install_root / "current.json").read_bytes(), pointer_before)
+            self.assertEqual(list(install_root.glob(".launcher-backup-*")), [])
+            assert_launcher_usable(
+                self,
+                launcher_root / "opc-app.py",
+                environment=environment,
+                cwd=base,
+            )
+
+    def test_launcher_restore_failure_preserves_recoverable_backup(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            home = base / "home"
+            home.mkdir()
+            state_root = base / "app-state"
+            install_root = base / "runtime"
+            environment = clean_environment(home, state_root)
+            first_source = make_source(base, "9.1.5-launcher-old")
+            second_source = make_source(base, "9.1.6-launcher-new")
+            run_admin(
+                "install",
+                "--source",
+                str(first_source),
+                "--install-root",
+                str(install_root),
+                "--apply",
+                environment=environment,
+            )
+            launcher_root = install_root / "bin"
+            before = launcher_snapshot(launcher_root)
+            pointer_before = (install_root / "current.json").read_bytes()
+            arguments = SimpleNamespace(
+                source=str(second_source),
+                install_root=str(install_root),
+                apply=True,
+                dry_run=False,
+            )
+            original_replace = opc_app_admin.os.replace
+
+            def fail_activation_and_restore(source_path, destination_path):
+                source_path = Path(source_path)
+                destination_path = Path(destination_path)
+                if destination_path == launcher_root and (
+                    source_path.name.startswith(".launcher-stage-")
+                    or source_path.name.startswith(".launcher-backup-")
+                ):
+                    raise PermissionError("injected launcher swap failure")
+                return original_replace(source_path, destination_path)
+
+            with (
+                mock.patch.object(
+                    opc_app_admin.os,
+                    "replace",
+                    side_effect=fail_activation_and_restore,
+                ),
+                self.assertRaises(opc_app_admin.AppInstallError),
+            ):
+                opc_app_admin.install_or_update(arguments)
+            self.assertFalse(launcher_root.exists())
+            backups = list(install_root.glob(".launcher-backup-*"))
+            self.assertEqual(len(backups), 1)
+            self.assertEqual(launcher_snapshot(backups[0]), before)
+            opc_app_admin._validate_launcher_set(install_root, backups[0])
+            self.assertEqual((install_root / "current.json").read_bytes(), pointer_before)
+            assert_launcher_usable(
+                self,
+                backups[0] / "opc-app.py",
+                environment=environment,
+                cwd=base,
+            )
+
     def test_permission_and_pointer_activation_failures_preserve_current_release(self):
         with tempfile.TemporaryDirectory() as directory:
             base = Path(directory)
@@ -502,6 +852,13 @@ def fail_pointer(path, payload):
                 install_root / "releases" / before["current"],
                 expected_release=before["current"],
             )
+            opc_app_admin._validate_launcher_set(install_root)
+            assert_launcher_usable(
+                self,
+                install_root / "bin" / "opc-app.py",
+                environment=environment,
+                cwd=base,
+            )
 
             second_plugin = opc_app_admin._plugin_source(second_source)
             second_manifest = opc_app_admin._manifest(second_plugin)

From 057b70716e8aaf4184b5127dae89d8b5d42b5154 Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 15:16:48 +0800
Subject: [PATCH 04/11] feat: add preview-first host adapters

---
 CHANGELOG.md                                  |    1 +
 README.md                                     |    8 +
 README.zh-CN.md                               |    7 +
 ...0018-host-adapters-use-public-contracts.md |   37 +
 docs/architecture.md                          |    2 +
 docs/host-adapters.md                         |   99 ++
 .../assets/adapters/capability-matrix.v1.json |   70 +
 .../codex-opc-team/assets/app/dashboard.css   |  230 ++++
 .../codex-opc-team/assets/app/dashboard.js    |  208 ++-
 plugins/codex-opc-team/assets/app/index.html  |   34 +
 .../codex-opc-team/scripts/opc_adapters.py    | 1186 +++++++++++++++++
 plugins/codex-opc-team/scripts/opc_app.py     |   76 +-
 scripts/opc_app_admin.py                      |   34 +-
 tests/unit/test_opc_adapters.py               |  431 ++++++
 tests/unit/test_opc_app.py                    |   74 +-
 15 files changed, 2485 insertions(+), 12 deletions(-)
 create mode 100644 docs/adr/0018-host-adapters-use-public-contracts.md
 create mode 100644 docs/host-adapters.md
 create mode 100644 plugins/codex-opc-team/assets/adapters/capability-matrix.v1.json
 create mode 100644 plugins/codex-opc-team/scripts/opc_adapters.py
 create mode 100644 tests/unit/test_opc_adapters.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 453a514..8531e59 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Added
 
+- Added preview-first host Adapters for Codex, Claude Code, and Kimi Code CLI, with pinned public contracts, App-owned ownership manifests, exact logical Diff, explicit confirmation, host discovery verification, drift protection, and rollback without changing File/Git knowledge authority.
 - Added an explicitly started, loopback-only, read-only OPC Dashboard for project status, acceptance, knowledge governance, manager queue, lineage evidence, and provider health.
 - Added fixed-field privacy projection, safe optional-provider degradation, synthetic demo data, and local server security gates without introducing Node, a database, or remote assets.
 - Added evidence-gated capability evolution for versioned repository roles, Skills, and organization policies, with exact Git provenance, paired bounded pilots, manager and independent-QA approvals, one-path unstaged promotion/rollback, explicit commit confirmation, v0.1 compatibility, and private auditable history.
diff --git a/README.md b/README.md
index f7e8217..4a3f79b 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,13 @@ preserve project `.opc`, File/Git knowledge, Git history, user configuration,
 and Mem0 data. See [OPC App](docs/opc-app.en.md) for the product, installation,
 privacy, and recovery contract.
 
+The App also exposes a preview-first Adapters page for already installed Codex,
+Claude Code, and Kimi Code CLI hosts. Codex reuses the existing Marketplace
+lifecycle, Claude uses its public plugin CLI when the pinned version is safe,
+and Kimi manages only its documented user Skill projection while non-interactive
+Plugin management remains blocked. See [Host Adapters](docs/host-adapters.md)
+for the capability matrix, limits, ownership rules, and independent QA steps.
+
 ### Compatible local Dashboard
 
 The `main` branch includes an explicitly started, loopback-only, read-only Dashboard for manager visibility. It is not part of stable `v0.1.0`, does not scan for projects, and has no approval or promotion actions:
@@ -193,6 +200,7 @@ Capability evolution is an evidence-gated private lifecycle for versioned roles,
 | [Capability evolution](docs/capability-evolution.md) | Versioned role/Skill/policy pilots, evidence gates, one-path Git handoff, observation, and rollback |
 | [OPC Dashboard](docs/opc-dashboard.md) | Explicitly started local read-only manager view, data semantics, security boundaries, and limitations |
 | [OPC App](docs/opc-app.en.md) | Independent local control plane, App-owned settings, install lifecycle, privacy, and Dashboard compatibility |
+| [Host Adapters](docs/host-adapters.md) | Codex, Claude, and Kimi capability matrix, preview/apply lifecycle, limits, and recovery |
 | [v0.2 release readiness](docs/release-readiness-v0.2.0.md) | Public synthetic evidence, private 3–5 task pilot protocol, exact-commit gates, blockers, and non-claims |
 | [Roadmap](docs/roadmap.md) | Planned delivery stages |
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 5d97bd7..657bc56 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -97,6 +97,12 @@ App 的更新、回滚与卸载不会删除项目 `.opc`、File/Git knowledge、
 用户配置或 Mem0 数据。产品边界、安装、隐私与恢复契约见
 [OPC App](docs/opc-app.md)。
 
+App 还提供默认只预览的 Adapters 页面，用来管理用户已安装的 Codex、Claude
+Code 与 Kimi Code CLI 中的 OPC 集成。Codex 复用现有 Marketplace 生命周期；
+Claude 仅在钉住的安全版本范围内调用公开 Plugin CLI；Kimi 只管理官方公开的
+用户 Skill 投影，非交互 Plugin 安装仍明确阻止。能力矩阵、所有权规则、限制与
+独立验收步骤见 [Host Adapters](docs/host-adapters.md)。
+
 ### 兼容的本地 Dashboard
 
 `main` 提供一个显式启动、仅本机访问、只读的经理 Dashboard。它不属于稳定版 `v0.1.0`，不会扫描磁盘发现项目，也没有批准或晋升操作：
@@ -208,6 +214,7 @@ Hook/运行事件只进入私有 `PLUGIN_DATA` 或项目 `.opc` 回退，绝不
 | [受控能力进化](docs/capability-evolution.md) | 角色/Skill/策略版本、证据门禁、单路径 Git 交接、观察与回滚 |
 | [OPC Dashboard](docs/opc-dashboard.md) | 显式启动的本地只读经理视图、数据语义、安全边界与已知限制 |
 | [OPC App](docs/opc-app.md) | 独立本地控制平面、App 自有设置、安装生命周期、隐私与 Dashboard 兼容性 |
+| [Host Adapters](docs/host-adapters.md) | Codex、Claude、Kimi 能力矩阵、预览/执行生命周期、限制与恢复 |
 | [v0.2 发布就绪度](docs/release-readiness-v0.2.0.md) | 公开 synthetic 证据、私有 3–5 task 协议、exact-commit Gate、阻断项与非主张 |
 | [路线图](docs/roadmap.md) | 分阶段交付计划 |
 
diff --git a/docs/adr/0018-host-adapters-use-public-contracts.md b/docs/adr/0018-host-adapters-use-public-contracts.md
new file mode 100644
index 0000000..b765173
--- /dev/null
+++ b/docs/adr/0018-host-adapters-use-public-contracts.md
@@ -0,0 +1,37 @@
+# ADR-0018: Host Adapters use public lifecycle contracts
+
+- Status: Accepted
+- Date: 2026-07-25
+- Depends on: ADR-0002, ADR-0005, ADR-0017
+
+## Context
+
+OPC must project one canonical package into several local Agent hosts without
+making their extension models appear equivalent. Blind file copying would
+bypass official discovery, create ambiguous ownership, and make safe uninstall
+impossible.
+
+## Decision
+
+The App calls a host-neutral Adapter core with stable `probe`, preview-plan,
+explicit `apply`, `verify`, and `rollback` stages. Host implementations remain
+separate:
+
+- Codex delegates to the existing Marketplace/Plugin lifecycle and
+  `plugin_admin.py`.
+- Claude uses its documented non-interactive Marketplace Plugin CLI and
+  preserves plugin data during uninstall.
+- Kimi manages documented user Skill directories. Plugin automation remains
+  blocked while the public Plugin manager is interactive-only.
+
+File/Git remains authoritative. Adapter manifests and backups are operational,
+rebuildable App state, not organizational memory. A host target may be changed
+or removed only when the manifest proves OPC ownership and the current hash
+still matches. Unknown host versions and unsupported mechanisms fail closed.
+
+## Consequences
+
+The three hosts can expose different support levels without false parity.
+Plans are auditable and writes require explicit confirmation. Real installed
+state still needs independent host-specific QA because clean-room fake CLIs
+cannot prove logged-in discovery or interactive Skill invocation.
diff --git a/docs/architecture.md b/docs/architecture.md
index b633eff..9040801 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -145,6 +145,7 @@ sequenceDiagram
 | Mem0 索引 | 用户私有数据目录 | 可删除、可重建，不是权威源 |
 | Dashboard 展示状态 | 进程内即时只读投影，不持久化 | 关闭本地进程即消失，不成为事实来源 |
 | OPC App 接入清单与偏好 | `OPC_APP_HOME` 或平台用户状态目录 | 独立于 runtime、checkout、项目和知识；可删除重建 |
+| Host Adapter manifest、投影与备份 | `OPC_APP_HOME/adapters` | 仅记录 OPC 所有权、版本、Ref、哈希和恢复引用；不是组织知识 |
 | OPC App runtime releases | 平台用户数据目录 | 内容哈希版本可升级/回滚；卸载不触碰 App 状态或业务数据 |
 | 原始运行日志 | 默认最小化并设置保留策略 | 不进入公共仓库和知识层 |
 
@@ -189,6 +190,7 @@ v0.1 以 `plugins/codex-opc-team/scripts/opc_memory.py` 为真实可调用契约
 | 健康与运行状态 | `MemoryService.status()` / `doctor()` |
 | 本地只读经理视图 | `opc_dashboard.py` 的固定字段 `/api/snapshot`；loopback-only，不提供治理写操作 |
 | 共享本地投影服务 | `opc_snapshot_service.py`；旧 Dashboard 与 OPC App 使用同一 snapshot builder、DTO 和脱敏器 |
+| Host Adapter 核心 | `opc_adapters.py`；UI 只调用 probe/plan/apply/verify/rollback 契约，不实现宿主安装逻辑 |
 | 独立本地控制平面 | `opc_app.py`；治理 API 只读，唯一写状态为显式项目清单与当前选择，不承担 Agent Harness |
 | 候选只读回放与 control/treatment 证据 | `opc_shadow.py preview` / `evaluate` / `report`；不属于 `MemoryService` 状态迁移 |
 | 角色/Skill/组织策略版本生命周期 | `opc_evolution.py` 的 private proposal/pilot/evaluate/transition/confirm；只产生一个 unstaged allowlisted diff，不修改全局 Codex 配置 |
diff --git a/docs/host-adapters.md b/docs/host-adapters.md
new file mode 100644
index 0000000..63c81aa
--- /dev/null
+++ b/docs/host-adapters.md
@@ -0,0 +1,99 @@
+# OPC host adapters
+
+## Product boundary
+
+Adapters manage an OPC integration unit inside an already installed host. They
+do not install the host application, manage accounts or models, run Agent
+sessions, or change File/Git knowledge authority.
+
+```text
+canonical OPC package
+        |
+        +-- Codex  -> existing marketplace + plugin_admin.py
+        +-- Claude -> generated local marketplace plugin
+        `-- Kimi   -> documented user Skill directory projection
+```
+
+Every mutation is `probe -> preview -> explicit confirmation -> apply ->
+fresh-process verification`. The preview is in memory and performs no write.
+The ownership manifest is App-private state and contains only adapter/source
+versions, source ref, hashes, logical managed targets, and backup references.
+It never contains knowledge text, credentials, host configuration, or telemetry.
+
+## Capability matrix
+
+The machine-readable source is
+`plugins/codex-opc-team/assets/adapters/capability-matrix.v1.json`.
+
+| Host | Verified contract | Actual managed unit | Important asymmetry |
+|---|---|---|---|
+| Codex | `>=0.144.1,<0.145.0` | Marketplace Plugin | Reuses `scripts/plugin_admin.py`; it does not copy the Codex cache or enable global roles/features. |
+| Claude Code | `>=2.1.212,<3.0.0` | Marketplace Plugin | Uninstall always uses `--keep-data`. Versions below 2.1.212 are blocked because Anthropic documents a same-name cross-marketplace uninstall bug fixed in 2.1.212. |
+| Kimi Code CLI | `>=0.29.1,<0.30.0` | User Skill projection | Kimi Plugins exist, but management is currently interactive `/plugins`; the App does not automate that surface. Fresh-process Skill discovery requires a configured model and can remain `verification_required`. |
+
+Unknown versions fail closed. A missing CLI is `unavailable`; an incompatible
+version or unusable official discovery result is `blocked`. Neither state
+writes an ownership manifest or host file.
+
+## Installation location resolution
+
+| Host | Resolution |
+|---|---|
+| Codex | The official Codex CLI resolves its own config and cache. The Adapter passes the canonical marketplace source to the existing lifecycle script. |
+| Claude | The official Claude CLI resolves user-scope plugin state. The Adapter retains a generated, versioned marketplace projection under App-owned state. |
+| Kimi | `$KIMI_CODE_HOME/skills/<skill>` when set, otherwise `~/.kimi-code/skills/<skill>`. Tests always inject a disposable `KIMI_CODE_HOME`. |
+
+The browser API emits logical targets such as `kimi:skill/opc-manager`, not
+absolute user-home paths.
+
+## Conflict and recovery rules
+
+- Install refuses an existing unknown target.
+- Update and uninstall require an ownership manifest and an unchanged current
+  hash. User edits and links are preserved as conflicts.
+- Kimi directory swaps use App-owned staging and backups. A partial swap
+  restores already moved targets in reverse order.
+- Claude data is preserved on uninstall. Codex knowledge initialization is
+  explicitly skipped by the Adapter because knowledge lifecycle is independent.
+- Uninstall never touches `OPC_KNOWLEDGE_HOME`, project `.opc`, Git history,
+  manager preferences/rules/experience, optional Mem0 data, or other hosts.
+- Verification failure is not PASS. The operation attempts rollback and returns
+  a structured failure or recovery requirement.
+
+## Manual installed-state QA
+
+Automated tests prove plan/apply separation, one-time confirmation, fake-home
+isolation, exact logical Diff, ownership/hash conflict behavior, partial-failure
+recovery, and host command construction. They do not prove real logged-in host
+discovery.
+
+Run release QA in disposable host homes:
+
+| Host | Independent acceptance |
+|---|---|
+| Codex | Install through the App, start a fresh `codex` process, run `codex plugin list --json`, and invoke one OPC Skill. Update, uninstall, rollback, and repeat discovery. |
+| Claude | Use Claude Code 2.1.212 or newer, install/update/uninstall, verify with a fresh `claude plugin list --json`, and confirm plugin data remains after uninstall. |
+| Kimi | Configure a disposable model/provider, install the Skill projection, start a fresh `kimi` process, invoke `/skill:opc-manager`, then repeat after update, uninstall, and rollback. |
+
+Record the exact host versions, disposable home roots, command output, and
+reviewer identity outside the public repository. Do not accept implementer
+self-report as independent QA evidence.
+
+## Primary sources
+
+- Codex plugins and marketplaces:
+  <https://developers.openai.com/plugins/build/plugins>
+- Codex CLI plugin commands:
+  <https://developers.openai.com/codex/developer-commands>
+- Claude plugin discovery:
+  <https://code.claude.com/docs/en/discover-plugins>
+- Claude plugin reference:
+  <https://code.claude.com/docs/en/plugins-reference>
+- Claude marketplaces and uninstall compatibility note:
+  <https://code.claude.com/docs/en/plugin-marketplaces>
+- Kimi Skills:
+  <https://moonshotai.github.io/kimi-code/en/customization/skills>
+- Kimi Plugins:
+  <https://moonshotai.github.io/kimi-code/en/customization/plugins.html>
+- Kimi command reference:
+  <https://moonshotai.github.io/kimi-code/en/reference/kimi-command.html>
diff --git a/plugins/codex-opc-team/assets/adapters/capability-matrix.v1.json b/plugins/codex-opc-team/assets/adapters/capability-matrix.v1.json
new file mode 100644
index 0000000..b21337d
--- /dev/null
+++ b/plugins/codex-opc-team/assets/adapters/capability-matrix.v1.json
@@ -0,0 +1,70 @@
+{
+  "schema_version": "opc-adapters.capability-matrix.v1",
+  "verified_at": "2026-07-25",
+  "adapter_version": "1.0.0",
+  "hosts": [
+    {
+      "host_id": "codex",
+      "verified_range": ">=0.144.1,<0.145.0",
+      "verified_local_version": "0.144.1",
+      "managed_unit": "marketplace_plugin",
+      "lifecycle": {
+        "probe": "supported",
+        "install": "supported",
+        "update": "supported",
+        "uninstall": "supported",
+        "verify": "fresh_process_json"
+      },
+      "components": {
+        "skills": "supported",
+        "agents": "not_projected",
+        "hooks": "supported_by_canonical_plugin",
+        "mcp": "not_managed",
+        "apps": "supported_by_canonical_plugin"
+      }
+    },
+    {
+      "host_id": "claude",
+      "verified_range": ">=2.1.212,<3.0.0",
+      "verified_local_version": "2.1.204",
+      "managed_unit": "marketplace_plugin",
+      "local_status": "blocked_known_uninstall_safety_bug",
+      "lifecycle": {
+        "probe": "supported",
+        "install": "supported_when_compatible",
+        "update": "supported_when_compatible",
+        "uninstall": "supported_with_keep_data_when_compatible",
+        "verify": "fresh_process_json"
+      },
+      "components": {
+        "skills": "supported",
+        "agents": "not_projected",
+        "hooks": "host_specific_not_projected",
+        "mcp": "host_specific_not_projected",
+        "apps": "unsupported"
+      }
+    },
+    {
+      "host_id": "kimi",
+      "verified_range": ">=0.29.1,<0.30.0",
+      "verified_local_version": "0.29.1",
+      "managed_unit": "user_skill_projection",
+      "lifecycle": {
+        "probe": "supported",
+        "install": "supported",
+        "update": "supported",
+        "uninstall": "supported",
+        "verify": "fresh_process_prompt_requires_configured_model",
+        "plugin_apply": "blocked_no_public_noninteractive_cli"
+      },
+      "components": {
+        "skills": "supported",
+        "plugins": "interactive_only",
+        "agents": "not_projected",
+        "hooks": "plugin_only_not_managed",
+        "mcp": "plugin_only_not_managed",
+        "apps": "unsupported"
+      }
+    }
+  ]
+}
diff --git a/plugins/codex-opc-team/assets/app/dashboard.css b/plugins/codex-opc-team/assets/app/dashboard.css
index f717f40..f7dd7f6 100644
--- a/plugins/codex-opc-team/assets/app/dashboard.css
+++ b/plugins/codex-opc-team/assets/app/dashboard.css
@@ -1351,6 +1351,216 @@ dialog::backdrop {
   font-size: 11px;
 }
 
+.adapter-surface {
+  max-width: 1240px;
+}
+
+.adapter-contract {
+  color: var(--text-500);
+  font-family: var(--font-mono);
+  font-size: .75rem;
+}
+
+.adapter-boundary {
+  align-items: center;
+  background: color-mix(in srgb, var(--cyan-400) 7%, white);
+  border: 1px solid color-mix(in srgb, var(--cyan-400) 24%, var(--line));
+  border-radius: 10px;
+  color: var(--text-500);
+  display: flex;
+  font-size: .82rem;
+  gap: 10px;
+  margin: 4px 0 20px;
+  padding: 11px 13px;
+}
+
+.adapter-boundary .icon {
+  color: var(--cyan-600);
+  flex: 0 0 auto;
+}
+
+.adapter-grid {
+  display: grid;
+  gap: 16px;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.adapter-card {
+  background: var(--surface-muted);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  display: flex;
+  flex-direction: column;
+  min-height: 325px;
+  padding: 18px;
+}
+
+.adapter-card.is-blocked {
+  border-color: color-mix(in srgb, var(--red-600) 35%, var(--line));
+}
+
+.adapter-card.is-warning {
+  border-color: color-mix(in srgb, var(--amber-600) 48%, var(--line));
+}
+
+.adapter-card > header,
+.adapter-card > header > div,
+.adapter-card > header > div > span:last-child {
+  display: flex;
+}
+
+.adapter-card > header {
+  align-items: flex-start;
+  justify-content: space-between;
+}
+
+.adapter-card > header > div {
+  align-items: center;
+  gap: 10px;
+}
+
+.adapter-card > header > div > span:last-child {
+  flex-direction: column;
+  gap: 2px;
+}
+
+.adapter-card header small {
+  color: var(--text-500);
+  font-size: .72rem;
+}
+
+.adapter-mark {
+  align-items: center;
+  background: var(--ink-950);
+  border-radius: 9px;
+  color: white;
+  display: inline-flex;
+  font-weight: 760;
+  height: 34px;
+  justify-content: center;
+  width: 34px;
+}
+
+.adapter-card dl {
+  border-top: 1px solid var(--line);
+  margin: 18px 0 0;
+}
+
+.adapter-card dl div {
+  border-bottom: 1px solid var(--line);
+  display: grid;
+  font-size: .78rem;
+  gap: 8px;
+  grid-template-columns: 78px 1fr;
+  padding: 9px 0;
+}
+
+.adapter-card dt {
+  color: var(--text-500);
+}
+
+.adapter-card dd {
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+
+.adapter-warning {
+  background: #fff7e6;
+  border-radius: 8px;
+  color: var(--amber-600);
+  font-size: .75rem;
+  margin: 12px 0 0;
+  padding: 9px 10px;
+}
+
+.adapter-actions {
+  display: flex;
+  gap: 8px;
+  margin-top: auto;
+  padding-top: 16px;
+}
+
+.adapter-actions button {
+  flex: 1;
+}
+
+.adapter-dialog {
+  max-width: 680px;
+}
+
+.adapter-plan-meta {
+  display: grid;
+  gap: 0 20px;
+  grid-template-columns: 1fr 1fr;
+  margin: 18px 0;
+}
+
+.adapter-plan-meta div {
+  border-bottom: 1px solid var(--line);
+  padding: 10px 0;
+}
+
+.adapter-plan-meta dt {
+  color: var(--text-500);
+  font-size: .72rem;
+}
+
+.adapter-plan-meta dd {
+  font-size: .82rem;
+  margin: 4px 0 0;
+  overflow-wrap: anywhere;
+}
+
+.adapter-diff {
+  background: #edf2f7;
+  border-radius: 9px;
+  display: grid;
+  gap: 1px;
+  padding: 8px;
+}
+
+.adapter-diff div {
+  align-items: center;
+  background: var(--surface);
+  display: grid;
+  gap: 12px;
+  grid-template-columns: 72px 1fr;
+  padding: 9px;
+}
+
+.adapter-diff strong {
+  font-size: .68rem;
+  letter-spacing: .06em;
+}
+
+.diff-add {
+  color: var(--green-600);
+}
+
+.diff-replace {
+  color: var(--amber-600);
+}
+
+.diff-remove {
+  color: var(--red-600);
+}
+
+.diff-keep {
+  color: var(--text-500);
+}
+
+.adapter-confirm {
+  align-items: flex-start;
+  display: flex;
+  font-size: .79rem;
+  gap: 9px;
+  margin: 18px 0 4px;
+}
+
+.adapter-confirm input {
+  margin-top: 2px;
+}
+
 .drawer-notice {
   display: flex;
   gap: 10px;
@@ -1717,6 +1927,26 @@ dialog::backdrop {
   }
 }
 
+@media (max-width: 980px) {
+  .adapter-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .adapter-card {
+    min-height: 0;
+  }
+}
+
+@media (max-width: 560px) {
+  .adapter-plan-meta {
+    grid-template-columns: 1fr;
+  }
+
+  .adapter-actions {
+    flex-direction: column;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   *,
   *::before,
diff --git a/plugins/codex-opc-team/assets/app/dashboard.js b/plugins/codex-opc-team/assets/app/dashboard.js
index 02d5ef9..872857e 100644
--- a/plugins/codex-opc-team/assets/app/dashboard.js
+++ b/plugins/codex-opc-team/assets/app/dashboard.js
@@ -9,6 +9,7 @@
     knowledge: "知识",
     lineage: "证据链",
     health: "系统健康",
+    adapters: "Adapters",
     settings: "设置",
   };
 
@@ -17,6 +18,8 @@
     context: null,
     csrf: "",
     queue: new Map(),
+    adapters: null,
+    adapterPlan: null,
     refreshTimer: null,
   };
 
@@ -505,6 +508,109 @@
     setText("knowledge-published", `${finiteNumber(knowledge.published)} 条可验证知识`);
   }
 
+  function adapterStateLabel(value) {
+    return {
+      available: "可安装",
+      installed: "已安装",
+      drifted: "检测到漂移",
+      blocked: "已阻止",
+      unavailable: "宿主不可用",
+    }[String(value || "")] || "未知";
+  }
+
+  function adapterReason(value) {
+    return {
+      HOST_NOT_FOUND: "未在 PATH 中发现宿主 CLI",
+      HOST_VERSION_INCOMPATIBLE: "宿主版本不在已验证范围",
+      HOST_VERSION_INCOMPATIBLE_UNINSTALL_SAFETY: "当前版本存在官方已知卸载安全缺陷",
+      HOST_DISCOVERY_FAILED: "官方发现命令执行失败",
+      HOST_DISCOVERY_INVALID: "官方发现结果无法验证",
+      HOST_CONFIG_INVALID: "宿主配置损坏或无法通过官方诊断",
+      DEMO_OR_ADAPTER_SERVICE_UNAVAILABLE: "演示模式不探测或修改真实宿主",
+    }[String(value || "")] || String(value || "");
+  }
+
+  function adapterAction(host, operation, label, style = "secondary-button") {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = style;
+    button.textContent = label;
+    button.dataset.adapterHost = host.host_id;
+    button.dataset.adapterOperation = operation;
+    button.disabled = !["available", "installed", "drifted"].includes(host.state);
+    return button;
+  }
+
+  function renderAdapters() {
+    const target = byId("adapter-list");
+    target.replaceChildren();
+    const hosts = asArray(asObject(state.adapters).hosts);
+    if (!hosts.length) {
+      target.append(emptyState("尚无 Adapter 状态", "刷新后重新执行本地只读探测。"));
+      return;
+    }
+    hosts.forEach((host) => {
+      const card = document.createElement("article");
+      card.className = `adapter-card filterable is-${tone(host.state)}`;
+      const header = document.createElement("header");
+      const identity = document.createElement("div");
+      const mark = document.createElement("span");
+      mark.className = "adapter-mark";
+      mark.textContent = String(host.display_name || host.host_id).slice(0, 1);
+      const title = document.createElement("span");
+      const strong = document.createElement("strong");
+      strong.textContent = host.display_name || host.host_id;
+      const unit = document.createElement("small");
+      unit.textContent = host.integration_unit || "能力未发现";
+      title.append(strong, unit);
+      identity.append(mark, title);
+      const badge = document.createElement("em");
+      badge.className = `status-chip is-${tone(host.state)}`;
+      badge.textContent = adapterStateLabel(host.state);
+      header.append(identity, badge);
+
+      const facts = document.createElement("dl");
+      [
+        ["宿主版本", host.host_version || "未发现"],
+        ["已安装", host.installed_version || "—"],
+        ["目标版本", host.target_version || "—"],
+        ["验证契约", host.verified_contract || "未钉住"],
+      ].forEach(([label, value]) => {
+        const row = document.createElement("div");
+        const dt = document.createElement("dt");
+        const dd = document.createElement("dd");
+        dt.textContent = label;
+        dd.textContent = value;
+        row.append(dt, dd);
+        facts.append(row);
+      });
+      card.append(header, facts);
+
+      if (host.reason || host.plugin_management) {
+        const warning = document.createElement("p");
+        warning.className = "adapter-warning";
+        warning.textContent = host.reason
+          ? adapterReason(host.reason)
+          : "Kimi Plugin 后台安装不受支持；当前仅管理官方 Skill 投影。";
+        card.append(warning);
+      }
+      const actions = document.createElement("div");
+      actions.className = "adapter-actions";
+      if (host.state === "available") {
+        actions.append(adapterAction(host, "install", "预览安装", "primary-button"));
+      } else if (host.state === "installed" || (host.state === "drifted" && host.ownership)) {
+        actions.append(adapterAction(host, "update", host.state === "drifted" ? "查看修复计划" : "检查更新", "primary-button"));
+        actions.append(adapterAction(host, "uninstall", "预览卸载"));
+      } else {
+        const unavailable = adapterAction(host, "inspect", "当前不可执行");
+        unavailable.disabled = true;
+        actions.append(unavailable);
+      }
+      card.append(actions);
+      target.append(card);
+    });
+  }
+
   function renderLineage() {
     const project = selectedSnapshotProject();
     const stages = [...document.querySelectorAll("#lineage-timeline li")];
@@ -578,6 +684,7 @@
     renderKnowledge();
     renderLineage();
     renderHealth();
+    renderAdapters();
     renderWarnings();
     applySearch();
     setText("live-status", "OPC App 本地状态已刷新");
@@ -605,12 +712,14 @@
   async function refresh() {
     byId("refresh-button").disabled = true;
     try {
-      const [context, snapshot] = await Promise.all([
+      const [context, snapshot, adapters] = await Promise.all([
         fetchJSON("/api/app-context"),
         fetchJSON("/api/snapshot"),
+        fetchJSON("/api/adapters"),
       ]);
       state.context = context;
       state.snapshot = snapshot;
+      state.adapters = adapters;
       state.csrf = String(context.csrf_token || "");
       renderAll();
     } catch (error) {
@@ -639,6 +748,92 @@
     await refresh();
   }
 
+  async function adapterRequest(path, body) {
+    return fetchJSON(path, {
+      method: "POST",
+      headers: {
+        "X-OPC-CSRF": state.csrf,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+  }
+
+  function adapterErrorMessage(code) {
+    return {
+      HOST_BLOCKED: "宿主缺失、版本不兼容或官方发现不可用；未执行任何写入。",
+      NOT_OPC_OWNED: "没有可证明的 OPC 所有权记录，已拒绝修改。",
+      USER_MODIFIED_CONFLICT: "受管内容已被用户修改；已保留现场并转为人工处理。",
+      UNKNOWN_TARGET_CONFLICT: "目标位置已有未知内容；已保留且未覆盖。",
+      CONFIRMATION_REQUIRED: "必须重新核对计划并明确确认。",
+      PLAN_NOT_FOUND_OR_USED: "计划已过期或已经执行，请重新生成。",
+      VERIFY_FAILED_ROLLED_BACK: "宿主回读验证失败，已尝试恢复操作前状态。",
+      APPLY_FAILED: "宿主写入失败；其他 Adapter 和私人知识未被修改。",
+    }[String(code || "")] || "操作未完成；请刷新后查看结构化状态。";
+  }
+
+  async function openAdapterPlan(hostId, operation) {
+    try {
+      const plan = await adapterRequest("/api/adapters/plan", {
+        host_id: hostId,
+        operation,
+      });
+      state.adapterPlan = plan;
+      setText("adapter-dialog-host", `${hostId} · ${operation}`);
+      setText("adapter-plan-version", plan.source_version);
+      setText("adapter-plan-ref", plan.source_ref);
+      setText("adapter-plan-hash", String(plan.content_hash || "").slice(0, 16));
+      setText("adapter-plan-rollback", plan.rollback);
+      const diff = byId("adapter-plan-diff");
+      diff.replaceChildren();
+      asArray(plan.changes).forEach((change) => {
+        const row = document.createElement("div");
+        const action = document.createElement("strong");
+        action.className = `diff-${change.action}`;
+        action.textContent = String(change.action || "").toUpperCase();
+        const target = document.createElement("code");
+        target.textContent = change.target || "";
+        row.append(action, target);
+        diff.append(row);
+      });
+      setText("adapter-plan-preserves", `明确保留：${asArray(plan.preserves).join("、")}`);
+      byId("adapter-confirm").checked = false;
+      byId("apply-adapter-plan").disabled = true;
+      byId("adapter-plan-error").hidden = true;
+      byId("adapter-dialog").showModal();
+    } catch (error) {
+      showBanner(adapterErrorMessage(error.code));
+    }
+  }
+
+  async function applyAdapterPlan() {
+    const plan = asObject(state.adapterPlan);
+    if (!byId("adapter-confirm").checked || !plan.plan_id) return;
+    const button = byId("apply-adapter-plan");
+    const errorNode = byId("adapter-plan-error");
+    button.disabled = true;
+    errorNode.hidden = true;
+    try {
+      const result = await adapterRequest("/api/adapters/apply", {
+        plan_id: plan.plan_id,
+        confirmation_token: plan.confirmation_token,
+      });
+      byId("adapter-dialog").close();
+      state.adapterPlan = null;
+      await refresh();
+      showBanner(
+        result.state === "verification_required"
+          ? "宿主写入已完成，但 Kimi 新进程发现仍需在已配置模型的环境中人工验收。"
+          : "Adapter 已执行并通过宿主官方发现机制回读。"
+      );
+    } catch (error) {
+      errorNode.textContent = adapterErrorMessage(error.code);
+      errorNode.hidden = false;
+    } finally {
+      button.disabled = !byId("adapter-confirm").checked;
+    }
+  }
+
   function errorMessage(code) {
     const mapping = {
       ABSOLUTE_PROJECT_ROOT_REQUIRED: "请输入项目的绝对目录。",
@@ -817,6 +1012,17 @@
         setText("live-status", "浏览器未允许复制；请手动选择文本");
       }
     });
+    byId("adapter-list").addEventListener("click", (event) => {
+      const button = event.target.closest("button[data-adapter-host]");
+      if (!button) return;
+      openAdapterPlan(button.dataset.adapterHost, button.dataset.adapterOperation);
+    });
+    byId("close-adapter-dialog").addEventListener("click", () => byId("adapter-dialog").close());
+    byId("cancel-adapter-plan").addEventListener("click", () => byId("adapter-dialog").close());
+    byId("adapter-confirm").addEventListener("change", (event) => {
+      byId("apply-adapter-plan").disabled = !event.target.checked;
+    });
+    byId("apply-adapter-plan").addEventListener("click", applyAdapterPlan);
   }
 
   function scheduleRefresh() {
diff --git a/plugins/codex-opc-team/assets/app/index.html b/plugins/codex-opc-team/assets/app/index.html
index 9047752..b871b7c 100644
--- a/plugins/codex-opc-team/assets/app/index.html
+++ b/plugins/codex-opc-team/assets/app/index.html
@@ -29,6 +29,7 @@
     <symbol id="icon-chevron" viewBox="0 0 24 24"><path d="m9 5 7 7-7 7"/></symbol>
     <symbol id="icon-menu" viewBox="0 0 24 24"><path d="M4 6h16M4 12h16M4 18h16"/></symbol>
     <symbol id="icon-trash" viewBox="0 0 24 24"><path d="M4 7h16M9 7V4h6v3M7 7l1 14h8l1-14M10 11v6M14 11v6"/></symbol>
+    <symbol id="icon-adapter" viewBox="0 0 24 24"><path d="M8 3v5M16 3v5M5 8h14v4a7 7 0 0 1-7 7 7 7 0 0 1-7-7z"/><path d="M12 19v3"/></symbol>
   </svg>
 
   <div class="app-shell">
@@ -41,6 +42,7 @@
         <a class="nav-item" href="#knowledge" data-nav="knowledge"><svg class="icon" aria-hidden="true"><use href="#icon-knowledge"></use></svg><span>知识</span></a>
         <a class="nav-item" href="#lineage" data-nav="lineage"><svg class="icon" aria-hidden="true"><use href="#icon-lineage"></use></svg><span>证据链</span></a>
         <a class="nav-item" href="#health" data-nav="health"><svg class="icon" aria-hidden="true"><use href="#icon-health"></use></svg><span>系统健康</span></a>
+        <a class="nav-item" href="#adapters" data-nav="adapters"><svg class="icon" aria-hidden="true"><use href="#icon-adapter"></use></svg><span>Adapters</span></a>
       </nav>
       <a class="nav-item utility-nav" href="#settings" data-nav="settings"><svg class="icon" aria-hidden="true"><use href="#icon-settings"></use></svg><span>设置</span></a>
       <div class="privacy-note">
@@ -164,6 +166,20 @@ <h1 id="view-title">总览</h1>
         </section>
       </section>
 
+      <section class="app-view" id="adapters" data-view="adapters" aria-labelledby="view-title" hidden>
+        <section class="surface full-surface adapter-surface">
+          <header class="surface-heading">
+            <div><h2>本地宿主集成</h2><p>先探测、再预览 Diff；只有明确确认后才写入宿主。</p></div>
+            <span class="adapter-contract">File/Git authoritative</span>
+          </header>
+          <div class="adapter-boundary">
+            <svg class="icon" aria-hidden="true"><use href="#icon-health"></use></svg>
+            <span>这里管理 OPC 集成物，不安装宿主 App，不读取账号、模型、凭据或私人知识正文。</span>
+          </div>
+          <div class="adapter-grid" id="adapter-list" aria-live="polite"></div>
+        </section>
+      </section>
+
       <section class="app-view" id="settings" data-view="settings" aria-labelledby="view-title" hidden>
         <section class="surface settings-surface">
           <header class="surface-heading"><div><h2>App 设置</h2><p>这里只管理 OPC App 自有、可删除重建的本地状态</p></div></header>
@@ -210,6 +226,24 @@ <h3>验证预览（只读检查）</h3>
     <button class="secondary-button" id="copy-next-step" type="button"><svg class="icon" aria-hidden="true"><use href="#icon-copy"></use></svg>复制下一步建议</button>
   </dialog>
 
+  <dialog class="detail-dialog adapter-dialog" id="adapter-dialog" aria-labelledby="adapter-dialog-title">
+    <div class="dialog-header">
+      <div><span id="adapter-dialog-host">Adapter</span><h2 id="adapter-dialog-title">变更预览</h2></div>
+      <button class="icon-button" id="close-adapter-dialog" type="button" aria-label="关闭 Adapter 计划"><svg class="icon" aria-hidden="true"><use href="#icon-close"></use></svg></button>
+    </div>
+    <dl class="adapter-plan-meta">
+      <div><dt>来源版本</dt><dd id="adapter-plan-version">—</dd></div>
+      <div><dt>来源 Ref</dt><dd id="adapter-plan-ref">—</dd></div>
+      <div><dt>内容哈希</dt><dd><code id="adapter-plan-hash">—</code></dd></div>
+      <div><dt>回滚点</dt><dd id="adapter-plan-rollback">—</dd></div>
+    </dl>
+    <div class="adapter-diff" id="adapter-plan-diff"></div>
+    <p class="surface-note" id="adapter-plan-preserves"></p>
+    <label class="adapter-confirm"><input id="adapter-confirm" type="checkbox">我已核对目标、Diff、保留范围和回滚点，确认执行本次宿主写入。</label>
+    <p class="field-error" id="adapter-plan-error" role="alert" hidden></p>
+    <div class="drawer-actions"><button class="secondary-button" id="cancel-adapter-plan" type="button">取消</button><button class="primary-button" id="apply-adapter-plan" type="button" disabled>确认并执行</button></div>
+  </dialog>
+
   <script src="/dashboard.js" defer></script>
 </body>
 </html>
diff --git a/plugins/codex-opc-team/scripts/opc_adapters.py b/plugins/codex-opc-team/scripts/opc_adapters.py
new file mode 100644
index 0000000..b9096e2
--- /dev/null
+++ b/plugins/codex-opc-team/scripts/opc_adapters.py
@@ -0,0 +1,1186 @@
+#!/usr/bin/env python3
+"""Host adapter lifecycle for the local OPC App.
+
+The module deliberately keeps host mutation outside the web UI.  A caller must
+first create an immutable preview plan and then present its one-time
+confirmation token back to :class:`AdapterManager.apply`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import secrets
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping, Sequence
+
+
+ADAPTER_API_SCHEMA = "opc-adapters.api.v1"
+ADAPTER_PLAN_SCHEMA = "opc-adapters.plan.v1"
+OWNERSHIP_SCHEMA = "opc-adapters.ownership.v1"
+ADAPTER_VERSION = "1.0.0"
+HOST_IDS = ("codex", "claude", "kimi")
+PLUGIN_ID = "codex-opc-team"
+MARKETPLACE_ID = "opc"
+MAX_MANIFEST_BYTES = 512 * 1024
+PORTABLE_TOKEN = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._:@/-]{0,255}$")
+VERSION = re.compile(r"(?<!\d)(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?")
+
+
+class AdapterError(RuntimeError):
+    """A stable, UI-safe adapter failure."""
+
+    def __init__(self, code: str, *, detail: str | None = None):
+        super().__init__(code)
+        self.code = code
+        self.detail = detail
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+
+CommandRunner = Callable[[Sequence[str], Mapping[str, str] | None], CommandResult]
+
+
+def _run_command(
+    command: Sequence[str],
+    environment: Mapping[str, str] | None = None,
+) -> CommandResult:
+    try:
+        result = subprocess.run(
+            list(command),
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=45,
+            env=dict(environment) if environment is not None else None,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return CommandResult(127, "", type(exc).__name__)
+    return CommandResult(result.returncode, result.stdout, result.stderr)
+
+
+def _version_tuple(value: str) -> tuple[int, int, int] | None:
+    match = VERSION.search(value)
+    if match is None:
+        return None
+    return tuple(int(item) for item in match.groups())  # type: ignore[return-value]
+
+
+def _sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _is_link(path: Path) -> bool:
+    try:
+        metadata = path.lstat()
+    except OSError:
+        return False
+    attributes = getattr(metadata, "st_file_attributes", 0)
+    reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    return stat.S_ISLNK(metadata.st_mode) or bool(reparse and attributes & reparse)
+
+
+def _safe_tree_files(root: Path) -> list[Path]:
+    if _is_link(root):
+        raise AdapterError("UNSAFE_SOURCE")
+    files: list[Path] = []
+    for path in root.rglob("*"):
+        if _is_link(path):
+            raise AdapterError("UNSAFE_SOURCE")
+        if path.is_file() and "__pycache__" not in path.parts and path.suffix != ".pyc":
+            files.append(path)
+    return sorted(files, key=lambda item: item.relative_to(root).as_posix())
+
+
+def tree_digest(root: Path) -> str:
+    digest = hashlib.sha256()
+    for path in _safe_tree_files(root):
+        relative = path.relative_to(root).as_posix().encode("utf-8")
+        payload = path.read_bytes()
+        digest.update(len(relative).to_bytes(8, "big"))
+        digest.update(relative)
+        digest.update(len(payload).to_bytes(8, "big"))
+        digest.update(payload)
+    return digest.hexdigest()
+
+
+def _atomic_json(path: Path, payload: Mapping[str, Any]) -> None:
+    encoded = json.dumps(
+        payload,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    if len(encoded) > MAX_MANIFEST_BYTES:
+        raise AdapterError("MANIFEST_TOO_LARGE")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.parent / f".{path.name}.{secrets.token_hex(6)}.tmp"
+    try:
+        with temporary.open("xb") as handle:
+            handle.write(encoded)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    except OSError as exc:
+        raise AdapterError("STATE_WRITE_FAILED") from exc
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    try:
+        raw = path.read_bytes()
+        if len(raw) > MAX_MANIFEST_BYTES:
+            raise AdapterError("INVALID_MANIFEST")
+        payload = json.loads(raw.decode("utf-8"))
+    except AdapterError:
+        raise
+    except (OSError, UnicodeError, ValueError, json.JSONDecodeError) as exc:
+        raise AdapterError("INVALID_MANIFEST") from exc
+    if not isinstance(payload, dict):
+        raise AdapterError("INVALID_MANIFEST")
+    return payload
+
+
+class OwnershipStore:
+    """Adapter-owned state, isolated below an already validated App state root."""
+
+    def __init__(self, app_state_root: Path | str):
+        self.root = Path(os.path.abspath(app_state_root)) / "adapters"
+
+    def manifest_path(self, host_id: str) -> Path:
+        return self.root / host_id / "manifest.json"
+
+    def read(self, host_id: str) -> dict[str, Any] | None:
+        path = self.manifest_path(host_id)
+        if not path.exists():
+            return None
+        if _is_link(path) or _is_link(path.parent):
+            raise AdapterError("UNSAFE_ADAPTER_STATE")
+        payload = _read_json(path)
+        required = {
+            "schema_version",
+            "host_id",
+            "adapter_version",
+            "source_version",
+            "source_ref",
+            "content_hash",
+            "managed_targets",
+            "backup_refs",
+        }
+        if (
+            set(payload) != required
+            or payload.get("schema_version") != OWNERSHIP_SCHEMA
+            or payload.get("host_id") != host_id
+            or not isinstance(payload.get("managed_targets"), list)
+            or not isinstance(payload.get("backup_refs"), list)
+        ):
+            raise AdapterError("INVALID_MANIFEST")
+        return payload
+
+    def write(self, host_id: str, payload: Mapping[str, Any]) -> None:
+        _atomic_json(self.manifest_path(host_id), payload)
+
+    def remove(self, host_id: str) -> None:
+        path = self.manifest_path(host_id)
+        if path.exists():
+            if _is_link(path):
+                raise AdapterError("UNSAFE_ADAPTER_STATE")
+            path.unlink()
+
+    def backup_root(self, host_id: str, operation_id: str) -> Path:
+        if not PORTABLE_TOKEN.fullmatch(operation_id):
+            raise AdapterError("INVALID_OPERATION")
+        return self.root / host_id / "backups" / operation_id
+
+    def operation_path(self, host_id: str, operation_id: str) -> Path:
+        if not PORTABLE_TOKEN.fullmatch(operation_id):
+            raise AdapterError("INVALID_OPERATION")
+        return self.root / host_id / "operations" / f"{operation_id}.json"
+
+    def write_operation(
+        self,
+        host_id: str,
+        operation_id: str,
+        *,
+        operation: str,
+        prior_manifest: dict[str, Any] | None,
+    ) -> None:
+        _atomic_json(
+            self.operation_path(host_id, operation_id),
+            {
+                "schema_version": "opc-adapters.operation.v1",
+                "host_id": host_id,
+                "operation": operation,
+                "prior_manifest": prior_manifest,
+            },
+        )
+
+    def read_operation(self, host_id: str, operation_id: str) -> dict[str, Any]:
+        path = self.operation_path(host_id, operation_id)
+        if not path.is_file() or _is_link(path):
+            raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
+        payload = _read_json(path)
+        if (
+            payload.get("schema_version") != "opc-adapters.operation.v1"
+            or payload.get("host_id") != host_id
+            or payload.get("operation") not in {"install", "update", "uninstall"}
+            or not (
+                payload.get("prior_manifest") is None
+                or isinstance(payload.get("prior_manifest"), dict)
+            )
+        ):
+            raise AdapterError("INVALID_ROLLBACK_POINT")
+        return payload
+
+
+class HostAdapter:
+    host_id = ""
+    display_name = ""
+    integration_unit = ""
+    verified_contract = ""
+
+    def __init__(
+        self,
+        *,
+        source_root: Path,
+        store: OwnershipStore,
+        runner: CommandRunner = _run_command,
+        executable: str | None = None,
+        environment: Mapping[str, str] | None = None,
+    ):
+        self.source_root = Path(source_root).resolve()
+        repository_plugin = self.source_root / "plugins" / "codex-opc-team"
+        installed_plugin = self.source_root / "plugin"
+        self.plugin_root = (
+            repository_plugin if repository_plugin.is_dir() else installed_plugin
+        )
+        self.store = store
+        self.runner = runner
+        self.executable = executable
+        self.environment = dict(environment) if environment is not None else None
+
+    @property
+    def source_version(self) -> str:
+        payload = _read_json(self.plugin_root / ".codex-plugin" / "plugin.json")
+        value = payload.get("version")
+        if not isinstance(value, str) or not value:
+            raise AdapterError("INVALID_SOURCE")
+        return value
+
+    @property
+    def source_ref(self) -> str:
+        value = os.environ.get("OPC_ADAPTER_SOURCE_REF", "").strip()
+        return value if PORTABLE_TOKEN.fullmatch(value) else f"release/{self.source_version}"
+
+    @property
+    def content_hash(self) -> str:
+        return tree_digest(self.plugin_root / "skills")
+
+    def _command(self, *arguments: str) -> CommandResult:
+        executable = self.executable or shutil.which(self.host_id)
+        if not executable:
+            return CommandResult(127, "", "host executable unavailable")
+        return self.runner((executable, *arguments), self.environment)
+
+    def probe(self) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[str, str]]:
+        raise NotImplementedError
+
+    def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def verify(self, expected_installed: bool) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def rollback_operation(
+        self,
+        operation: str,
+        prior_manifest: dict[str, Any] | None,
+        operation_id: str,
+    ) -> dict[str, Any]:
+        inverse = "uninstall" if prior_manifest is None else "install"
+        return self.apply_operation(inverse, f"{operation_id}-rollback")
+
+    def _status(self, state: str, **extra: Any) -> dict[str, Any]:
+        return {
+            "host_id": self.host_id,
+            "display_name": self.display_name,
+            "state": state,
+            "integration_unit": self.integration_unit,
+            "verified_contract": self.verified_contract,
+            **extra,
+        }
+
+    def plan(self, operation: str) -> dict[str, Any]:
+        if operation not in {"install", "update", "uninstall"}:
+            raise AdapterError("UNSUPPORTED_OPERATION")
+        probe = self.probe()
+        if probe["state"] not in {"available", "installed", "drifted"}:
+            raise AdapterError("HOST_BLOCKED", detail=probe.get("reason"))
+        manifest = self.store.read(self.host_id)
+        if operation == "uninstall" and manifest is None:
+            raise AdapterError("NOT_OPC_OWNED")
+        if probe.get("state") == "drifted" and manifest is None:
+            raise AdapterError("OWNERSHIP_CONFLICT")
+        changes = self.changes(operation, manifest)
+        no_change = bool(
+            operation == "update"
+            and manifest
+            and manifest.get("content_hash") == self.content_hash
+            and probe.get("state") == "installed"
+        )
+        return {
+            "schema_version": ADAPTER_PLAN_SCHEMA,
+            "host_id": self.host_id,
+            "operation": operation,
+            "adapter_version": ADAPTER_VERSION,
+            "source_version": self.source_version,
+            "source_ref": self.source_ref,
+            "content_hash": self.content_hash,
+            "changes": changes,
+            "no_change": no_change,
+            "preserves": [
+                "OPC_KNOWLEDGE_HOME",
+                "project .opc",
+                "File/Git history",
+                "manager preferences/rules/experience",
+                "optional Mem0 data",
+                "other host adapters",
+            ],
+            "rollback": "restore this operation's OPC-owned pre-state",
+            "confirmation_required": True,
+        }
+
+
+class CodexAdapter(HostAdapter):
+    host_id = "codex"
+    display_name = "Codex"
+    integration_unit = "Marketplace Plugin"
+    verified_contract = "codex-cli >=0.144.1,<0.145.0"
+
+    def __init__(self, **kwargs: Any):
+        super().__init__(**kwargs)
+        repository_admin = self.source_root / "scripts" / "plugin_admin.py"
+        packaged_admin = self.plugin_root / "scripts" / "plugin_admin.py"
+        self.admin = repository_admin if repository_admin.is_file() else packaged_admin
+
+    def probe(self) -> dict[str, Any]:
+        result = self._command("--version")
+        version = _version_tuple(result.stdout or result.stderr)
+        if result.returncode != 0 or version is None:
+            return self._status("unavailable", reason="HOST_NOT_FOUND")
+        if not ((0, 144, 1) <= version < (0, 145, 0)):
+            return self._status(
+                "blocked",
+                host_version=".".join(map(str, version)),
+                reason="HOST_VERSION_INCOMPATIBLE",
+            )
+        listed = self._command("plugin", "list", "--json")
+        installed = False
+        if listed.returncode == 0:
+            try:
+                installed = any(
+                    item.get("pluginId") == f"{PLUGIN_ID}@{MARKETPLACE_ID}"
+                    for item in json.loads(listed.stdout).get("installed", [])
+                )
+            except (ValueError, AttributeError):
+                return self._status("blocked", reason="HOST_DISCOVERY_INVALID")
+        manifest = self.store.read(self.host_id)
+        state = "installed" if installed and manifest else "available"
+        if installed != bool(manifest):
+            state = "drifted"
+        return self._status(
+            state,
+            host_version=".".join(map(str, version)),
+            installed_version=manifest.get("source_version") if manifest else None,
+            target_version=self.source_version,
+            drift=state == "drifted",
+            ownership=bool(manifest),
+        )
+
+    def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[str, str]]:
+        action = {
+            "install": "add",
+            "update": (
+                "keep"
+                if manifest and manifest.get("content_hash") == self.content_hash
+                else "replace" if manifest else "add"
+            ),
+            "uninstall": "remove",
+        }[operation]
+        return [
+            {"action": action, "target": "codex:plugin/codex-opc-team@opc"},
+            {
+                "action": "keep",
+                "target": "codex:global-agent-roles-and-feature-flags",
+            },
+        ]
+
+    def _run_admin(
+        self,
+        operation: str,
+        *,
+        source: Path | None = None,
+        remove_marketplace: bool = False,
+    ) -> CommandResult:
+        if not self.admin.is_file():
+            return CommandResult(127, "", "plugin_admin.py unavailable")
+        arguments = [
+            sys.executable,
+            str(self.admin),
+            "uninstall" if operation == "uninstall" else "install",
+        ]
+        if operation != "uninstall":
+            source = source or self._codex_source()
+            arguments.extend(
+                [
+                    "--source",
+                    str(source),
+                    "--skip-knowledge-init",
+                ]
+            )
+            if operation == "update":
+                arguments.append("--force-reinstall")
+        elif remove_marketplace:
+            arguments.append("--remove-marketplace")
+        arguments.append("--apply")
+        return self.runner(arguments, self.environment)
+
+    def _codex_source(self) -> Path:
+        root = self.store.root / self.host_id / "projection" / self.source_version
+        if root.exists():
+            if tree_digest(root / "plugins" / "codex-opc-team" / "skills") != self.content_hash:
+                raise AdapterError("PROJECTION_CONFLICT")
+            return root
+        stage = root.parent / f".stage-{secrets.token_hex(6)}"
+        try:
+            target = stage / "plugins" / "codex-opc-team"
+            target.parent.mkdir(parents=True)
+            shutil.copytree(self.plugin_root, target)
+            (stage / ".agents" / "plugins").mkdir(parents=True)
+            _atomic_json(
+                stage / ".agents" / "plugins" / "marketplace.json",
+                {
+                    "name": MARKETPLACE_ID,
+                    "interface": {"displayName": "Codex OPC Team"},
+                    "plugins": [
+                        {
+                            "name": PLUGIN_ID,
+                            "source": {
+                                "source": "local",
+                                "path": "./plugins/codex-opc-team",
+                            },
+                            "policy": {
+                                "installation": "AVAILABLE",
+                                "authentication": "ON_INSTALL",
+                            },
+                            "category": "Productivity",
+                        }
+                    ],
+                },
+            )
+            root.parent.mkdir(parents=True, exist_ok=True)
+            os.replace(stage, root)
+        except AdapterError:
+            raise
+        except OSError as exc:
+            raise AdapterError("PROJECTION_WRITE_FAILED") from exc
+        finally:
+            if stage.exists():
+                shutil.rmtree(stage, ignore_errors=True)
+        return root
+
+    def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
+        prior = self.store.read(self.host_id)
+        if operation == "update" and prior is not None:
+            removed = self._run_admin("uninstall", remove_marketplace=True)
+            if removed.returncode != 0:
+                raise AdapterError("APPLY_FAILED")
+            result = self._run_admin("install")
+            if result.returncode != 0:
+                previous = (
+                    self.store.root
+                    / self.host_id
+                    / "projection"
+                    / prior["source_version"]
+                )
+                if previous.is_dir():
+                    self._run_admin("install", source=previous)
+                raise AdapterError("APPLY_FAILED")
+        else:
+            result = self._run_admin(operation)
+        if result.returncode != 0:
+            raise AdapterError("APPLY_FAILED")
+        return {"state": "applied", "operation_id": operation_id}
+
+    def rollback_operation(
+        self,
+        operation: str,
+        prior_manifest: dict[str, Any] | None,
+        operation_id: str,
+    ) -> dict[str, Any]:
+        if prior_manifest is None:
+            result = self._run_admin("uninstall", remove_marketplace=True)
+        else:
+            previous = (
+                self.store.root
+                / self.host_id
+                / "projection"
+                / prior_manifest["source_version"]
+            )
+            if not previous.is_dir():
+                raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
+            self._run_admin("uninstall", remove_marketplace=True)
+            result = self._run_admin("install", source=previous)
+        if result.returncode != 0:
+            raise AdapterError("ROLLBACK_FAILED")
+        return {"state": "rolled_back"}
+
+    def verify(self, expected_installed: bool) -> dict[str, Any]:
+        result = self._command("plugin", "list", "--json")
+        if result.returncode != 0:
+            return {"state": "failed", "reason": "HOST_DISCOVERY_FAILED"}
+        try:
+            installed = any(
+                item.get("pluginId") == f"{PLUGIN_ID}@{MARKETPLACE_ID}"
+                for item in json.loads(result.stdout).get("installed", [])
+            )
+        except (ValueError, AttributeError):
+            return {"state": "failed", "reason": "HOST_DISCOVERY_INVALID"}
+        return {
+            "state": "verified" if installed == expected_installed else "failed",
+            "mechanism": "codex plugin list --json (fresh process)",
+        }
+
+
+class ClaudeAdapter(HostAdapter):
+    host_id = "claude"
+    display_name = "Claude Code"
+    integration_unit = "Marketplace Plugin"
+    verified_contract = "claude-code >=2.1.212,<3.0.0"
+
+    def projection_root(self) -> Path:
+        return self.store.root / self.host_id / "projection" / self.source_version
+
+    def probe(self) -> dict[str, Any]:
+        result = self._command("--version")
+        version = _version_tuple(result.stdout or result.stderr)
+        if result.returncode != 0 or version is None:
+            return self._status("unavailable", reason="HOST_NOT_FOUND")
+        if not ((2, 1, 212) <= version < (3, 0, 0)):
+            return self._status(
+                "blocked",
+                host_version=".".join(map(str, version)),
+                reason="HOST_VERSION_INCOMPATIBLE_UNINSTALL_SAFETY",
+            )
+        listed = self._command("plugin", "list", "--json")
+        if listed.returncode != 0:
+            return self._status("blocked", reason="HOST_DISCOVERY_FAILED")
+        try:
+            values = json.loads(listed.stdout)
+            entries = values if isinstance(values, list) else values.get("plugins", [])
+            installed = any(
+                str(item.get("id") or item.get("name", "")).startswith(PLUGIN_ID)
+                for item in entries
+                if isinstance(item, dict)
+            )
+        except (ValueError, AttributeError):
+            return self._status("blocked", reason="HOST_DISCOVERY_INVALID")
+        manifest = self.store.read(self.host_id)
+        state = "installed" if installed and manifest else "available"
+        if installed != bool(manifest):
+            state = "drifted"
+        return self._status(
+            state,
+            host_version=".".join(map(str, version)),
+            installed_version=manifest.get("source_version") if manifest else None,
+            target_version=self.source_version,
+            drift=state == "drifted",
+            ownership=bool(manifest),
+        )
+
+    def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[str, str]]:
+        action = {
+            "install": "add",
+            "update": (
+                "keep"
+                if manifest and manifest.get("content_hash") == self.content_hash
+                else "replace" if manifest else "add"
+            ),
+            "uninstall": "remove",
+        }[operation]
+        return [
+            {"action": action, "target": "claude:plugin/codex-opc-team@opc"},
+            {"action": "keep", "target": "claude:plugin-data"},
+            {"action": "keep", "target": "claude:unrelated-marketplaces"},
+        ]
+
+    def _build_projection(self) -> Path:
+        root = self.projection_root()
+        if root.exists():
+            if _is_link(root) or tree_digest(root / "plugin" / "skills") != self.content_hash:
+                raise AdapterError("PROJECTION_CONFLICT")
+            return root
+        stage = root.parent / f".stage-{secrets.token_hex(6)}"
+        try:
+            plugin = stage / "plugin"
+            (plugin / ".claude-plugin").mkdir(parents=True)
+            shutil.copytree(self.plugin_root / "skills", plugin / "skills")
+            _atomic_json(
+                plugin / ".claude-plugin" / "plugin.json",
+                {
+                    "name": PLUGIN_ID,
+                    "version": self.source_version,
+                    "description": "OPC governance skills projected from the canonical package.",
+                },
+            )
+            (stage / ".claude-plugin").mkdir()
+            _atomic_json(
+                stage / ".claude-plugin" / "marketplace.json",
+                {
+                    "name": MARKETPLACE_ID,
+                    "owner": {"name": "coconilu"},
+                    "plugins": [
+                        {
+                            "name": PLUGIN_ID,
+                            "source": "./plugin",
+                            "version": self.source_version,
+                        }
+                    ],
+                },
+            )
+            root.parent.mkdir(parents=True, exist_ok=True)
+            os.replace(stage, root)
+        except AdapterError:
+            raise
+        except OSError as exc:
+            raise AdapterError("PROJECTION_WRITE_FAILED") from exc
+        finally:
+            if stage.exists():
+                shutil.rmtree(stage, ignore_errors=True)
+        return root
+
+    def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
+        selector = f"{PLUGIN_ID}@{MARKETPLACE_ID}"
+        if operation == "uninstall":
+            command = ("plugin", "uninstall", selector, "--scope", "user", "--keep-data")
+            result = self._command(*command)
+        else:
+            projection = self._build_projection()
+            if operation == "update":
+                self._command("plugin", "marketplace", "remove", MARKETPLACE_ID)
+            marketplace = self._command(
+                "plugin", "marketplace", "add", str(projection)
+            )
+            if marketplace.returncode != 0 and "already" not in (
+                marketplace.stdout + marketplace.stderr
+            ).lower():
+                raise AdapterError("APPLY_FAILED")
+            if operation == "update":
+                self._command("plugin", "marketplace", "update", MARKETPLACE_ID)
+                result = self._command("plugin", "update", selector, "--scope", "user")
+            else:
+                result = self._command("plugin", "install", selector, "--scope", "user")
+        if result.returncode != 0:
+            raise AdapterError("APPLY_FAILED")
+        return {"state": "applied", "operation_id": operation_id}
+
+    def rollback_operation(
+        self,
+        operation: str,
+        prior_manifest: dict[str, Any] | None,
+        operation_id: str,
+    ) -> dict[str, Any]:
+        selector = f"{PLUGIN_ID}@{MARKETPLACE_ID}"
+        if prior_manifest is None:
+            result = self._command(
+                "plugin", "uninstall", selector, "--scope", "user", "--keep-data"
+            )
+        else:
+            previous = (
+                self.store.root
+                / self.host_id
+                / "projection"
+                / prior_manifest["source_version"]
+            )
+            if not previous.is_dir():
+                raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
+            self._command("plugin", "marketplace", "remove", MARKETPLACE_ID)
+            added = self._command("plugin", "marketplace", "add", str(previous))
+            if added.returncode != 0:
+                raise AdapterError("ROLLBACK_FAILED")
+            result = self._command("plugin", "install", selector, "--scope", "user")
+        if result.returncode != 0:
+            raise AdapterError("ROLLBACK_FAILED")
+        return {"state": "rolled_back"}
+
+    def verify(self, expected_installed: bool) -> dict[str, Any]:
+        result = self._command("plugin", "list", "--json")
+        if result.returncode != 0:
+            return {"state": "failed", "reason": "HOST_DISCOVERY_FAILED"}
+        try:
+            payload = json.loads(result.stdout)
+            entries = payload if isinstance(payload, list) else payload.get("plugins", [])
+            installed = any(
+                str(item.get("id") or item.get("name", "")).startswith(PLUGIN_ID)
+                for item in entries
+                if isinstance(item, dict)
+            )
+        except (ValueError, AttributeError):
+            return {"state": "failed", "reason": "HOST_DISCOVERY_INVALID"}
+        return {
+            "state": "verified" if installed == expected_installed else "failed",
+            "mechanism": "claude plugin list --json (fresh process)",
+        }
+
+
+class KimiAdapter(HostAdapter):
+    host_id = "kimi"
+    display_name = "Kimi Code CLI"
+    integration_unit = "User Skill projection"
+    verified_contract = "kimi-code >=0.29.1,<0.30.0; Plugin apply blocked"
+
+    @property
+    def host_home(self) -> Path:
+        configured = (
+            (self.environment or {}).get("KIMI_CODE_HOME")
+            or os.environ.get("KIMI_CODE_HOME")
+        )
+        return (
+            Path(configured).expanduser()
+            if configured
+            else Path.home() / ".kimi-code"
+        )
+
+    @property
+    def skill_names(self) -> list[str]:
+        return [path.name for path in sorted((self.plugin_root / "skills").iterdir()) if path.is_dir()]
+
+    def _target(self, name: str) -> Path:
+        return self.host_home / "skills" / name
+
+    def probe(self) -> dict[str, Any]:
+        result = self._command("--version")
+        version = _version_tuple(result.stdout or result.stderr)
+        if result.returncode != 0 or version is None:
+            return self._status("unavailable", reason="HOST_NOT_FOUND")
+        if not ((0, 29, 1) <= version < (0, 30, 0)):
+            return self._status(
+                "blocked",
+                host_version=".".join(map(str, version)),
+                reason="HOST_VERSION_INCOMPATIBLE",
+            )
+        doctor = self._command("doctor")
+        if doctor.returncode != 0:
+            return self._status(
+                "blocked",
+                host_version=".".join(map(str, version)),
+                reason="HOST_CONFIG_INVALID",
+            )
+        manifest = self.store.read(self.host_id)
+        drift = False
+        if manifest:
+            for item in manifest["managed_targets"]:
+                target = self._target(item["name"])
+                if (
+                    not target.is_dir()
+                    or _is_link(target)
+                    or tree_digest(target) != item["hash"]
+                ):
+                    drift = True
+                    break
+        state = "drifted" if drift else "installed" if manifest else "available"
+        return self._status(
+            state,
+            host_version=".".join(map(str, version)),
+            installed_version=manifest.get("source_version") if manifest else None,
+            target_version=self.source_version,
+            drift=drift,
+            ownership=bool(manifest),
+            plugin_management="blocked_no_public_noninteractive_cli",
+        )
+
+    def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[str, str]]:
+        action = {
+            "install": "add",
+            "update": (
+                "keep"
+                if manifest and manifest.get("content_hash") == self.content_hash
+                else "replace" if manifest else "add"
+            ),
+            "uninstall": "remove",
+        }[operation]
+        return [
+            {"action": action, "target": f"kimi:skill/{name}"}
+            for name in self.skill_names
+        ]
+
+    def _assert_owned_unchanged(self, manifest: dict[str, Any]) -> None:
+        for item in manifest["managed_targets"]:
+            target = self._target(item["name"])
+            if (
+                not target.is_dir()
+                or _is_link(target)
+                or tree_digest(target) != item["hash"]
+            ):
+                raise AdapterError("USER_MODIFIED_CONFLICT")
+
+    def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
+        manifest = self.store.read(self.host_id)
+        if manifest:
+            self._assert_owned_unchanged(manifest)
+        if operation == "uninstall":
+            if manifest is None:
+                raise AdapterError("NOT_OPC_OWNED")
+            backup = self.store.backup_root(self.host_id, operation_id)
+            moved: list[tuple[Path, Path]] = []
+            try:
+                backup.mkdir(parents=True)
+                for item in manifest["managed_targets"]:
+                    target = self._target(item["name"])
+                    saved = backup / item["name"]
+                    os.replace(target, saved)
+                    moved.append((target, saved))
+            except OSError as exc:
+                for target, saved in reversed(moved):
+                    if saved.exists() and not target.exists():
+                        try:
+                            os.replace(saved, target)
+                        except OSError:
+                            pass
+                raise AdapterError("APPLY_FAILED") from exc
+            return {
+                "state": "applied",
+                "operation_id": operation_id,
+                "backup_ref": operation_id,
+            }
+
+        skill_root = self.host_home / "skills"
+        if _is_link(skill_root):
+            raise AdapterError("UNSAFE_HOST_TARGET")
+        skill_root.mkdir(parents=True, exist_ok=True)
+        backup = self.store.backup_root(self.host_id, operation_id)
+        stage = self.store.root / self.host_id / f".stage-{operation_id}"
+        activated: list[tuple[Path, Path | None]] = []
+        try:
+            stage.mkdir(parents=True)
+            for name in self.skill_names:
+                source = self.plugin_root / "skills" / name
+                staged = stage / name
+                shutil.copytree(source, staged)
+                if tree_digest(staged) != tree_digest(source):
+                    raise AdapterError("PROJECTION_VERIFY_FAILED")
+            for name in self.skill_names:
+                target = self._target(name)
+                if target.exists() and manifest is None:
+                    raise AdapterError("UNKNOWN_TARGET_CONFLICT")
+                previous: Path | None = None
+                if target.exists():
+                    backup.mkdir(parents=True, exist_ok=True)
+                    previous = backup / name
+                    os.replace(target, previous)
+                try:
+                    os.replace(stage / name, target)
+                except OSError:
+                    if previous is not None and previous.exists() and not target.exists():
+                        os.replace(previous, target)
+                    raise
+                activated.append((target, previous))
+        except AdapterError:
+            self._restore_activated(activated)
+            raise
+        except OSError as exc:
+            self._restore_activated(activated)
+            raise AdapterError("APPLY_FAILED") from exc
+        finally:
+            if stage.exists():
+                shutil.rmtree(stage, ignore_errors=True)
+        return {
+            "state": "applied",
+            "operation_id": operation_id,
+            "backup_ref": operation_id if backup.exists() else None,
+        }
+
+    @staticmethod
+    def _restore_activated(activated: list[tuple[Path, Path | None]]) -> None:
+        for target, previous in reversed(activated):
+            if target.exists():
+                shutil.rmtree(target, ignore_errors=True)
+            if previous is not None and previous.exists():
+                try:
+                    os.replace(previous, target)
+                except OSError:
+                    pass
+
+    def verify(self, expected_installed: bool) -> dict[str, Any]:
+        # Kimi has no public non-interactive skill-list command.  A fresh prompt
+        # is the public discovery mechanism; it may require the user's configured
+        # model and therefore can be inconclusive without becoming a false PASS.
+        command = ["--output-format", "stream-json"]
+        for name in self.skill_names:
+            command.extend(["--skills-dir", str(self._target(name))])
+        command.extend(["--prompt", "List the explicitly available OPC skills by name only."])
+        result = self._command(*command)
+        if not expected_installed:
+            absent = all(not self._target(name).exists() for name in self.skill_names)
+            return {
+                "state": "verified" if absent else "failed",
+                "mechanism": "fresh filesystem projection removal check",
+            }
+        if result.returncode != 0:
+            return {
+                "state": "verification_required",
+                "reason": "KIMI_FRESH_PROCESS_REQUIRES_CONFIGURED_MODEL",
+                "mechanism": "fresh kimi --skills-dir prompt",
+            }
+        discovered = all(name in result.stdout for name in self.skill_names)
+        return {
+            "state": "verified" if discovered else "failed",
+            "mechanism": "fresh kimi --skills-dir prompt",
+        }
+
+    def rollback_operation(
+        self,
+        operation: str,
+        prior_manifest: dict[str, Any] | None,
+        operation_id: str,
+    ) -> dict[str, Any]:
+        backup = self.store.backup_root(self.host_id, operation_id)
+        current = self.store.read(self.host_id)
+        if operation == "install" and prior_manifest is None:
+            targets = (
+                current["managed_targets"]
+                if current
+                else [
+                    {"name": name, "hash": tree_digest(self.plugin_root / "skills" / name)}
+                    for name in self.skill_names
+                ]
+            )
+            for item in targets:
+                target = self._target(item["name"])
+                if target.exists():
+                    if _is_link(target) or tree_digest(target) != item["hash"]:
+                        raise AdapterError("ROLLBACK_CONFLICT")
+                    shutil.rmtree(target)
+            return {"state": "rolled_back"}
+        if not backup.is_dir():
+            raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
+        restored: list[str] = []
+        for name in self.skill_names:
+            source = backup / name
+            target = self._target(name)
+            if not source.is_dir():
+                continue
+            if target.exists():
+                if current is None:
+                    raise AdapterError("ROLLBACK_CONFLICT")
+                shutil.rmtree(target)
+            os.replace(source, target)
+            restored.append(name)
+        if not restored:
+            raise AdapterError("ROLLBACK_FAILED")
+        return {"state": "rolled_back"}
+
+
+class AdapterManager:
+    """Thread-safe preview/apply coordinator shared by CLI and local App API."""
+
+    def __init__(
+        self,
+        *,
+        source_root: Path | str,
+        app_state_root: Path | str,
+        adapters: Mapping[str, HostAdapter] | None = None,
+        runner: CommandRunner = _run_command,
+        environments: Mapping[str, Mapping[str, str]] | None = None,
+        executables: Mapping[str, str] | None = None,
+    ):
+        self.source_root = Path(source_root).resolve()
+        self.store = OwnershipStore(app_state_root)
+        self._lock = threading.RLock()
+        self._plans: dict[str, dict[str, Any]] = {}
+        if adapters is not None:
+            self.adapters = dict(adapters)
+        else:
+            environments = environments or {}
+            executables = executables or {}
+            common = {"source_root": self.source_root, "store": self.store, "runner": runner}
+            self.adapters = {
+                "codex": CodexAdapter(
+                    **common,
+                    executable=executables.get("codex"),
+                    environment=environments.get("codex"),
+                ),
+                "claude": ClaudeAdapter(
+                    **common,
+                    executable=executables.get("claude"),
+                    environment=environments.get("claude"),
+                ),
+                "kimi": KimiAdapter(
+                    **common,
+                    executable=executables.get("kimi"),
+                    environment=environments.get("kimi"),
+                ),
+            }
+
+    def inventory(self) -> dict[str, Any]:
+        hosts: list[dict[str, Any]] = []
+        for host_id in HOST_IDS:
+            try:
+                hosts.append(self.adapters[host_id].probe())
+            except AdapterError as exc:
+                hosts.append(
+                    self.adapters[host_id]._status("blocked", reason=exc.code)
+                )
+        return {"schema_version": ADAPTER_API_SCHEMA, "hosts": hosts}
+
+    def create_plan(self, host_id: str, operation: str) -> dict[str, Any]:
+        adapter = self.adapters.get(host_id)
+        if adapter is None:
+            raise AdapterError("UNKNOWN_HOST")
+        payload = adapter.plan(operation)
+        serialized = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+        plan_id = f"plan-{secrets.token_hex(12)}"
+        confirmation = secrets.token_urlsafe(24)
+        record = {
+            "payload": payload,
+            "digest": _sha256_bytes(serialized),
+            "confirmation": confirmation,
+        }
+        with self._lock:
+            self._plans[plan_id] = record
+        return {**payload, "plan_id": plan_id, "confirmation_token": confirmation}
+
+    def apply(
+        self,
+        *,
+        plan_id: str,
+        confirmation_token: str,
+    ) -> dict[str, Any]:
+        with self._lock:
+            record = self._plans.pop(plan_id, None)
+        if record is None:
+            raise AdapterError("PLAN_NOT_FOUND_OR_USED")
+        if not secrets.compare_digest(record["confirmation"], confirmation_token):
+            raise AdapterError("CONFIRMATION_REQUIRED")
+        payload = record["payload"]
+        current_digest = _sha256_bytes(
+            json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+        )
+        if not secrets.compare_digest(record["digest"], current_digest):
+            raise AdapterError("PLAN_CHANGED")
+        adapter = self.adapters[payload["host_id"]]
+        current_probe = adapter.probe()
+        if current_probe["state"] not in {"available", "installed", "drifted"}:
+            raise AdapterError("HOST_CHANGED_OR_BLOCKED")
+        prior_manifest = self.store.read(adapter.host_id)
+        operation_id = f"op-{secrets.token_hex(10)}"
+        try:
+            if payload.get("no_change"):
+                verification = adapter.verify(True)
+                if verification["state"] == "failed":
+                    raise AdapterError("VERIFY_FAILED")
+                return {
+                    "schema_version": ADAPTER_API_SCHEMA,
+                    "host_id": adapter.host_id,
+                    "operation": payload["operation"],
+                    "state": "no_change",
+                    "verification": verification,
+                    "rollback_id": None,
+                }
+            applied = adapter.apply_operation(payload["operation"], operation_id)
+            verification = adapter.verify(payload["operation"] != "uninstall")
+            if verification["state"] == "failed":
+                adapter.rollback_operation(
+                    payload["operation"], prior_manifest, operation_id
+                )
+                raise AdapterError("VERIFY_FAILED_ROLLED_BACK")
+            if payload["operation"] == "uninstall":
+                self.store.remove(adapter.host_id)
+            else:
+                backup_refs = []
+                if applied.get("backup_ref"):
+                    backup_refs.append(applied["backup_ref"])
+                managed_targets = [
+                    {
+                        "name": name,
+                        "hash": tree_digest(adapter._target(name)),
+                    }
+                    for name in adapter.skill_names
+                ] if isinstance(adapter, KimiAdapter) else [
+                    {
+                        "name": f"{adapter.integration_unit}:{PLUGIN_ID}",
+                        "hash": adapter.content_hash,
+                    }
+                ]
+                self.store.write(
+                    adapter.host_id,
+                    {
+                        "schema_version": OWNERSHIP_SCHEMA,
+                        "host_id": adapter.host_id,
+                        "adapter_version": ADAPTER_VERSION,
+                        "source_version": adapter.source_version,
+                        "source_ref": adapter.source_ref,
+                        "content_hash": adapter.content_hash,
+                        "managed_targets": managed_targets,
+                        "backup_refs": backup_refs,
+                    },
+                )
+            self.store.write_operation(
+                adapter.host_id,
+                operation_id,
+                operation=payload["operation"],
+                prior_manifest=prior_manifest,
+            )
+            return {
+                "schema_version": ADAPTER_API_SCHEMA,
+                "host_id": adapter.host_id,
+                "operation": payload["operation"],
+                "state": (
+                    "verification_required"
+                    if verification["state"] == "verification_required"
+                    else "completed"
+                ),
+                "verification": verification,
+                "rollback_id": operation_id,
+            }
+        except AdapterError:
+            raise
+        except OSError as exc:
+            raise AdapterError("APPLY_FAILED") from exc
+
+    def rollback(self, host_id: str, rollback_id: str) -> dict[str, Any]:
+        adapter = self.adapters.get(host_id)
+        if adapter is None:
+            raise AdapterError("UNKNOWN_HOST")
+        record = self.store.read_operation(host_id, rollback_id)
+        prior_manifest = record["prior_manifest"]
+        result = adapter.rollback_operation(
+            record["operation"], prior_manifest, rollback_id
+        )
+        if prior_manifest is None:
+            self.store.remove(host_id)
+        else:
+            self.store.write(host_id, prior_manifest)
+        return {
+            "schema_version": ADAPTER_API_SCHEMA,
+            "host_id": host_id,
+            **result,
+        }
diff --git a/plugins/codex-opc-team/scripts/opc_app.py b/plugins/codex-opc-team/scripts/opc_app.py
index d557ea0..093811a 100644
--- a/plugins/codex-opc-team/scripts/opc_app.py
+++ b/plugins/codex-opc-team/scripts/opc_app.py
@@ -37,6 +37,11 @@
     SnapshotService,
 )
 from opc_memory import resolve_data_root, resolve_knowledge_root
+from opc_adapters import (
+    ADAPTER_API_SCHEMA,
+    AdapterError,
+    AdapterManager,
+)
 
 
 APP_CONTEXT_SCHEMA = "opc-app.context.v1"
@@ -483,10 +488,12 @@ def __init__(
         snapshot_provider: Any,
         asset_root: Path,
         settings_store: AppSettingsStore | DemoSettingsStore,
+        adapter_manager: AdapterManager | None,
         demo: bool,
     ) -> None:
         self.settings_store = settings_store
         self.demo = demo
+        self.adapter_manager = adapter_manager
         self.csrf_token = secrets.token_urlsafe(32)
         super().__init__(
             address,
@@ -535,7 +542,7 @@ def _context_payload(self) -> dict[str, Any]:
 
     def _handle_read(self, *, head_only: bool) -> None:
         parsed = urlsplit(self.path)
-        if parsed.path != "/api/app-context":
+        if parsed.path not in {"/api/app-context", "/api/adapters"}:
             super()._handle_read(head_only=head_only)
             return
         if not self._valid_host():
@@ -547,7 +554,28 @@ def _handle_read(self, *, head_only: bool) -> None:
         if parsed.query or parsed.fragment:
             self._json_error(404, "NOT_FOUND", head_only=head_only)
             return
-        self._send_json(200, self._context_payload(), head_only=head_only)
+        if parsed.path == "/api/app-context":
+            payload = self._context_payload()
+        elif self.app_server.adapter_manager is None:
+            payload = {
+                "schema_version": ADAPTER_API_SCHEMA,
+                "hosts": [
+                    {
+                        "host_id": host_id,
+                        "display_name": display_name,
+                        "state": "unavailable",
+                        "reason": "DEMO_OR_ADAPTER_SERVICE_UNAVAILABLE",
+                    }
+                    for host_id, display_name in (
+                        ("codex", "Codex"),
+                        ("claude", "Claude Code"),
+                        ("kimi", "Kimi Code CLI"),
+                    )
+                ],
+            }
+        else:
+            payload = self.app_server.adapter_manager.inventory()
+        self._send_json(200, payload, head_only=head_only)
 
     def _valid_csrf(self) -> bool:
         values = self.headers.get_all("X-OPC-CSRF", [])
@@ -612,12 +640,45 @@ def do_POST(self) -> None:
             elif parsed.path == "/api/selection" and set(payload) == {"project_id"}:
                 store.select_project(payload["project_id"])
                 status = 200
+            elif (
+                parsed.path == "/api/adapters/plan"
+                and set(payload) == {"host_id", "operation"}
+                and self.app_server.adapter_manager is not None
+            ):
+                result = self.app_server.adapter_manager.create_plan(
+                    payload["host_id"], payload["operation"]
+                )
+                self._send_json(200, result)
+                return
+            elif (
+                parsed.path == "/api/adapters/apply"
+                and set(payload) == {"plan_id", "confirmation_token"}
+                and self.app_server.adapter_manager is not None
+            ):
+                result = self.app_server.adapter_manager.apply(
+                    plan_id=payload["plan_id"],
+                    confirmation_token=payload["confirmation_token"],
+                )
+                self._send_json(200, result)
+                return
+            elif (
+                parsed.path == "/api/adapters/rollback"
+                and set(payload) == {"host_id", "rollback_id"}
+                and self.app_server.adapter_manager is not None
+            ):
+                result = self.app_server.adapter_manager.rollback(
+                    payload["host_id"], payload["rollback_id"]
+                )
+                self._send_json(200, result)
+                return
             else:
                 self._json_error(404, "NOT_FOUND")
                 return
             self._send_json(status, self._context_payload())
         except AppSettingsError as exc:
             self._json_error(400, exc.code)
+        except AdapterError as exc:
+            self._json_error(409, exc.code)
 
     def do_DELETE(self) -> None:
         if not self._prepare_mutation():
@@ -653,6 +714,7 @@ def create_app_server(
     port: int,
     snapshot_provider: Any,
     settings_store: AppSettingsStore | DemoSettingsStore,
+    adapter_manager: AdapterManager | None = None,
     demo: bool = False,
     asset_root: Path | str | None = None,
 ) -> OPCAppHTTPServer:
@@ -668,6 +730,7 @@ def create_app_server(
             snapshot_provider=snapshot_provider,
             asset_root=root,
             settings_store=settings_store,
+            adapter_manager=adapter_manager,
             demo=demo,
         )
     except OSError as exc:
@@ -712,11 +775,20 @@ def main(argv: Sequence[str] | None = None) -> int:
                 data_root=data_root,
                 allow_empty=True,
             )
+        adapter_manager = (
+            None
+            if args.demo
+            else AdapterManager(
+                source_root=SOURCE_CONTAINER_ROOT,
+                app_state_root=settings_store.root,
+            )
+        )
         server = create_app_server(
             host=args.host,
             port=args.port,
             snapshot_provider=service.snapshot,
             settings_store=settings_store,
+            adapter_manager=adapter_manager,
             demo=args.demo,
         )
     except (DashboardError, AppSettingsError) as exc:
diff --git a/scripts/opc_app_admin.py b/scripts/opc_app_admin.py
index 953693f..3743125 100644
--- a/scripts/opc_app_admin.py
+++ b/scripts/opc_app_admin.py
@@ -145,6 +145,7 @@ def _plugin_source(source: Path) -> Path:
     required = (
         plugin / ".codex-plugin" / "plugin.json",
         plugin / "scripts" / "opc_app.py",
+        plugin / "scripts" / "opc_adapters.py",
         plugin / "scripts" / "opc_dashboard.py",
         plugin / "scripts" / "opc_snapshot_service.py",
         plugin / "assets" / "app" / "index.html",
@@ -185,13 +186,28 @@ def _source_files(plugin: Path) -> list[Path]:
     return sorted(files, key=lambda item: item.relative_to(plugin).as_posix())
 
 
+def _packaged_payloads(plugin: Path) -> list[tuple[str, bytes]]:
+    payloads = [
+        (path.relative_to(plugin).as_posix(), path.read_bytes())
+        for path in _source_files(plugin)
+    ]
+    packaged_admin = plugin / "scripts" / "plugin_admin.py"
+    if not packaged_admin.is_file():
+        payloads.append(
+            (
+                "scripts/plugin_admin.py",
+                (ROOT / "scripts" / "plugin_admin.py").read_bytes(),
+            )
+        )
+    return sorted(payloads, key=lambda item: item[0])
+
+
 def _release_id(plugin: Path, version: str) -> str:
     digest = hashlib.sha256()
-    for path in _source_files(plugin):
-        relative = path.relative_to(plugin).as_posix().encode("utf-8")
+    for relative_text, payload in _packaged_payloads(plugin):
+        relative = relative_text.encode("utf-8")
         digest.update(len(relative).to_bytes(4, "big"))
         digest.update(relative)
-        payload = path.read_bytes()
         digest.update(len(payload).to_bytes(8, "big"))
         digest.update(payload)
     safe_version = "".join(char if char.isalnum() or char in ".-" else "-" for char in version)
@@ -200,11 +216,10 @@ def _release_id(plugin: Path, version: str) -> str:
 
 def _release_manifest(plugin: Path, version: str, release: str) -> dict[str, Any]:
     files = []
-    for path in _source_files(plugin):
-        payload = path.read_bytes()
+    for relative, payload in _packaged_payloads(plugin):
         files.append(
             {
-                "path": path.relative_to(plugin).as_posix(),
+                "path": relative,
                 "size": len(payload),
                 "sha256": hashlib.sha256(payload).hexdigest(),
             }
@@ -814,6 +829,13 @@ def _install_validated_release(
             stage / "plugin",
             ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"),
         )
+        # Ship the existing Codex Marketplace lifecycle implementation with the
+        # App release.  The Adapter invokes this exact script; it does not grow a
+        # second Codex installer inside the UI or adapter core.
+        shutil.copy2(
+            ROOT / "scripts" / "plugin_admin.py",
+            stage / "plugin" / "scripts" / "plugin_admin.py",
+        )
         _atomic_json(
             stage / "release-manifest.json",
             _release_manifest(stage / "plugin", version, release),
diff --git a/tests/unit/test_opc_adapters.py b/tests/unit/test_opc_adapters.py
new file mode 100644
index 0000000..87caf0c
--- /dev/null
+++ b/tests/unit/test_opc_adapters.py
@@ -0,0 +1,431 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+
+ROOT = Path(__file__).resolve().parents[2]
+PLUGIN_SCRIPTS = ROOT / "plugins" / "codex-opc-team" / "scripts"
+sys.path.insert(0, str(PLUGIN_SCRIPTS))
+
+import opc_adapters  # noqa: E402
+
+
+class FakeHosts:
+    def __init__(
+        self,
+        *,
+        codex_version: str = "codex-cli 0.144.1",
+        claude_version: str = "2.1.212 (Claude Code)",
+        kimi_version: str = "0.29.1",
+        kimi_verify: bool = True,
+        invalid_discovery: set[str] | None = None,
+        invalid_config: set[str] | None = None,
+        fail_apply: set[str] | None = None,
+        fail_verify: set[str] | None = None,
+    ):
+        self.versions = {
+            "codex": codex_version,
+            "claude": claude_version,
+            "kimi": kimi_version,
+        }
+        self.installed = {"codex": False, "claude": False}
+        self.kimi_verify = kimi_verify
+        self.invalid_discovery = invalid_discovery or set()
+        self.invalid_config = invalid_config or set()
+        self.fail_apply = fail_apply or set()
+        self.fail_verify = fail_verify or set()
+        self.calls: list[list[str]] = []
+
+    def __call__(self, command, environment=None):
+        values = [str(item) for item in command]
+        self.calls.append(values)
+        joined = " ".join(values)
+        executable = Path(values[0]).name.lower()
+        if "plugin_admin.py" in joined:
+            host = "codex"
+            if "install" in values and host in self.fail_apply:
+                return opc_adapters.CommandResult(1, "", "injected apply failure")
+            if "uninstall" in values:
+                self.installed[host] = False
+            elif "install" in values:
+                self.installed[host] = True
+            return opc_adapters.CommandResult(0)
+        host = next(
+            (
+                item
+                for item in ("codex", "claude", "kimi")
+                if item in executable
+            ),
+            None,
+        )
+        if host is None:
+            return opc_adapters.CommandResult(127)
+        if "--version" in values:
+            return opc_adapters.CommandResult(0, self.versions[host])
+        if host == "kimi" and "doctor" in values:
+            return opc_adapters.CommandResult(
+                1 if host in self.invalid_config else 0
+            )
+        if host == "codex" and values[-3:] == ["plugin", "list", "--json"]:
+            if host in self.invalid_discovery:
+                return opc_adapters.CommandResult(0, "{broken")
+            installed = (
+                [{"pluginId": "codex-opc-team@opc"}]
+                if self.installed["codex"] and host not in self.fail_verify
+                else []
+            )
+            return opc_adapters.CommandResult(0, json.dumps({"installed": installed}))
+        if host == "claude" and "plugin" in values and "list" in values:
+            if host in self.invalid_discovery:
+                return opc_adapters.CommandResult(0, "{broken")
+            plugins = (
+                [{"id": "codex-opc-team@opc"}]
+                if self.installed["claude"] and host not in self.fail_verify
+                else []
+            )
+            return opc_adapters.CommandResult(0, json.dumps(plugins))
+        if host == "claude" and "plugin" in values:
+            if ("install" in values or "update" in values) and host in self.fail_apply:
+                return opc_adapters.CommandResult(1, "", "injected apply failure")
+            if "uninstall" in values:
+                self.installed["claude"] = False
+            elif "install" in values or "update" in values:
+                self.installed["claude"] = True
+            return opc_adapters.CommandResult(0)
+        if host == "kimi" and "--prompt" in values:
+            if not self.kimi_verify:
+                return opc_adapters.CommandResult(1, "", "No model configured")
+            if host in self.fail_verify:
+                return opc_adapters.CommandResult(0, "")
+            skills = [
+                path.name
+                for path in (ROOT / "plugins" / "codex-opc-team" / "skills").iterdir()
+                if path.is_dir()
+            ]
+            return opc_adapters.CommandResult(0, " ".join(skills))
+        return opc_adapters.CommandResult(0)
+
+
+class AdapterTests(unittest.TestCase):
+    def manager(self, base: Path, fake: FakeHosts) -> opc_adapters.AdapterManager:
+        homes = {}
+        executables = {}
+        for host in opc_adapters.HOST_IDS:
+            home = base / f"{host}-home"
+            home.mkdir()
+            homes[host] = {
+                "HOME": str(home),
+                "USERPROFILE": str(home),
+                "KIMI_CODE_HOME": str(home / "kimi-state"),
+            }
+            executables[host] = str(base / f"{host}.fake")
+        return opc_adapters.AdapterManager(
+            source_root=ROOT,
+            app_state_root=base / "app-state",
+            runner=fake,
+            environments=homes,
+            executables=executables,
+        )
+
+    @staticmethod
+    def apply(
+        manager: opc_adapters.AdapterManager,
+        host: str,
+        operation: str,
+    ) -> dict:
+        plan = manager.create_plan(host, operation)
+        return manager.apply(
+            plan_id=plan["plan_id"],
+            confirmation_token=plan["confirmation_token"],
+        )
+
+    def test_probe_is_read_only_and_reports_host_contract_asymmetry(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts(claude_version="2.1.204 (Claude Code)")
+            manager = self.manager(base, fake)
+            state_root = base / "app-state"
+            inventory = manager.inventory()
+            self.assertFalse(state_root.exists())
+            by_host = {item["host_id"]: item for item in inventory["hosts"]}
+            self.assertEqual(by_host["codex"]["state"], "available")
+            self.assertEqual(by_host["claude"]["state"], "blocked")
+            self.assertEqual(
+                by_host["claude"]["reason"],
+                "HOST_VERSION_INCOMPATIBLE_UNINSTALL_SAFETY",
+            )
+            self.assertEqual(
+                by_host["kimi"]["plugin_management"],
+                "blocked_no_public_noninteractive_cli",
+            )
+
+    def test_each_host_missing_incompatible_and_invalid_contract_is_zero_write(self):
+        cases = (
+            (
+                FakeHosts(codex_version="", claude_version="", kimi_version=""),
+                {"codex": "unavailable", "claude": "unavailable", "kimi": "unavailable"},
+            ),
+            (
+                FakeHosts(
+                    codex_version="0.143.0",
+                    claude_version="2.1.100",
+                    kimi_version="0.28.0",
+                ),
+                {"codex": "blocked", "claude": "blocked", "kimi": "blocked"},
+            ),
+            (
+                FakeHosts(
+                    invalid_discovery={"codex", "claude"},
+                    invalid_config={"kimi"},
+                ),
+                {"codex": "blocked", "claude": "blocked", "kimi": "blocked"},
+            ),
+        )
+        for fake, expected in cases:
+            with self.subTest(expected=expected), tempfile.TemporaryDirectory() as directory:
+                base = Path(directory)
+                manager = self.manager(base, fake)
+                inventory = manager.inventory()
+                actual = {item["host_id"]: item["state"] for item in inventory["hosts"]}
+                self.assertEqual(actual, expected)
+                self.assertFalse((base / "app-state").exists())
+
+    def test_codex_and_claude_apply_and_verify_failures_leave_no_owned_install(self):
+        for host in ("codex", "claude"):
+            with self.subTest(host=host), tempfile.TemporaryDirectory() as directory:
+                base = Path(directory)
+                manager = self.manager(base, FakeHosts(fail_apply={host}))
+                plan = manager.create_plan(host, "install")
+                with self.assertRaisesRegex(opc_adapters.AdapterError, "APPLY_FAILED"):
+                    manager.apply(
+                        plan_id=plan["plan_id"],
+                        confirmation_token=plan["confirmation_token"],
+                    )
+                self.assertIsNone(manager.store.read(host))
+
+            with self.subTest(host=f"{host}-verify"), tempfile.TemporaryDirectory() as directory:
+                base = Path(directory)
+                fake = FakeHosts(fail_verify={host})
+                manager = self.manager(base, fake)
+                plan = manager.create_plan(host, "install")
+                with self.assertRaisesRegex(
+                    opc_adapters.AdapterError, "VERIFY_FAILED_ROLLED_BACK"
+                ):
+                    manager.apply(
+                        plan_id=plan["plan_id"],
+                        confirmation_token=plan["confirmation_token"],
+                    )
+                self.assertIsNone(manager.store.read(host))
+                self.assertFalse(fake.installed[host])
+
+    def test_kimi_verification_failure_rolls_back_new_projection(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            manager = self.manager(base, FakeHosts(fail_verify={"kimi"}))
+            plan = manager.create_plan("kimi", "install")
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError, "VERIFY_FAILED_ROLLED_BACK"
+            ):
+                manager.apply(
+                    plan_id=plan["plan_id"],
+                    confirmation_token=plan["confirmation_token"],
+                )
+            self.assertIsNone(manager.store.read("kimi"))
+            self.assertEqual(
+                list((base / "kimi-home" / "kimi-state" / "skills").iterdir()),
+                [],
+            )
+
+    def test_preview_is_zero_write_and_confirmation_is_one_time(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            plan = manager.create_plan("kimi", "install")
+            self.assertFalse((base / "app-state").exists())
+            self.assertTrue(plan["confirmation_required"])
+            self.assertTrue(all("target" in item for item in plan["changes"]))
+            with self.assertRaisesRegex(opc_adapters.AdapterError, "CONFIRMATION_REQUIRED"):
+                manager.apply(
+                    plan_id=plan["plan_id"],
+                    confirmation_token="wrong",
+                )
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError, "PLAN_NOT_FOUND_OR_USED"
+            ):
+                manager.apply(
+                    plan_id=plan["plan_id"],
+                    confirmation_token=plan["confirmation_token"],
+                )
+
+    def test_kimi_clean_idempotent_uninstall_reinstall_and_rollback(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            installed = self.apply(manager, "kimi", "install")
+            self.assertEqual(installed["state"], "completed")
+            manifest = manager.store.read("kimi")
+            self.assertIsNotNone(manifest)
+            for item in manifest["managed_targets"]:
+                self.assertTrue(
+                    (base / "kimi-home" / "kimi-state" / "skills" / item["name"]).is_dir()
+                )
+
+            no_change = self.apply(manager, "kimi", "update")
+            self.assertEqual(no_change["state"], "no_change")
+
+            removed = self.apply(manager, "kimi", "uninstall")
+            self.assertEqual(removed["state"], "completed")
+            self.assertIsNone(manager.store.read("kimi"))
+            rolled_back = manager.rollback("kimi", removed["rollback_id"])
+            self.assertEqual(rolled_back["state"], "rolled_back")
+            self.assertIsNotNone(manager.store.read("kimi"))
+
+            removed_again = self.apply(manager, "kimi", "uninstall")
+            self.assertEqual(removed_again["state"], "completed")
+            reinstalled = self.apply(manager, "kimi", "install")
+            self.assertEqual(reinstalled["state"], "completed")
+
+    def test_user_modified_target_fails_closed_and_preserves_edit(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            self.apply(manager, "kimi", "install")
+            manifest = manager.store.read("kimi")
+            name = manifest["managed_targets"][0]["name"]
+            target = base / "kimi-home" / "kimi-state" / "skills" / name
+            marker = target / "user-edit.txt"
+            marker.write_text("preserve", encoding="utf-8")
+            plan = manager.create_plan("kimi", "uninstall")
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError, "USER_MODIFIED_CONFLICT"
+            ):
+                manager.apply(
+                    plan_id=plan["plan_id"],
+                    confirmation_token=plan["confirmation_token"],
+                )
+            self.assertEqual(marker.read_text(encoding="utf-8"), "preserve")
+            self.assertIsNotNone(manager.store.read("kimi"))
+
+    def test_unknown_target_symlink_and_corrupt_manifest_fail_closed(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            kimi = manager.adapters["kimi"]
+            target = kimi._target(kimi.skill_names[0])
+            target.mkdir(parents=True)
+            sentinel = target / "sentinel"
+            sentinel.write_text("keep", encoding="utf-8")
+            plan = manager.create_plan("kimi", "install")
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError, "UNKNOWN_TARGET_CONFLICT"
+            ):
+                manager.apply(
+                    plan_id=plan["plan_id"],
+                    confirmation_token=plan["confirmation_token"],
+                )
+            self.assertEqual(sentinel.read_text(encoding="utf-8"), "keep")
+
+            manifest = manager.store.manifest_path("kimi")
+            manifest.parent.mkdir(parents=True, exist_ok=True)
+            manifest.write_text("{broken", encoding="utf-8")
+            with self.assertRaisesRegex(opc_adapters.AdapterError, "INVALID_MANIFEST"):
+                manager.create_plan("kimi", "install")
+
+    def test_verification_required_is_not_reported_as_verified(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            manager = self.manager(base, FakeHosts(kimi_verify=False))
+            result = self.apply(manager, "kimi", "install")
+            self.assertEqual(result["state"], "verification_required")
+            self.assertEqual(result["verification"]["state"], "verification_required")
+
+    def test_codex_reuses_plugin_admin_and_preserves_knowledge_initialization(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            result = self.apply(manager, "codex", "install")
+            self.assertEqual(result["state"], "completed")
+            admin_calls = [call for call in fake.calls if "plugin_admin.py" in " ".join(call)]
+            self.assertEqual(len(admin_calls), 1)
+            self.assertIn("--skip-knowledge-init", admin_calls[0])
+            self.assertIn("--apply", admin_calls[0])
+            self.assertFalse(any("OPC_KNOWLEDGE_HOME" in " ".join(call) for call in fake.calls))
+
+    def test_claude_uses_keep_data_and_isolated_failure_does_not_touch_kimi(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            self.apply(manager, "kimi", "install")
+            sentinel_manifest = manager.store.manifest_path("kimi").read_bytes()
+            self.apply(manager, "claude", "install")
+            self.apply(manager, "claude", "uninstall")
+            uninstall = [
+                call
+                for call in fake.calls
+                if "claude.fake" in call[0] and "uninstall" in call
+            ][0]
+            self.assertIn("--keep-data", uninstall)
+            self.assertEqual(
+                manager.store.manifest_path("kimi").read_bytes(),
+                sentinel_manifest,
+            )
+
+    def test_permission_failure_restores_preexisting_kimi_tree(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            manager = self.manager(base, FakeHosts())
+            self.apply(manager, "kimi", "install")
+            before = {
+                path.relative_to(base).as_posix(): path.read_bytes()
+                for path in base.rglob("*")
+                if path.is_file()
+                and "app-state" not in path.parts
+            }
+            original_replace = os.replace
+            host_skill_root = base / "kimi-home" / "kimi-state" / "skills"
+            calls = 0
+
+            def fail_second_activation(source, destination):
+                nonlocal calls
+                destination = Path(destination)
+                if destination.parent == host_skill_root:
+                    calls += 1
+                    if calls == 2:
+                        raise PermissionError("injected")
+                return original_replace(source, destination)
+
+            # Force a real update rather than the no-change fast path.
+            manifest = manager.store.read("kimi")
+            manifest["content_hash"] = "0" * 64
+            manager.store.write("kimi", manifest)
+            plan = manager.create_plan("kimi", "update")
+            with mock.patch.object(opc_adapters.os, "replace", side_effect=fail_second_activation):
+                with self.assertRaisesRegex(opc_adapters.AdapterError, "APPLY_FAILED"):
+                    manager.apply(
+                        plan_id=plan["plan_id"],
+                        confirmation_token=plan["confirmation_token"],
+                    )
+            after = {
+                path.relative_to(base).as_posix(): path.read_bytes()
+                for path in base.rglob("*")
+                if path.is_file()
+                and "app-state" not in path.parts
+            }
+            self.assertEqual(after, before)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/unit/test_opc_app.py b/tests/unit/test_opc_app.py
index 5f6cf14..0916fee 100644
--- a/tests/unit/test_opc_app.py
+++ b/tests/unit/test_opc_app.py
@@ -64,12 +64,13 @@ def project_fixture(root: Path, project_id: str = "sample-project") -> Path:
 
 
 @contextlib.contextmanager
-def running_server(*, store, demo=False, provider=None):
+def running_server(*, store, demo=False, provider=None, adapter_manager=None):
     server = opc_app.create_app_server(
         host="127.0.0.1",
         port=0,
         snapshot_provider=provider or opc_dashboard.load_demo_snapshot,
         settings_store=store,
+        adapter_manager=adapter_manager,
         demo=demo,
     )
     thread = threading.Thread(target=server.serve_forever, daemon=True)
@@ -293,6 +294,72 @@ def test_shared_service_validates_the_same_snapshot_contract(self):
 
 
 class HTTPTests(unittest.TestCase):
+    def test_adapter_routes_keep_preview_and_apply_separate(self):
+        class FakeManager:
+            def __init__(self):
+                self.applied = False
+
+            def inventory(self):
+                return {
+                    "schema_version": "opc-adapters.api.v1",
+                    "hosts": [{"host_id": "codex", "state": "available"}],
+                }
+
+            def create_plan(self, host_id, operation):
+                return {
+                    "schema_version": "opc-adapters.plan.v1",
+                    "host_id": host_id,
+                    "operation": operation,
+                    "plan_id": "plan-safe",
+                    "confirmation_token": "confirm-safe",
+                    "changes": [{"action": "add", "target": "codex:plugin/opc"}],
+                }
+
+            def apply(self, *, plan_id, confirmation_token):
+                if confirmation_token != "confirm-safe":
+                    raise opc_app.AdapterError("CONFIRMATION_REQUIRED")
+                self.applied = True
+                return {
+                    "schema_version": "opc-adapters.api.v1",
+                    "host_id": "codex",
+                    "state": "completed",
+                }
+
+        with tempfile.TemporaryDirectory() as directory:
+            store = opc_app.AppSettingsStore(Path(directory) / "state")
+            adapters = FakeManager()
+            with running_server(store=store, adapter_manager=adapters) as server:
+                authority = f"http://127.0.0.1:{server.server_address[1]}"
+                _, context, _, _ = request(server, "GET", "/api/app-context")
+                headers = {"Origin": authority, "X-OPC-CSRF": context["csrf_token"]}
+                status, inventory, _, raw = request(server, "GET", "/api/adapters")
+                self.assertEqual(status, 200)
+                self.assertEqual(inventory["hosts"][0]["state"], "available")
+                self.assertNotRegex(raw.decode(), r"[A-Za-z]:[\\/]")
+
+                status, plan, _, _ = request(
+                    server,
+                    "POST",
+                    "/api/adapters/plan",
+                    headers=headers,
+                    payload={"host_id": "codex", "operation": "install"},
+                )
+                self.assertEqual(status, 200)
+                self.assertFalse(adapters.applied)
+                status, error, _, _ = request(
+                    server,
+                    "POST",
+                    "/api/adapters/apply",
+                    headers=headers,
+                    payload={
+                        "plan_id": plan["plan_id"],
+                        "confirmation_token": "wrong",
+                    },
+                )
+                self.assertEqual(status, 409)
+                self.assertEqual(error["error"], "CONFIRMATION_REQUIRED")
+                self.assertFalse(adapters.applied)
+
     def test_context_is_redacted_and_security_boundaries_are_enforced(self):
         store = opc_app.DemoSettingsStore()
         with running_server(store=store, demo=True) as server:
@@ -400,17 +467,18 @@ def test_complete_app_surface_is_local_and_has_distinct_views(self):
         parser.feed((asset_root / "index.html").read_text(encoding="utf-8"))
         self.assertEqual(
             [item["data-nav"] for item in parser.navigation],
-            ["overview", "projects", "runs", "knowledge", "lineage", "health", "settings"],
+            ["overview", "projects", "runs", "knowledge", "lineage", "health", "adapters", "settings"],
         )
         self.assertEqual(
             [item["data-view"] for item in parser.views],
-            ["overview", "projects", "runs", "knowledge", "lineage", "health", "settings"],
+            ["overview", "projects", "runs", "knowledge", "lineage", "health", "adapters", "settings"],
         )
         self.assertEqual(parser.remote_resources, [])
         javascript = (asset_root / "dashboard.js").read_text(encoding="utf-8")
         stylesheet = (asset_root / "dashboard.css").read_text(encoding="utf-8")
         self.assertIn('fetchJSON("/api/app-context")', javascript)
         self.assertIn('fetchJSON("/api/snapshot")', javascript)
+        self.assertIn('fetchJSON("/api/adapters")', javascript)
         self.assertNotIn("innerHTML", javascript)
         self.assertIn(".filterable[hidden]", stylesheet)
         self.assertIn("display: none !important", stylesheet)

From a15b41a0f7c05abf0d386b30cfccb3c2ba008c76 Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 16:18:34 +0800
Subject: [PATCH 05/11] fix(adapters): harden host lifecycle transactions

---
 ...0018-host-adapters-use-public-contracts.md |  18 +-
 docs/host-adapters.md                         |  47 +-
 .../assets/adapters/capability-matrix.v1.json |  10 +-
 .../codex-opc-team/assets/app/dashboard.js    |   6 +
 plugins/codex-opc-team/assets/app/index.html  |   1 +
 .../codex-opc-team/scripts/opc_adapters.py    | 441 +++++++++++++++---
 tests/unit/test_opc_adapters.py               | 429 ++++++++++++++++-
 7 files changed, 855 insertions(+), 97 deletions(-)

diff --git a/docs/adr/0018-host-adapters-use-public-contracts.md b/docs/adr/0018-host-adapters-use-public-contracts.md
index b765173..6af214e 100644
--- a/docs/adr/0018-host-adapters-use-public-contracts.md
+++ b/docs/adr/0018-host-adapters-use-public-contracts.md
@@ -20,9 +20,17 @@ separate:
 - Codex delegates to the existing Marketplace/Plugin lifecycle and
   `plugin_admin.py`.
 - Claude uses its documented non-interactive Marketplace Plugin CLI and
-  preserves plugin data during uninstall.
-- Kimi manages documented user Skill directories. Plugin automation remains
-  blocked while the public Plugin manager is interactive-only.
+  preserves plugin data during uninstall. One stable App-owned marketplace
+  path is registered once; update and rollback atomically change that source
+  and use public marketplace/plugin update commands. Marketplace removal is
+  not an update or rollback primitive.
+- Kimi manages documented user Skill directories and passes their common scan
+  root once to `--skills-dir`. Plugin automation remains blocked while the
+  public Plugin manager is interactive-only.
+
+Preview plans are short-lived, one-time, and process-local. Apply re-captures
+and compares the source, host/version, official discovery, capability contract,
+ownership manifest, and resolved target state before the first write.
 
 File/Git remains authoritative. Adapter manifests and backups are operational,
 rebuildable App state, not organizational memory. A host target may be changed
@@ -33,5 +41,5 @@ still matches. Unknown host versions and unsupported mechanisms fail closed.
 
 The three hosts can expose different support levels without false parity.
 Plans are auditable and writes require explicit confirmation. Real installed
-state still needs independent host-specific QA because clean-room fake CLIs
-cannot prove logged-in discovery or interactive Skill invocation.
+state still needs independent host-specific QA; Developer-run disposable-host
+acceptance is implementation evidence, not release approval.
diff --git a/docs/host-adapters.md b/docs/host-adapters.md
index 63c81aa..a4aace0 100644
--- a/docs/host-adapters.md
+++ b/docs/host-adapters.md
@@ -14,8 +14,13 @@ canonical OPC package
         `-- Kimi   -> documented user Skill directory projection
 ```
 
-Every mutation is `probe -> preview -> explicit confirmation -> apply ->
-fresh-process verification`. The preview is in memory and performs no write.
+Every mutation is `probe -> preview -> explicit confirmation -> re-probe ->
+apply -> fresh-process verification`. The preview is in memory, expires after
+120 seconds, is consumed on its first apply attempt, does not survive an App
+restart, and performs no write. Before any mutation, the App compares a
+constant-time digest over the source version/ref/content, host version and
+official discovery result, capability contract, ownership manifest, and
+resolved target state. Any drift fails with zero writes.
 The ownership manifest is App-private state and contains only adapter/source
 versions, source ref, hashes, logical managed targets, and backup references.
 It never contains knowledge text, credentials, host configuration, or telemetry.
@@ -40,8 +45,8 @@ writes an ownership manifest or host file.
 | Host | Resolution |
 |---|---|
 | Codex | The official Codex CLI resolves its own config and cache. The Adapter passes the canonical marketplace source to the existing lifecycle script. |
-| Claude | The official Claude CLI resolves user-scope plugin state. The Adapter retains a generated, versioned marketplace projection under App-owned state. |
-| Kimi | `$KIMI_CODE_HOME/skills/<skill>` when set, otherwise `~/.kimi-code/skills/<skill>`. Tests always inject a disposable `KIMI_CODE_HOME`. |
+| Claude | The official Claude CLI resolves user-scope plugin state. The Adapter registers one stable App-owned marketplace source and retains immutable version/hash projections for recovery. |
+| Kimi | `$KIMI_CODE_HOME/skills/<skill>` when set, otherwise `~/.kimi-code/skills/<skill>`. Verification passes the common `skills` root once to `--skills-dir` and compares exact canonical Skill identities. Tests always inject a disposable `KIMI_CODE_HOME`. |
 
 The browser API emits logical targets such as `kimi:skill/opc-manager`, not
 absolute user-home paths.
@@ -53,19 +58,32 @@ absolute user-home paths.
   hash. User edits and links are preserved as conflicts.
 - Kimi directory swaps use App-owned staging and backups. A partial swap
   restores already moved targets in reverse order.
-- Claude data is preserved on uninstall. Codex knowledge initialization is
-  explicitly skipped by the Adapter because knowledge lifecycle is independent.
+- Claude update and rollback never remove its marketplace. The stable source
+  is swapped atomically, then refreshed with `plugin marketplace update` and
+  `plugin update`; every command is checked and a failed step restores the
+  previous source and plugin. Uninstall explicitly uses `--keep-data`.
+- Codex knowledge initialization is explicitly skipped by the Adapter because
+  knowledge lifecycle is independent.
 - Uninstall never touches `OPC_KNOWLEDGE_HOME`, project `.opc`, Git history,
   manager preferences/rules/experience, optional Mem0 data, or other hosts.
 - Verification failure is not PASS. The operation attempts rollback and returns
   a structured failure or recovery requirement.
 
-## Manual installed-state QA
+## Installed-state QA
 
-Automated tests prove plan/apply separation, one-time confirmation, fake-home
-isolation, exact logical Diff, ownership/hash conflict behavior, partial-failure
-recovery, and host command construction. They do not prove real logged-in host
-discovery.
+Automated tests prove plan/apply separation, expiry/replay/restart behavior,
+write-time state fingerprints, fake-home isolation, exact logical Diff,
+ownership/hash conflict behavior, Claude intermediate-step recovery, Kimi
+common-root discovery, and host command construction.
+
+On 2026-07-25 the Developer also ran a disposable-home acceptance pass. This is
+implementation evidence, not independent QA:
+
+| Host | Disposable acceptance result |
+|---|---|
+| Codex 0.144.1 | Preview, install, fresh JSON discovery, update no-op, uninstall, reinstall, rollback, and unrelated sentinel preservation passed. |
+| Claude 2.1.212 | The pinned official npm package (`@anthropic-ai/claude-code@2.1.212`, package SHA-256 `2162841dd793d21671eccb7fe76fe9c3da6816adf447ba3890a4871b7e5f4e69`) passed local marketplace install, real update, fresh JSON discovery, uninstall, reinstall, rollback, and config/plugin-data sentinel preservation. The user's installed 2.1.204 was not upgraded or used. |
+| Kimi 0.29.1 | A disposable `KIMI_CODE_HOME` and loopback-only OpenAI-compatible stub passed install, exact seven-Skill request discovery, update no-op, uninstall, reinstall, rollback, and unrelated sentinel preservation. Raw prompts, requests, paths, and session identifiers were not retained. |
 
 Run release QA in disposable host homes:
 
@@ -75,9 +93,10 @@ Run release QA in disposable host homes:
 | Claude | Use Claude Code 2.1.212 or newer, install/update/uninstall, verify with a fresh `claude plugin list --json`, and confirm plugin data remains after uninstall. |
 | Kimi | Configure a disposable model/provider, install the Skill projection, start a fresh `kimi` process, invoke `/skill:opc-manager`, then repeat after update, uninstall, and rollback. |
 
-Record the exact host versions, disposable home roots, command output, and
-reviewer identity outside the public repository. Do not accept implementer
-self-report as independent QA evidence.
+Independent release QA must repeat the relevant gates. Record only
+privacy-safe versions, hashes, results, and reviewer identity; keep disposable
+home paths and raw command/model traffic out of the public repository. Do not
+accept implementer self-report as independent QA evidence.
 
 ## Primary sources
 
diff --git a/plugins/codex-opc-team/assets/adapters/capability-matrix.v1.json b/plugins/codex-opc-team/assets/adapters/capability-matrix.v1.json
index b21337d..6a1761f 100644
--- a/plugins/codex-opc-team/assets/adapters/capability-matrix.v1.json
+++ b/plugins/codex-opc-team/assets/adapters/capability-matrix.v1.json
@@ -26,9 +26,13 @@
     {
       "host_id": "claude",
       "verified_range": ">=2.1.212,<3.0.0",
-      "verified_local_version": "2.1.204",
+      "verified_local_version": "2.1.212",
       "managed_unit": "marketplace_plugin",
-      "local_status": "blocked_known_uninstall_safety_bug",
+      "local_status": "verified_with_pinned_official_npm_package_in_disposable_home",
+      "verification_source": {
+        "package": "@anthropic-ai/claude-code@2.1.212",
+        "sha256": "2162841dd793d21671eccb7fe76fe9c3da6816adf447ba3890a4871b7e5f4e69"
+      },
       "lifecycle": {
         "probe": "supported",
         "install": "supported_when_compatible",
@@ -54,7 +58,7 @@
         "install": "supported",
         "update": "supported",
         "uninstall": "supported",
-        "verify": "fresh_process_prompt_requires_configured_model",
+        "verify": "fresh_process_common_skills_root_exact_identity_prompt_requires_configured_model",
         "plugin_apply": "blocked_no_public_noninteractive_cli"
       },
       "components": {
diff --git a/plugins/codex-opc-team/assets/app/dashboard.js b/plugins/codex-opc-team/assets/app/dashboard.js
index 872857e..9fa9096 100644
--- a/plugins/codex-opc-team/assets/app/dashboard.js
+++ b/plugins/codex-opc-team/assets/app/dashboard.js
@@ -767,6 +767,8 @@
       UNKNOWN_TARGET_CONFLICT: "目标位置已有未知内容；已保留且未覆盖。",
       CONFIRMATION_REQUIRED: "必须重新核对计划并明确确认。",
       PLAN_NOT_FOUND_OR_USED: "计划已过期或已经执行，请重新生成。",
+      PLAN_EXPIRED: "计划已超过有效期且已作废，请重新探测并生成。",
+      PLAN_STATE_CHANGED: "来源、宿主、发现结果、所有权或目标状态已变化；未执行任何写入。",
       VERIFY_FAILED_ROLLED_BACK: "宿主回读验证失败，已尝试恢复操作前状态。",
       APPLY_FAILED: "宿主写入失败；其他 Adapter 和私人知识未被修改。",
     }[String(code || "")] || "操作未完成；请刷新后查看结构化状态。";
@@ -783,6 +785,10 @@
       setText("adapter-plan-version", plan.source_version);
       setText("adapter-plan-ref", plan.source_ref);
       setText("adapter-plan-hash", String(plan.content_hash || "").slice(0, 16));
+      setText(
+        "adapter-plan-expiry",
+        `${Number(plan.expires_in_seconds || 0)} 秒（单次使用）`
+      );
       setText("adapter-plan-rollback", plan.rollback);
       const diff = byId("adapter-plan-diff");
       diff.replaceChildren();
diff --git a/plugins/codex-opc-team/assets/app/index.html b/plugins/codex-opc-team/assets/app/index.html
index b871b7c..532cd06 100644
--- a/plugins/codex-opc-team/assets/app/index.html
+++ b/plugins/codex-opc-team/assets/app/index.html
@@ -235,6 +235,7 @@ <h3>验证预览（只读检查）</h3>
       <div><dt>来源版本</dt><dd id="adapter-plan-version">—</dd></div>
       <div><dt>来源 Ref</dt><dd id="adapter-plan-ref">—</dd></div>
       <div><dt>内容哈希</dt><dd><code id="adapter-plan-hash">—</code></dd></div>
+      <div><dt>计划有效期</dt><dd id="adapter-plan-expiry">—</dd></div>
       <div><dt>回滚点</dt><dd id="adapter-plan-rollback">—</dd></div>
     </dl>
     <div class="adapter-diff" id="adapter-plan-diff"></div>
diff --git a/plugins/codex-opc-team/scripts/opc_adapters.py b/plugins/codex-opc-team/scripts/opc_adapters.py
index b9096e2..2502701 100644
--- a/plugins/codex-opc-team/scripts/opc_adapters.py
+++ b/plugins/codex-opc-team/scripts/opc_adapters.py
@@ -19,6 +19,7 @@
 import sys
 import tempfile
 import threading
+import time
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
@@ -27,7 +28,9 @@
 ADAPTER_API_SCHEMA = "opc-adapters.api.v1"
 ADAPTER_PLAN_SCHEMA = "opc-adapters.plan.v1"
 OWNERSHIP_SCHEMA = "opc-adapters.ownership.v1"
+CAPABILITY_CONTRACT_SCHEMA = "opc-adapters.capability-matrix.v1"
 ADAPTER_VERSION = "1.0.0"
+DEFAULT_PLAN_TTL_SECONDS = 120.0
 HOST_IDS = ("codex", "claude", "kimi")
 PLUGIN_ID = "codex-opc-team"
 MARKETPLACE_ID = "opc"
@@ -65,6 +68,8 @@ def _run_command(
             check=False,
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=45,
             env=dict(environment) if environment is not None else None,
         )
@@ -84,6 +89,14 @@ def _sha256_bytes(value: bytes) -> str:
     return hashlib.sha256(value).hexdigest()
 
 
+def _canonical_digest(value: Any) -> str:
+    return _sha256_bytes(
+        json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode(
+            "utf-8"
+        )
+    )
+
+
 def _is_link(path: Path) -> bool:
     try:
         metadata = path.lstat()
@@ -278,13 +291,16 @@ def __init__(
     def source_version(self) -> str:
         payload = _read_json(self.plugin_root / ".codex-plugin" / "plugin.json")
         value = payload.get("version")
-        if not isinstance(value, str) or not value:
+        if not isinstance(value, str) or VERSION.fullmatch(value) is None:
             raise AdapterError("INVALID_SOURCE")
         return value
 
     @property
     def source_ref(self) -> str:
-        value = os.environ.get("OPC_ADAPTER_SOURCE_REF", "").strip()
+        value = (
+            (self.environment or {}).get("OPC_ADAPTER_SOURCE_REF")
+            or os.environ.get("OPC_ADAPTER_SOURCE_REF", "")
+        ).strip()
         return value if PORTABLE_TOKEN.fullmatch(value) else f"release/{self.source_version}"
 
     @property
@@ -300,6 +316,26 @@ def _command(self, *arguments: str) -> CommandResult:
     def probe(self) -> dict[str, Any]:
         raise NotImplementedError
 
+    def target_fingerprint(self) -> dict[str, Any]:
+        """Return a privacy-safe snapshot of adapter-owned target state."""
+        return {"kind": self.integration_unit}
+
+    def capture_plan_state(self) -> dict[str, Any]:
+        """Capture every immutable input a plan is authorized against."""
+        return {
+            "capability_contract_schema": CAPABILITY_CONTRACT_SCHEMA,
+            "verified_contract": self.verified_contract,
+            "adapter_version": ADAPTER_VERSION,
+            "source": {
+                "version": self.source_version,
+                "ref": self.source_ref,
+                "content_hash": self.content_hash,
+            },
+            "probe": self.probe(),
+            "ownership_manifest": self.store.read(self.host_id),
+            "target": self.target_fingerprint(),
+        }
+
     def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[str, str]]:
         raise NotImplementedError
 
@@ -328,22 +364,28 @@ def _status(self, state: str, **extra: Any) -> dict[str, Any]:
             **extra,
         }
 
-    def plan(self, operation: str) -> dict[str, Any]:
+    def plan(
+        self,
+        operation: str,
+        captured_state: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
         if operation not in {"install", "update", "uninstall"}:
             raise AdapterError("UNSUPPORTED_OPERATION")
-        probe = self.probe()
+        state = dict(captured_state or self.capture_plan_state())
+        probe = state["probe"]
         if probe["state"] not in {"available", "installed", "drifted"}:
             raise AdapterError("HOST_BLOCKED", detail=probe.get("reason"))
-        manifest = self.store.read(self.host_id)
+        manifest = state["ownership_manifest"]
         if operation == "uninstall" and manifest is None:
             raise AdapterError("NOT_OPC_OWNED")
         if probe.get("state") == "drifted" and manifest is None:
             raise AdapterError("OWNERSHIP_CONFLICT")
         changes = self.changes(operation, manifest)
+        source = state["source"]
         no_change = bool(
             operation == "update"
             and manifest
-            and manifest.get("content_hash") == self.content_hash
+            and manifest.get("content_hash") == source["content_hash"]
             and probe.get("state") == "installed"
         )
         return {
@@ -351,9 +393,10 @@ def plan(self, operation: str) -> dict[str, Any]:
             "host_id": self.host_id,
             "operation": operation,
             "adapter_version": ADAPTER_VERSION,
-            "source_version": self.source_version,
-            "source_ref": self.source_ref,
-            "content_hash": self.content_hash,
+            "source_version": source["version"],
+            "source_ref": source["ref"],
+            "content_hash": source["content_hash"],
+            "state_fingerprint": _canonical_digest(state),
             "changes": changes,
             "no_change": no_change,
             "preserves": [
@@ -393,15 +436,17 @@ def probe(self) -> dict[str, Any]:
                 reason="HOST_VERSION_INCOMPATIBLE",
             )
         listed = self._command("plugin", "list", "--json")
+        if listed.returncode != 0:
+            return self._status("blocked", reason="HOST_DISCOVERY_FAILED")
         installed = False
-        if listed.returncode == 0:
-            try:
-                installed = any(
-                    item.get("pluginId") == f"{PLUGIN_ID}@{MARKETPLACE_ID}"
-                    for item in json.loads(listed.stdout).get("installed", [])
-                )
-            except (ValueError, AttributeError):
-                return self._status("blocked", reason="HOST_DISCOVERY_INVALID")
+        try:
+            discovery = json.loads(listed.stdout)
+            installed = any(
+                item.get("pluginId") == f"{PLUGIN_ID}@{MARKETPLACE_ID}"
+                for item in discovery.get("installed", [])
+            )
+        except (ValueError, AttributeError):
+            return self._status("blocked", reason="HOST_DISCOVERY_INVALID")
         manifest = self.store.read(self.host_id)
         state = "installed" if installed and manifest else "available"
         if installed != bool(manifest):
@@ -413,8 +458,26 @@ def probe(self) -> dict[str, Any]:
             target_version=self.source_version,
             drift=state == "drifted",
             ownership=bool(manifest),
+            discovery_fingerprint=_canonical_digest(discovery),
         )
 
+    def target_fingerprint(self) -> dict[str, Any]:
+        projection = (
+            self.store.root
+            / self.host_id
+            / "projection"
+            / f"{self.source_version}-{self.content_hash[:16]}"
+        )
+        return {
+            "projection_exists": projection.is_dir(),
+            "projection_is_link": _is_link(projection),
+            "projection_hash": (
+                tree_digest(projection / "plugins" / PLUGIN_ID / "skills")
+                if projection.is_dir() and not _is_link(projection)
+                else None
+            ),
+        }
+
     def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[str, str]]:
         action = {
             "install": "add",
@@ -576,8 +639,20 @@ class ClaudeAdapter(HostAdapter):
     integration_unit = "Marketplace Plugin"
     verified_contract = "claude-code >=2.1.212,<3.0.0"
 
-    def projection_root(self) -> Path:
-        return self.store.root / self.host_id / "projection" / self.source_version
+    def projection_root(
+        self,
+        source_version: str | None = None,
+        content_hash: str | None = None,
+    ) -> Path:
+        version = source_version or self.source_version
+        digest = content_hash or self.content_hash
+        if not PORTABLE_TOKEN.fullmatch(version) or not re.fullmatch(r"[0-9a-f]{64}", digest):
+            raise AdapterError("INVALID_PROJECTION_REF")
+        return self.store.root / self.host_id / "projection" / f"{version}-{digest[:16]}"
+
+    @property
+    def marketplace_root(self) -> Path:
+        return self.store.root / self.host_id / "marketplace-current"
 
     def probe(self) -> dict[str, Any]:
         result = self._command("--version")
@@ -594,13 +669,13 @@ def probe(self) -> dict[str, Any]:
         if listed.returncode != 0:
             return self._status("blocked", reason="HOST_DISCOVERY_FAILED")
         try:
-            values = json.loads(listed.stdout)
-            entries = values if isinstance(values, list) else values.get("plugins", [])
-            installed = any(
-                str(item.get("id") or item.get("name", "")).startswith(PLUGIN_ID)
-                for item in entries
-                if isinstance(item, dict)
+            discovery = json.loads(listed.stdout)
+            entries = (
+                discovery
+                if isinstance(discovery, list)
+                else discovery.get("plugins", [])
             )
+            installed = self._is_installed(entries)
         except (ValueError, AttributeError):
             return self._status("blocked", reason="HOST_DISCOVERY_INVALID")
         manifest = self.store.read(self.host_id)
@@ -614,8 +689,58 @@ def probe(self) -> dict[str, Any]:
             target_version=self.source_version,
             drift=state == "drifted",
             ownership=bool(manifest),
+            discovery_fingerprint=_canonical_digest(discovery),
+        )
+
+    def target_fingerprint(self) -> dict[str, Any]:
+        root = self.marketplace_root
+        if not root.exists():
+            return {
+                "marketplace_exists": False,
+                "marketplace_is_link": False,
+                "marketplace_hash": None,
+            }
+        if _is_link(root) or not root.is_dir():
+            return {
+                "marketplace_exists": True,
+                "marketplace_is_link": True,
+                "marketplace_hash": None,
+            }
+        skills = root / "plugin" / "skills"
+        return {
+            "marketplace_exists": True,
+            "marketplace_is_link": False,
+            "marketplace_hash": tree_digest(skills) if skills.is_dir() else "invalid",
+        }
+
+    @staticmethod
+    def _is_installed(entries: Sequence[Any]) -> bool:
+        selector = f"{PLUGIN_ID}@{MARKETPLACE_ID}"
+        return any(
+            (
+                item.get("id") == selector
+                or (
+                    item.get("id") is None
+                    and item.get("name") in {PLUGIN_ID, selector}
+                )
+            )
+            for item in entries
+            if isinstance(item, dict)
         )
 
+    def _discover_installed(self) -> bool:
+        result = self._command("plugin", "list", "--json")
+        if result.returncode != 0:
+            raise AdapterError("HOST_DISCOVERY_FAILED")
+        try:
+            payload = json.loads(result.stdout)
+            entries = payload if isinstance(payload, list) else payload.get("plugins", [])
+            if not isinstance(entries, list):
+                raise ValueError
+            return self._is_installed(entries)
+        except (ValueError, AttributeError, TypeError) as exc:
+            raise AdapterError("HOST_DISCOVERY_INVALID") from exc
+
     def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[str, str]]:
         action = {
             "install": "add",
@@ -677,6 +802,74 @@ def _build_projection(self) -> Path:
                 shutil.rmtree(stage, ignore_errors=True)
         return root
 
+    def _activate_marketplace(self, projection: Path, operation_id: str) -> Path | None:
+        """Atomically replace the stable App-owned marketplace source."""
+        root = self.marketplace_root
+        if root.exists() and (_is_link(root) or not root.is_dir()):
+            raise AdapterError("UNSAFE_HOST_TARGET")
+        backup_root = self.store.backup_root(self.host_id, operation_id)
+        previous = backup_root / "marketplace-current"
+        stage = root.parent / f".marketplace-stage-{secrets.token_hex(6)}"
+        moved_previous = False
+        try:
+            root.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copytree(projection, stage)
+            if tree_digest(stage / "plugin" / "skills") != tree_digest(
+                projection / "plugin" / "skills"
+            ):
+                raise AdapterError("PROJECTION_VERIFY_FAILED")
+            if root.exists():
+                backup_root.mkdir(parents=True, exist_ok=True)
+                if previous.exists():
+                    raise AdapterError("BACKUP_CONFLICT")
+                os.replace(root, previous)
+                moved_previous = True
+            os.replace(stage, root)
+        except AdapterError:
+            if moved_previous and previous.exists() and not root.exists():
+                os.replace(previous, root)
+            raise
+        except OSError as exc:
+            if moved_previous and previous.exists() and not root.exists():
+                try:
+                    os.replace(previous, root)
+                except OSError:
+                    pass
+            raise AdapterError("APPLY_FAILED") from exc
+        finally:
+            if stage.exists():
+                shutil.rmtree(stage, ignore_errors=True)
+        return previous if moved_previous else None
+
+    def _restore_marketplace(self, previous: Path | None) -> None:
+        if previous is None:
+            if self.marketplace_root.exists():
+                shutil.rmtree(self.marketplace_root)
+            return
+        if not previous.is_dir() or _is_link(previous):
+            raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
+        if self.marketplace_root.exists():
+            if _is_link(self.marketplace_root):
+                raise AdapterError("ROLLBACK_CONFLICT")
+            shutil.rmtree(self.marketplace_root)
+        os.replace(previous, self.marketplace_root)
+
+    def _refresh_plugin(self, *, failure_code: str) -> None:
+        selector = f"{PLUGIN_ID}@{MARKETPLACE_ID}"
+        marketplace = self._command(
+            "plugin", "marketplace", "update", MARKETPLACE_ID
+        )
+        if marketplace.returncode != 0:
+            raise AdapterError(failure_code)
+        plugin = self._command("plugin", "update", selector, "--scope", "user")
+        if plugin.returncode != 0:
+            raise AdapterError(failure_code)
+
+    def _restore_after_failed_refresh(self, previous: Path | None) -> None:
+        self._restore_marketplace(previous)
+        if previous is not None:
+            self._refresh_plugin(failure_code="ROLLBACK_FAILED")
+
     def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
         selector = f"{PLUGIN_ID}@{MARKETPLACE_ID}"
         if operation == "uninstall":
@@ -684,23 +877,50 @@ def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
             result = self._command(*command)
         else:
             projection = self._build_projection()
-            if operation == "update":
-                self._command("plugin", "marketplace", "remove", MARKETPLACE_ID)
-            marketplace = self._command(
-                "plugin", "marketplace", "add", str(projection)
-            )
-            if marketplace.returncode != 0 and "already" not in (
-                marketplace.stdout + marketplace.stderr
-            ).lower():
-                raise AdapterError("APPLY_FAILED")
-            if operation == "update":
-                self._command("plugin", "marketplace", "update", MARKETPLACE_ID)
-                result = self._command("plugin", "update", selector, "--scope", "user")
-            else:
+            previous = self._activate_marketplace(projection, operation_id)
+            if operation == "install":
+                marketplace = self._command(
+                    "plugin", "marketplace", "add", str(self.marketplace_root)
+                )
+                if marketplace.returncode != 0 and "already" not in (
+                    marketplace.stdout + marketplace.stderr
+                ).lower():
+                    self._restore_marketplace(previous)
+                    raise AdapterError("APPLY_FAILED")
                 result = self._command("plugin", "install", selector, "--scope", "user")
+            else:
+                try:
+                    self._refresh_plugin(failure_code="APPLY_FAILED")
+                except AdapterError as exc:
+                    self._restore_after_failed_refresh(previous)
+                    raise exc
+                result = CommandResult(0)
         if result.returncode != 0:
+            if operation != "uninstall":
+                if operation == "install":
+                    if self._discover_installed():
+                        cleanup = self._command(
+                            "plugin",
+                            "uninstall",
+                            selector,
+                            "--scope",
+                            "user",
+                            "--keep-data",
+                        )
+                        if cleanup.returncode != 0:
+                            raise AdapterError("ROLLBACK_FAILED")
+                    if previous is not None:
+                        self._restore_after_failed_refresh(previous)
+                    # With no previous source, retain the successfully registered
+                    # stable marketplace so its configuration never dangles.
+                else:
+                    self._restore_after_failed_refresh(previous)
             raise AdapterError("APPLY_FAILED")
-        return {"state": "applied", "operation_id": operation_id}
+        return {
+            "state": "applied",
+            "operation_id": operation_id,
+            "backup_ref": operation_id if operation != "uninstall" and previous else None,
+        }
 
     def rollback_operation(
         self,
@@ -714,19 +934,30 @@ def rollback_operation(
                 "plugin", "uninstall", selector, "--scope", "user", "--keep-data"
             )
         else:
-            previous = (
-                self.store.root
-                / self.host_id
-                / "projection"
-                / prior_manifest["source_version"]
+            projection = self.projection_root(
+                prior_manifest["source_version"],
+                prior_manifest["content_hash"],
             )
-            if not previous.is_dir():
+            if not projection.is_dir():
                 raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
-            self._command("plugin", "marketplace", "remove", MARKETPLACE_ID)
-            added = self._command("plugin", "marketplace", "add", str(previous))
-            if added.returncode != 0:
-                raise AdapterError("ROLLBACK_FAILED")
-            result = self._command("plugin", "install", selector, "--scope", "user")
+            rollback_operation_id = f"{operation_id}-restore"
+            current = self._activate_marketplace(projection, rollback_operation_id)
+            try:
+                if operation == "uninstall":
+                    result = self._command(
+                        "plugin", "install", selector, "--scope", "user"
+                    )
+                    if result.returncode != 0:
+                        raise AdapterError("ROLLBACK_FAILED")
+                else:
+                    self._refresh_plugin(failure_code="ROLLBACK_FAILED")
+            except AdapterError:
+                if operation == "uninstall":
+                    self._restore_marketplace(current)
+                else:
+                    self._restore_after_failed_refresh(current)
+                raise
+            result = CommandResult(0)
         if result.returncode != 0:
             raise AdapterError("ROLLBACK_FAILED")
         return {"state": "rolled_back"}
@@ -738,11 +969,7 @@ def verify(self, expected_installed: bool) -> dict[str, Any]:
         try:
             payload = json.loads(result.stdout)
             entries = payload if isinstance(payload, list) else payload.get("plugins", [])
-            installed = any(
-                str(item.get("id") or item.get("name", "")).startswith(PLUGIN_ID)
-                for item in entries
-                if isinstance(item, dict)
-            )
+            installed = self._is_installed(entries)
         except (ValueError, AttributeError):
             return {"state": "failed", "reason": "HOST_DISCOVERY_INVALID"}
         return {
@@ -815,8 +1042,34 @@ def probe(self) -> dict[str, Any]:
             drift=drift,
             ownership=bool(manifest),
             plugin_management="blocked_no_public_noninteractive_cli",
+            discovery_fingerprint=_canonical_digest(
+                {
+                    "doctor_returncode": doctor.returncode,
+                    "doctor_stdout_hash": _sha256_bytes(doctor.stdout.encode("utf-8")),
+                    "doctor_stderr_hash": _sha256_bytes(doctor.stderr.encode("utf-8")),
+                }
+            ),
         )
 
+    def target_fingerprint(self) -> dict[str, Any]:
+        targets: list[dict[str, Any]] = []
+        for name in self.skill_names:
+            target = self._target(name)
+            is_link = _is_link(target)
+            targets.append(
+                {
+                    "name": name,
+                    "exists": target.exists(),
+                    "is_link": is_link,
+                    "hash": (
+                        tree_digest(target)
+                        if target.is_dir() and not is_link
+                        else None
+                    ),
+                }
+            )
+        return {"skills_root": targets}
+
     def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[str, str]]:
         action = {
             "install": "add",
@@ -933,10 +1186,18 @@ def verify(self, expected_installed: bool) -> dict[str, Any]:
         # Kimi has no public non-interactive skill-list command.  A fresh prompt
         # is the public discovery mechanism; it may require the user's configured
         # model and therefore can be inconclusive without becoming a false PASS.
-        command = ["--output-format", "stream-json"]
-        for name in self.skill_names:
-            command.extend(["--skills-dir", str(self._target(name))])
-        command.extend(["--prompt", "List the explicitly available OPC skills by name only."])
+        expected = sorted(self.skill_names)
+        command = [
+            "--output-format",
+            "stream-json",
+            "--skills-dir",
+            str(self.host_home / "skills"),
+            "--prompt",
+            (
+                "Inspect the Skills available for this launch. Output one line only as "
+                "OPC_SKILLS_JSON followed by a JSON array of their exact canonical names."
+            ),
+        ]
         result = self._command(*command)
         if not expected_installed:
             absent = all(not self._target(name).exists() for name in self.skill_names)
@@ -950,10 +1211,39 @@ def verify(self, expected_installed: bool) -> dict[str, Any]:
                 "reason": "KIMI_FRESH_PROCESS_REQUIRES_CONFIGURED_MODEL",
                 "mechanism": "fresh kimi --skills-dir prompt",
             }
-        discovered = all(name in result.stdout for name in self.skill_names)
+        assistant_text: list[str] = []
+        try:
+            for line in result.stdout.splitlines():
+                payload = json.loads(line)
+                if not isinstance(payload, dict):
+                    continue
+                role = payload.get("role")
+                message = payload.get("message")
+                if isinstance(message, dict):
+                    role = message.get("role", role)
+                    content = message.get("content")
+                else:
+                    content = payload.get("content")
+                if role not in {None, "assistant"}:
+                    continue
+                if isinstance(content, str):
+                    assistant_text.append(content)
+                elif isinstance(content, list):
+                    assistant_text.extend(
+                        str(item.get("text"))
+                        for item in content
+                        if isinstance(item, dict) and isinstance(item.get("text"), str)
+                    )
+            marker = re.search(
+                r"OPC_SKILLS_JSON\s*(\[[^\r\n]*\])",
+                "\n".join(assistant_text),
+            )
+            discovered = json.loads(marker.group(1)) if marker else None
+        except (ValueError, AttributeError, TypeError):
+            discovered = None
         return {
-            "state": "verified" if discovered else "failed",
-            "mechanism": "fresh kimi --skills-dir prompt",
+            "state": "verified" if discovered == expected else "failed",
+            "mechanism": "fresh kimi --skills-dir common-root prompt with exact identities",
         }
 
     def rollback_operation(
@@ -1011,11 +1301,17 @@ def __init__(
         runner: CommandRunner = _run_command,
         environments: Mapping[str, Mapping[str, str]] | None = None,
         executables: Mapping[str, str] | None = None,
+        clock: Callable[[], float] = time.monotonic,
+        plan_ttl_seconds: float = DEFAULT_PLAN_TTL_SECONDS,
     ):
+        if plan_ttl_seconds <= 0:
+            raise ValueError("plan_ttl_seconds must be positive")
         self.source_root = Path(source_root).resolve()
         self.store = OwnershipStore(app_state_root)
         self._lock = threading.RLock()
         self._plans: dict[str, dict[str, Any]] = {}
+        self._clock = clock
+        self._plan_ttl_seconds = float(plan_ttl_seconds)
         if adapters is not None:
             self.adapters = dict(adapters)
         else:
@@ -1055,18 +1351,27 @@ def create_plan(self, host_id: str, operation: str) -> dict[str, Any]:
         adapter = self.adapters.get(host_id)
         if adapter is None:
             raise AdapterError("UNKNOWN_HOST")
-        payload = adapter.plan(operation)
+        captured_state = adapter.capture_plan_state()
+        payload = adapter.plan(operation, captured_state)
         serialized = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
         plan_id = f"plan-{secrets.token_hex(12)}"
         confirmation = secrets.token_urlsafe(24)
+        issued_at = self._clock()
         record = {
             "payload": payload,
             "digest": _sha256_bytes(serialized),
             "confirmation": confirmation,
+            "state_digest": _canonical_digest(captured_state),
+            "expires_at": issued_at + self._plan_ttl_seconds,
         }
         with self._lock:
             self._plans[plan_id] = record
-        return {**payload, "plan_id": plan_id, "confirmation_token": confirmation}
+        return {
+            **payload,
+            "plan_id": plan_id,
+            "confirmation_token": confirmation,
+            "expires_in_seconds": self._plan_ttl_seconds,
+        }
 
     def apply(
         self,
@@ -1080,6 +1385,8 @@ def apply(
             raise AdapterError("PLAN_NOT_FOUND_OR_USED")
         if not secrets.compare_digest(record["confirmation"], confirmation_token):
             raise AdapterError("CONFIRMATION_REQUIRED")
+        if self._clock() >= record["expires_at"]:
+            raise AdapterError("PLAN_EXPIRED")
         payload = record["payload"]
         current_digest = _sha256_bytes(
             json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
@@ -1087,9 +1394,9 @@ def apply(
         if not secrets.compare_digest(record["digest"], current_digest):
             raise AdapterError("PLAN_CHANGED")
         adapter = self.adapters[payload["host_id"]]
-        current_probe = adapter.probe()
-        if current_probe["state"] not in {"available", "installed", "drifted"}:
-            raise AdapterError("HOST_CHANGED_OR_BLOCKED")
+        current_state_digest = _canonical_digest(adapter.capture_plan_state())
+        if not secrets.compare_digest(record["state_digest"], current_state_digest):
+            raise AdapterError("PLAN_STATE_CHANGED")
         prior_manifest = self.store.read(adapter.host_id)
         operation_id = f"op-{secrets.token_hex(10)}"
         try:
diff --git a/tests/unit/test_opc_adapters.py b/tests/unit/test_opc_adapters.py
index 87caf0c..6e3be13 100644
--- a/tests/unit/test_opc_adapters.py
+++ b/tests/unit/test_opc_adapters.py
@@ -41,6 +41,11 @@ def __init__(
         self.invalid_config = invalid_config or set()
         self.fail_apply = fail_apply or set()
         self.fail_verify = fail_verify or set()
+        self.discovery_nonce = {host: "initial" for host in opc_adapters.HOST_IDS}
+        self.fail_next_claude_step: str | None = None
+        self.partial_claude_failure = False
+        self.claude_marketplaces = {"unrelated-marketplace"}
+        self.claude_plugin_data = {"sentinel": "preserved"}
         self.calls: list[list[str]] = []
 
     def __call__(self, command, environment=None):
@@ -71,7 +76,8 @@ def __call__(self, command, environment=None):
             return opc_adapters.CommandResult(0, self.versions[host])
         if host == "kimi" and "doctor" in values:
             return opc_adapters.CommandResult(
-                1 if host in self.invalid_config else 0
+                1 if host in self.invalid_config else 0,
+                self.discovery_nonce[host],
             )
         if host == "codex" and values[-3:] == ["plugin", "list", "--json"]:
             if host in self.invalid_discovery:
@@ -81,7 +87,15 @@ def __call__(self, command, environment=None):
                 if self.installed["codex"] and host not in self.fail_verify
                 else []
             )
-            return opc_adapters.CommandResult(0, json.dumps({"installed": installed}))
+            return opc_adapters.CommandResult(
+                0,
+                json.dumps(
+                    {
+                        "installed": installed,
+                        "discoveryNonce": self.discovery_nonce[host],
+                    }
+                ),
+            )
         if host == "claude" and "plugin" in values and "list" in values:
             if host in self.invalid_discovery:
                 return opc_adapters.CommandResult(0, "{broken")
@@ -90,13 +104,39 @@ def __call__(self, command, environment=None):
                 if self.installed["claude"] and host not in self.fail_verify
                 else []
             )
-            return opc_adapters.CommandResult(0, json.dumps(plugins))
+            return opc_adapters.CommandResult(
+                0,
+                json.dumps(
+                    {
+                        "plugins": plugins,
+                        "discoveryNonce": self.discovery_nonce[host],
+                    }
+                ),
+            )
         if host == "claude" and "plugin" in values:
+            step = None
+            if values[1:4] == ["plugin", "marketplace", "add"]:
+                step = "marketplace_add"
+            elif values[1:4] == ["plugin", "marketplace", "update"]:
+                step = "marketplace_update"
+            elif values[1:3] == ["plugin", "install"]:
+                step = "plugin_install"
+            elif values[1:3] == ["plugin", "update"]:
+                step = "plugin_update"
+            elif values[1:3] == ["plugin", "uninstall"]:
+                step = "plugin_uninstall"
+            if step == self.fail_next_claude_step:
+                self.fail_next_claude_step = None
+                if self.partial_claude_failure and step == "plugin_install":
+                    self.installed["claude"] = True
+                return opc_adapters.CommandResult(1, "", f"injected {step} failure")
             if ("install" in values or "update" in values) and host in self.fail_apply:
                 return opc_adapters.CommandResult(1, "", "injected apply failure")
-            if "uninstall" in values:
+            if step == "marketplace_add":
+                self.claude_marketplaces.add("opc")
+            if step == "plugin_uninstall":
                 self.installed["claude"] = False
-            elif "install" in values or "update" in values:
+            elif step in {"plugin_install", "plugin_update"}:
                 self.installed["claude"] = True
             return opc_adapters.CommandResult(0)
         if host == "kimi" and "--prompt" in values:
@@ -109,17 +149,30 @@ def __call__(self, command, environment=None):
                 for path in (ROOT / "plugins" / "codex-opc-team" / "skills").iterdir()
                 if path.is_dir()
             ]
-            return opc_adapters.CommandResult(0, " ".join(skills))
+            return opc_adapters.CommandResult(
+                0,
+                json.dumps(
+                    {
+                        "role": "assistant",
+                        "content": f"OPC_SKILLS_JSON {json.dumps(sorted(skills))}",
+                    }
+                ),
+            )
         return opc_adapters.CommandResult(0)
 
 
 class AdapterTests(unittest.TestCase):
-    def manager(self, base: Path, fake: FakeHosts) -> opc_adapters.AdapterManager:
+    def manager(
+        self,
+        base: Path,
+        fake: FakeHosts,
+        **manager_options,
+    ) -> opc_adapters.AdapterManager:
         homes = {}
         executables = {}
         for host in opc_adapters.HOST_IDS:
             home = base / f"{host}-home"
-            home.mkdir()
+            home.mkdir(exist_ok=True)
             homes[host] = {
                 "HOME": str(home),
                 "USERPROFILE": str(home),
@@ -132,6 +185,7 @@ def manager(self, base: Path, fake: FakeHosts) -> opc_adapters.AdapterManager:
             runner=fake,
             environments=homes,
             executables=executables,
+            **manager_options,
         )
 
     @staticmethod
@@ -265,6 +319,152 @@ def test_preview_is_zero_write_and_confirmation_is_one_time(self):
                     confirmation_token=plan["confirmation_token"],
                 )
 
+    def test_plans_expire_are_one_time_and_do_not_survive_restart(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            now = [100.0]
+            manager = self.manager(
+                base,
+                fake,
+                clock=lambda: now[0],
+                plan_ttl_seconds=5,
+            )
+            expired = manager.create_plan("codex", "install")
+            now[0] = 106.0
+            with self.assertRaisesRegex(opc_adapters.AdapterError, "PLAN_EXPIRED"):
+                manager.apply(
+                    plan_id=expired["plan_id"],
+                    confirmation_token=expired["confirmation_token"],
+                )
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError, "PLAN_NOT_FOUND_OR_USED"
+            ):
+                manager.apply(
+                    plan_id=expired["plan_id"],
+                    confirmation_token=expired["confirmation_token"],
+                )
+
+            restart_plan = manager.create_plan("claude", "install")
+            restarted = self.manager(base, fake)
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError, "PLAN_NOT_FOUND_OR_USED"
+            ):
+                restarted.apply(
+                    plan_id=restart_plan["plan_id"],
+                    confirmation_token=restart_plan["confirmation_token"],
+                )
+            self.assertFalse((base / "app-state").exists())
+
+    def test_every_host_rejects_host_version_and_discovery_drift_before_write(self):
+        for host in opc_adapters.HOST_IDS:
+            with self.subTest(host=f"{host}-version"), tempfile.TemporaryDirectory() as directory:
+                base = Path(directory)
+                fake = FakeHosts()
+                manager = self.manager(base, fake)
+                plan = manager.create_plan(host, "install")
+                fake.versions[host] = {
+                    "codex": "codex-cli 0.144.2",
+                    "claude": "2.1.213 (Claude Code)",
+                    "kimi": "0.29.2",
+                }[host]
+                with self.assertRaisesRegex(
+                    opc_adapters.AdapterError, "PLAN_STATE_CHANGED"
+                ):
+                    manager.apply(
+                        plan_id=plan["plan_id"],
+                        confirmation_token=plan["confirmation_token"],
+                    )
+                self.assertFalse((base / "app-state").exists())
+
+            with self.subTest(host=f"{host}-discovery"), tempfile.TemporaryDirectory() as directory:
+                base = Path(directory)
+                fake = FakeHosts()
+                manager = self.manager(base, fake)
+                plan = manager.create_plan(host, "install")
+                fake.discovery_nonce[host] = "changed"
+                with self.assertRaisesRegex(
+                    opc_adapters.AdapterError, "PLAN_STATE_CHANGED"
+                ):
+                    manager.apply(
+                        plan_id=plan["plan_id"],
+                        confirmation_token=plan["confirmation_token"],
+                    )
+                self.assertFalse((base / "app-state").exists())
+
+    def test_every_host_rejects_manifest_source_or_target_drift_before_write(self):
+        for host in opc_adapters.HOST_IDS:
+            with self.subTest(host=f"{host}-manifest"), tempfile.TemporaryDirectory() as directory:
+                base = Path(directory)
+                fake = FakeHosts()
+                manager = self.manager(base, fake)
+                plan = manager.create_plan(host, "install")
+                manifest_path = manager.store.manifest_path(host)
+                manifest_path.parent.mkdir(parents=True, exist_ok=True)
+                opc_adapters._atomic_json(
+                    manifest_path,
+                    {
+                        "schema_version": opc_adapters.OWNERSHIP_SCHEMA,
+                        "host_id": host,
+                        "adapter_version": opc_adapters.ADAPTER_VERSION,
+                        "source_version": "0.0.0",
+                        "source_ref": "release/0.0.0",
+                        "content_hash": "0" * 64,
+                        "managed_targets": [],
+                        "backup_refs": [],
+                    },
+                )
+                with self.assertRaisesRegex(
+                    opc_adapters.AdapterError, "PLAN_STATE_CHANGED"
+                ):
+                    manager.apply(
+                        plan_id=plan["plan_id"],
+                        confirmation_token=plan["confirmation_token"],
+                    )
+                self.assertFalse(fake.installed.get(host, False))
+
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            plan = manager.create_plan("kimi", "install")
+            target = manager.adapters["kimi"]._target(
+                manager.adapters["kimi"].skill_names[0]
+            )
+            target.mkdir(parents=True)
+            (target / "user-sentinel").write_text("keep", encoding="utf-8")
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError, "PLAN_STATE_CHANGED"
+            ):
+                manager.apply(
+                    plan_id=plan["plan_id"],
+                    confirmation_token=plan["confirmation_token"],
+                )
+            self.assertEqual((target / "user-sentinel").read_text(), "keep")
+
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            adapter = manager.adapters["claude"]
+            plan = manager.create_plan("claude", "install")
+            original_hash = type(adapter).content_hash
+            with mock.patch.object(
+                type(adapter),
+                "content_hash",
+                new_callable=mock.PropertyMock,
+                return_value="f" * 64,
+            ):
+                with self.assertRaisesRegex(
+                    opc_adapters.AdapterError, "PLAN_STATE_CHANGED"
+                ):
+                    manager.apply(
+                        plan_id=plan["plan_id"],
+                        confirmation_token=plan["confirmation_token"],
+                    )
+            self.assertIsNotNone(original_hash)
+            self.assertFalse(fake.installed["claude"])
+
     def test_kimi_clean_idempotent_uninstall_reinstall_and_rollback(self):
         with tempfile.TemporaryDirectory() as directory:
             base = Path(directory)
@@ -350,6 +550,28 @@ def test_verification_required_is_not_reported_as_verified(self):
             self.assertEqual(result["state"], "verification_required")
             self.assertEqual(result["verification"]["state"], "verification_required")
 
+    def test_kimi_verification_uses_one_common_root_and_exact_skill_identities(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            self.apply(manager, "kimi", "install")
+            prompt_call = next(
+                call
+                for call in fake.calls
+                if "kimi.fake" in call[0] and "--prompt" in call
+            )
+            self.assertEqual(prompt_call.count("--skills-dir"), 1)
+            index = prompt_call.index("--skills-dir")
+            self.assertEqual(
+                Path(prompt_call[index + 1]),
+                base / "kimi-home" / "kimi-state" / "skills",
+            )
+
+            fake.fail_verify.add("kimi")
+            verification = manager.adapters["kimi"].verify(True)
+            self.assertEqual(verification["state"], "failed")
+
     def test_codex_reuses_plugin_admin_and_preserves_knowledge_initialization(self):
         with tempfile.TemporaryDirectory() as directory:
             base = Path(directory)
@@ -383,6 +605,197 @@ def test_claude_uses_keep_data_and_isolated_failure_does_not_touch_kimi(self):
                 sentinel_manifest,
             )
 
+    def test_claude_install_failure_steps_preserve_data_and_unrelated_marketplace(self):
+        for step in ("marketplace_add", "plugin_install"):
+            with self.subTest(step=step), tempfile.TemporaryDirectory() as directory:
+                base = Path(directory)
+                fake = FakeHosts()
+                manager = self.manager(base, fake)
+                fake.fail_next_claude_step = step
+                fake.partial_claude_failure = step == "plugin_install"
+                data_before = dict(fake.claude_plugin_data)
+                plan = manager.create_plan("claude", "install")
+                with self.assertRaisesRegex(opc_adapters.AdapterError, "APPLY_FAILED"):
+                    manager.apply(
+                        plan_id=plan["plan_id"],
+                        confirmation_token=plan["confirmation_token"],
+                    )
+                self.assertIsNone(manager.store.read("claude"))
+                self.assertEqual(
+                    manager.adapters["claude"].marketplace_root.exists(),
+                    step == "plugin_install",
+                )
+                self.assertFalse(fake.installed["claude"])
+                self.assertEqual(fake.claude_plugin_data, data_before)
+                self.assertIn("unrelated-marketplace", fake.claude_marketplaces)
+                self.assertFalse(
+                    any(
+                        call[1:4] == ["plugin", "marketplace", "remove"]
+                        for call in fake.calls
+                    )
+                )
+
+    def test_claude_partial_install_cleanup_failure_is_explicit_and_recoverable(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            fake.partial_claude_failure = True
+            fake.fail_next_claude_step = "plugin_install"
+            original_call = fake.__call__
+            cleanup_failed = False
+
+            def fail_cleanup(command, environment=None):
+                nonlocal cleanup_failed
+                values = [str(item) for item in command]
+                if (
+                    fake.installed["claude"]
+                    and values[1:3] == ["plugin", "uninstall"]
+                    and not cleanup_failed
+                ):
+                    cleanup_failed = True
+                    fake.calls.append(values)
+                    return opc_adapters.CommandResult(1, "", "injected cleanup failure")
+                return original_call(command, environment)
+
+            manager.adapters["claude"].runner = fail_cleanup
+            plan = manager.create_plan("claude", "install")
+            with self.assertRaisesRegex(opc_adapters.AdapterError, "ROLLBACK_FAILED"):
+                manager.apply(
+                    plan_id=plan["plan_id"],
+                    confirmation_token=plan["confirmation_token"],
+                )
+            self.assertIsNone(manager.store.read("claude"))
+            self.assertTrue(manager.adapters["claude"].marketplace_root.is_dir())
+            self.assertTrue(fake.installed["claude"])
+            self.assertEqual(fake.claude_plugin_data["sentinel"], "preserved")
+            self.assertIn("unrelated-marketplace", fake.claude_marketplaces)
+            self.assertTrue(cleanup_failed)
+
+    def test_claude_uninstall_rollback_install_failure_preserves_absent_prestate(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            fake = FakeHosts()
+            manager = self.manager(base, fake)
+            self.apply(manager, "claude", "install")
+            removed = self.apply(manager, "claude", "uninstall")
+            source_before = opc_adapters.tree_digest(
+                manager.adapters["claude"].marketplace_root
+            )
+            fake.fail_next_claude_step = "plugin_install"
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError, "ROLLBACK_FAILED"
+            ):
+                manager.rollback("claude", removed["rollback_id"])
+            self.assertFalse(fake.installed["claude"])
+            self.assertIsNone(manager.store.read("claude"))
+            self.assertEqual(
+                opc_adapters.tree_digest(manager.adapters["claude"].marketplace_root),
+                source_before,
+            )
+            self.assertEqual(fake.claude_plugin_data["sentinel"], "preserved")
+
+    def test_claude_update_failure_steps_restore_old_working_source_and_manifest(self):
+        for step in ("marketplace_update", "plugin_update"):
+            with self.subTest(step=step), tempfile.TemporaryDirectory() as directory:
+                base = Path(directory)
+                fake = FakeHosts()
+                manager = self.manager(base, fake)
+                self.apply(manager, "claude", "install")
+                adapter = manager.adapters["claude"]
+                manifest_before = manager.store.manifest_path("claude").read_bytes()
+                source_before = opc_adapters.tree_digest(adapter.marketplace_root)
+                data_before = dict(fake.claude_plugin_data)
+                fake.fail_next_claude_step = step
+                with (
+                    mock.patch.object(
+                        opc_adapters.HostAdapter,
+                        "source_version",
+                        new_callable=mock.PropertyMock,
+                        return_value="9.9.9",
+                    ),
+                    mock.patch.object(
+                        opc_adapters.HostAdapter,
+                        "content_hash",
+                        new_callable=mock.PropertyMock,
+                        return_value="f" * 64,
+                    ),
+                ):
+                    plan = manager.create_plan("claude", "update")
+                    with self.assertRaisesRegex(
+                        opc_adapters.AdapterError, "APPLY_FAILED"
+                    ):
+                        manager.apply(
+                            plan_id=plan["plan_id"],
+                            confirmation_token=plan["confirmation_token"],
+                        )
+                self.assertTrue(fake.installed["claude"])
+                self.assertEqual(
+                    opc_adapters.tree_digest(adapter.marketplace_root),
+                    source_before,
+                )
+                self.assertEqual(
+                    manager.store.manifest_path("claude").read_bytes(),
+                    manifest_before,
+                )
+                self.assertEqual(fake.claude_plugin_data, data_before)
+                self.assertIn("unrelated-marketplace", fake.claude_marketplaces)
+                self.assertFalse(
+                    any(
+                        call[1:4] == ["plugin", "marketplace", "remove"]
+                        for call in fake.calls
+                    )
+                )
+
+    def test_claude_rollback_failure_steps_restore_current_working_source(self):
+        for step in ("marketplace_update", "plugin_update"):
+            with self.subTest(step=step), tempfile.TemporaryDirectory() as directory:
+                base = Path(directory)
+                fake = FakeHosts()
+                manager = self.manager(base, fake)
+                self.apply(manager, "claude", "install")
+                with (
+                    mock.patch.object(
+                        opc_adapters.HostAdapter,
+                        "source_version",
+                        new_callable=mock.PropertyMock,
+                        return_value="9.9.9",
+                    ),
+                    mock.patch.object(
+                        opc_adapters.HostAdapter,
+                        "content_hash",
+                        new_callable=mock.PropertyMock,
+                        return_value="f" * 64,
+                    ),
+                ):
+                    updated = self.apply(manager, "claude", "update")
+                current_manifest = manager.store.manifest_path("claude").read_bytes()
+                current_source = opc_adapters.tree_digest(
+                    manager.adapters["claude"].marketplace_root
+                )
+                fake.fail_next_claude_step = step
+                with self.assertRaisesRegex(
+                    opc_adapters.AdapterError, "ROLLBACK_FAILED"
+                ):
+                    manager.rollback("claude", updated["rollback_id"])
+                self.assertEqual(
+                    opc_adapters.tree_digest(manager.adapters["claude"].marketplace_root),
+                    current_source,
+                )
+                self.assertEqual(
+                    manager.store.manifest_path("claude").read_bytes(),
+                    current_manifest,
+                )
+                self.assertTrue(fake.installed["claude"])
+                self.assertEqual(fake.claude_plugin_data["sentinel"], "preserved")
+                self.assertIn("unrelated-marketplace", fake.claude_marketplaces)
+                self.assertFalse(
+                    any(
+                        call[1:4] == ["plugin", "marketplace", "remove"]
+                        for call in fake.calls
+                    )
+                )
+
     def test_permission_failure_restores_preexisting_kimi_tree(self):
         with tempfile.TemporaryDirectory() as directory:
             base = Path(directory)

From 51541be8505dd299a0ee8b243b6e2b9d79144593 Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 17:03:54 +0800
Subject: [PATCH 06/11] test: stabilize disposable git cleanup

---
 docs/host-adapters.md            | 158 +++++++++++++++++++++++++++++++
 tests/unit/test_opc_evolution.py |  34 +++++++
 2 files changed, 192 insertions(+)

diff --git a/docs/host-adapters.md b/docs/host-adapters.md
index a4aace0..001a541 100644
--- a/docs/host-adapters.md
+++ b/docs/host-adapters.md
@@ -93,6 +93,164 @@ Run release QA in disposable host homes:
 | Claude | Use Claude Code 2.1.212 or newer, install/update/uninstall, verify with a fresh `claude plugin list --json`, and confirm plugin data remains after uninstall. |
 | Kimi | Configure a disposable model/provider, install the Skill projection, start a fresh `kimi` process, invoke `/skill:opc-manager`, then repeat after update, uninstall, and rollback. |
 
+### Reproducible reviewer command recipe
+
+The repository does not claim a cross-host CI installed-state PASS: Codex,
+Claude, and Kimi have different distribution and model/account prerequisites.
+The following PowerShell recipe is the reproducible acceptance harness for an
+independent reviewer. Run it only inside a disposable OS/container account,
+from the repository root, with compatible `codex`, `claude`, and `kimi`
+executables already on `PATH`. Kimi must have a disposable provider/model
+configuration; `verification_required` is not PASS.
+
+The first block creates isolated homes and starts the real App in a background
+job. It does not print credentials, plans, paths, prompts, or host output:
+
+```powershell
+$repo = (Resolve-Path '.').Path
+$qaRoot = Join-Path ([IO.Path]::GetTempPath()) (
+  'opc-adapter-review-' + [guid]::NewGuid().ToString('N')
+)
+$roots = @(
+  'home', 'codex', 'claude', 'kimi', 'app-state', 'knowledge', 'data'
+)
+foreach ($name in $roots) {
+  New-Item -ItemType Directory -Force -Path (Join-Path $qaRoot $name) | Out-Null
+}
+
+$env:HOME = Join-Path $qaRoot 'home'
+$env:USERPROFILE = $env:HOME
+$env:CODEX_HOME = Join-Path $qaRoot 'codex'
+$env:CLAUDE_CONFIG_DIR = Join-Path $qaRoot 'claude'
+$env:KIMI_CODE_HOME = Join-Path $qaRoot 'kimi'
+
+$sentinels = @(
+  (Join-Path $env:CODEX_HOME 'reviewer-sentinel.txt'),
+  (Join-Path $env:CLAUDE_CONFIG_DIR 'reviewer-sentinel.txt'),
+  (Join-Path $env:KIMI_CODE_HOME 'reviewer-sentinel.txt')
+)
+foreach ($path in $sentinels) {
+  [IO.File]::WriteAllText($path, 'must survive adapter lifecycle')
+}
+$before = @{}
+foreach ($path in $sentinels) {
+  $before[$path] = (Get-FileHash -Algorithm SHA256 $path).Hash
+}
+
+$appJob = Start-Job -ScriptBlock {
+  param($repo, $qaRoot)
+  Set-Location $repo
+  python plugins/codex-opc-team/scripts/opc_app.py `
+    --state-root (Join-Path $qaRoot 'app-state') `
+    --knowledge-root (Join-Path $qaRoot 'knowledge') `
+    --data-root (Join-Path $qaRoot 'data') `
+    --host 127.0.0.1 --port 8570 --no-open
+} -ArgumentList $repo, $qaRoot
+
+$base = 'http://127.0.0.1:8570'
+$ready = $false
+foreach ($attempt in 1..50) {
+  try {
+    $null = Invoke-RestMethod "$base/api/adapters"
+    $ready = $true
+    break
+  } catch {
+    Start-Sleep -Milliseconds 100
+  }
+}
+if (-not $ready) { throw 'OPC App did not become ready' }
+```
+
+The second block exercises preview/apply, fresh-process verification, uninstall,
+reinstall, and rollback for every host. It deliberately records only
+privacy-safe state labels:
+
+```powershell
+function Invoke-AdapterMutation([string]$hostId, [string]$operation) {
+  $planBody = @{ host_id = $hostId; operation = $operation } |
+    ConvertTo-Json -Compress
+  $plan = Invoke-RestMethod -Method Post `
+    -Uri "$base/api/adapters/plan" -ContentType 'application/json' `
+    -Body $planBody
+  $applyBody = @{
+    plan_id = $plan.plan_id
+    confirmation_token = $plan.confirmation_token
+  } | ConvertTo-Json -Compress
+  $result = Invoke-RestMethod -Method Post `
+    -Uri "$base/api/adapters/apply" -ContentType 'application/json' `
+    -Body $applyBody
+  [pscustomobject]@{
+    host = $hostId
+    operation = $operation
+    state = $result.state
+    verification = $result.verification.state
+    rollback_id = $result.rollback_id
+  }
+}
+
+$safeResults = @()
+try {
+  $inventory = Invoke-RestMethod "$base/api/adapters"
+  $inventory.hosts |
+    Select-Object host_id, host_version, state, reason
+  if ($inventory.hosts.Where({ $_.state -ne 'available' }).Count -ne 0) {
+    throw 'all hosts must be compatible, discoverable, and initially absent'
+  }
+
+  foreach ($hostId in @('codex', 'claude', 'kimi')) {
+    $safeResults += Invoke-AdapterMutation $hostId 'install'
+    $safeResults += Invoke-AdapterMutation $hostId 'update'
+    $safeResults += Invoke-AdapterMutation $hostId 'uninstall'
+    $reinstall = Invoke-AdapterMutation $hostId 'install'
+    $safeResults += $reinstall
+    $rollbackBody = @{
+      host_id = $hostId
+      rollback_id = $reinstall.rollback_id
+    } | ConvertTo-Json -Compress
+    $rollback = Invoke-RestMethod -Method Post `
+      -Uri "$base/api/adapters/rollback" -ContentType 'application/json' `
+      -Body $rollbackBody
+    $safeResults += [pscustomobject]@{
+      host = $hostId
+      operation = 'rollback'
+      state = $rollback.state
+      verification = $null
+      rollback_id = $null
+    }
+    $postRollback = (Invoke-RestMethod "$base/api/adapters").hosts |
+      Where-Object host_id -eq $hostId
+    $safeResults += [pscustomobject]@{
+      host = $hostId
+      operation = 'post_rollback_probe'
+      state = $postRollback.state
+      verification = $null
+      rollback_id = $null
+    }
+  }
+
+  $safeResults | Select-Object host, operation, state, verification
+  foreach ($path in $sentinels) {
+    if (-not (Test-Path -LiteralPath $path)) { throw 'sentinel was removed' }
+    if ((Get-FileHash -Algorithm SHA256 $path).Hash -ne $before[$path]) {
+      throw 'sentinel was modified'
+    }
+  }
+} finally {
+  Stop-Job $appJob -ErrorAction SilentlyContinue
+  Remove-Job $appJob -Force -ErrorAction SilentlyContinue
+}
+git status --short
+```
+
+PASS requires `completed`/`verified` for mutations that install or remove
+content, `no_change` with `verified` for an unchanged update, `rolled_back` for
+rollback, `available` after the post-rollback probe, unchanged sentinels, and no
+repository changes. Preserve only the
+redacted result table, exact host versions, package hashes, and commit SHA.
+Destroy the disposable OS/container after review. Do not publish the temporary
+root, App state, raw CLI/model traffic, plan tokens, credentials, or session
+identifiers.
+
 Independent release QA must repeat the relevant gates. Record only
 privacy-safe versions, hashes, results, and reviewer identity; keep disposable
 home paths and raw command/model traffic out of the public repository. Do not
diff --git a/tests/unit/test_opc_evolution.py b/tests/unit/test_opc_evolution.py
index 4089cb9..4d751cf 100644
--- a/tests/unit/test_opc_evolution.py
+++ b/tests/unit/test_opc_evolution.py
@@ -28,6 +28,22 @@ def digest(path: Path) -> str:
     return hashlib.sha256(path.read_bytes()).hexdigest()
 
 
+def disable_disposable_repo_background_maintenance(repo: Path) -> None:
+    """Keep detached Git maintenance from racing TemporaryDirectory cleanup."""
+    settings = {
+        "maintenance.auto": "false",
+        "maintenance.autoDetach": "false",
+        "gc.auto": "0",
+        "gc.autoDetach": "false",
+    }
+    for key, value in settings.items():
+        subprocess.run(
+            ["git", "-C", str(repo), "config", "--local", key, value],
+            check=True,
+            capture_output=True,
+        )
+
+
 @unittest.skipUnless(shutil.which("git"), "Git is required")
 class CapabilityEvolutionTests(unittest.TestCase):
     def setUp(self) -> None:
@@ -47,6 +63,7 @@ def setUp(self) -> None:
         self.target.write_text("---\nname: demo\n---\n\nCurrent behavior.\n", encoding="utf-8")
         self.user_similar.write_text("user-owned similar filename\n", encoding="utf-8")
         subprocess.run(["git", "init", "-b", "main", str(self.repo)], check=True, capture_output=True)
+        disable_disposable_repo_background_maintenance(self.repo)
         subprocess.run(["git", "-C", str(self.repo), "add", "--", "skills/demo/.SKILL.md.opc-backup-user"], check=True, capture_output=True)
         self.base = self._commit("base")
         subprocess.run(["git", "-C", str(self.repo), "switch", "-c", "candidate"], check=True, capture_output=True)
@@ -85,6 +102,23 @@ def setUp(self) -> None:
         self._write_evidence("lineage/source.json", "lineage", "verified", "not_applicable")
         self.proposal = self._proposal()
 
+    def test_disposable_repository_disables_detached_git_maintenance(self) -> None:
+        expected = {
+            "maintenance.auto": "false",
+            "maintenance.autoDetach": "false",
+            "gc.auto": "0",
+            "gc.autoDetach": "false",
+        }
+        for key, value in expected.items():
+            with self.subTest(key=key):
+                actual = subprocess.run(
+                    ["git", "-C", str(self.repo), "config", "--local", "--get", key],
+                    check=True,
+                    capture_output=True,
+                    text=True,
+                ).stdout.strip()
+                self.assertEqual(actual, value)
+
     def _artifact(self, relative: str, value: dict) -> dict:
         path = self.project / ".opc" / relative
         path.parent.mkdir(parents=True, exist_ok=True)

From 210b5dae5ec856ddc4bde0333f6413e489b538ac Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 17:27:15 +0800
Subject: [PATCH 07/11] docs: include adapter mutation security headers

---
 docs/host-adapters.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/host-adapters.md b/docs/host-adapters.md
index 001a541..1041510 100644
--- a/docs/host-adapters.md
+++ b/docs/host-adapters.md
@@ -159,6 +159,11 @@ foreach ($attempt in 1..50) {
   }
 }
 if (-not $ready) { throw 'OPC App did not become ready' }
+$context = Invoke-RestMethod "$base/api/app-context"
+$mutationHeaders = @{
+  Origin = $base
+  'X-OPC-CSRF' = $context.csrf_token
+}
 ```
 
 The second block exercises preview/apply, fresh-process verification, uninstall,
@@ -171,6 +176,7 @@ function Invoke-AdapterMutation([string]$hostId, [string]$operation) {
     ConvertTo-Json -Compress
   $plan = Invoke-RestMethod -Method Post `
     -Uri "$base/api/adapters/plan" -ContentType 'application/json' `
+    -Headers $mutationHeaders `
     -Body $planBody
   $applyBody = @{
     plan_id = $plan.plan_id
@@ -178,6 +184,7 @@ function Invoke-AdapterMutation([string]$hostId, [string]$operation) {
   } | ConvertTo-Json -Compress
   $result = Invoke-RestMethod -Method Post `
     -Uri "$base/api/adapters/apply" -ContentType 'application/json' `
+    -Headers $mutationHeaders `
     -Body $applyBody
   [pscustomobject]@{
     host = $hostId
@@ -209,6 +216,7 @@ try {
     } | ConvertTo-Json -Compress
     $rollback = Invoke-RestMethod -Method Post `
       -Uri "$base/api/adapters/rollback" -ContentType 'application/json' `
+      -Headers $mutationHeaders `
       -Body $rollbackBody
     $safeResults += [pscustomobject]@{
       host = $hostId

From 48400b7f3ba7ebb0cae6b6c78b791f2e391d1c95 Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 17:56:38 +0800
Subject: [PATCH 08/11] docs: isolate Windows adapter acceptance caches

---
 docs/host-adapters.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/host-adapters.md b/docs/host-adapters.md
index 1041510..213e249 100644
--- a/docs/host-adapters.md
+++ b/docs/host-adapters.md
@@ -112,7 +112,8 @@ $qaRoot = Join-Path ([IO.Path]::GetTempPath()) (
   'opc-adapter-review-' + [guid]::NewGuid().ToString('N')
 )
 $roots = @(
-  'home', 'codex', 'claude', 'kimi', 'app-state', 'knowledge', 'data'
+  'home', 'appdata', 'localappdata', 'codex', 'claude', 'kimi',
+  'app-state', 'knowledge', 'data'
 )
 foreach ($name in $roots) {
   New-Item -ItemType Directory -Force -Path (Join-Path $qaRoot $name) | Out-Null
@@ -120,6 +121,8 @@ foreach ($name in $roots) {
 
 $env:HOME = Join-Path $qaRoot 'home'
 $env:USERPROFILE = $env:HOME
+$env:APPDATA = Join-Path $qaRoot 'appdata'
+$env:LOCALAPPDATA = Join-Path $qaRoot 'localappdata'
 $env:CODEX_HOME = Join-Path $qaRoot 'codex'
 $env:CLAUDE_CONFIG_DIR = Join-Path $qaRoot 'claude'
 $env:KIMI_CODE_HOME = Join-Path $qaRoot 'kimi'
@@ -139,6 +142,13 @@ foreach ($path in $sentinels) {
 
 $appJob = Start-Job -ScriptBlock {
   param($repo, $qaRoot)
+  $env:HOME = Join-Path $qaRoot 'home'
+  $env:USERPROFILE = $env:HOME
+  $env:APPDATA = Join-Path $qaRoot 'appdata'
+  $env:LOCALAPPDATA = Join-Path $qaRoot 'localappdata'
+  $env:CODEX_HOME = Join-Path $qaRoot 'codex'
+  $env:CLAUDE_CONFIG_DIR = Join-Path $qaRoot 'claude'
+  $env:KIMI_CODE_HOME = Join-Path $qaRoot 'kimi'
   Set-Location $repo
   python plugins/codex-opc-team/scripts/opc_app.py `
     --state-root (Join-Path $qaRoot 'app-state') `

From 221fb4205e4e3ed821d9012dd92c42732428931e Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 18:15:39 +0800
Subject: [PATCH 09/11] docs: redirect PowerShell module cache

---
 docs/host-adapters.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/host-adapters.md b/docs/host-adapters.md
index 213e249..65ebeb9 100644
--- a/docs/host-adapters.md
+++ b/docs/host-adapters.md
@@ -123,6 +123,9 @@ $env:HOME = Join-Path $qaRoot 'home'
 $env:USERPROFILE = $env:HOME
 $env:APPDATA = Join-Path $qaRoot 'appdata'
 $env:LOCALAPPDATA = Join-Path $qaRoot 'localappdata'
+$env:PSModuleAnalysisCachePath = Join-Path $env:LOCALAPPDATA (
+  'Microsoft\Windows\PowerShell\ModuleAnalysisCache'
+)
 $env:CODEX_HOME = Join-Path $qaRoot 'codex'
 $env:CLAUDE_CONFIG_DIR = Join-Path $qaRoot 'claude'
 $env:KIMI_CODE_HOME = Join-Path $qaRoot 'kimi'
@@ -146,6 +149,9 @@ $appJob = Start-Job -ScriptBlock {
   $env:USERPROFILE = $env:HOME
   $env:APPDATA = Join-Path $qaRoot 'appdata'
   $env:LOCALAPPDATA = Join-Path $qaRoot 'localappdata'
+  $env:PSModuleAnalysisCachePath = Join-Path $env:LOCALAPPDATA (
+    'Microsoft\Windows\PowerShell\ModuleAnalysisCache'
+  )
   $env:CODEX_HOME = Join-Path $qaRoot 'codex'
   $env:CLAUDE_CONFIG_DIR = Join-Path $qaRoot 'claude'
   $env:KIMI_CODE_HOME = Join-Path $qaRoot 'kimi'

From 52647b9710d79f1dd4d46b091b86e6a587e93774 Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 21:20:40 +0800
Subject: [PATCH 10/11] fix(app): address review feedback

---
 ...independent-local-opc-app-control-plane.md |  5 +++++
 docs/opc-app.md                               |  5 +++--
 plugins/codex-opc-team/scripts/opc_app.py     |  5 ++++-
 scripts/opc_app_admin.py                      |  5 ++++-
 tests/unit/test_opc_app.py                    | 20 +++++++++++++++++++
 5 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/docs/adr/0017-independent-local-opc-app-control-plane.md b/docs/adr/0017-independent-local-opc-app-control-plane.md
index c283943..0fbcd6d 100644
--- a/docs/adr/0017-independent-local-opc-app-control-plane.md
+++ b/docs/adr/0017-independent-local-opc-app-control-plane.md
@@ -55,6 +55,11 @@ loopback-only 浏览器视图可以安全降低经理理解 OPC 状态的成本
    App 状态、项目、File/Git knowledge、Git 历史、用户配置和 Mem0 数据全部保留。
 10. **旧入口兼容。** 不安装或不启动 App 时，Codex Plugin、Skills、Hook、
     脚本和 `opc_dashboard.py` 的行为与生命周期 Gate 不变。
+11. **单写实例是当前支持边界。** `settings.json` 的更新使用进程内锁和原子
+    replace，能避免单实例内并发损坏，但不提供跨进程事务或丢失更新保护。同一
+    `OPC_APP_HOME` 同时只支持一个可写 App 实例；第二实例属于不受支持的运维
+    配置。未来若需要多实例，必须先引入有明确所有权、锁超时和崩溃恢复契约的
+    跨进程协调，不能把文件原子写误称为多实例安全。
 
 ## API 与状态
 
diff --git a/docs/opc-app.md b/docs/opc-app.md
index 86daa7a..501f211 100644
--- a/docs/opc-app.md
+++ b/docs/opc-app.md
@@ -75,8 +75,9 @@ App runtime 默认位于平台用户数据目录；App 状态与 runtime 分开
 | Windows | `%LOCALAPPDATA%\OPC\App` |
 | Linux | `${XDG_STATE_HOME:-$HOME/.local/state}/opc-app` |
 
-可用 `OPC_APP_HOME` 显式覆盖状态根。状态根保存项目接入清单和当前项目选择，
-可以删除重建，但不是 OPC 业务事实来源。
+可用绝对路径形式的 `OPC_APP_HOME` 显式覆盖状态根；相对路径会被拒绝，避免同一
+App 从不同工作目录启动时解析到不同接入清单。状态根保存项目接入清单和当前项目
+选择，可以删除重建，但不是 OPC 业务事实来源。
 
 状态根不能与源码 checkout、插件/runtime、任何显式项目或 `.opc`、知识根、数据
 根存在父子重叠，也不能经过 symlink/junction parent。检查同时比较 lexical path
diff --git a/plugins/codex-opc-team/scripts/opc_app.py b/plugins/codex-opc-team/scripts/opc_app.py
index d557ea0..6742904 100644
--- a/plugins/codex-opc-team/scripts/opc_app.py
+++ b/plugins/codex-opc-team/scripts/opc_app.py
@@ -60,7 +60,10 @@ def __init__(self, code: str):
 def resolve_app_state_root(value: str | None = None) -> Path:
     configured = value or os.environ.get("OPC_APP_HOME")
     if configured:
-        return Path(os.path.abspath(Path(configured).expanduser()))
+        expanded = Path(configured).expanduser()
+        if not expanded.is_absolute():
+            raise AppSettingsError("ABSOLUTE_APP_STATE_ROOT_REQUIRED")
+        return Path(os.path.abspath(expanded))
     if os.name == "nt":
         local = os.environ.get("LOCALAPPDATA")
         base = Path(local) if local else Path.home() / "AppData" / "Local"
diff --git a/scripts/opc_app_admin.py b/scripts/opc_app_admin.py
index 953693f..a63ff7f 100644
--- a/scripts/opc_app_admin.py
+++ b/scripts/opc_app_admin.py
@@ -51,7 +51,10 @@ def default_install_root() -> Path:
 def default_state_root() -> Path:
     configured = os.environ.get("OPC_APP_HOME")
     if configured:
-        return Path(os.path.abspath(Path(configured).expanduser()))
+        expanded = Path(configured).expanduser()
+        if not expanded.is_absolute():
+            raise AppInstallError("OPC_APP_HOME must be an absolute path")
+        return Path(os.path.abspath(expanded))
     if os.name == "nt":
         local = os.environ.get("LOCALAPPDATA")
         base = Path(local) if local else Path.home() / "AppData" / "Local"
diff --git a/tests/unit/test_opc_app.py b/tests/unit/test_opc_app.py
index 5f6cf14..e34e03a 100644
--- a/tests/unit/test_opc_app.py
+++ b/tests/unit/test_opc_app.py
@@ -16,8 +16,10 @@
 ROOT = Path(__file__).resolve().parents[2]
 SCRIPTS = ROOT / "plugins" / "codex-opc-team" / "scripts"
 sys.path.insert(0, str(SCRIPTS))
+sys.path.insert(0, str(ROOT / "scripts"))
 
 import opc_app  # noqa: E402
+import opc_app_admin  # noqa: E402
 import opc_dashboard  # noqa: E402
 import opc_snapshot_service  # noqa: E402
 from opc_snapshot_service import SnapshotService  # noqa: E402
@@ -107,6 +109,24 @@ def request(
 
 
 class SettingsStoreTests(unittest.TestCase):
+    def test_relative_app_state_root_is_rejected_by_runtime_and_installer(self):
+        with self.assertRaises(opc_app.AppSettingsError) as runtime:
+            opc_app.resolve_app_state_root("relative/app-state")
+        self.assertEqual(
+            runtime.exception.code,
+            "ABSOLUTE_APP_STATE_ROOT_REQUIRED",
+        )
+        previous = os.environ.get("OPC_APP_HOME")
+        os.environ["OPC_APP_HOME"] = "relative/app-state"
+        try:
+            with self.assertRaises(opc_app_admin.AppInstallError):
+                opc_app_admin.default_state_root()
+        finally:
+            if previous is None:
+                os.environ.pop("OPC_APP_HOME", None)
+            else:
+                os.environ["OPC_APP_HOME"] = previous
+
     def test_state_root_rejects_checkout_before_directory_creation(self):
         candidate = ROOT / f".opc-app-state-test-{os.getpid()}"
         self.assertFalse(candidate.exists())

From 7c9514c0102469e4e2513a2f9b97b7def69f95f6 Mon Sep 17 00:00:00 2001
From: BayesWang <827130441@qq.com>
Date: Sat, 25 Jul 2026 21:22:53 +0800
Subject: [PATCH 11/11] fix(adapters): close review safety gaps

---
 ...0018-host-adapters-use-public-contracts.md |  11 +
 docs/host-adapters.md                         |  21 +
 .../codex-opc-team/assets/app/dashboard.css   |  16 +
 .../codex-opc-team/assets/app/dashboard.js    | 101 ++++
 plugins/codex-opc-team/assets/app/index.html  |  13 +
 .../codex-opc-team/scripts/opc_adapters.py    | 490 +++++++++++++++---
 plugins/codex-opc-team/scripts/opc_app.py     |  11 +-
 tests/unit/test_opc_adapters.py               | 268 +++++++++-
 tests/unit/test_opc_app.py                    |  64 +++
 9 files changed, 911 insertions(+), 84 deletions(-)

diff --git a/docs/adr/0018-host-adapters-use-public-contracts.md b/docs/adr/0018-host-adapters-use-public-contracts.md
index 6af214e..e754ba5 100644
--- a/docs/adr/0018-host-adapters-use-public-contracts.md
+++ b/docs/adr/0018-host-adapters-use-public-contracts.md
@@ -37,6 +37,17 @@ rebuildable App state, not organizational memory. A host target may be changed
 or removed only when the manifest proves OPC ownership and the current hash
 still matches. Unknown host versions and unsupported mechanisms fail closed.
 
+Each host has one mutation lock spanning final state verification, host writes,
+fresh-process verification, manifest publication, and operation-record
+publication. An operation record is written before mutation and retains only
+logical rollback identity, prior manifest, hashes, status, and a stable error
+code. Completed or recoverable failed operations appear in the App as recovery
+entries. Rollback is a separate Host/Origin/CSRF-protected request and the UI
+requires its own confirmation dialog; it rechecks the recorded post-operation
+fingerprint before changing anything. Codex and Claude cannot claim byte-level
+host-cache drift because their public discovery contracts do not expose a
+supported cache digest; Kimi can hash its managed public Skill directories.
+
 ## Consequences
 
 The three hosts can expose different support levels without false parity.
diff --git a/docs/host-adapters.md b/docs/host-adapters.md
index 65ebeb9..7ede0e5 100644
--- a/docs/host-adapters.md
+++ b/docs/host-adapters.md
@@ -51,11 +51,21 @@ writes an ownership manifest or host file.
 The browser API emits logical targets such as `kimi:skill/opc-manager`, not
 absolute user-home paths.
 
+Codex and Claude drift detection is intentionally limited to the official
+installed-state discovery result plus the App-owned immutable projection or
+marketplace source. Their public CLIs do not expose a supported installed-cache
+content digest, so the Adapter does not claim byte-level host-cache drift
+detection. Kimi is different: its public integration unit is the managed Skill
+directory itself, so every owned target is hash-verified.
+
 ## Conflict and recovery rules
 
 - Install refuses an existing unknown target.
 - Update and uninstall require an ownership manifest and an unchanged current
   hash. User edits and links are preserved as conflicts.
+- A Kimi update rejects a newly introduced canonical Skill when its target is
+  already user-owned, and removes a deleted canonical Skill only when the old
+  manifest and current hash still prove OPC ownership.
 - Kimi directory swaps use App-owned staging and backups. A partial swap
   restores already moved targets in reverse order.
 - Claude update and rollback never remove its marketplace. The stable source
@@ -68,6 +78,17 @@ absolute user-home paths.
   manager preferences/rules/experience, optional Mem0 data, or other hosts.
 - Verification failure is not PASS. The operation attempts rollback and returns
   a structured failure or recovery requirement.
+- Operation records are persisted before mutation. Successful and recoverable
+  failed operations expose a logical rollback ID in the App; no backup path is
+  returned. Rollback rechecks the exact post-operation target fingerprint and
+  refuses to remove user changes.
+- Apply and rollback are serialized per host across fingerprint verification,
+  mutation, manifest publication, and operation-record publication. Different
+  hosts remain independent.
+- `/api/adapters/rollback` is protected by the same Host, Origin, and CSRF
+  boundary as apply. The App additionally requires a dedicated visible
+  confirmation dialog before it sends the rollback request; rollback IDs alone
+  are not treated as authorization.
 
 ## Installed-state QA
 
diff --git a/plugins/codex-opc-team/assets/app/dashboard.css b/plugins/codex-opc-team/assets/app/dashboard.css
index f7dd7f6..c6adad3 100644
--- a/plugins/codex-opc-team/assets/app/dashboard.css
+++ b/plugins/codex-opc-team/assets/app/dashboard.css
@@ -1473,6 +1473,22 @@ dialog::backdrop {
   padding: 9px 10px;
 }
 
+.adapter-recovery {
+  background: color-mix(in srgb, var(--amber-600) 8%, white);
+  border: 1px solid color-mix(in srgb, var(--amber-600) 30%, var(--line));
+  border-radius: 9px;
+  display: grid;
+  gap: 8px;
+  margin-top: 12px;
+  padding: 11px;
+}
+
+.adapter-recovery code {
+  color: var(--text-500);
+  font-size: .72rem;
+  overflow-wrap: anywhere;
+}
+
 .adapter-actions {
   display: flex;
   gap: 8px;
diff --git a/plugins/codex-opc-team/assets/app/dashboard.js b/plugins/codex-opc-team/assets/app/dashboard.js
index 9fa9096..e27e1e8 100644
--- a/plugins/codex-opc-team/assets/app/dashboard.js
+++ b/plugins/codex-opc-team/assets/app/dashboard.js
@@ -20,6 +20,7 @@
     queue: new Map(),
     adapters: null,
     adapterPlan: null,
+    adapterRollback: null,
     refreshTimer: null,
   };
 
@@ -594,6 +595,26 @@
           : "Kimi Plugin 后台安装不受支持；当前仅管理官方 Skill 投影。";
         card.append(warning);
       }
+      const recovery = asObject(host.recovery);
+      if (recovery.rollback_id) {
+        const recoveryNode = document.createElement("section");
+        recoveryNode.className = "adapter-recovery";
+        const recoveryTitle = document.createElement("strong");
+        recoveryTitle.textContent = recovery.status === "failed"
+          ? "上次操作需要恢复"
+          : "可回滚上次操作";
+        const recoveryId = document.createElement("code");
+        recoveryId.textContent = recovery.rollback_id;
+        const recoveryAction = document.createElement("button");
+        recoveryAction.type = "button";
+        recoveryAction.className = "secondary-button";
+        recoveryAction.textContent = "回滚本次操作";
+        recoveryAction.dataset.adapterRollbackHost = host.host_id;
+        recoveryAction.dataset.adapterRollbackId = recovery.rollback_id;
+        recoveryAction.dataset.adapterRollbackError = recovery.error_code || "";
+        recoveryNode.append(recoveryTitle, recoveryId, recoveryAction);
+        card.append(recoveryNode);
+      }
       const actions = document.createElement("div");
       actions.className = "adapter-actions";
       if (host.state === "available") {
@@ -704,6 +725,7 @@
     if (!response.ok) {
       const error = new Error(payload.error || `HTTP_${response.status}`);
       error.code = payload.error || `HTTP_${response.status}`;
+      error.rollbackId = payload.rollback_id || null;
       throw error;
     }
     return payload;
@@ -771,9 +793,25 @@
       PLAN_STATE_CHANGED: "来源、宿主、发现结果、所有权或目标状态已变化；未执行任何写入。",
       VERIFY_FAILED_ROLLED_BACK: "宿主回读验证失败，已尝试恢复操作前状态。",
       APPLY_FAILED: "宿主写入失败；其他 Adapter 和私人知识未被修改。",
+      ROLLBACK_FAILED: "自动恢复未完成；现场已保留，请使用恢复入口。",
+      ROLLBACK_CONFLICT: "回滚点之后的目标状态已变化；为保护用户修改，已拒绝回滚。",
+      ROLLBACK_POINT_USED: "此回滚点已经使用，不能重复执行。",
     }[String(code || "")] || "操作未完成；请刷新后查看结构化状态。";
   }
 
+  function exposeAdapterRecovery(hostId, rollbackId, errorCode = null) {
+    const hosts = asArray(asObject(state.adapters).hosts);
+    const host = hosts.find((item) => item.host_id === hostId);
+    if (!host || !rollbackId) return;
+    host.recovery = {
+      rollback_id: rollbackId,
+      operation: asObject(state.adapterPlan).operation || "unknown",
+      status: errorCode ? "failed" : "completed",
+      error_code: errorCode,
+    };
+    renderAdapters();
+  }
+
   async function openAdapterPlan(hostId, operation) {
     try {
       const plan = await adapterRequest("/api/adapters/plan", {
@@ -825,8 +863,10 @@
         confirmation_token: plan.confirmation_token,
       });
       byId("adapter-dialog").close();
+      const hostId = plan.host_id;
       state.adapterPlan = null;
       await refresh();
+      exposeAdapterRecovery(hostId, result.rollback_id);
       showBanner(
         result.state === "verification_required"
           ? "宿主写入已完成，但 Kimi 新进程发现仍需在已配置模型的环境中人工验收。"
@@ -835,11 +875,57 @@
     } catch (error) {
       errorNode.textContent = adapterErrorMessage(error.code);
       errorNode.hidden = false;
+      if (error.rollbackId) {
+        exposeAdapterRecovery(plan.host_id, error.rollbackId, error.code);
+      }
     } finally {
       button.disabled = !byId("adapter-confirm").checked;
     }
   }
 
+  function openAdapterRollback(hostId, rollbackId, errorCode = "") {
+    state.adapterRollback = {
+      host_id: hostId,
+      rollback_id: rollbackId,
+    };
+    setText("adapter-rollback-host", hostId);
+    setText("adapter-rollback-id", rollbackId);
+    setText(
+      "adapter-rollback-reason",
+      errorCode
+        ? `上次操作返回 ${errorCode}；将恢复该操作记录绑定的 OPC-owned 前置状态。`
+        : "将恢复该操作记录绑定的 OPC-owned 前置状态。"
+    );
+    byId("adapter-rollback-confirm").checked = false;
+    byId("confirm-adapter-rollback").disabled = true;
+    byId("adapter-rollback-error").hidden = true;
+    byId("adapter-rollback-dialog").showModal();
+  }
+
+  async function rollbackAdapterOperation() {
+    const rollback = asObject(state.adapterRollback);
+    if (!byId("adapter-rollback-confirm").checked || !rollback.rollback_id) return;
+    const button = byId("confirm-adapter-rollback");
+    const errorNode = byId("adapter-rollback-error");
+    button.disabled = true;
+    errorNode.hidden = true;
+    try {
+      await adapterRequest("/api/adapters/rollback", {
+        host_id: rollback.host_id,
+        rollback_id: rollback.rollback_id,
+      });
+      byId("adapter-rollback-dialog").close();
+      state.adapterRollback = null;
+      await refresh();
+      showBanner("已通过记录的回滚点恢复操作前状态，并保留私人知识与无关宿主内容。");
+    } catch (error) {
+      errorNode.textContent = adapterErrorMessage(error.code);
+      errorNode.hidden = false;
+    } finally {
+      button.disabled = !byId("adapter-rollback-confirm").checked;
+    }
+  }
+
   function errorMessage(code) {
     const mapping = {
       ABSOLUTE_PROJECT_ROOT_REQUIRED: "请输入项目的绝对目录。",
@@ -1019,6 +1105,15 @@
       }
     });
     byId("adapter-list").addEventListener("click", (event) => {
+      const rollbackButton = event.target.closest("button[data-adapter-rollback-id]");
+      if (rollbackButton) {
+        openAdapterRollback(
+          rollbackButton.dataset.adapterRollbackHost,
+          rollbackButton.dataset.adapterRollbackId,
+          rollbackButton.dataset.adapterRollbackError
+        );
+        return;
+      }
       const button = event.target.closest("button[data-adapter-host]");
       if (!button) return;
       openAdapterPlan(button.dataset.adapterHost, button.dataset.adapterOperation);
@@ -1029,6 +1124,12 @@
       byId("apply-adapter-plan").disabled = !event.target.checked;
     });
     byId("apply-adapter-plan").addEventListener("click", applyAdapterPlan);
+    byId("close-adapter-rollback").addEventListener("click", () => byId("adapter-rollback-dialog").close());
+    byId("cancel-adapter-rollback").addEventListener("click", () => byId("adapter-rollback-dialog").close());
+    byId("adapter-rollback-confirm").addEventListener("change", (event) => {
+      byId("confirm-adapter-rollback").disabled = !event.target.checked;
+    });
+    byId("confirm-adapter-rollback").addEventListener("click", rollbackAdapterOperation);
   }
 
   function scheduleRefresh() {
diff --git a/plugins/codex-opc-team/assets/app/index.html b/plugins/codex-opc-team/assets/app/index.html
index 532cd06..1a275e5 100644
--- a/plugins/codex-opc-team/assets/app/index.html
+++ b/plugins/codex-opc-team/assets/app/index.html
@@ -245,6 +245,19 @@ <h3>验证预览（只读检查）</h3>
     <div class="drawer-actions"><button class="secondary-button" id="cancel-adapter-plan" type="button">取消</button><button class="primary-button" id="apply-adapter-plan" type="button" disabled>确认并执行</button></div>
   </dialog>
 
+  <dialog class="detail-dialog adapter-dialog" id="adapter-rollback-dialog" aria-labelledby="adapter-rollback-title">
+    <div class="dialog-header">
+      <div><span id="adapter-rollback-host">Adapter</span><h2 id="adapter-rollback-title">回滚本次操作</h2></div>
+      <button class="icon-button" id="close-adapter-rollback" type="button" aria-label="关闭 Adapter 回滚"><svg class="icon" aria-hidden="true"><use href="#icon-close"></use></svg></button>
+    </div>
+    <p id="adapter-rollback-reason">将恢复该操作记录绑定的 OPC-owned 前置状态。</p>
+    <div class="next-step-box"><strong>回滚点</strong><code id="adapter-rollback-id">—</code></div>
+    <p class="surface-note">执行前会重新核对目标指纹；若用户在操作后修改过内容，将拒绝删除或覆盖。</p>
+    <label class="adapter-confirm"><input id="adapter-rollback-confirm" type="checkbox">我已确认回滚范围，仅恢复本次 OPC-owned 操作。</label>
+    <p class="field-error" id="adapter-rollback-error" role="alert" hidden></p>
+    <div class="drawer-actions"><button class="secondary-button" id="cancel-adapter-rollback" type="button">取消</button><button class="primary-button" id="confirm-adapter-rollback" type="button" disabled>确认回滚</button></div>
+  </dialog>
+
   <script src="/dashboard.js" defer></script>
 </body>
 </html>
diff --git a/plugins/codex-opc-team/scripts/opc_adapters.py b/plugins/codex-opc-team/scripts/opc_adapters.py
index 2502701..d4f468e 100644
--- a/plugins/codex-opc-team/scripts/opc_adapters.py
+++ b/plugins/codex-opc-team/scripts/opc_adapters.py
@@ -42,10 +42,17 @@
 class AdapterError(RuntimeError):
     """A stable, UI-safe adapter failure."""
 
-    def __init__(self, code: str, *, detail: str | None = None):
+    def __init__(
+        self,
+        code: str,
+        *,
+        detail: str | None = None,
+        rollback_id: str | None = None,
+    ):
         super().__init__(code)
         self.code = code
         self.detail = detail
+        self.rollback_id = rollback_id
 
 
 @dataclass(frozen=True)
@@ -232,14 +239,24 @@ def write_operation(
         *,
         operation: str,
         prior_manifest: dict[str, Any] | None,
+        status: str,
+        error_code: str | None,
+        pre_target_digest: str,
+        target_state_digest: str,
+        backup_ref: str | None,
     ) -> None:
         _atomic_json(
             self.operation_path(host_id, operation_id),
             {
-                "schema_version": "opc-adapters.operation.v1",
+                "schema_version": "opc-adapters.operation.v2",
                 "host_id": host_id,
                 "operation": operation,
                 "prior_manifest": prior_manifest,
+                "status": status,
+                "error_code": error_code,
+                "pre_target_digest": pre_target_digest,
+                "target_state_digest": target_state_digest,
+                "backup_ref": backup_ref,
             },
         )
 
@@ -248,18 +265,77 @@ def read_operation(self, host_id: str, operation_id: str) -> dict[str, Any]:
         if not path.is_file() or _is_link(path):
             raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
         payload = _read_json(path)
+        if payload.get("schema_version") == "opc-adapters.operation.v1":
+            payload = {
+                **payload,
+                "status": "completed",
+                "error_code": None,
+                "pre_target_digest": None,
+                "target_state_digest": None,
+                "backup_ref": operation_id,
+            }
         if (
-            payload.get("schema_version") != "opc-adapters.operation.v1"
+            payload.get("schema_version") not in {
+                "opc-adapters.operation.v1",
+                "opc-adapters.operation.v2",
+            }
             or payload.get("host_id") != host_id
             or payload.get("operation") not in {"install", "update", "uninstall"}
+            or payload.get("status")
+            not in {"pending", "completed", "failed", "rolled_back"}
             or not (
                 payload.get("prior_manifest") is None
                 or isinstance(payload.get("prior_manifest"), dict)
             )
+            or not (
+                payload.get("error_code") is None
+                or isinstance(payload.get("error_code"), str)
+            )
+            or not (
+                payload.get("pre_target_digest") is None
+                or re.fullmatch(r"[0-9a-f]{64}", payload["pre_target_digest"])
+            )
+            or not (
+                payload.get("target_state_digest") is None
+                or re.fullmatch(r"[0-9a-f]{64}", payload["target_state_digest"])
+            )
+            or not (
+                payload.get("backup_ref") is None
+                or payload.get("backup_ref") == operation_id
+            )
         ):
             raise AdapterError("INVALID_ROLLBACK_POINT")
         return payload
 
+    def recoveries(self, host_id: str) -> list[dict[str, Any]]:
+        root = self.root / host_id / "operations"
+        if not root.is_dir() or _is_link(root):
+            return []
+        records: list[tuple[int, dict[str, Any]]] = []
+        for path in root.glob("*.json"):
+            operation_id = path.stem
+            if not PORTABLE_TOKEN.fullmatch(operation_id):
+                continue
+            try:
+                record = self.read_operation(host_id, operation_id)
+                modified = path.stat().st_mtime_ns
+            except (AdapterError, OSError):
+                continue
+            if record["status"] not in {"pending", "completed", "failed"}:
+                continue
+            records.append(
+                (
+                    modified,
+                    {
+                        "rollback_id": operation_id,
+                        "operation": record["operation"],
+                        "status": record["status"],
+                        "error_code": record["error_code"],
+                    },
+                )
+            )
+        return [record for _, record in sorted(records, reverse=True)]
+
 
 class HostAdapter:
     host_id = ""
@@ -350,6 +426,8 @@ def rollback_operation(
         operation: str,
         prior_manifest: dict[str, Any] | None,
         operation_id: str,
+        *,
+        operation_record: Mapping[str, Any] | None = None,
     ) -> dict[str, Any]:
         inverse = "uninstall" if prior_manifest is None else "install"
         return self.apply_operation(inverse, f"{operation_id}-rollback")
@@ -424,6 +502,17 @@ def __init__(self, **kwargs: Any):
         packaged_admin = self.plugin_root / "scripts" / "plugin_admin.py"
         self.admin = repository_admin if repository_admin.is_file() else packaged_admin
 
+    def projection_root(
+        self,
+        source_version: str | None = None,
+        content_hash: str | None = None,
+    ) -> Path:
+        version = source_version or self.source_version
+        digest = content_hash or self.content_hash
+        if not PORTABLE_TOKEN.fullmatch(version) or not re.fullmatch(r"[0-9a-f]{64}", digest):
+            raise AdapterError("INVALID_PROJECTION_REF")
+        return self.store.root / self.host_id / "projection" / f"{version}-{digest[:16]}"
+
     def probe(self) -> dict[str, Any]:
         result = self._command("--version")
         version = _version_tuple(result.stdout or result.stderr)
@@ -462,12 +551,7 @@ def probe(self) -> dict[str, Any]:
         )
 
     def target_fingerprint(self) -> dict[str, Any]:
-        projection = (
-            self.store.root
-            / self.host_id
-            / "projection"
-            / f"{self.source_version}-{self.content_hash[:16]}"
-        )
+        projection = self.projection_root()
         return {
             "projection_exists": projection.is_dir(),
             "projection_is_link": _is_link(projection),
@@ -527,7 +611,7 @@ def _run_admin(
         return self.runner(arguments, self.environment)
 
     def _codex_source(self) -> Path:
-        root = self.store.root / self.host_id / "projection" / self.source_version
+        root = self.projection_root()
         if root.exists():
             if tree_digest(root / "plugins" / "codex-opc-team" / "skills") != self.content_hash:
                 raise AdapterError("PROJECTION_CONFLICT")
@@ -579,10 +663,10 @@ def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
             result = self._run_admin("install")
             if result.returncode != 0:
                 previous = (
-                    self.store.root
-                    / self.host_id
-                    / "projection"
-                    / prior["source_version"]
+                    self.projection_root(
+                        prior["source_version"],
+                        prior["content_hash"],
+                    )
                 )
                 if previous.is_dir():
                     self._run_admin("install", source=previous)
@@ -598,15 +682,17 @@ def rollback_operation(
         operation: str,
         prior_manifest: dict[str, Any] | None,
         operation_id: str,
+        *,
+        operation_record: Mapping[str, Any] | None = None,
     ) -> dict[str, Any]:
         if prior_manifest is None:
             result = self._run_admin("uninstall", remove_marketplace=True)
         else:
             previous = (
-                self.store.root
-                / self.host_id
-                / "projection"
-                / prior_manifest["source_version"]
+                self.projection_root(
+                    prior_manifest["source_version"],
+                    prior_manifest["content_hash"],
+                )
             )
             if not previous.is_dir():
                 raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
@@ -717,13 +803,7 @@ def target_fingerprint(self) -> dict[str, Any]:
     def _is_installed(entries: Sequence[Any]) -> bool:
         selector = f"{PLUGIN_ID}@{MARKETPLACE_ID}"
         return any(
-            (
-                item.get("id") == selector
-                or (
-                    item.get("id") is None
-                    and item.get("name") in {PLUGIN_ID, selector}
-                )
-            )
+            item.get("id") == selector
             for item in entries
             if isinstance(item, dict)
         )
@@ -927,6 +1007,8 @@ def rollback_operation(
         operation: str,
         prior_manifest: dict[str, Any] | None,
         operation_id: str,
+        *,
+        operation_record: Mapping[str, Any] | None = None,
     ) -> dict[str, Any]:
         selector = f"{PLUGIN_ID}@{MARKETPLACE_ID}"
         if prior_manifest is None:
@@ -1071,6 +1153,12 @@ def target_fingerprint(self) -> dict[str, Any]:
         return {"skills_root": targets}
 
     def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[str, str]]:
+        current_names = set(self.skill_names)
+        managed_names = {
+            item["name"]
+            for item in (manifest or {}).get("managed_targets", [])
+            if isinstance(item, Mapping) and isinstance(item.get("name"), str)
+        }
         action = {
             "install": "add",
             "update": (
@@ -1080,10 +1168,16 @@ def changes(self, operation: str, manifest: dict[str, Any] | None) -> list[dict[
             ),
             "uninstall": "remove",
         }[operation]
-        return [
+        changes = [
             {"action": action, "target": f"kimi:skill/{name}"}
-            for name in self.skill_names
+            for name in sorted(current_names)
         ]
+        if operation == "update":
+            changes.extend(
+                {"action": "remove", "target": f"kimi:skill/{name}"}
+                for name in sorted(managed_names - current_names)
+            )
+        return changes
 
     def _assert_owned_unchanged(self, manifest: dict[str, Any]) -> None:
         for item in manifest["managed_targets"]:
@@ -1131,19 +1225,37 @@ def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
         skill_root.mkdir(parents=True, exist_ok=True)
         backup = self.store.backup_root(self.host_id, operation_id)
         stage = self.store.root / self.host_id / f".stage-{operation_id}"
-        activated: list[tuple[Path, Path | None]] = []
+        managed = {
+            item["name"]: item
+            for item in (manifest or {}).get("managed_targets", [])
+            if isinstance(item, Mapping) and isinstance(item.get("name"), str)
+        }
+        current_names = set(self.skill_names)
+        activated: list[tuple[Path, Path | None, str | None]] = []
         try:
             stage.mkdir(parents=True)
-            for name in self.skill_names:
+            for name in sorted(current_names):
                 source = self.plugin_root / "skills" / name
                 staged = stage / name
                 shutil.copytree(source, staged)
                 if tree_digest(staged) != tree_digest(source):
                     raise AdapterError("PROJECTION_VERIFY_FAILED")
-            for name in self.skill_names:
+            for name in sorted(current_names):
                 target = self._target(name)
-                if target.exists() and manifest is None:
+                if target.exists() and name not in managed:
                     raise AdapterError("UNKNOWN_TARGET_CONFLICT")
+            for name in sorted(set(managed) - current_names):
+                target = self._target(name)
+                if not target.exists():
+                    raise AdapterError("USER_MODIFIED_CONFLICT")
+                backup.mkdir(parents=True, exist_ok=True)
+                previous = backup / name
+                os.replace(target, previous)
+                activated.append((target, previous, None))
+            for name in sorted(current_names):
+                source = self.plugin_root / "skills" / name
+                expected_hash = tree_digest(source)
+                target = self._target(name)
                 previous: Path | None = None
                 if target.exists():
                     backup.mkdir(parents=True, exist_ok=True)
@@ -1155,12 +1267,18 @@ def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
                     if previous is not None and previous.exists() and not target.exists():
                         os.replace(previous, target)
                     raise
-                activated.append((target, previous))
-        except AdapterError:
-            self._restore_activated(activated)
+                activated.append((target, previous, expected_hash))
+        except AdapterError as exc:
+            try:
+                self._restore_activated(activated)
+            except AdapterError as restore_error:
+                raise restore_error from exc
             raise
         except OSError as exc:
-            self._restore_activated(activated)
+            try:
+                self._restore_activated(activated)
+            except AdapterError as restore_error:
+                raise restore_error from exc
             raise AdapterError("APPLY_FAILED") from exc
         finally:
             if stage.exists():
@@ -1172,15 +1290,27 @@ def apply_operation(self, operation: str, operation_id: str) -> dict[str, Any]:
         }
 
     @staticmethod
-    def _restore_activated(activated: list[tuple[Path, Path | None]]) -> None:
-        for target, previous in reversed(activated):
+    def _restore_activated(
+        activated: list[tuple[Path, Path | None, str | None]]
+    ) -> None:
+        for target, previous, expected_hash in reversed(activated):
             if target.exists():
-                shutil.rmtree(target, ignore_errors=True)
+                if (
+                    expected_hash is None
+                    or _is_link(target)
+                    or not target.is_dir()
+                    or tree_digest(target) != expected_hash
+                ):
+                    raise AdapterError("ROLLBACK_FAILED")
+                try:
+                    shutil.rmtree(target)
+                except OSError as exc:
+                    raise AdapterError("ROLLBACK_FAILED") from exc
             if previous is not None and previous.exists():
                 try:
                     os.replace(previous, target)
-                except OSError:
-                    pass
+                except OSError as exc:
+                    raise AdapterError("ROLLBACK_FAILED") from exc
 
     def verify(self, expected_installed: bool) -> dict[str, Any]:
         # Kimi has no public non-interactive skill-list command.  A fresh prompt
@@ -1251,19 +1381,30 @@ def rollback_operation(
         operation: str,
         prior_manifest: dict[str, Any] | None,
         operation_id: str,
+        *,
+        operation_record: Mapping[str, Any] | None = None,
     ) -> dict[str, Any]:
         backup = self.store.backup_root(self.host_id, operation_id)
         current = self.store.read(self.host_id)
+        current_targets = {
+            item["name"]: item
+            for item in (current or {}).get("managed_targets", [])
+            if isinstance(item, Mapping) and isinstance(item.get("name"), str)
+        }
+        prior_targets = {
+            item["name"]: item
+            for item in (prior_manifest or {}).get("managed_targets", [])
+            if isinstance(item, Mapping) and isinstance(item.get("name"), str)
+        }
         if operation == "install" and prior_manifest is None:
-            targets = (
-                current["managed_targets"]
-                if current
-                else [
-                    {"name": name, "hash": tree_digest(self.plugin_root / "skills" / name)}
-                    for name in self.skill_names
-                ]
-            )
-            for item in targets:
+            targets = current_targets or {
+                name: {
+                    "name": name,
+                    "hash": tree_digest(self.plugin_root / "skills" / name),
+                }
+                for name in self.skill_names
+            }
+            for item in targets.values():
                 target = self._target(item["name"])
                 if target.exists():
                     if _is_link(target) or tree_digest(target) != item["hash"]:
@@ -1272,14 +1413,35 @@ def rollback_operation(
             return {"state": "rolled_back"}
         if not backup.is_dir():
             raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
+        for name, item in current_targets.items():
+            if name in prior_targets:
+                continue
+            target = self._target(name)
+            if target.exists():
+                if _is_link(target) or tree_digest(target) != item["hash"]:
+                    raise AdapterError("ROLLBACK_CONFLICT")
+                shutil.rmtree(target)
         restored: list[str] = []
-        for name in self.skill_names:
+        for name, prior_item in prior_targets.items():
             source = backup / name
             target = self._target(name)
             if not source.is_dir():
-                continue
+                if (
+                    target.is_dir()
+                    and not _is_link(target)
+                    and tree_digest(target) == prior_item["hash"]
+                ):
+                    restored.append(name)
+                    continue
+                raise AdapterError("ROLLBACK_POINT_UNAVAILABLE")
             if target.exists():
-                if current is None:
+                current_item = current_targets.get(name)
+                if (
+                    current_item is None
+                    or _is_link(target)
+                    or not target.is_dir()
+                    or tree_digest(target) != current_item["hash"]
+                ):
                     raise AdapterError("ROLLBACK_CONFLICT")
                 shutil.rmtree(target)
             os.replace(source, target)
@@ -1335,24 +1497,33 @@ def __init__(
                     environment=environments.get("kimi"),
                 ),
             }
+        self._host_locks = {
+            host_id: threading.RLock()
+            for host_id in self.adapters
+        }
 
     def inventory(self) -> dict[str, Any]:
         hosts: list[dict[str, Any]] = []
         for host_id in HOST_IDS:
-            try:
-                hosts.append(self.adapters[host_id].probe())
-            except AdapterError as exc:
-                hosts.append(
-                    self.adapters[host_id]._status("blocked", reason=exc.code)
-                )
+            adapter = self.adapters[host_id]
+            with self._host_locks[host_id]:
+                try:
+                    host = adapter.probe()
+                except AdapterError as exc:
+                    host = adapter._status("blocked", reason=exc.code)
+                recoveries = self.store.recoveries(host_id)
+                if recoveries:
+                    host["recovery"] = recoveries[0]
+                hosts.append(host)
         return {"schema_version": ADAPTER_API_SCHEMA, "hosts": hosts}
 
     def create_plan(self, host_id: str, operation: str) -> dict[str, Any]:
         adapter = self.adapters.get(host_id)
         if adapter is None:
             raise AdapterError("UNKNOWN_HOST")
-        captured_state = adapter.capture_plan_state()
-        payload = adapter.plan(operation, captured_state)
+        with self._host_locks[host_id]:
+            captured_state = adapter.capture_plan_state()
+            payload = adapter.plan(operation, captured_state)
         serialized = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
         plan_id = f"plan-{secrets.token_hex(12)}"
         confirmation = secrets.token_urlsafe(24)
@@ -1362,6 +1533,7 @@ def create_plan(self, host_id: str, operation: str) -> dict[str, Any]:
             "digest": _sha256_bytes(serialized),
             "confirmation": confirmation,
             "state_digest": _canonical_digest(captured_state),
+            "captured_state": captured_state,
             "expires_at": issued_at + self._plan_ttl_seconds,
         }
         with self._lock:
@@ -1394,11 +1566,18 @@ def apply(
         if not secrets.compare_digest(record["digest"], current_digest):
             raise AdapterError("PLAN_CHANGED")
         adapter = self.adapters[payload["host_id"]]
+        with self._host_locks[adapter.host_id]:
+            return self._apply_locked(adapter, record, payload)
+
+    def _apply_locked(
+        self,
+        adapter: HostAdapter,
+        record: Mapping[str, Any],
+        payload: Mapping[str, Any],
+    ) -> dict[str, Any]:
         current_state_digest = _canonical_digest(adapter.capture_plan_state())
         if not secrets.compare_digest(record["state_digest"], current_state_digest):
             raise AdapterError("PLAN_STATE_CHANGED")
-        prior_manifest = self.store.read(adapter.host_id)
-        operation_id = f"op-{secrets.token_hex(10)}"
         try:
             if payload.get("no_change"):
                 verification = adapter.verify(True)
@@ -1412,11 +1591,51 @@ def apply(
                     "verification": verification,
                     "rollback_id": None,
                 }
+            prior_manifest = self.store.read(adapter.host_id)
+            operation_id = f"op-{secrets.token_hex(10)}"
+            pre_target_digest = _canonical_digest(record["captured_state"]["target"])
+            self.store.write_operation(
+                adapter.host_id,
+                operation_id,
+                operation=payload["operation"],
+                prior_manifest=prior_manifest,
+                status="pending",
+                error_code=None,
+                pre_target_digest=pre_target_digest,
+                target_state_digest=pre_target_digest,
+                backup_ref=None,
+            )
             applied = adapter.apply_operation(payload["operation"], operation_id)
             verification = adapter.verify(payload["operation"] != "uninstall")
             if verification["state"] == "failed":
                 adapter.rollback_operation(
-                    payload["operation"], prior_manifest, operation_id
+                    payload["operation"],
+                    prior_manifest,
+                    operation_id,
+                    operation_record={
+                        "status": "pending",
+                        "target_state_digest": _canonical_digest(
+                            adapter.target_fingerprint()
+                        ),
+                    },
+                )
+                restored_digest = _canonical_digest(adapter.target_fingerprint())
+                self.store.write_operation(
+                    adapter.host_id,
+                    operation_id,
+                    operation=payload["operation"],
+                    prior_manifest=prior_manifest,
+                    status="rolled_back",
+                    error_code="VERIFY_FAILED_ROLLED_BACK",
+                    pre_target_digest=pre_target_digest,
+                    target_state_digest=restored_digest,
+                    backup_ref=(
+                        operation_id
+                        if self.store.backup_root(
+                            adapter.host_id, operation_id
+                        ).is_dir()
+                        else None
+                    ),
                 )
                 raise AdapterError("VERIFY_FAILED_ROLLED_BACK")
             if payload["operation"] == "uninstall":
@@ -1455,6 +1674,15 @@ def apply(
                 operation_id,
                 operation=payload["operation"],
                 prior_manifest=prior_manifest,
+                status="completed",
+                error_code=None,
+                pre_target_digest=pre_target_digest,
+                target_state_digest=_canonical_digest(adapter.target_fingerprint()),
+                backup_ref=(
+                    operation_id
+                    if self.store.backup_root(adapter.host_id, operation_id).is_dir()
+                    else None
+                ),
             )
             return {
                 "schema_version": ADAPTER_API_SCHEMA,
@@ -1468,26 +1696,128 @@ def apply(
                 "verification": verification,
                 "rollback_id": operation_id,
             }
-        except AdapterError:
-            raise
+        except AdapterError as exc:
+            if "operation_id" not in locals():
+                raise
+            already_rolled_back = exc.code == "VERIFY_FAILED_ROLLED_BACK"
+            recoverable = self._record_failed_operation(
+                adapter=adapter,
+                operation_id=operation_id,
+                operation=payload["operation"],
+                prior_manifest=prior_manifest,
+                pre_target_digest=pre_target_digest,
+                error_code=exc.code,
+                already_rolled_back=already_rolled_back,
+            )
+            raise AdapterError(
+                exc.code,
+                detail=exc.detail,
+                rollback_id=operation_id if recoverable else None,
+            ) from exc
         except OSError as exc:
-            raise AdapterError("APPLY_FAILED") from exc
+            if "operation_id" not in locals():
+                raise AdapterError("APPLY_FAILED") from exc
+            recoverable = self._record_failed_operation(
+                adapter=adapter,
+                operation_id=operation_id,
+                operation=payload["operation"],
+                prior_manifest=prior_manifest,
+                pre_target_digest=pre_target_digest,
+                error_code="APPLY_FAILED",
+                already_rolled_back=False,
+            )
+            raise AdapterError(
+                "APPLY_FAILED",
+                rollback_id=operation_id if recoverable else None,
+            ) from exc
+
+    def _record_failed_operation(
+        self,
+        *,
+        adapter: HostAdapter,
+        operation_id: str,
+        operation: str,
+        prior_manifest: dict[str, Any] | None,
+        pre_target_digest: str,
+        error_code: str,
+        already_rolled_back: bool,
+    ) -> bool:
+        try:
+            target_state_digest = _canonical_digest(adapter.target_fingerprint())
+        except (AdapterError, OSError):
+            target_state_digest = _canonical_digest({"state": "unreadable"})
+        backup = self.store.backup_root(adapter.host_id, operation_id)
+        try:
+            backup_has_entries = backup.is_dir() and any(backup.rglob("*"))
+        except OSError:
+            backup_has_entries = True
+        recoverable = (
+            not already_rolled_back
+            and (
+                target_state_digest != pre_target_digest
+                or backup_has_entries
+                or error_code == "ROLLBACK_FAILED"
+            )
+        )
+        if not already_rolled_back:
+            try:
+                self.store.write_operation(
+                    adapter.host_id,
+                    operation_id,
+                    operation=operation,
+                    prior_manifest=prior_manifest,
+                    status="failed",
+                    error_code=error_code,
+                    pre_target_digest=pre_target_digest,
+                    target_state_digest=target_state_digest,
+                    backup_ref=operation_id if backup_has_entries else None,
+                )
+            except OSError:
+                # The pending record was published before host mutation. If the
+                # state volume is temporarily unwritable, preserve the original
+                # host failure and still surface the recovery identifier.
+                pass
+        return recoverable
 
     def rollback(self, host_id: str, rollback_id: str) -> dict[str, Any]:
         adapter = self.adapters.get(host_id)
         if adapter is None:
             raise AdapterError("UNKNOWN_HOST")
-        record = self.store.read_operation(host_id, rollback_id)
-        prior_manifest = record["prior_manifest"]
-        result = adapter.rollback_operation(
-            record["operation"], prior_manifest, rollback_id
-        )
-        if prior_manifest is None:
-            self.store.remove(host_id)
-        else:
-            self.store.write(host_id, prior_manifest)
-        return {
-            "schema_version": ADAPTER_API_SCHEMA,
-            "host_id": host_id,
-            **result,
-        }
+        with self._host_locks[host_id]:
+            record = self.store.read_operation(host_id, rollback_id)
+            if record["status"] == "rolled_back":
+                raise AdapterError("ROLLBACK_POINT_USED")
+            expected_digest = record.get("target_state_digest")
+            if expected_digest is not None:
+                actual_digest = _canonical_digest(adapter.target_fingerprint())
+                if not secrets.compare_digest(expected_digest, actual_digest):
+                    raise AdapterError("ROLLBACK_CONFLICT")
+            prior_manifest = record["prior_manifest"]
+            result = adapter.rollback_operation(
+                record["operation"],
+                prior_manifest,
+                rollback_id,
+                operation_record=record,
+            )
+            if prior_manifest is None:
+                self.store.remove(host_id)
+            else:
+                self.store.write(host_id, prior_manifest)
+            self.store.write_operation(
+                host_id,
+                rollback_id,
+                operation=record["operation"],
+                prior_manifest=prior_manifest,
+                status="rolled_back",
+                error_code=record.get("error_code"),
+                pre_target_digest=record.get("pre_target_digest")
+                or _canonical_digest({"state": "legacy"}),
+                target_state_digest=_canonical_digest(adapter.target_fingerprint()),
+                backup_ref=record.get("backup_ref"),
+            )
+            return {
+                "schema_version": ADAPTER_API_SCHEMA,
+                "host_id": host_id,
+                "rollback_id": rollback_id,
+                **result,
+            }
diff --git a/plugins/codex-opc-team/scripts/opc_app.py b/plugins/codex-opc-team/scripts/opc_app.py
index 093811a..84049fd 100644
--- a/plugins/codex-opc-team/scripts/opc_app.py
+++ b/plugins/codex-opc-team/scripts/opc_app.py
@@ -678,7 +678,16 @@ def do_POST(self) -> None:
         except AppSettingsError as exc:
             self._json_error(400, exc.code)
         except AdapterError as exc:
-            self._json_error(409, exc.code)
+            if exc.rollback_id is None:
+                self._json_error(409, exc.code)
+            else:
+                self._send_json(
+                    409,
+                    {
+                        "error": exc.code,
+                        "rollback_id": exc.rollback_id,
+                    },
+                )
 
     def do_DELETE(self) -> None:
         if not self._prepare_mutation():
diff --git a/tests/unit/test_opc_adapters.py b/tests/unit/test_opc_adapters.py
index 6e3be13..2b98930 100644
--- a/tests/unit/test_opc_adapters.py
+++ b/tests/unit/test_opc_adapters.py
@@ -5,6 +5,7 @@
 import shutil
 import sys
 import tempfile
+import threading
 import unittest
 from pathlib import Path
 from unittest import mock
@@ -144,9 +145,10 @@ def __call__(self, command, environment=None):
                 return opc_adapters.CommandResult(1, "", "No model configured")
             if host in self.fail_verify:
                 return opc_adapters.CommandResult(0, "")
+            skills_root = Path(values[values.index("--skills-dir") + 1])
             skills = [
                 path.name
-                for path in (ROOT / "plugins" / "codex-opc-team" / "skills").iterdir()
+                for path in skills_root.iterdir()
                 if path.is_dir()
             ]
             return opc_adapters.CommandResult(
@@ -166,6 +168,8 @@ def manager(
         self,
         base: Path,
         fake: FakeHosts,
+        *,
+        source_root: Path = ROOT,
         **manager_options,
     ) -> opc_adapters.AdapterManager:
         homes = {}
@@ -180,7 +184,7 @@ def manager(
             }
             executables[host] = str(base / f"{host}.fake")
         return opc_adapters.AdapterManager(
-            source_root=ROOT,
+            source_root=source_root,
             app_state_root=base / "app-state",
             runner=fake,
             environments=homes,
@@ -188,6 +192,17 @@ def manager(
             **manager_options,
         )
 
+    @staticmethod
+    def copied_source(base: Path) -> Path:
+        source = base / "source"
+        plugin = source / "plugins" / "codex-opc-team"
+        plugin.parent.mkdir(parents=True)
+        shutil.copytree(ROOT / "plugins" / "codex-opc-team", plugin)
+        scripts = source / "scripts"
+        scripts.mkdir()
+        shutil.copy2(ROOT / "scripts" / "plugin_admin.py", scripts / "plugin_admin.py")
+        return source
+
     @staticmethod
     def apply(
         manager: opc_adapters.AdapterManager,
@@ -494,6 +509,149 @@ def test_kimi_clean_idempotent_uninstall_reinstall_and_rollback(self):
             reinstalled = self.apply(manager, "kimi", "install")
             self.assertEqual(reinstalled["state"], "completed")
 
+    def test_kimi_update_rejects_new_user_owned_target(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            source = self.copied_source(base)
+            manager = self.manager(base, FakeHosts(), source_root=source)
+            self.apply(manager, "kimi", "install")
+            plugin_skills = source / "plugins" / "codex-opc-team" / "skills"
+            shutil.copytree(plugin_skills / "opc-manager", plugin_skills / "user-skill")
+            target = manager.adapters["kimi"]._target("user-skill")
+            target.mkdir()
+            sentinel = target / "user-sentinel"
+            sentinel.write_text("preserve", encoding="utf-8")
+
+            plan = manager.create_plan("kimi", "update")
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError,
+                "UNKNOWN_TARGET_CONFLICT",
+            ):
+                manager.apply(
+                    plan_id=plan["plan_id"],
+                    confirmation_token=plan["confirmation_token"],
+                )
+
+            self.assertEqual(sentinel.read_text(encoding="utf-8"), "preserve")
+            self.assertNotIn(
+                "user-skill",
+                {
+                    item["name"]
+                    for item in manager.store.read("kimi")["managed_targets"]
+                },
+            )
+
+    def test_kimi_update_removes_deleted_owned_skill_and_rollback_restores_it(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            source = self.copied_source(base)
+            manager = self.manager(base, FakeHosts(), source_root=source)
+            self.apply(manager, "kimi", "install")
+            manifest = manager.store.read("kimi")
+            removed_name = manifest["managed_targets"][0]["name"]
+            removed_target = manager.adapters["kimi"]._target(removed_name)
+            removed_hash = opc_adapters.tree_digest(removed_target)
+            shutil.rmtree(
+                source
+                / "plugins"
+                / "codex-opc-team"
+                / "skills"
+                / removed_name
+            )
+
+            plan = manager.create_plan("kimi", "update")
+            self.assertIn(
+                {"action": "remove", "target": f"kimi:skill/{removed_name}"},
+                plan["changes"],
+            )
+            updated = manager.apply(
+                plan_id=plan["plan_id"],
+                confirmation_token=plan["confirmation_token"],
+            )
+            self.assertFalse(removed_target.exists())
+            self.assertNotIn(
+                removed_name,
+                {
+                    item["name"]
+                    for item in manager.store.read("kimi")["managed_targets"]
+                },
+            )
+
+            manager.rollback("kimi", updated["rollback_id"])
+            self.assertTrue(removed_target.is_dir())
+            self.assertEqual(opc_adapters.tree_digest(removed_target), removed_hash)
+            self.assertIn(
+                removed_name,
+                {
+                    item["name"]
+                    for item in manager.store.read("kimi")["managed_targets"]
+                },
+            )
+
+    def test_kimi_rollback_rejects_post_operation_user_edit(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            source = self.copied_source(base)
+            manager = self.manager(base, FakeHosts(), source_root=source)
+            self.apply(manager, "kimi", "install")
+            changed = (
+                source
+                / "plugins"
+                / "codex-opc-team"
+                / "skills"
+                / "opc-manager"
+                / "SKILL.md"
+            )
+            changed.write_text(
+                changed.read_text(encoding="utf-8") + "\nUpdate marker.\n",
+                encoding="utf-8",
+            )
+            updated = self.apply(manager, "kimi", "update")
+            target = manager.adapters["kimi"]._target("opc-manager")
+            edit = target / "user-after-update.txt"
+            edit.write_text("preserve", encoding="utf-8")
+
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError,
+                "ROLLBACK_CONFLICT",
+            ):
+                manager.rollback("kimi", updated["rollback_id"])
+
+            self.assertEqual(edit.read_text(encoding="utf-8"), "preserve")
+
+    def test_codex_projection_key_includes_content_hash_and_claude_requires_exact_id(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            source = self.copied_source(base)
+            manager = self.manager(base, FakeHosts(), source_root=source)
+            codex = manager.adapters["codex"]
+            first = codex._codex_source()
+            skill = (
+                source
+                / "plugins"
+                / "codex-opc-team"
+                / "skills"
+                / "opc-manager"
+                / "SKILL.md"
+            )
+            skill.write_text(
+                skill.read_text(encoding="utf-8") + "\nContent revision.\n",
+                encoding="utf-8",
+            )
+            second = codex._codex_source()
+            self.assertNotEqual(first, second)
+            self.assertTrue(second.name.endswith(codex.content_hash[:16]))
+            self.assertFalse(
+                opc_adapters.ClaudeAdapter._is_installed(
+                    [{"name": "codex-opc-team"}]
+                )
+            )
+            self.assertTrue(
+                opc_adapters.ClaudeAdapter._is_installed(
+                    [{"id": "codex-opc-team@opc"}]
+                )
+            )
+
     def test_user_modified_target_fails_closed_and_preserves_edit(self):
         with tempfile.TemporaryDirectory() as directory:
             base = Path(directory)
@@ -660,17 +818,121 @@ def fail_cleanup(command, environment=None):
 
             manager.adapters["claude"].runner = fail_cleanup
             plan = manager.create_plan("claude", "install")
-            with self.assertRaisesRegex(opc_adapters.AdapterError, "ROLLBACK_FAILED"):
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError,
+                "ROLLBACK_FAILED",
+            ) as caught:
                 manager.apply(
                     plan_id=plan["plan_id"],
                     confirmation_token=plan["confirmation_token"],
                 )
+            self.assertIsNotNone(caught.exception.rollback_id)
             self.assertIsNone(manager.store.read("claude"))
             self.assertTrue(manager.adapters["claude"].marketplace_root.is_dir())
             self.assertTrue(fake.installed["claude"])
             self.assertEqual(fake.claude_plugin_data["sentinel"], "preserved")
             self.assertIn("unrelated-marketplace", fake.claude_marketplaces)
             self.assertTrue(cleanup_failed)
+            recovery = {
+                item["host_id"]: item
+                for item in manager.inventory()["hosts"]
+            }["claude"]["recovery"]
+            self.assertEqual(recovery["rollback_id"], caught.exception.rollback_id)
+            self.assertEqual(recovery["status"], "failed")
+
+            rolled_back = manager.rollback("claude", caught.exception.rollback_id)
+            self.assertEqual(rolled_back["state"], "rolled_back")
+            self.assertFalse(fake.installed["claude"])
+            self.assertNotIn(
+                "recovery",
+                {
+                    item["host_id"]: item
+                    for item in manager.inventory()["hosts"]
+                }["claude"],
+            )
+
+    def test_manifest_publication_failure_keeps_a_recoverable_operation(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            manager = self.manager(base, FakeHosts())
+            original_write = manager.store.write
+            injected = False
+
+            def fail_once(host_id, manifest):
+                nonlocal injected
+                if host_id == "kimi" and not injected:
+                    injected = True
+                    raise OSError("injected manifest publication failure")
+                return original_write(host_id, manifest)
+
+            manager.store.write = fail_once
+            plan = manager.create_plan("kimi", "install")
+            with self.assertRaisesRegex(
+                opc_adapters.AdapterError,
+                "APPLY_FAILED",
+            ) as caught:
+                manager.apply(
+                    plan_id=plan["plan_id"],
+                    confirmation_token=plan["confirmation_token"],
+                )
+            self.assertTrue(injected)
+            self.assertIsNotNone(caught.exception.rollback_id)
+            self.assertIsNone(manager.store.read("kimi"))
+            recovery = {
+                item["host_id"]: item
+                for item in manager.inventory()["hosts"]
+            }["kimi"]["recovery"]
+            self.assertEqual(recovery["rollback_id"], caught.exception.rollback_id)
+            self.assertEqual(recovery["status"], "failed")
+
+            rolled_back = manager.rollback("kimi", caught.exception.rollback_id)
+            self.assertEqual(rolled_back["state"], "rolled_back")
+            for name in manager.adapters["kimi"].skill_names:
+                self.assertFalse(manager.adapters["kimi"]._target(name).exists())
+
+    def test_same_host_applies_are_serialized_across_state_check_and_write(self):
+        with tempfile.TemporaryDirectory() as directory:
+            base = Path(directory)
+            manager = self.manager(base, FakeHosts())
+            first_plan = manager.create_plan("kimi", "install")
+            second_plan = manager.create_plan("kimi", "install")
+            adapter = manager.adapters["kimi"]
+            original = adapter.apply_operation
+            entered = threading.Event()
+            release = threading.Event()
+            calls = 0
+
+            def blocked_apply(operation, operation_id):
+                nonlocal calls
+                calls += 1
+                entered.set()
+                self.assertTrue(release.wait(timeout=10))
+                return original(operation, operation_id)
+
+            adapter.apply_operation = blocked_apply
+            outcomes: list[str] = []
+
+            def run(plan):
+                try:
+                    manager.apply(
+                        plan_id=plan["plan_id"],
+                        confirmation_token=plan["confirmation_token"],
+                    )
+                    outcomes.append("completed")
+                except opc_adapters.AdapterError as exc:
+                    outcomes.append(exc.code)
+
+            first = threading.Thread(target=run, args=(first_plan,))
+            second = threading.Thread(target=run, args=(second_plan,))
+            first.start()
+            self.assertTrue(entered.wait(timeout=10))
+            second.start()
+            release.set()
+            first.join(timeout=20)
+            second.join(timeout=20)
+
+            self.assertEqual(sorted(outcomes), ["PLAN_STATE_CHANGED", "completed"])
+            self.assertEqual(calls, 1)
 
     def test_claude_uninstall_rollback_install_failure_preserves_absent_prestate(self):
         with tempfile.TemporaryDirectory() as directory:
diff --git a/tests/unit/test_opc_app.py b/tests/unit/test_opc_app.py
index 0916fee..02845a9 100644
--- a/tests/unit/test_opc_app.py
+++ b/tests/unit/test_opc_app.py
@@ -298,6 +298,8 @@ def test_adapter_routes_keep_preview_and_apply_separate(self):
         class FakeManager:
             def __init__(self):
                 self.applied = False
+                self.fail_with_recovery = False
+                self.rolled_back = False
 
             def inventory(self):
                 return {
@@ -318,11 +320,26 @@ def create_plan(self, host_id, operation):
             def apply(self, *, plan_id, confirmation_token):
                 if confirmation_token != "confirm-safe":
                     raise opc_app.AdapterError("CONFIRMATION_REQUIRED")
+                if self.fail_with_recovery:
+                    raise opc_app.AdapterError(
+                        "ROLLBACK_FAILED",
+                        rollback_id="op-recover-safe",
+                    )
                 self.applied = True
                 return {
                     "schema_version": "opc-adapters.api.v1",
                     "host_id": "codex",
                     "state": "completed",
+                    "rollback_id": "op-complete-safe",
+                }
+
+            def rollback(self, host_id, rollback_id):
+                self.rolled_back = True
+                return {
+                    "schema_version": "opc-adapters.api.v1",
+                    "host_id": host_id,
+                    "state": "rolled_back",
+                    "rollback_id": rollback_id,
                 }
 
         with tempfile.TemporaryDirectory() as directory:
@@ -359,6 +376,47 @@ def apply(self, *, plan_id, confirmation_token):
                 self.assertEqual(status, 409)
                 self.assertEqual(error["error"], "CONFIRMATION_REQUIRED")
                 self.assertFalse(adapters.applied)
+                adapters.fail_with_recovery = True
+                status, error, _, _ = request(
+                    server,
+                    "POST",
+                    "/api/adapters/apply",
+                    headers=headers,
+                    payload={
+                        "plan_id": plan["plan_id"],
+                        "confirmation_token": plan["confirmation_token"],
+                    },
+                )
+                self.assertEqual(status, 409)
+                self.assertEqual(error["error"], "ROLLBACK_FAILED")
+                self.assertEqual(error["rollback_id"], "op-recover-safe")
+
+                adapters.fail_with_recovery = False
+                status, result, _, _ = request(
+                    server,
+                    "POST",
+                    "/api/adapters/apply",
+                    headers=headers,
+                    payload={
+                        "plan_id": plan["plan_id"],
+                        "confirmation_token": plan["confirmation_token"],
+                    },
+                )
+                self.assertEqual(status, 200)
+                self.assertEqual(result["rollback_id"], "op-complete-safe")
+                status, result, _, _ = request(
+                    server,
+                    "POST",
+                    "/api/adapters/rollback",
+                    headers=headers,
+                    payload={
+                        "host_id": "codex",
+                        "rollback_id": result["rollback_id"],
+                    },
+                )
+                self.assertEqual(status, 200)
+                self.assertEqual(result["state"], "rolled_back")
+                self.assertTrue(adapters.rolled_back)
 
     def test_context_is_redacted_and_security_boundaries_are_enforced(self):
         store = opc_app.DemoSettingsStore()
@@ -479,7 +537,13 @@ def test_complete_app_surface_is_local_and_has_distinct_views(self):
         self.assertIn('fetchJSON("/api/app-context")', javascript)
         self.assertIn('fetchJSON("/api/snapshot")', javascript)
         self.assertIn('fetchJSON("/api/adapters")', javascript)
+        self.assertIn('"/api/adapters/rollback"', javascript)
+        self.assertIn("adapter-rollback-confirm", javascript)
+        self.assertIn("dataset.adapterRollbackId", javascript)
         self.assertNotIn("innerHTML", javascript)
+        markup = (asset_root / "index.html").read_text(encoding="utf-8")
+        self.assertIn('id="adapter-rollback-dialog"', markup)
+        self.assertIn('id="confirm-adapter-rollback"', markup)
         self.assertIn(".filterable[hidden]", stylesheet)
         self.assertIn("display: none !important", stylesheet)