@inventec/dsh-copilot-auth 1.2.3 → 1.2.5

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,22 @@
 - 🔐 **设备码登录/注销**：网页 + 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**：136 条单元测试（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.5+ | `0.1.7-rc.2`+（`0.2.0-rc.1` web 与 `0.2.0-rc.2` desktop 已实测） | runtime 内置，插件不挂载 | **desktop 只读形态可刷新**：进程内目录注册表注入（ADR 0003），无需重启、不碰官方产物；同批修复 pi-ai ≥0.99.0 的 `chat:` 目录键格式 |
+| 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,12 +77,14 @@ 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`，**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/服务形态同样生效。
 
 ## 工作原理
 
@@ -95,7 +99,7 @@ pi-ai 的模型目录是打包时硬编码的 JSON：上游新增模型（如 ge
 
 ```bash
 npm install
-npm test        # node:test：patch 结构 + host/目录/状态机/启动序列共 107 条
+npm test        # node:test：patch 结构 + host/目录/状态机/启动序列/可写性门禁/注册表注入 共 136 条（CI 跑 ubuntu/windows/macos 三平台矩阵）
 npm run build   # esbuild 打包 client 到 lib/client.js（__ModuleLoader__ 信封）
 npm pack --dry-run
 ```
@@ -104,6 +108,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 安装免构建） |
@@ -123,8 +128,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 桌面版）可刷新模型目录（v1.2.5 起）**：运行时树打包在只读的 `app.asar` 内，写盘通道物理不可用，但刷新改走进程内目录注册表注入（ADR 0003）——当次生效、无需重启、不碰官方产物。前提是该进程的 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" });
+var initial = Object.freeze({ name: "idle", catalogWritable: null, catalogMode: null });
 function reduce(state, event) {
   switch (state.name) {
     case "idle":
@@ -59,8 +59,12 @@ function reduce(state, event) {
         const refresh = event.status?.refresh;
         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" }, null];
-        return state.name === "idle" ? [state, null] : [state, null];
+        if (refresh?.pendingRestart === true) {
+          return [{ name: "restartNeeded", catalogWritable: refresh?.catalogWritable ?? null, catalogMode: refresh?.catalogMode ?? null }, null];
+        }
+        const writable = refresh && "catalogWritable" in refresh ? refresh.catalogWritable : state.catalogWritable ?? null;
+        const mode = refresh && "catalogMode" in refresh ? refresh.catalogMode : state.catalogMode ?? null;
+        return [{ ...state, catalogWritable: writable, catalogMode: mode }, null];
       }
       return [state, null];
     }
@@ -85,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 }];
       }
@@ -120,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) };
     }
@@ -192,7 +203,12 @@ var DICTS = {
     srcLatest: "Catalog source: latest pi-ai from npm",
     srcLocal: "Catalog source: local only (npm fetch failed)",
     srcOverlay: "Catalog source: bundled overlay (offline bootstrap)",
-    none: "(none)"
+    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.",
+    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",
@@ -235,10 +251,21 @@ var DICTS = {
     srcLatest: "\u76EE\u5F55\u6765\u6E90\uFF1Anpm \u6700\u65B0 pi-ai",
     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"
+    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",
+    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;
@@ -420,14 +447,31 @@ 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")
     ] }),
+    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")
+    ] }),
     /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: styles.modalActions, children: [
       p.catalogSource === "local" && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", style: { ...styles.button, ...styles.secondary, marginRight: "auto" }, onClick: onOverlay, children: t("overlayBtn") }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", style: { ...styles.button, ...styles.secondary }, onClick: onCancel, children: t("cancel") }),
-      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", style: { ...styles.button, ...styles.primary }, onClick: onConfirm, children: t("confirmRefresh") })
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        "button",
+        {
+          type: "button",
+          style: { ...styles.button, ...styles.primary, ...refreshBlocked(p) ? { opacity: 0.5, cursor: "not-allowed" } : null },
+          disabled: refreshBlocked(p),
+          onClick: onConfirm,
+          children: t("confirmRefresh")
+        }
+      )
     ] })
   ] }) });
 }
@@ -551,18 +595,27 @@ function CopilotSection({ t = (key) => DICTS.en[key] ?? key }) {
         "button",
         {
           type: "button",
-          style: { ...styles.button, ...styles.primary },
-          disabled: 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" && 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 }),
+    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.3",
+  "version": "1.2.5",
   "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

@@ -1,7 +1,7 @@
 // catalog.mjs — 数据核心：tgz 严格解析、条目校验、只增不更新合并、diff、digest、
 // pi-ai 安装定位。合并语义「只增不更新」（ADR 0001）：已有 id 的元数据永不覆盖。
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, openSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { gunzipSync } from "node:zlib";
 
@@ -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) {
@@ -154,3 +222,45 @@ export function findPiAiInstallation({ startPath } = {}) {
   } catch { /* 安装树结构变化 → null（调用方降级） */ }
   return null;
 }
+
+// ==================== 安装目标可写性分类（desktop asar 只读问题，ADR 0002） ====================
+// dsh-desktop（Electron）把整个运行时树打进 resources/app.asar，pi-ai 是其中唯一副本：
+// asar 虚拟文件系统读没问题、创建/写入必被拒（ENOENT "... not found in <archive>"）。
+// 数据级目录补丁在写盘前必须先分类目标，把"物理不可写"变成结构化错误而不是天书 ENOENT。
+
+// Electron 的 asar 拦截按"路径中任一段以 .asar 结尾"判定（大小写不敏感，分隔符 / 与 \ 都认，
+// Win 路径在 POSIX 主机上测试时也要能识别）。.asar.unpacked 不以 .asar 结尾，不会误判。
+export function isAsarPath(p) {
+  const s = String(p ?? "");
+  if (/\.asar$/i.test(s)) return true;
+  return s.split(/[\\/]/).some((seg) => /\.asar$/i.test(seg));
+}
+
+// 功能性可写探测：在目录内排他创建 + 删除一个探针文件。覆盖 asar 之外的不可写形态
+// （只读卷、根属主安装、ACL 拒绝——win32 chmod 弱语义下唯一可靠的通用手段）。
+// 探针文件名带 UUID，排他创建，任何失败路径都尝试清理并返回 false。
+export function probeWritable(dir) {
+  const probe = join(dir, `.copilot-auth-write-probe-${randomUUID()}`);
+  let fd;
+  try {
+    fd = openSync(probe, "wx");
+    closeSync(fd);
+    fd = undefined;
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* 已关闭 */ }
+    }
+    try { unlinkSync(probe); } catch { /* 探针可能未创建成功 */ }
+  }
+}
+
+// 分类结果平铺进安装对象：writable: boolean；不可写时 unwritableReason: "asar" | "probe-failed"。
+// writableProbe 仅作测试注入钩子（生产恒用默认实现）。
+export function classifyCatalogTarget(catalogFile, writableProbe = probeWritable) {
+  if (isAsarPath(catalogFile)) return { writable: false, unwritableReason: "asar" };
+  if (!writableProbe(dirname(catalogFile))) return { writable: false, unwritableReason: "probe-failed" };
+  return { writable: true, unwritableReason: null };
+}

package/src/host.mjs

@@ -1,15 +1,16 @@
 // host 半区：cordis 插件。注册 6 条 exact 路由，把内置 github-copilot 的
 // OAuth 设备码流（ctx.authorization）暴露给 Web client，并提供「手动刷新可用
 // 模型目录」（数据级目录补丁，pi-ai 代码版本不动；只读 GET /models 适配显式
-// 耦合 pi-ai 0.84.4，详见 CONTEXT.md 与 ADR 0001）。
+// 耦合 pi-ai 0.84.4，详见 GLOSSARY.md 与 ADR 0001）。
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 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 } 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);
@@ -163,22 +172,46 @@ function readBody(req) {
 // 版本与 catalog 同根解析（R3-8）：注入 catalogFile 时 version 取其所在根的
 // package.json（opts.piAiVersion 为测试钩子）；生产走 findPiAiInstallation()。
 function resolveInstall(opts) {
+  let install;
   if (opts.catalogFile) {
-    if (opts.piAiVersion) return { catalogFile: opts.catalogFile, version: opts.piAiVersion };
-    const root = dirname(dirname(dirname(dirname(opts.catalogFile))));
-    const packageJsonFile = join(root, "package.json");
-    const pkg = JSON.parse(readFileSync(packageJsonFile, "utf8"));
-    return { catalogFile: opts.catalogFile, packageJsonFile, version: pkg.version };
+    if (opts.piAiVersion) {
+      install = { catalogFile: opts.catalogFile, version: opts.piAiVersion };
+    } else {
+      const root = dirname(dirname(dirname(dirname(opts.catalogFile))));
+      const packageJsonFile = join(root, "package.json");
+      const pkg = JSON.parse(readFileSync(packageJsonFile, "utf8"));
+      install = { catalogFile: opts.catalogFile, packageJsonFile, version: pkg.version };
+    }
+  } else {
+    const found = findPiAiInstallation();
+    if (!found) throw new Error("pi-ai installation not found");
+    install = found;
+  }
+  // 可写性门禁（ADR 0002）：desktop asar 打包形态下 catalogFile 在只读归档内——读一切
+  // 正常、写必被拒。这里统一分类，apply/boot 据此结构化快速失败而非抛天书 ENOENT。
+  // opts.writableProbe 为测试注入钩子（生产恒用默认探测实现）。
+  return { ...install, ...classifyCatalogTarget(install.catalogFile, opts.writableProbe) };
+}
+
+// 定位失败不抛（boot/同步/settings 都必须能在安装树异常时降级）。
+function safeInstall(opts = {}) {
+  try {
+    return resolveInstall(opts);
+  } catch {
+    return null;
   }
-  const found = findPiAiInstallation();
-  if (!found) throw new Error("pi-ai installation not found");
-  return found;
 }
 
 function readLocalCatalog(opts) {
-  const file = resolveInstall(opts).catalogFile;
-  const bytes = readFileSync(file);
-  return { file, bytes, catalog: JSON.parse(bytes.toString("utf8")) };
+  const install = resolveInstall(opts);
+  const bytes = readFileSync(install.catalogFile);
+  return {
+    file: install.catalogFile,
+    bytes,
+    catalog: JSON.parse(bytes.toString("utf8")),
+    writable: install.writable,
+    unwritableReason: install.unwritableReason,
+  };
 }
 
 // 账号可用模型：现场拉取（显式耦合 0.84.4）→ 任何失败回退凭证缓存 availableModelIds
@@ -195,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 },
@@ -209,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 },
@@ -218,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" },
@@ -289,6 +329,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") {
@@ -299,8 +365,16 @@ async function bootRefresh(ctx, opts) {
       }
       const replay = mergeCatalog(readDiskCatalog(), state.journal.pendingOverlay);
       if (replay.added.length > 0) {
-        writeJsonAtomic(install.catalogFile, replay.merged);
-        bootPatched = true;
+        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;
+        }
+        bootPatched = landed.wrote;
       }
       state.appliedOverlay = mergeCatalog(state.appliedOverlay, state.journal.pendingOverlay).merged;
       state.appliedProvenance = {
@@ -310,7 +384,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);
@@ -327,14 +403,23 @@ async function bootRefresh(ctx, opts) {
         } else if (install.version === baseline) {
           const replay = mergeCatalog(readDiskCatalog(), state.appliedOverlay);
           if (replay.added.length > 0) {
-            writeJsonAtomic(install.catalogFile, replay.merged); // 原子重放
-            bootPatched = true;
-            state.restartState = restartMarker("self-heal", digest(state.appliedOverlay));
-            state = clearLastError(state);
-            saveState(stateFile, state);
+            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 {
+              bootPatched = landed.wrote;
+              // 注册表注入是进程内的、当次 boot 即生效，不需要重启标记（ADR 0003）。
+              if (landed.wrote) state.restartState = restartMarker("self-heal", digest(state.appliedOverlay));
+              state = clearLastError(state);
+              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(",")}`);
@@ -355,7 +440,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");
@@ -389,7 +474,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);
@@ -424,7 +509,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);
@@ -450,6 +535,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();
@@ -467,7 +586,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);
   });
