@inventec/dsh-copilot-auth 1.2.4 → 1.2.6

package/README.md

@@ -4,7 +4,7 @@
 [![npm](https://img.shields.io/npm/v/%40inventec%2Fdsh-copilot-auth?label=npm)](https://www.npmjs.com/package/@inventec/dsh-copilot-auth)
 [![CI](https://img.shields.io/github/actions/workflow/status/iasiv5/dsh-copilot-auth/ci.yml?branch=main&label=CI)](https://github.com/iasiv5/dsh-copilot-auth/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/iasiv5/dsh-copilot-auth?label=License)](https://github.com/iasiv5/dsh-copilot-auth/blob/main/LICENSE)
-[![DSH Web](https://img.shields.io/badge/DSH%20Web-0.1.7--rc.2%20%2F%200.2.0--rc.1%20verified-2563eb)](#前置要求)
+[![DSH](https://img.shields.io/badge/DSH-0.1.7--rc.2%20%7C%200.2.0--rc.1%2Frc.2%20verified-2563eb)](#前置要求)
 
 为 DSH（DeepSeek Harness）内置的 GitHub Copilot LLM provider 补上 Web 端设备码（device flow）登录/注销入口，并预置一条开箱即用的 GitHub Copilot 提供方路由。
 
@@ -19,20 +19,23 @@
 - 🔐 **设备码登录/注销**：网页 + user code，免 API Token；SSO 组织授权友好
 - 🧩 **预置提供方路由**：安装即出现在 Models 页，无需手动配置
 - 📦 **模型目录兜底填充**：登录成功时，若 GitHub Copilot 路由还没有模型目录，自动填入账号全部可用模型；你已精简/定制过的目录**永不覆盖**（重启、重新登录均不重置）
-- 🔄 **手动补充新模型目录条目**：GHC 设置页一键刷新——diff 预览 + 二次确认 + 数据级目录补丁（**pi-ai 版本不动**），新模型（如 gemini-3.8-flash）即可加入、失效模型镜像移除
+- 🔄 **手动补充新模型目录条目**：GHC 设置页一键刷新——diff 预览 + 二次确认；可写安装树走数据级目录补丁（**pi-ai 版本不动**），**只读安装树（desktop `app.asar`）走进程内目录注册表注入**（ADR 0003：零写盘、无需重启），新模型（如 `gpt-6.1-sol`）即可加入、失效模型镜像移除
 - 🌐 **中/英双语界面**：跟随 DSH 语言设置自动切换
 - 🔑 **凭据安全托管**：存入 DSH 内置凭据库（文件强制 0600 权限），Copilot 临时 token 到期自动刷新
-- 🧪 **测试与 CI**：107 条单元测试；GitHub Actions 构建测试 + tag 触发自动发布（provenance）
+- 🧪 **测试与 CI**：139 条单元测试（ubuntu/windows/macos 三平台矩阵）；GitHub Actions 构建测试 + tag 触发自动发布（provenance）
 
 ## 前置要求
 
-- DSH `0.1.7-rc.2` / `0.2.0-rc.1`（实测版本，v1.2.x 的适配目标；0.2.0 起注意插件 peer 精确版本守卫，见下文版本矩阵）
+- DSH `0.1.7-rc.2` / `0.2.0-rc.1` / `0.2.0-rc.2`（实测版本，v1.2.x 的适配目标；0.2.0 起注意插件 peer 精确版本守卫，见下文版本矩阵）
   - 版本矩阵：`0.1.2-rc.1` ～ `0.1.5-rc.2` 请用 **v1.1.x**（v1.2.0 移除了旧版必需的 authorization 挂载补丁，在旧版上无法激活）
   - v1.2.0 适配了 0.1.7 的 settings API 重塑（`settings.get` 移除），目录保护逻辑改走 `describe()`：**`describe()` 读取在 value 层缺失时回退 user 层，兼容旧版 describe 行形状**；DSH 版本支持矩阵见下表
 
 | 本插件 | DSH 实测版本 | authorization 服务 | 说明 |
 |---|---|---|---|
-| v1.2.x | `0.1.7-rc.2`+（`0.2.0-rc.1` 已实测通过） | runtime 内置，插件不挂载 | 适配 settings API 重塑后的 describe() 行形状 |
+| v1.2.6+ | `0.1.7-rc.2`+（`0.2.0-rc.1` web 与 `0.2.0-rc.2` desktop 已实测） | runtime 内置，插件不挂载 | **重启后自动恢复**：注入后以宿主 `listModels` 复核，未端出即同值触碰触发快照重建（修复 v1.2.5 的"重启后注入条目被宿主旧快照丢弃"）；`/status.settingsNotServed` 可直接诊断 |
+| v1.2.5 | `0.1.7-rc.2`+（`0.2.0-rc.1` web 与 `0.2.0-rc.2` desktop 已实测） | runtime 内置，插件不挂载 | **desktop 只读形态可刷新**：进程内目录注册表注入（ADR 0003），无需重启、不碰官方产物；`0.2.0-rc.2` desktop **实机端到端已验**（注入条目完成真实推理请求）；同批修复 pi-ai ≥0.99.0 的 `chat:` 目录键格式。**已知缺陷**：重启后若宿主快照先于注入定稿，注入条目会被丢弃（v1.2.6 修复） |
+| v1.2.4 | `0.1.7-rc.2`+（`0.2.0-rc.1` web 与 `0.2.0-rc.2` desktop 已实测） | runtime 内置，插件不挂载 | desktop asar 只读形态：目录刷新入口显式置灰（ADR 0002），登录/路由/settings 不受影响 |
+| v1.2.0 ～ v1.2.3 | `0.1.7-rc.2` ～ `0.2.0-rc.1`（web/服务形态） | runtime 内置，插件不挂载 | 适配 settings API 重塑后的 describe() 行形状；desktop asar 形态下目录刷新不可用且报错不友好 |
 | v1.1.x | `0.1.2-rc.1` ～ `0.1.5-rc.2` | 由 cordis.patch.yml insert 挂载 | v1.2.0 起移除该补丁，旧版 DSH 上无法激活 |
 
 - 有效的 GitHub Copilot 订阅（公司分配的 github.com 组织账号，SSO 登录）
@@ -75,13 +78,15 @@ dsh plugin --profile web add @inventec/dsh-copilot-auth
 
 pi-ai 的模型目录是打包时硬编码的 JSON：上游新增模型（如 gemini-3.8-flash）在本机无法解析、失效模型残留。「刷新可用模型目录」按钮（GHC 设置页，登录后可见）在不升级 pi-ai 的前提下解决这一问题。
 
-- **两阶段生效**：确认后先对本机 `github-copilot.json` 做原子数据级补丁（pi-ai 代码版本不变）；**重启 dsh web 后**插件再把 settings 模型目录镜像重建为「账号可用 ∩ 目录可解析」集合（目录在模块加载时读取，同 boot 内写完目录不会同步 settings）。
+- **生效时机按落地通道分叉**：可写安装树（web/服务）→ 先对本机 `github-copilot.json` 做原子数据级补丁（pi-ai 代码版本不变），**重启 dsh web 后**插件再把 settings 模型目录镜像重建为「账号可用 ∩ 目录可解析」集合（目录在模块加载时读取，同 boot 内写完目录不会同步 settings）；只读安装树（desktop `app.asar`）→ 进程内注册表注入（ADR 0003），**当次生效、无需重启**。
 - **diff 预览 + 二次确认**：弹窗展示新增（绿）/移除（红）/保留计数、被校验跳过的上游条目、以及**将被重置的定制名单**（字段微调与 modelOverrides）。确认前请核对三条风险：失效模型将消失、你的定制将被重置、需重启后才生效。
-- **激活边界**：插件首次安装/升级后处于未激活态，启动时不触碰 pi-ai 安装树；只有成功执行过一次手动刷新后才激活。DSH 升级冲掉补丁后，已激活实例启动时自愈重放**历史上实际应用过**的补丁条目（内置覆盖层仅作离线数据源，绝不自动应用）。
-- **数据源与回退**：账号可用模型现场拉取（失败回退凭证缓存）；目录数据从 npm 拉取最新 pi-ai tarball（强制 `dist.integrity` 校验、超时与大小上限、tar 严格解析），失败时可改用内置覆盖层（0.85.1 收割，integrity `sha512-+VgVIJDkDO2efYJKEEqvPTH4zmnIaXdAppGbO+vKFA9qy5PdhFiAenuFAkU+oiCSfOC4dMHDyrjdQeL4ZoC5CQ==`）出 diff。
+- **激活边界**：插件首次安装/升级后处于未激活态，启动时不触碰 pi-ai 安装树；只有成功执行过一次手动刷新后才激活。DSH 升级冲掉补丁后，已激活实例启动时自愈重放**历史上实际应用过**的补丁条目（内置覆盖层仅作离线数据源，绝不自动应用）。- **数据源与回退**：账号可用模型现场拉取（失败回退凭证缓存）；目录数据从 npm 拉取最新 pi-ai tarball（强制 `dist.integrity` 校验、超时与大小上限、tar 严格解析），失败时可改用内置覆盖层（0.85.1 收割，integrity `sha512-+VgVIJDkDO2efYJKEEqvPTH4zmnIaXdAppGbO+vKFA9qy5PdhFiAenuFAkU+oiCSfOC4dMHDyrjdQeL4ZoC5CQ==`）出 diff。
 - **只增不更新**：合并只补充本机从未见过的模型条目；上游对已有 id 的元数据修正（api 归属、contextWindow 等）不会同步——这是「永不覆盖」语义的代价（ADR 0001）。
 - **digest 绑定**：preview 与 apply 之间以输入 digest（settings 完整配置 / 可用模型 / 本地目录 / 目录来源）绑定，任何漂移即 409 并要求重新预览确认。
-- **可写性门禁（v1.2.4 起，ADR 0002）**：dsh-desktop（Electron）把整个运行时树打包进只读的 `resources/app.asar`，pi-ai 是其中唯一副本——读一切正常、写必被拒。插件在写盘前对目标做可写性分类（asar 路径识别 + 探针文件实测）：不可写时 preview/`/status` 暴露 `catalogWritable:false`、UI 置灰刷新入口并给出解释文案，apply 在 write-ahead **之前**以 400 `catalog-not-writable` 结构化快速失败（绝不留下 prepared journal）；boot 序列遇到只读目标同样不重试写盘，journal/overlay 原样保留，目标变可写（如桌面版改为解包 pi-ai）后恢复/自愈自动完成。Web/服务部署形态（pi-ai 在真实磁盘）行为不变。
+- **可写性门禁（v1.2.4 起，ADR 0002）**：dsh-desktop（Electron）把整个运行时树打包进只读的 `resources/app.asar`，pi-ai 是其中唯一副本——读一切正常、写必被拒。插件在写盘前对目标做可写性分类（asar 路径识别 + 探针文件实测）：不可写时 preview/`/status` 暴露 `catalogWritable:false`，**v1.2.4 起该形态按只读处理**（v1.2.3 及之前会抛 `ENOENT ... not found in ...app.asar` 天书并遗留 prepared journal）。Web/服务部署形态（pi-ai 在真实磁盘）行为不变。
+- **只读安装树的落地通道（v1.2.5 起，ADR 0003）**：只读目标不再意味着"刷新不可用"。写入面换成了 pi-ai 的**进程内目录注册表**（`MODELS["github-copilot"]`，DSH 每次构建快照都现读它）：插件把增量条目注入该对象，内置 `GitHub Copilot` 路由即把新模型端出来——OAuth 凭据、消息翻译、三协议分派（按条目自带的 `api`）、picker/设置页全部复用既有链路，**不新增路由、不改宿主任何文件、不碰官方安装树、无需重启**。注入成功才写 settings，随后用 `ctx.llm.listModels` 端到端自证；任一条目端不出来即**回滚 settings** 并返回 500 `registry-not-effective`（绝不产出"能选中但发不出去"的假模型）。注册表面不可用（模块加载失败 / 注册表被冻结 / 条目非法）一律结构化报错并保留 journal，可 grep `registry-*`。`/status` 的 `catalogMode`（`file`|`registry`）与 `registryInjected` 可观测。**可写安装树完全不加载注册表面**，web 形态零新增副作用。
+- **远端目录形状规范化（v1.2.5 起）**：pi-ai ≥0.99.0 把目录 JSON 的键改成 `chat:<内层裸 id>`（运行时仍按裸 id 编键）。插件在 preview/apply 共用的取数层统一规范化回裸 id 形状，并跳过键与内层 id 冲突的条目——**不规范化时刷新会"拿到新目录却一个条目都加不进来"**，这条修复对 Web/服务形态同样生效。
+- **重启后的自愈与快照时序（v1.2.6 起）**：注册表注入只活在进程里，重启后由启动序列（boot1）重放。但 `dsh-llm-pi-ai` 在**挂载时**就把目录解析结果定稿并 memoize（只在 settings 配置对象身份变化时重建），而插件挂载晚于它——boot 期注入可能落在快照之后，表现为"settings 里还有该模型、picker 里却看不到"。v1.2.6 起注入后会用**宿主自己的** `listModels` 复核；缺失即对该路由 `models` 做一次**同值触碰**（写回与当前完全相同的值，只改配置对象身份、不改用户内容）触发重建，再复核。仍端不出来时记可 grep 的 `lastError: registry-not-served: <ids>`，并把结果暴露在 `/status.settingsNotServed`（宿主 API 不可用时为 `null`）。用户没引用的条目一律不触碰 settings——启动期不写用户配置的原则不破。
 
 ## 工作原理
 
@@ -96,7 +101,7 @@ pi-ai 的模型目录是打包时硬编码的 JSON：上游新增模型（如 ge
 
 ```bash
 npm install
-npm test        # node:test：patch 结构 + host/目录/状态机/启动序列/可写性门禁共 114 条（CI 跑 ubuntu/windows/macos 三平台矩阵）
+npm test        # node:test：patch 结构 + host/目录/状态机/启动序列/可写性门禁/注册表注入 共 139 条（CI 跑 ubuntu/windows/macos 三平台矩阵）
 npm run build   # esbuild 打包 client 到 lib/client.js（__ModuleLoader__ 信封）
 npm pack --dry-run
 ```
@@ -105,6 +110,7 @@ npm pack --dry-run
 |---|---|
 | `cordis.patch.yml` | 两段 patch（本插件 entry / 预置路由；authorization 服务 0.1.7+ 由 runtime 内置，不再挂载） |
 | `src/host.mjs` · `src/shared.mjs` | host 半区：登录状态机、6 条本地路由、模型目录同步、刷新 preview/apply 与启动序列 |
+| `src/catalog-registry.mjs` | 只读安装树的落地通道：进程内目录注册表注入（ADR 0003） |
 | `src/client.jsx` | client 半区：settings.section 插槽 + 设备码交互 + 双语文案 |
 | `scripts/build-client.mjs` | client 打包（`__ModuleLoader__` CJS 工厂信封） |
 | `lib/client.js` | 构建产物（入库，使 git 安装免构建） |
@@ -124,9 +130,9 @@ npm pack --dry-run
 - 路由前缀 `/copilot-auth` 两侧硬编码，不可配置
 - DSH rc 版本耦合：实测 `0.1.7-rc.2` 与 `0.2.0-rc.1`（v1.2.x；`0.1.2-rc.1` 由 v1.1.x 实测），peer 仅 `@deepseek-ai/cordis@^4.0.2`
 - 模型目录只在「尚不存在」时由登录成功兜底填充一次，填充后归用户所有：账号新增的模型不会自动出现——用 GHC 设置页的「**刷新可用模型目录**」同步（见上节），或在 Models 页手动添加
-- 模型目录只写入 pi-ai 内置目录已描述的模型：目录快照外的新模型需先经「刷新可用模型目录」补入目录条目（数据级补丁，pi-ai 版本不变）才会出现在可选列表
+- 模型目录只写入「可解析」的模型：目录快照外的新模型须先经「刷新可用模型目录」补入——可写安装树补进目录文件、只读安装树（desktop）注入进程内注册表（ADR 0003），两条通道都保持 pi-ai 版本不变
 - DSH 升级后自愈仅在 pi-ai 基线版本不变（0.84.4）时重放；跨版本且条目未原生存在时上报 `self-heal-incompatible`，不修改安装树（重新执行一次手动刷新即可在新基线上激活）
-- **dsh-desktop（Electron 桌面版）无法刷新模型目录**：运行时树（含 pi-ai 唯一副本）打包在只读的 `app.asar` 内，数据级目录补丁物理不可写。v1.2.4 起该形态被显式识别：刷新入口置灰 + `catalog-not-writable` 结构化报错（v1.2.3 及之前会抛 `ENOENT ... not found in ...app.asar` 天书并遗留 prepared journal）。登录/注销/settings 模型目录镜像不受影响；目录刷新请用 Web/服务部署形态（ADR 0002）
+- **dsh-desktop（Electron 桌面版）可刷新模型目录（v1.2.5 起）**：运行时树打包在只读的 `app.asar` 内，写盘通道物理不可用，但刷新改走进程内目录注册表注入（ADR 0003）——当次生效、无需重启、不碰官方产物；重启后由启动序列重放，并按 v1.2.6 的复核/同值触碰机制保证路由真的端出这些模型。前提是该进程的 pi-ai 目录注册表形态与实测一致（`MODELS[provider]` 未冻结、扁平、键=模型 id）；上游改形状时注入守卫会拦下并报 `registry-*` 结构化错误，模型列表保持原样（不写 settings）。v1.2.4 及之前该形态只能置灰刷新入口（`catalog-not-writable`，另见 ADR 0002）
 - 并发保护为宿主单进程内 mutex，**不支持多实例/多进程并发刷新**
 - 状态落盘后的目录 fsync 仅在 POSIX 执行：Windows 无目录 fsync 语义（对目录句柄 fsync 必然 `EPERM`），win32 直接跳过、不再刷告警，目录项一致性由 NTFS 元数据日志保证（v1.2.3 起，issue #1）；POSIX 行为不变
 

package/lib/client.js

@@ -44,7 +44,7 @@ var routes = () => ({
 });
 
 // src/refresh-flow.mjs
-var initial = Object.freeze({ name: "idle", catalogWritable: null });
+var initial = Object.freeze({ name: "idle", catalogWritable: null, catalogMode: null });
 function reduce(state, event) {
   switch (state.name) {
     case "idle":
@@ -60,10 +60,11 @@ function reduce(state, event) {
         if (!event.status) return [state, null];
         if (refresh?.lastError === "state-corrupt") return [{ name: "failed", error: "state-corrupt" }, null];
         if (refresh?.pendingRestart === true) {
-          return [{ name: "restartNeeded", catalogWritable: refresh?.catalogWritable ?? null }, null];
+          return [{ name: "restartNeeded", catalogWritable: refresh?.catalogWritable ?? null, catalogMode: refresh?.catalogMode ?? null }, null];
         }
         const writable = refresh && "catalogWritable" in refresh ? refresh.catalogWritable : state.catalogWritable ?? null;
-        return [{ ...state, catalogWritable: writable }, null];
+        const mode = refresh && "catalogMode" in refresh ? refresh.catalogMode : state.catalogMode ?? null;
+        return [{ ...state, catalogWritable: writable, catalogMode: mode }, null];
       }
       return [state, null];
     }
@@ -88,7 +89,9 @@ function reduce(state, event) {
       return [state, null];
     }
     case "applying": {
-      if (event.type === "apply-ok") return [{ name: "restartNeeded" }, null];
+      if (event.type === "apply-ok") {
+        return event.restartRequired === false ? [{ name: "applied", mode: event.mode ?? null, injected: event.injected ?? 0 }, null] : [{ name: "restartNeeded", catalogMode: state.catalogMode ?? null }, null];
+      }
       if (event.type === "apply-stale") {
         return [{ name: "previewing", mode: state.mode, stale: true }, { type: "preview", mode: state.mode }];
       }
@@ -123,7 +126,12 @@ async function runEffect(effect, fetchImpl) {
       });
       const body = await res.json().catch(() => null);
       if (res.status === 409) return { type: "apply-stale" };
-      return res.status === 200 && body?.ok ? { type: "apply-ok" } : { type: "apply-fail", error: body?.error ?? `HTTP ${res.status}` };
+      return res.status === 200 && body?.ok ? {
+        type: "apply-ok",
+        restartRequired: body.restartRequired !== false,
+        mode: body.mode ?? null,
+        injected: Array.isArray(body.injected) ? body.injected.length : 0
+      } : { type: "apply-fail", error: body?.error ?? `HTTP ${res.status}` };
     } catch (err) {
       return { type: "apply-fail", error: String(err?.message ?? err) };
     }
@@ -196,7 +204,11 @@ var DICTS = {
     srcLocal: "Catalog source: local only (npm fetch failed)",
     srcOverlay: "Catalog source: bundled overlay (offline bootstrap)",
     none: "(none)",
-    notWritable: "This DSH installation packages the model catalog read-only (inside app.asar) \u2014 the refresh cannot be written. Use a web/service deployment for catalog refresh, or wait for a desktop build that unpacks pi-ai."
+    notWritable: "This DSH installation packages the model catalog read-only (inside app.asar) \u2014 the refresh cannot be written. Use a web/service deployment for catalog refresh, or wait for a desktop build that unpacks pi-ai.",
+    registryMode: "This installation's app.asar is read-only, so the refresh does not write the catalog file: new entries are injected into the running catalog registry instead. No restart needed.",
+    registryApplied: "Injected %s new model(s) into the running catalog \u2014 live now. The boot sequence replays them after a restart.",
+    registryFailed: "Catalog registry injection failed \u2014 nothing was written and your model list was left unchanged.",
+    riskImmediate: "Takes effect immediately in this process (registry injection); the boot sequence replays it after a restart."
   },
   zh: {
     nav: "GHC\u8BBE\u7F6E",
@@ -240,10 +252,20 @@ var DICTS = {
     srcLocal: "\u76EE\u5F55\u6765\u6E90\uFF1A\u4EC5\u672C\u5730\u76EE\u5F55\uFF08npm \u62C9\u53D6\u5931\u8D25\uFF09",
     srcOverlay: "\u76EE\u5F55\u6765\u6E90\uFF1A\u5185\u7F6E\u8986\u76D6\u5C42\uFF08\u79BB\u7EBF bootstrap\uFF09",
     none: "\uFF08\u65E0\uFF09",
-    notWritable: "\u5F53\u524D DSH \u5B89\u88C5\u628A\u6A21\u578B\u76EE\u5F55\u6253\u5305\u5728\u53EA\u8BFB\u7684 app.asar \u5185\uFF0C\u5237\u65B0\u65E0\u6CD5\u5199\u5165\u3002\u8BF7\u5728 Web/\u670D\u52A1\u90E8\u7F72\u5F62\u6001\u4E0B\u5237\u65B0\u76EE\u5F55\uFF0C\u6216\u7B49\u5F85\u684C\u9762\u7248\u63D0\u4F9B\u53EF\u5199\u5E03\u5C40\u540E\u91CD\u8BD5\u3002"
+    notWritable: "\u5F53\u524D DSH \u5B89\u88C5\u628A\u6A21\u578B\u76EE\u5F55\u6253\u5305\u5728\u53EA\u8BFB\u7684 app.asar \u5185\uFF0C\u5237\u65B0\u65E0\u6CD5\u5199\u5165\u3002\u8BF7\u5728 Web/\u670D\u52A1\u90E8\u7F72\u5F62\u6001\u4E0B\u5237\u65B0\u76EE\u5F55\uFF0C\u6216\u7B49\u5F85\u684C\u9762\u7248\u63D0\u4F9B\u53EF\u5199\u5E03\u5C40\u540E\u91CD\u8BD5\u3002",
+    registryMode: "\u5F53\u524D\u5B89\u88C5\u7684 app.asar \u53EA\u8BFB\uFF0C\u5237\u65B0\u4E0D\u5199\u76EE\u5F55\u6587\u4EF6\uFF1A\u65B0\u6761\u76EE\u76F4\u63A5\u6CE8\u5165\u8FD0\u884C\u4E2D\u7684\u76EE\u5F55\u6CE8\u518C\u8868\u3002\u65E0\u9700\u91CD\u542F\u3002",
+    registryApplied: "\u5DF2\u5411\u8FD0\u884C\u4E2D\u7684\u76EE\u5F55\u6CE8\u5165 %s \u4E2A\u65B0\u6A21\u578B\u2014\u2014\u5373\u523B\u751F\u6548\uFF1B\u91CD\u542F\u540E\u7531\u542F\u52A8\u5E8F\u5217\u81EA\u52A8\u91CD\u653E\u3002",
+    registryFailed: "\u76EE\u5F55\u6CE8\u518C\u8868\u6CE8\u5165\u5931\u8D25\u2014\u2014\u672A\u5199\u5165\u4EFB\u4F55\u5185\u5BB9\uFF0C\u6A21\u578B\u5217\u8868\u4FDD\u6301\u539F\u6837\u3002",
+    riskImmediate: "\u672C\u8FDB\u7A0B\u5185\u5373\u523B\u751F\u6548\uFF08\u6CE8\u518C\u8868\u6CE8\u5165\uFF09\uFF1B\u91CD\u542F\u540E\u7531\u542F\u52A8\u5E8F\u5217\u81EA\u52A8\u91CD\u653E\u3002"
   }
 };
 var NAV_TEXTS = Object.keys(DICTS).map((locale) => DICTS[locale].nav);
+function isRegistryMode(flags) {
+  return flags?.catalogWritable === false && flags?.catalogMode === "registry";
+}
+function refreshBlocked(flags) {
+  return flags?.catalogWritable === false && flags?.catalogMode !== "registry";
+}
 var COPILOT_ICON_SVG = '<svg aria-hidden="true" width="16" height="16" viewBox="0 0 16 16" fill="currentColor" style="flex:none"><path d="M7.998 15.035c-4.562 0-7.873-2.914-7.998-3.749V9.338c.085-.628.677-1.686 1.588-2.065.013-.07.024-.143.036-.218.029-.183.06-.384.126-.612-.201-.508-.254-1.084-.254-1.656 0-.87.128-1.769.693-2.484.579-.733 1.494-1.124 2.724-1.261 1.206-.134 2.262.034 2.944.765.05.053.096.108.139.165.044-.057.094-.112.143-.165.682-.731 1.738-.899 2.944-.765 1.23.137 2.145.528 2.724 1.261.566.715.693 1.614.693 2.484 0 .572-.053 1.148-.254 1.656.066.228.098.429.126.612.924.385 1.522 1.471 1.591 2.095v1.872c0 .766-3.351 3.795-8.002 3.795Zm0-1.485c2.28 0 4.584-1.11 5.002-1.433V7.862l-.023-.116c-.49.21-1.075.291-1.727.291-1.146 0-2.059-.327-2.71-.991A3.222 3.222 0 0 1 8 6.303a3.24 3.24 0 0 1-.544.743c-.65.664-1.563.991-2.71.991-.652 0-1.236-.081-1.727-.291l-.023.116v4.255c.419.323 2.722 1.433 5.002 1.433ZM6.762 2.83c-.193-.206-.637-.413-1.682-.297-1.019.113-1.479.404-1.713.7-.247.312-.369.789-.369 1.554 0 .793.129 1.171.308 1.371.162.181.519.379 1.442.379.853 0 1.339-.235 1.638-.54.315-.322.527-.827.617-1.553.117-.935-.037-1.395-.241-1.614Zm4.155-.297c-1.044-.116-1.488.091-1.681.297-.204.219-.359.679-.242 1.614.091.726.303 1.231.618 1.553.299.305.784.54 1.638.54.922 0 1.28-.198 1.442-.379.179-.2.308-.578.308-1.371 0-.765-.123-1.242-.37-1.554-.233-.296-.693-.587-1.713-.7Z"/><path d="M6.25 9.037a.75.75 0 0 1 .75.75v1.501a.75.75 0 0 1-1.5 0V9.787a.75.75 0 0 1 .75-.75Zm4.25.75v1.501a.75.75 0 0 1-1.5 0V9.787a.75.75 0 0 1 1.5 0Z"/></svg>';
 function enforceNavIcon(labelText) {
   if (!labelText) return;
@@ -425,11 +447,15 @@ function RefreshModal({ t, flow, onConfirm, onCancel, onOverlay }) {
       "\u26A0 ",
       t("riskReset")
     ] }),
-    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.risk, children: [
+    isRegistryMode(p) ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: styles.modalText, children: t("riskImmediate") }) : /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.risk, children: [
       "\u26A0 ",
       t("riskRestart")
     ] }),
-    p.catalogWritable === false && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.error, children: [
+    isRegistryMode(p) && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.banner, children: [
+      "\u24D8 ",
+      t("registryMode")
+    ] }),
+    refreshBlocked(p) && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.error, children: [
       "\u26A0 ",
       t("notWritable")
     ] }),
@@ -440,8 +466,8 @@ function RefreshModal({ t, flow, onConfirm, onCancel, onOverlay }) {
         "button",
         {
           type: "button",
-          style: { ...styles.button, ...styles.primary, ...p.catalogWritable === false ? { opacity: 0.5, cursor: "not-allowed" } : null },
-          disabled: p.catalogWritable === false,
+          style: { ...styles.button, ...styles.primary, ...refreshBlocked(p) ? { opacity: 0.5, cursor: "not-allowed" } : null },
+          disabled: refreshBlocked(p),
           onClick: onConfirm,
           children: t("confirmRefresh")
         }
@@ -569,22 +595,27 @@ function CopilotSection({ t = (key) => DICTS.en[key] ?? key }) {
         "button",
         {
           type: "button",
-          style: { ...styles.button, ...styles.primary, ...flow.catalogWritable === false ? { opacity: 0.5, cursor: "not-allowed" } : null },
-          disabled: flow.catalogWritable === false || flow.name === "previewing" || flow.name === "applying",
+          style: { ...styles.button, ...styles.primary, ...refreshBlocked(flow) ? { opacity: 0.5, cursor: "not-allowed" } : null },
+          disabled: refreshBlocked(flow) || flow.name === "previewing" || flow.name === "applying",
           onClick: () => drive({ type: "start" }),
           children: flow.name === "previewing" ? t("refreshing") : flow.name === "applying" ? t("applying") : t("refreshNow")
         }
       )
     ] }),