@@ -566,6 +685,11 @@ export function apply(ctx, opts = {}) {
         piAiVersion: install?.version ?? null,
         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,
       };
       json(res, 200, { configured, syncError: lastSyncError, refresh });
     },
@@ -615,6 +739,9 @@ export function apply(ctx, opts = {}) {
           source: inputs.source,
           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,
@@ -666,6 +793,68 @@ export function apply(ctx, opts = {}) {
           // digest 全部一致后才解析版本（写入失败点上移，500 不留 journal）
           const install = resolveInstall(opts);
           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: 200,
+              payload: {
+                ok: true,
+                restartRequired: false,
+                mode: "registry",
+                registryVia: injected.via,
+                injected: [...injected.injected, ...injected.present],
+                target: inputs.diff.target.length,
+              },
+            };
+          }
           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" });
+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"}
@@ -24,8 +24,16 @@ export function reduce(state, event) {
         const refresh = event.status?.refresh;
         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" }, null];
-        return state.name === "idle" ? [state, null] : [state, null];
+        if (refresh?.pendingRestart === true) {
+          return [{ name: "restartNeeded", catalogWritable: refresh?.catalogWritable ?? null, catalogMode: refresh?.catalogMode ?? null }, null];
+        }
+        // 干净水合：catalogWritable / catalogMode 随 /status 落态。desktop asar 只读
+        // 形态下 catalogWritable=false 且 catalogMode="registry"（ADR 0003：刷新走
+        // 进程内目录注册表注入，入口保持可用且无需重启）；旧宿主不携带这两个字段时
+        // 保持现值不回退（不回退为"可写"，避免误导）。
+        const writable = refresh && "catalogWritable" in refresh ? refresh.catalogWritable : state.catalogWritable ?? null;
+        const mode = refresh && "catalogMode" in refresh ? refresh.catalogMode : state.catalogMode ?? null;
+        return [{ ...state, catalogWritable: writable, catalogMode: mode }, null];
       }
       return [state, null];
     }
@@ -52,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 }];
@@ -94,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) };