-    page === "authorized" && flow.catalogWritable === false && flow.name !== "failed" && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.banner, children: [
+    page === "authorized" && isRegistryMode(flow) && flow.name !== "failed" && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.banner, children: [
+      "\u24D8 ",
+      t("registryMode")
+    ] }),
+    page === "authorized" && refreshBlocked(flow) && flow.name !== "failed" && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.banner, children: [
       "\u26A0 ",
       t("notWritable")
     ] }),
+    page === "authorized" && flow.name === "applied" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: styles.banner, children: t("registryApplied").replace("%s", String(flow.injected ?? 0)) }),
     page === "authorized" && flow.name === "restartNeeded" && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("p", { style: styles.banner, children: [
       "\u26A0 ",
       t("restartNeeded")
     ] }),
-    page === "authorized" && flow.name === "failed" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: styles.error, children: flow.error === "state-corrupt" ? t("stateCorrupt") : flow.error === "catalog-not-writable" ? t("notWritable") : flow.error }),
+    page === "authorized" && flow.name === "failed" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: styles.error, children: flow.error === "state-corrupt" ? t("stateCorrupt") : flow.error === "catalog-not-writable" ? t("notWritable") : flow.error === "registry-inject-failed" || flow.error === "registry-not-effective" ? t("registryFailed") : flow.error }),
     flow.name === "confirming" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
       RefreshModal,
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inventec/dsh-copilot-auth",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "为内置 Copilot 提供方补设备码登录/注销设置页，预置开箱路由；凭据入内置凭据库，模型目录兜底不覆盖定制。适配 DSH 0.1.7+（settings API 重塑后；≤0.1.5 请用 1.1.x）。",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
     "README.md",
     "LICENSE",
     "src/catalog.mjs",
+    "src/catalog-registry.mjs",
     "src/catalog-fetch.mjs",
     "src/copilot-models.mjs",
     "src/atomic-json.mjs",

package/src/catalog-registry.mjs

@@ -0,0 +1,144 @@
+// catalog-registry.mjs — desktop/asar「只读安装树」的不写盘通道（ADR 0003）。
+//
+// 背景：dsh-desktop（Electron）把整个运行时打进只读 app.asar，数据级目录补丁
+// （ADR 0001）无法写 `.../pi-ai/dist/providers/data/github-copilot.json`。但 pi-ai
+// 的目录在进程内还有第二个可用面：`MODELS["github-copilot"]`（即
+// `GITHUB_COPILOT_MODELS`，一个未冻结的普通对象，键 = 模型 id），而 DSH 的
+// `catalogModels()` 每次构建快照都现读它（`Object.values(MODELS[provider])`）。
+//
+// 把增量条目注入这个对象，内置 github-copilot 路由就会把新模型端出来：鉴权
+// （OAuth 凭据记录）、DSH↔pi-ai 消息翻译、三协议分派、picker/设置页全部复用宿主
+// 既有链路——不新增路由、不写任何文件、不改任何官方产物。
+//
+// 三条硬约束（ADR 0003）：
+//   1. 注入后必须能被 getBuiltinModels() 看见，否则报告失败；调用方**不得**把该
+//      id 写进 settings——绝不产出"能选中但发不出去"的假模型；
+//   2. 条目按本机目录已见过的字段集合裁剪（pi-ai ≥0.99.0 新增 `type: "chat"` 之类
+//      的字段不进旧运行时的模型对象）；
+//   3. 全程 try/catch，任何失败只返回报告，绝不抛出、绝不阻断插件挂载。
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { validateCatalog, findPiAiInstallation, trimEntryToShape } from "./catalog.mjs";
+
+// 注入面只服务内置 github-copilot 路由（其他 provider 无既有凭据/翻译链路复用）。
+export const REGISTRY_ROUTE = "github-copilot";
+
+// 裸 specifier：由宿主 dsh-app-boot 的解析拦截路由到安装树内的同一份包，模块实例
+// 与宿主完全同一（首选）；asar 绝对路径 file URL 为退路（A2/A3 探针已验证可加载，
+// 但模块实例是否与宿主同一需要 getBuiltinModels 回读确认）。
+const MODELS_SPECIFIER = "@earendil-works/pi-ai/providers/github-copilot.models";
+const ALL_SPECIFIER = "@earendil-works/pi-ai/providers/all";
+
+const MODELS_ENTRY = join("providers", "github-copilot.models.js");
+const ALL_ENTRY = join("providers", "all.js");
+
+// catalogFile = <root>/dist/providers/data/github-copilot.json → <root>/dist
+export function registryDistDir(install) {
+  return dirname(dirname(dirname(install.catalogFile)));
+}
+
+// 依次尝试「裸 specifier → 绝对路径 file URL」加载目录注册表模块。
+// 两条路的返回都做形状校验：注册表必须是可写对象、getBuiltinModels 必须是函数。
+export async function loadRegistryModules(install, log) {
+  const dist = registryDistDir(install);
+  const attempts = [
+    { via: "bare", models: MODELS_SPECIFIER, all: ALL_SPECIFIER },
+    {
+      via: "file",
+      models: pathToFileURL(join(dist, MODELS_ENTRY)).href,
+      all: pathToFileURL(join(dist, ALL_ENTRY)).href,
+    },
+  ];
+  const errors = [];
+  for (const attempt of attempts) {
+    try {
+      const models = await import(attempt.models);
+      const all = await import(attempt.all);
+      const registry = models?.GITHUB_COPILOT_MODELS;
+      if (!registry || typeof registry !== "object" || Object.isFrozen(registry)) {
+        throw new TypeError(`registry object unusable (frozen=${Object.isFrozen(registry)})`);
+      }
+      if (typeof all?.getBuiltinModels !== "function") {
+        throw new TypeError("getBuiltinModels unavailable");
+      }
+      return { via: attempt.via, registry, all, errors };
+    } catch (err) {
+      errors.push(`${attempt.via}: ${err?.code ?? ""} ${err?.message ?? err}`.trim());
+    }
+  }
+  log?.(`copilot-auth: registry modules unavailable — ${errors.join(" | ")}`);
+  return { via: null, registry: null, all: null, errors };
+}
+
+// 注入 catalog-shaped 增量（{ api: { id: entry } }），返回报告对象（绝不抛）。
+// 已存在的 id（原生条目或本进程早前注入）视为成功，不覆盖——与目录补丁的
+// 「只增不更新」语义一致（ADR 0001）。
+export async function injectCatalogEntries(install, overlay, { log, allowedKeys } = {}) {
+  const wanted = [];
+  for (const [api, section] of Object.entries(overlay ?? {})) {
+    for (const [id, entry] of Object.entries(section ?? {})) wanted.push({ api, id, entry });
+  }
+  if (wanted.length === 0) {
+    return { ok: true, via: null, injected: [], present: [], rejected: [], missing: [], reason: null, errors: [] };
+  }
+  const modules = await loadRegistryModules(install, log);
+  if (!modules.via) {
+    return { ok: false, via: null, injected: [], present: [], rejected: [], missing: [], reason: "registry-modules-unavailable", errors: modules.errors };
+  }
+  const injected = [];
+  const present = [];
+  const rejected = [];
+  for (const { api, id, entry } of wanted) {
+    if (modules.registry[id] !== undefined) {
+      present.push(id);
+      continue;
+    }
+    const trimmed = trimEntryToShape(entry, allowedKeys);
+    const why = validateCatalog(api, id, trimmed);
+    if (why !== true) {
+      rejected.push({ api, id, reason: why });
+      continue;
+    }
+    modules.registry[id] = trimmed;
+    injected.push(id);
+  }
+  const visible = new Set(modules.all.getBuiltinModels(REGISTRY_ROUTE).map((m) => m?.id).filter(Boolean));
+  const missing = [...injected, ...present].filter((id) => !visible.has(id));
+  const ok = missing.length === 0 && rejected.length === 0;
+  if (!ok) {
+    log?.(
+      `copilot-auth: registry inject incomplete (via=${modules.via}) injected=${injected.length} missing=${missing.join(",") || "-"} rejected=${rejected.map((r) => `${r.id}:${r.reason}`).join(",") || "-"}`,
+    );
+  }
+  return {
+    ok,
+    via: modules.via,
+    injected,
+    present,
+    rejected,
+    missing,
+    reason: ok ? null : missing.length > 0 ? "not-visible-after-inject" : "invalid-entries",
+    errors: modules.errors,
+  };
+}
+
+// 当前注册表里 github-copilot 的模型 id 集合（注入面的事实来源；不可用时 null）。
+export async function registryModelIds(install, log) {
+  const modules = await loadRegistryModules(install, log);
+  if (!modules.via) return null;
+  try {
+    return new Set(modules.all.getBuiltinModels(REGISTRY_ROUTE).map((m) => m?.id).filter(Boolean));
+  } catch (err) {
+    log?.(`copilot-auth: registry read failed — ${String(err?.message ?? err)}`);
+    return null;
+  }
+}
+
+// 便捷入口：从进程入口定位安装树后注入。
+export async function injectIntoInstallation(overlay, { startPath, log, allowedKeys } = {}) {
+  const install = findPiAiInstallation({ startPath });
+  if (!install) {
+    return { ok: false, via: null, injected: [], present: [], rejected: [], missing: [], reason: "pi-ai-installation-not-found", errors: [] };
+  }
+  return injectCatalogEntries(install, overlay, { log, allowedKeys });
+}

package/src/catalog.mjs

@@ -100,6 +100,74 @@ export function mergeCatalog(local, remote) {
   return { merged, added, addedOverlay, skipped };
 }
 
+// ==================== 远端目录的形状规范化（pi-ai ≥0.99.0 的 chat: 键） ====================
+// pi-ai ≥0.99.0（实测 0.99.2 / 1.0.0，两份字节相同）把目录 JSON 的键改成
+// `chat:<内层裸 id>`（flattenChatModelCatalog 的产物）：这不是改名——运行时仍按条目
+// 内层的裸 id 编键，github-copilot 的 filterModels 也按裸 id 与账号可用集匹配。
+// 本模块的 mergeCatalog/validateCatalog 假定「键 == 条目内层 id」，因此远端目录
+// 必须先规范化回三段式裸 id 形状，两个世代的语义才一致。
+export const CHAT_KEY_PREFIX = "chat:";
+
+// 把远端目录（0.87.x 裸键 / ≥0.99.0 `chat:` 键）规范化为 `{ api: { 裸id: entry } }`。
+// 条目内层 id 与键冲突的条目一律跳过并记录（宁可少一个模型，不可写坏目录）。
+// allowedKeys 非空时按本机目录已见字段集合裁剪（见 trimEntryToShape）。
+// 返回 { catalog, renamed, skipped }。
+export function normalizeRemoteCatalog(data, { allowedKeys } = {}) {
+  const catalog = {};
+  const skipped = [];
+  let renamed = 0;
+  for (const [api, section] of Object.entries(data ?? {})) {
+    if (!section || typeof section !== "object" || Array.isArray(section)) {
+      skipped.push({ api, id: null, reason: "section is not an object" });
+      continue;
+    }
+    for (const [key, entry] of Object.entries(section)) {
+      const prefixed = key.startsWith(CHAT_KEY_PREFIX);
+      const id = prefixed ? key.slice(CHAT_KEY_PREFIX.length) : key;
+      if (id.length === 0) {
+        skipped.push({ api, id: key, reason: "empty id after prefix strip" });
+        continue;
+      }
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        skipped.push({ api, id, reason: "entry is not an object" });
+        continue;
+      }
+      if (typeof entry.id === "string" && entry.id !== id) {
+        skipped.push({ api, id, reason: `id mismatch: key=${key} entry.id=${entry.id}` });
+        continue;
+      }
+      if (prefixed) renamed += 1;
+      (catalog[api] ??= {})[id] = trimEntryToShape(entry, allowedKeys);
+    }
+  }
+  return { catalog, renamed, skipped };
+}
+
+// 把条目裁剪到本机运行时已见过的字段集合（allowedKeys 来自 catalogShapeKeys）。
+// 典型漂移：≥0.99.0 的条目多一个 `type: "chat"`，0.87.x 的模型对象里没有这个概念。
+// allowedKeys 为空集时不裁剪——拿不到参考形状时宁可不裁剪，也不误删必需字段。
+export function trimEntryToShape(entry, allowedKeys) {
+  if (!allowedKeys || allowedKeys.size === 0) return { ...entry };
+  const out = {};
+  for (const [k, v] of Object.entries(entry)) {
+    if (allowedKeys.has(k)) out[k] = v;
+  }
+  return out;
+}
+
+// 本机目录条目的字段并集——注入/规范化条目的裁剪基准。
+export function catalogShapeKeys(localCatalog) {
+  const keys = new Set();
+  for (const section of Object.values(localCatalog ?? {})) {
+    for (const entry of Object.values(section ?? {})) {
+      if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+        for (const k of Object.keys(entry)) keys.add(k);
+      }
+    }
+  }
+  return keys;
+}
+
 // R3：removed 以 target 为准，不以 available 为准——available 但目录不可解析的
 // 当前模型必须进 removed（settings 校验拒绝目录外 id，保留必报错）。
 export function diffModels(currentIds, availableIds, catalogIds) {

package/src/host.mjs

@@ -8,8 +8,9 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { CREDENTIAL_KEY, emptyState, routes } from "./shared.mjs";
 import { readJson, writeJsonAtomic, createMutex } from "./atomic-json.mjs";
-import { mergeCatalog, diffModels, digest, findPiAiInstallation, classifyCatalogTarget } from "./catalog.mjs";
+import { mergeCatalog, diffModels, digest, findPiAiInstallation, classifyCatalogTarget, normalizeRemoteCatalog, catalogShapeKeys } from "./catalog.mjs";
 import { fetchLatestCatalog } from "./catalog-fetch.mjs";
+import { injectCatalogEntries, registryModelIds } from "./catalog-registry.mjs";
 import { fetchLiveAvailableModelIds } from "./copilot-models.mjs";
 import { loadState, saveState, freshState, createJournal, advanceJournal, restartMarker, setLastError, clearLastError } from "./state.mjs";
 
@@ -35,20 +36,28 @@ function findCatalogFile() {
   return null;
 }
 
-// 读取 pi-ai 内置目录的 github-copilot 模型 id → 协议映射。只读不改。
-// 定位/解析失败返回 null（调用方回退 listModels 交集，见下）。
-function readCatalogModelIds() {
+// 读取 github-copilot 的「可解析模型 id → 协议」映射。只读不改。
+// 两个来源的并集：① 安装树内的目录数据文件；② 进程内目录注册表（ADR 0003——desktop
+// 只读安装树下，刷新出来的增量条目只存在于注册表，目录文件里永远看不到）。两者都
+// 拿不到才返回 null（调用方回退 listModels 交集）。
+async function readCatalogModelIds(install, log) {
+  const byId = {};
   try {
-    const dataFile = findCatalogFile();
-    if (!dataFile) return null;
-    const data = JSON.parse(readFileSync(dataFile, "utf8"));
-    const byId = {};
-    for (const [api, section] of Object.entries(data)) {
-      for (const id of Object.keys(section ?? {})) byId[id] ??= api;
+    const dataFile = install?.catalogFile ?? findCatalogFile();
+    if (dataFile) {
+      const data = JSON.parse(readFileSync(dataFile, "utf8"));
+      for (const [api, section] of Object.entries(data)) {
+        for (const id of Object.keys(section ?? {})) byId[id] ??= api;
+      }
     }
-    return byId;
   } catch { /* 安装树结构变化时回退 */ }
-  return null;
+  try {
+    // 注册表面只在**只读安装树**（desktop asar）上才有意义：可写安装树下目录文件就是
+    // 运行时加载的副本，多读一次模块只是白白把 pi-ai 的模块图拉进本进程。
+    const ids = install && install.writable !== true ? await registryModelIds(install, log) : null;
+    if (ids) for (const id of ids) byId[id] ??= "registry";
+  } catch { /* 注册表不可用不阻断同步 */ }
+  return Object.keys(byId).length > 0 ? byId : null;
 }
 
 // 登录成功后，把账号可用模型写入用户 settings 的模型目录
@@ -78,7 +87,7 @@ function readConfiguredRoute(ctx) {
   }
 }
 
-async function syncAvailableModels(ctx) {
+async function syncAvailableModels(ctx, opts = {}) {
   const record = await ctx.credentials.readRecord(CREDENTIAL_KEY);
   const available = record?.payload?.availableModelIds;
   if (!Array.isArray(available) || available.length === 0) return;
@@ -88,7 +97,7 @@ async function syncAvailableModels(ctx) {
     && typeof route.modelOverrides === "object"
     && Object.keys(route.modelOverrides).length > 0;
   if (modelsConfigured || overridesConfigured) return;
-  const catalog = readCatalogModelIds();
+  const catalog = await readCatalogModelIds(safeInstall(opts), (m) => ctx.logger?.info?.(m));
   let ids;
   if (catalog) {
     ids = available.filter((id) => catalog[id] !== undefined);
@@ -184,6 +193,15 @@ function resolveInstall(opts) {
   return { ...install, ...classifyCatalogTarget(install.catalogFile, opts.writableProbe) };
 }
 
+// 定位失败不抛（boot/同步/settings 都必须能在安装树异常时降级）。
+function safeInstall(opts = {}) {
+  try {
+    return resolveInstall(opts);
+  } catch {
+    return null;
+  }
+}
+
 function readLocalCatalog(opts) {
   const install = resolveInstall(opts);
   const bytes = readFileSync(install.catalogFile);
@@ -210,12 +228,16 @@ async function resolveAvailable(ctx, fetchImpl) {
 
 // R3-3 严格分支：仅 mode==="overlay" 读内置覆盖层；normal npm 失败只回
 // catalogSource:"local"（绝不隐式读 overlay）；未知 mode → 400。
-async function resolveCatalogSource(opts, mode, fetchImpl) {
+async function resolveCatalogSource(opts, mode, fetchImpl, allowedKeys) {
   if (mode === "overlay") {
-    const catalog = readJson(opts.overlayFile ?? defaultOverlayFile());
-    if (catalog === undefined) throw new Error("bundled overlay file missing");
+    const raw = readJson(opts.overlayFile ?? defaultOverlayFile());
+    if (raw === undefined) throw new Error("bundled overlay file missing");
+    // 形状规范化（ADR 0003）：pi-ai ≥0.99.0 的目录用 `chat:<id>` 键，必须规范化回
+    // 裸 id + 本机字段集合，合并/校验/digest 才与 0.87.x 世代同语义。
+    const normalized = normalizeRemoteCatalog(raw, { allowedKeys });
     return {
-      catalog,
+      catalog: normalized.catalog,
+      normalized: { renamed: normalized.renamed, skipped: normalized.skipped },
       catalogSource: "overlay",
       catalogError: null,
       provenance: { kind: "overlay", piAiVersion: OVERLAY_SOURCE_VERSION, integrity: null },
@@ -224,8 +246,10 @@ async function resolveCatalogSource(opts, mode, fetchImpl) {
   if (mode !== undefined && mode !== "latest") throw new InvalidModeError(String(mode));
   try {
     const r = await fetchLatestCatalog({ fetchImpl });
+    const normalized = normalizeRemoteCatalog(r.catalog, { allowedKeys });
     return {
-      catalog: r.catalog,
+      catalog: normalized.catalog,
+      normalized: { renamed: normalized.renamed, skipped: normalized.skipped },
       catalogSource: "latest",
       catalogError: null,
       provenance: { kind: "latest", piAiVersion: r.piAiVersion, integrity: r.integrity },
@@ -233,6 +257,7 @@ async function resolveCatalogSource(opts, mode, fetchImpl) {
   } catch (error) {
     return {
       catalog: readLocalCatalog(opts).catalog,
+      normalized: null,
       catalogSource: "local",
       catalogError: String(error?.message ?? error),
       provenance: { kind: "local" },
@@ -284,6 +309,80 @@ function overlayEntryIds(overlay) {
   return Object.values(overlay ?? {}).flatMap((s) => Object.keys(s ?? {}));
 }
 
+// ==================== 注入后的"路由是否真的端出来"复核（ADR 0003 增补） ====================
+// 为什么需要这一层：llm-pi-ai 在**挂载时**就构建快照，并把目录解析结果按 settings 配置
+// 对象的身份 memoize（其 profiles() 只在 config.providers.get() 变身份时重建）。插件挂载
+// 晚于它，动态 import pi-ai 模块图又要几秒——boot 期注入因此常常落在快照之后：注册表里
+// 有条目，路由仍按旧快照把它判为"目录不描述"并丢弃。注入成功后必须用**宿主自己的**
+// listModels 复核（不能用我们自己的模块实例自证，那是自指的），缺失就做一次
+// **同值 settings 触碰**触发快照重建——只改配置对象身份，绝不改用户内容。
+
+// 路由当前端出的模型 id 集合；宿主 API 不可用时返回 null（无从判断，不误报）。
+async function servedModelIds(ctx) {
+  try {
+    return new Set((await ctx.llm.listModels("github-copilot")).map((m) => m?.id).filter(Boolean));
+  } catch {
+    return null;
+  }
+}
+
+// 用户 settings 里当前引用的模型 id（只有它们才需要"端得出来"）。
+function configuredModelIds(ctx) {
+  const models = readConfiguredRoute(ctx).models;
+  return new Set((Array.isArray(models) ? models : []).map((m) => m?.id).filter(Boolean));
+}
+
+// 诊断口径：已注入条目中，被 settings 引用却没能从路由端出来的 id。
+// 返回 { referenced, missing }；宿主 API 不可用时 missing 为 null。
+async function registryServedDiagnostics(ctx, overlayIds) {
+  const referenced = [...new Set(overlayIds)].filter((id) => configuredModelIds(ctx).has(id));
+  if (referenced.length === 0) return { referenced, missing: [] };
+  const served = await servedModelIds(ctx);
+  if (served === null) return { referenced, missing: null };
+  return { referenced, missing: referenced.filter((id) => !served.has(id)) };
+}
+
+// 同值触碰后的短重试复核（快照重建是异步的）。
+async function registryMissingWithRetry(ctx, ids, { attempts = 5, delayMs = 150 } = {}) {
+  let missing = ids;
+  for (let i = 0; i < attempts; i++) {
+    const diag = await registryServedDiagnostics(ctx, ids);
+    missing = diag.missing ?? missing;
+    if (missing.length === 0) return [];
+    if (i < attempts - 1) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return missing;
+}
+
+// boot 期注入后的自愈复核：缺失即同值触碰，再复核。返回 { ok, touched, referenced, missing }。
+async function ensureRegistryServed(ctx, overlayIds, log) {
+  const before = await registryServedDiagnostics(ctx, overlayIds);
+  if (before.referenced.length === 0) return { ok: true, touched: false, ...before };
+  if (before.missing !== null && before.missing.length === 0) return { ok: true, touched: false, ...before };
+  let touched = false;
+  try {
+    const desc = ctx.settings?.describe?.()?.find?.((x) => x?.ns === "llm-pi-ai");
+    const rawModels = desc?.user?.providers?.["github-copilot"]?.models;
+    if (Array.isArray(rawModels)) {
+      await ctx.settings.mutate("llm-pi-ai", [
+        { op: "set", path: ["providers", "github-copilot", "models"], value: rawModels },
+      ], desc.revision);
+      touched = true;
+    }
+  } catch (err) {
+    log?.(`copilot-auth: registry snapshot touch failed — ${String(err?.message ?? err)}`);
+  }
+  const missing = touched ? await registryMissingWithRetry(ctx, before.referenced) : before.missing;
+  const ok = missing !== null && missing.length === 0;
+  if (!ok) {
+    log?.(
+      `copilot-auth: registry-not-served — ${(missing ?? before.referenced).join(",")}`
+        + (touched ? "" : " (同值触碰未执行：settings 未注入或该路由无 models)"),
+    );
+  }
+  return { ok, touched, referenced: before.referenced, missing };
+}
+
 // 启动序列（严格按序 boot 0→1→2；整体 try/catch，失败只记 lastError +
 // logger.warn，绝不阻断挂载；所有写入幂等，崩溃现场下个 boot 安全重试）。
 async function bootRefresh(ctx, opts) {
@@ -304,6 +403,32 @@ async function bootRefresh(ctx, opts) {
     let bootPatched = false;
     const readDiskCatalog = () => JSON.parse(readFileSync(install.catalogFile, "utf8"));
     const diskIds = (disk) => new Set(Object.values(disk).flatMap((s) => Object.keys(s ?? {})));
+    const log = (m) => ctx.logger?.info?.(m);
+    // 测试注入钩子：opts.injectRegistry / opts.registryIds（生产恒用真实实现）。
+    const injectRegistry = opts.injectRegistry ?? injectCatalogEntries;
+    const readRegistryIds = opts.registryIds ?? registryModelIds;
+    // 落地一次目录增量：可写安装树走原子写盘（ADR 0001）；只读安装树（desktop asar）
+    // 走进程内目录注册表注入（ADR 0003）。返回 { ok, wrote, mode, reason }，绝不抛。
+    const landIncrement = async (overlay, merged) => {
+      if (install.writable) {
+        writeJsonAtomic(install.catalogFile, merged.merged);
+        return { ok: true, wrote: true, mode: "file", reason: null };
+      }
+      const r = await injectRegistry(install, overlay, {
+        log,
+        allowedKeys: catalogShapeKeys(readDiskCatalog()),
+      });
+      return { ok: r.ok, wrote: false, mode: "registry", reason: r.reason, detail: r };
+    };
+    // 运行时实际可解析的模型 id：目录文件 ∪ 进程内注册表（ADR 0003——注入的条目
+    // 不在文件里，任何"目录可解析"判定都必须走这一面）。
+    const servedIds = async () => {
+      const ids = diskIds(readDiskCatalog());
+      // 同 readCatalogModelIds：只有只读安装树才需要并注册表面（可写树下两者同源）。
+      const reg = install.writable === true ? null : await readRegistryIds(install, log);
+      if (reg) for (const id of reg) ids.add(id);
+      return ids;
+    };
 
     // boot 0：journal=prepared 崩溃恢复（先于激活门，但先过兼容 gate，R3-1）
     if (state.journal?.phase === "prepared") {
@@ -314,15 +439,21 @@ async function bootRefresh(ctx, opts) {
       }
       const replay = mergeCatalog(readDiskCatalog(), state.journal.pendingOverlay);
       if (replay.added.length > 0) {
-        // 可写性门禁（ADR 0002）：不可写目标不重试写盘——journal 原样保留，安装将来
-        // 变可写（如桌面版改为解包 pi-ai）后本恢复自动完成。零写入、可 grep 的 lastError。
-        if (!install.writable) {
-          state = setLastError(state, `catalog-not-writable (${install.unwritableReason}): pi-ai catalog is read-only; prepared journal kept, refresh will complete automatically once the target becomes writable`);
+        const landed = await landIncrement(state.journal.pendingOverlay, replay);
+        if (!landed.ok) {
+          // 落地失败（不可写且注册表注入失败）：journal 原样保留、零写入、可 grep 的
+          // lastError，下次 boot 重试；安装树将来变可写后本恢复自动完成。
+          const why = landed.mode === "file" ? `catalog-not-writable (${install.unwritableReason})` : `registry-inject-failed (${landed.reason})`;
+          state = setLastError(state, `${why}: pi-ai catalog is not landable; prepared journal kept`);
           saveState(stateFile, state);
           return;
         }
-        writeJsonAtomic(install.catalogFile, replay.merged);
-        bootPatched = true;
+        bootPatched = landed.wrote;
+        // 注册表通道：注入只是把条目放进进程内注册表，宿主快照可能已在挂载时按旧目录
+        // 定稿——用宿主 API 复核，缺失即同值触碰触发重建（ADR 0003 增补）。
+        if (landed.mode === "registry") {
+          await ensureRegistryServed(ctx, overlayEntryIds(state.journal.pendingOverlay), log);
+        }
       }
       state.appliedOverlay = mergeCatalog(state.appliedOverlay, state.journal.pendingOverlay).merged;
       state.appliedProvenance = {
@@ -332,7 +463,9 @@ async function bootRefresh(ctx, opts) {
         catalogSchemaVersion: 1,
       };
       state.activated = true;
-      state.restartState = restartMarker("refresh", digest(state.appliedOverlay));
+      // file 通道才需要重启标记（下个 boot 由 2a 把 settings 镜像到 target）；
+      // 注册表注入当次生效，boot2a 在本 boot 就会同步 settings（ADR 0003）。
+      if (install.writable) state.restartState = restartMarker("refresh", digest(state.appliedOverlay));
       state.journal = advanceJournal(state.journal);
       state = clearLastError(state);
       saveState(stateFile, state);
@@ -349,21 +482,33 @@ async function bootRefresh(ctx, opts) {
         } else if (install.version === baseline) {
           const replay = mergeCatalog(readDiskCatalog(), state.appliedOverlay);
           if (replay.added.length > 0) {
-            // 可写性门禁（ADR 0002）：自愈同理不重试写盘——appliedOverlay 保留，
-            // 目标可写后下一 boot 重放；不抛错、不阻断启动序列。
-            if (!install.writable) {
-              state = setLastError(state, `catalog-not-writable (${install.unwritableReason}): pi-ai catalog is read-only; self-heal deferred, overlay entries stay pending`);
+            const landed = await landIncrement(state.appliedOverlay, replay);
+            if (!landed.ok) {
+              // 自愈失败不抛错、不阻断启动序列：appliedOverlay 保留，下次 boot 重放。
+              const why = landed.mode === "file" ? `catalog-not-writable (${install.unwritableReason})` : `registry-inject-failed (${landed.reason})`;
+              state = setLastError(state, `${why}: self-heal deferred, overlay entries stay pending`);
               saveState(stateFile, state);
             } else {
-              writeJsonAtomic(install.catalogFile, replay.merged); // 原子重放
-              bootPatched = true;
-              state.restartState = restartMarker("self-heal", digest(state.appliedOverlay));
+              bootPatched = landed.wrote;
+              // 注册表注入是进程内的、当次 boot 即生效，不需要重启标记（ADR 0003）。
+              if (landed.wrote) state.restartState = restartMarker("self-heal", digest(state.appliedOverlay));
               state = clearLastError(state);
               saveState(stateFile, state);
+              // 注入通常落在宿主快照之后（宿主在挂载时即定稿目录解析结果）——用宿主
+              // 自己的 listModels 复核，缺失即同值触碰触发重建；仍缺失则记可 grep 的
+              // lastError（不写盘、不阻断挂载）。
+              if (landed.mode === "registry") {
+                const served = await ensureRegistryServed(ctx, overlayEntryIds(state.appliedOverlay), log);
+                if (!served.ok) {
+                  state = setLastError(state, `registry-not-served: ${(served.missing ?? served.referenced).join(",")} — injected entries are in the registry but the route still does not serve them`);
+                  saveState(stateFile, state);
+                }
+              }
             }
           }
         } else {
-          const missing = overlayIds.filter((id) => !diskIds(readDiskCatalog()).has(id));
+          const served = await servedIds();
+          const missing = overlayIds.filter((id) => !served.has(id));
           if (missing.length > 0) {
             // 跨版本有缺失：上报 self-heal-incompatible，不改安装树
             state = setLastError(state, `self-heal-incompatible: pi-ai ${install.version} != baseline ${baseline}, missing ${missing.join(",")}`);
@@ -384,7 +529,7 @@ async function bootRefresh(ctx, opts) {
         try {
           if (!install) throw new Error("pi-ai installation not found");
           // 语义前置（Y2-3）：targetIds 全部可由当前目录解析；whole-file digest 仅诊断
-          const ids = diskIds(readDiskCatalog());
+          const ids = await servedIds();
           const unresolvable = j.targetIds.filter((id) => !ids.has(id));
           if (unresolvable.length > 0) throw new Error(`target-unresolvable: ${unresolvable.join(",")}`);
           const desc = ctx.settings?.describe?.()?.find?.((x) => x?.ns === "llm-pi-ai");
@@ -418,7 +563,7 @@ async function bootRefresh(ctx, opts) {
       // 2b. restartState 非空且 expected entries 已在目录 → 仅清 restartState
       // （不携带 settings 意图：单独存在时不得触碰 describe/mutate）
       if (state.restartState && install) {
-        const ids = diskIds(readDiskCatalog());
+        const ids = await servedIds();
         if (overlayEntryIds(state.appliedOverlay).every((id) => ids.has(id))) {
           state.restartState = null;
           state = clearLastError(state);
@@ -453,7 +598,7 @@ async function computeRefreshInputs(ctx, opts, mode) {
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch?.bind(globalThis);
   const { ids, source } = await resolveAvailable(ctx, fetchImpl);
   const local = readLocalCatalog(opts);
-  const resolved = await resolveCatalogSource(opts, mode, fetchImpl);
+  const resolved = await resolveCatalogSource(opts, mode, fetchImpl, catalogShapeKeys(local.catalog));
   const merged = mergeCatalog(local.catalog, resolved.catalog);
   const catalogIds = new Set(Object.values(merged.merged).flatMap((s) => Object.keys(s ?? {})));
   const view = rawSettingsView(ctx);
@@ -479,6 +624,40 @@ async function computeRefreshInputs(ctx, opts, mode) {
   return { view, ids, source, local, resolved, merged, diff, customizationReset, digests };
 }
 
+// 端到端自证（ADR 0003）：注入 + settings 写入后，路由必须真的把 target 端出来。
+// settings→快照重建是异步的，故带短重试。返回 { ok, missing, served }。
+async function waitForServedModels(ctx, targetIds, { attempts = 6, delayMs = 150 } = {}) {
+  const want = [...new Set(targetIds)];
+  let served = new Set();
+  for (let i = 0; i < attempts; i++) {
+    try {
+      served = new Set((await ctx.llm.listModels("github-copilot")).map((m) => m?.id).filter(Boolean));
+    } catch (err) {
+      if (i === attempts - 1) return { ok: false, missing: want, served: [...served], error: String(err?.message ?? err) };
+    }
+    const missing = want.filter((id) => !served.has(id));
+    if (missing.length === 0) return { ok: true, missing: [], served: [...served] };
+    if (i < attempts - 1) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return { ok: false, missing: want.filter((id) => !served.has(id)), served: [...served] };
+}
+
+// 自证失败时的 best-effort 回滚：把用户 settings 的 models 恢复成刷新前的视图。
+// 回滚本身失败不掩盖原错误——调用方以结构化错误（rolledBack:false）上报。
+async function rollbackSettings(ctx, previous) {
+  try {
+    const desc = ctx.settings?.describe?.()?.find?.((x) => x?.ns === "llm-pi-ai");
+    if (!desc) return false;
+    const ops = previous?.modelsPresent
+      ? [{ op: "set", path: ["providers", "github-copilot", "models"], value: previous.models }]
+      : [{ op: "unset", path: ["providers", "github-copilot", "models"] }];
+    await ctx.settings.mutate("llm-pi-ai", ops, desc.revision);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function apply(ctx, opts = {}) {
   const r = routes();
   let attempt = emptyState();
@@ -496,7 +675,7 @@ export function apply(ctx, opts = {}) {
   // 模型目录同步只在登录成功后执行（2026-09-05 对齐结论：挂载不再同步）。
   // 插件启动/重启绝不触碰用户 settings，用户精简过的目录不会被动重置。
   // 失败不静默：错误经 /status 的 syncError 字段暴露，便于诊断。
-  const sync = () => syncAvailableModels(ctx).then(() => { lastSyncError = undefined; }).catch((err) => {
+  const sync = () => syncAvailableModels(ctx, opts).then(() => { lastSyncError = undefined; }).catch((err) => {
     lastSyncError = String(err?.message ?? err);
     ctx.logger?.warn?.("copilot-auth: model sync failed: %s", lastSyncError);
   });
@@ -596,7 +775,14 @@ export function apply(ctx, opts = {}) {
         catalogDigest,
         catalogFile: install?.catalogFile ?? null,
         catalogWritable: install ? install.writable === true : null,
+        // 落地通道（ADR 0003）：file = 可写安装树走目录补丁；registry = 只读安装树
+        // （desktop asar）走进程内目录注册表注入。registryInjected = 已注入条目数。
+        catalogMode: install ? (install.writable === true ? "file" : "registry") : null,
+        registryInjected: overlayEntryIds(state.appliedOverlay).length,
       };
+      // 诊断口径（ADR 0003 增补）：已注入、被 settings 引用、却没能从路由端出来的 id。
+      // "注册表里有了但 picker 里看不到"这类问题的唯一直接证据；宿主 API 不可用时为 null。
+      refresh.settingsNotServed = (await registryServedDiagnostics(ctx, overlayEntryIds(state.appliedOverlay))).missing;
       json(res, 200, { configured, syncError: lastSyncError, refresh });
     },
   });
@@ -646,6 +832,8 @@ export function apply(ctx, opts = {}) {
           catalogSource: inputs.resolved.catalogSource,
           catalogError: inputs.resolved.catalogError,
           catalogWritable: inputs.local.writable,
+          catalogMode: inputs.local.writable ? "file" : "registry",
+          catalogNormalized: inputs.resolved.normalized,
           skipped: inputs.merged.skipped,
           added: inputs.diff.added,
           removed: inputs.diff.removed,
@@ -696,15 +884,69 @@ export function apply(ctx, opts = {}) {
           }
           // digest 全部一致后才解析版本（写入失败点上移，500 不留 journal）
           const install = resolveInstall(opts);
-          // 可写性门禁（ADR 0002）：不可写目标在 write-ahead 之前快速失败——绝不留
-          // prepared journal（desktop asar 形态下那会让每个 boot 都重试写归档）。
+          const stateFile = opts.stateFile ?? defaultStateFile();
           if (!install.writable) {
+            // 只读安装树（desktop asar）：ADR 0002 的写盘门禁之外再开一条**不写盘**的
+            // 落地通道——进程内目录注册表注入（ADR 0003）。注入成功才写 settings，
+            // 再以 listModels 端到端自证；自证失败回滚 settings，绝不产出
+            // "能选中但发不出去"的假模型。
+            const injectRegistry = opts.injectRegistry ?? injectCatalogEntries;
+            const injected = await injectRegistry(install, inputs.merged.addedOverlay, {
+              log: (m) => ctx.logger?.info?.(m),
+              allowedKeys: catalogShapeKeys(inputs.local.catalog),
+            });
+            if (!injected.ok) {
+              return {
+                code: 400,
+                payload: {
+                  ok: false,
+                  error: "registry-inject-failed",
+                  reason: injected.reason,
+                  missing: injected.missing,
+                  rejected: injected.rejected,
+                  catalogFile: install.catalogFile,
+                },
+              };
+            }
+            const desc = ctx.settings?.describe?.()?.find?.((x) => x?.ns === "llm-pi-ai");
+            if (!desc) {
+              return { code: 500, payload: { ok: false, error: "settings namespace llm-pi-ai unavailable" } };
+            }
+            await ctx.settings.mutate("llm-pi-ai", [
+              { op: "set", path: ["providers", "github-copilot", "models"], value: inputs.diff.target.map((id) => ({ id })) },
+            ], desc.revision);
+            const served = await waitForServedModels(ctx, inputs.diff.target);
+            if (!served.ok) {
+              const rolledBack = await rollbackSettings(ctx, inputs.view);
+              return {
+                code: 500,
+                payload: { ok: false, error: "registry-not-effective", missing: served.missing, rolledBack },
+              };
+            }
+            let state = loadState(stateFile);
+            state.appliedOverlay = mergeCatalog(state.appliedOverlay, inputs.merged.addedOverlay).merged;
+            state.appliedProvenance = {
+              sourcePiAiVersion: inputs.resolved.provenance.piAiVersion ?? null,
+              integrity: inputs.resolved.provenance.integrity ?? null,
+              appliedAgainstPiAiVersion: install.version,
+              catalogSchemaVersion: 1,
+            };
+            state.activated = true;
+            state.journal = null; // 注册表注入当次生效，无写盘、无重启相位
+            state = clearLastError(state);
+            saveState(stateFile, state);
             return {
-              code: 400,
-              payload: { ok: false, error: "catalog-not-writable", reason: install.unwritableReason, catalogFile: install.catalogFile },
+              code: 200,
+              payload: {
+                ok: true,
+                restartRequired: false,
+                mode: "registry",
+                registryVia: injected.via,
+                injected: [...injected.injected, ...injected.present],
+                target: inputs.diff.target.length,
+              },
             };
           }
-          const stateFile = opts.stateFile ?? defaultStateFile();
           const patchedBytes = Buffer.from(JSON.stringify(inputs.merged.merged, null, 2) + "\n", "utf8");
           let state = loadState(stateFile);
           state.journal = createJournal({

package/src/refresh-flow.mjs

@@ -6,7 +6,7 @@
 // POST preview）→ 成功进 confirming(staleNotice)；restartNeeded 可由 /status 水合。
 import { routes } from "./shared.mjs";
 
-export const initial = Object.freeze({ name: "idle", catalogWritable: null });
+export const initial = Object.freeze({ name: "idle", catalogWritable: null, catalogMode: null });
 
 // reduce(state, event) → [nextState, effect | null]
 // effect 为数据化指令：{type:"preview",mode} | {type:"apply",mode,digests} | {type:"status"}
@@ -25,12 +25,15 @@ export function reduce(state, event) {
         if (!event.status) return [state, null]; // status 拉取失败不硬失败
         if (refresh?.lastError === "state-corrupt") return [{ name: "failed", error: "state-corrupt" }, null];
         if (refresh?.pendingRestart === true) {
-          return [{ name: "restartNeeded", catalogWritable: refresh?.catalogWritable ?? null }, null];
+          return [{ name: "restartNeeded", catalogWritable: refresh?.catalogWritable ?? null, catalogMode: refresh?.catalogMode ?? null }, null];
         }
-        // 干净水合：catalogWritable 随 /status 落态（desktop asar 只读形态 → false，
-        // UI 置灰刷新入口）；旧宿主不携带该字段时保持现值不回退。
+        // 干净水合：catalogWritable / catalogMode 随 /status 落态。desktop asar 只读
+        // 形态下 catalogWritable=false 且 catalogMode="registry"（ADR 0003：刷新走
+        // 进程内目录注册表注入，入口保持可用且无需重启）；旧宿主不携带这两个字段时
+        // 保持现值不回退（不回退为"可写"，避免误导）。
         const writable = refresh && "catalogWritable" in refresh ? refresh.catalogWritable : state.catalogWritable ?? null;
-        return [{ ...state, catalogWritable: writable }, null];
+        const mode = refresh && "catalogMode" in refresh ? refresh.catalogMode : state.catalogMode ?? null;
+        return [{ ...state, catalogWritable: writable, catalogMode: mode }, null];
       }
       return [state, null];
     }
@@ -57,7 +60,13 @@ export function reduce(state, event) {
       return [state, null];
     }
     case "applying": {
-      if (event.type === "apply-ok") return [{ name: "restartNeeded" }, null];
+      // apply-ok 携带 restartRequired / mode（ADR 0003）：registry 通道当次生效，
+      // 不要求重启；file 通道仍是两阶段（下个 boot 同步 settings）。
+      if (event.type === "apply-ok") {
+        return event.restartRequired === false
+          ? [{ name: "applied", mode: event.mode ?? null, injected: event.injected ?? 0 }, null]
+          : [{ name: "restartNeeded", catalogMode: state.catalogMode ?? null }, null];
+      }
       if (event.type === "apply-stale") {
         // 409 preview-stale：以原 mode 重新 preview（保持 overlay 来源，R2-5）
         return [{ name: "previewing", mode: state.mode, stale: true }, { type: "preview", mode: state.mode }];
@@ -99,7 +108,12 @@ export async function runEffect(effect, fetchImpl) {
       const body = await res.json().catch(() => null);
       if (res.status === 409) return { type: "apply-stale" };
       return res.status === 200 && body?.ok
-        ? { type: "apply-ok" }
+        ? {
+            type: "apply-ok",
+            restartRequired: body.restartRequired !== false,
+            mode: body.mode ?? null,
+            injected: Array.isArray(body.injected) ? body.injected.length : 0,
+          }
         : { type: "apply-fail", error: body?.error ?? `HTTP ${res.status}` };
     } catch (err) {
       return { type: "apply-fail", error: String(err?.message ?? err) };