@inventec/dsh-copilot-auth 1.2.6 → 1.2.8

package/src/host.mjs

@@ -1,27 +1,34 @@
-// host 半区：cordis 插件。注册 6 条 exact 路由，把内置 github-copilot 的
-// OAuth 设备码流（ctx.authorization）暴露给 Web client，并提供「手动刷新可用
-// 模型目录」（数据级目录补丁，pi-ai 代码版本不动；只读 GET /models 适配显式
-// 耦合 pi-ai 0.84.4，详见 GLOSSARY.md 与 ADR 0001）。
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+// host 半区：cordis 插件。注册 8 条 exact 路由，把内置 github-copilot 的
+// OAuth 设备码流（ctx.authorization）暴露给 Web client（T3 授权控制器），并提供
+// 「补充模型／重建模型列表」双入口（T8 预览服务 + T9 事务内核，协议 v2）。
+// 数据级目录补丁（只增）与供应链守卫复用 catalog/catalog-fetch/catalog-registry；
+// pi-ai 代码版本不动；只读 GET /models 适配显式耦合 pi-ai 0.84.4（见 GLOSSARY 与 ADR 0001）。
+import { existsSync, mkdirSync, 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 { CREDENTIAL_KEY, PROTOCOL_VERSION, routes } from "./shared.mjs";
 import { readJson, writeJsonAtomic, createMutex } from "./atomic-json.mjs";
-import { mergeCatalog, diffModels, digest, findPiAiInstallation, classifyCatalogTarget, normalizeRemoteCatalog, catalogShapeKeys } from "./catalog.mjs";
+import { createAuthorizationController, sanitizeAuthError } from "./auth-host.mjs";
+import { resolveRuntimeScope } from "./runtime-scope.mjs";
+import { mergeCatalog, 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";
+import { injectCatalogEntries, registryModelIds, registryVia, registryInstanceMismatch, loadRegistryModules } from "./catalog-registry.mjs";
+import { loadRefreshState, saveRefreshState } from "./state.mjs";
+import { createRefreshService } from "./refresh-service.mjs";
+import { createTransaction } from "./refresh-transaction.mjs";
 
 export const name = "copilot-auth";
 export const inject = ["webServer", "authorization", "credentials", "settings", "llm"];
 
-// 内置覆盖层的收割来源版本（Task 7，integrity 记录于 README「模型目录刷新」章节）
+// 内置覆盖层的收割来源版本（integrity 记录于 README「模型目录刷新」章节）
 const OVERLAY_SOURCE_VERSION = "0.85.1";
 
-// pi-ai 目录数据文件定位层（从 readCatalogModelIds 拆出，行为不变）：
-// 从进程入口（dsh 可执行文件）逐级向上找 node_modules/@earendil-works/pi-ai。
+const defaultStateFile = () => join(homedir(), ".dsh", "copilot-auth-state.json");
+const defaultOverlayFile = () => fileURLToPath(new URL("./catalog-overlay.json", import.meta.url));
+const realClock = { now: () => Date.now() };
+
+// pi-ai 目录数据文件定位层：从进程入口逐级向上找 node_modules/@earendil-works/pi-ai。
 function findCatalogFile() {
   try {
     let dir = dirname(realpathSync(process.argv?.[1] ?? ""));
@@ -36,10 +43,7 @@ function findCatalogFile() {
   return null;
 }
 
-// 读取 github-copilot 的「可解析模型 id → 协议」映射。只读不改。
-// 两个来源的并集：① 安装树内的目录数据文件；② 进程内目录注册表（ADR 0003——desktop
-// 只读安装树下，刷新出来的增量条目只存在于注册表，目录文件里永远看不到）。两者都
-// 拿不到才返回 null（调用方回退 listModels 交集）。
+// 读取 github-copilot 的「可解析模型 id → 协议」映射（目录文件 ∪ 进程内注册表）。
 async function readCatalogModelIds(install, log) {
   const byId = {};
   try {
@@ -52,31 +56,14 @@ async function readCatalogModelIds(install, log) {
     }
   } catch { /* 安装树结构变化时回退 */ }
   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 的模型目录
-// （turnkey，用户新增需求 2026-09-04；目录保护，用户反馈 2026-09-05）。
-// 可写集合取交集：凭据 payload.availableModelIds（账号可用）∩ 内置目录已描述。
-// 目录快照外的 id 必须排除——catalog 路由校验要求模型的 wire 协议可解析
-// （api = 路由设置 ?? 目录条目 ?? 路由共享协议），目录外 id 三者皆空会被整体
-// 拒绝；pi-ai 目录更新后它们会自然进入可写集合。
-// 目录保护（2026-09-05）：该路由已配置模型目录（models 键存在，含空列表）或
-// modelOverrides 时视作用户所有，同步直接让路——用户在 Models 页精简过的目录
-// 不会被重置。只有目录尚不存在时才填充一次；想重置全量，删掉 settings.yaml
-// 里该路由的 models 列表后重新登录即可。
-
-// 读取解析后的 github-copilot 路由配置（base 层 + 用户层的最终值）。
-// 0.1.7 起 settings.get(ns) 被移除（settings API 重塑，见 know-how 013 §3），
-// 改经 describe()：value 层（base+user 合成）语义等价旧 get；旧版 DSH 的
-// describe 行无 value 时回退 user 层（用户定制目录恰在 user 层）。
-// settings 未注入 / 未注册 / 读取失败一律按空处理——回退到可写入分支，
-// 保持既有 turnkey 行为不变。
+// 登录成功（handoff 完好）后首次填充：可写集合＝账号可用 ∩ 内置目录已描述；
+// 目录保护：models 键存在（含空列表）或 modelOverrides 视作用户所有，同步让路。
 function readConfiguredRoute(ctx) {
   try {
     const desc = ctx.settings?.describe?.()?.find?.((x) => x?.ns === "llm-pi-ai");
@@ -102,15 +89,24 @@ async function syncAvailableModels(ctx, opts = {}) {
   if (catalog) {
     ids = available.filter((id) => catalog[id] !== undefined);
   } else {
-    // 回退：listModels 反映当前已配置列表，存在「已配置→只见已配置」自锁，
-    // 仅作目录定位失败时的降级。
     const served = new Set((await ctx.llm.listModels("github-copilot")).map((m) => m?.id).filter(Boolean));
     ids = available.filter((id) => served.has(id));
   }
   if (ids.length === 0) return;
-  // 真 CAS（与 boot 2a 同款，2026-09-28 审计补充）：携带 expectedRevision 提交，
-  // 与用户在 Models 页的并发编辑互斥——冲突时 settings 抛 SETTINGS_CONFLICT，
-  // 由 sync() 的 catch 记入 syncError（失败不静默），不再有静默覆盖窗口。
+  // T4 首次填充保护：提交前重核 handoff 仍完好（同 attempt、originIntentVersion 仍当前、
+  // 无撤回/超时标记）——取数 await 期间意图已变则只记录事实，不写配置。
+  if (opts.handoff) {
+    const intact = typeof opts.handoffIntact === "function" ? opts.handoffIntact(opts.handoff) : false;
+    if (!intact) {
+      // 计划 T4「记录跳过原因」：留可 grep 痕迹（attemptId/意图版本），不误报为失败
+      ctx.logger?.info?.(
+        "copilot-auth: first-fill skipped — handoff stale (attemptId=%s, originIntentVersion=%s)",
+        opts.handoff.attemptId ?? "?", opts.handoff.originIntentVersion ?? "?",
+      );
+      return;
+    }
+  }
+  // 真 CAS：携带 expectedRevision 提交，与用户并发编辑互斥（冲突抛 SETTINGS_CONFLICT）
   const desc = ctx.settings?.describe?.()?.find?.((x) => x?.ns === "llm-pi-ai");
   await ctx.settings.mutate("llm-pi-ai", [
     { op: "set", path: ["providers", "github-copilot", "models"], value: ids.map((id) => ({ id })) },
@@ -144,14 +140,6 @@ function guard(req, res, method) {
   return true;
 }
 
-// ==================== 模型目录手动刷新（数据级目录补丁，ADR 0001） ====================
-
-class InvalidModeError extends Error {}
-
-const defaultStateFile = () => join(homedir(), ".dsh", "copilot-auth-state.json");
-const defaultOverlayFile = () => fileURLToPath(new URL("./catalog-overlay.json", import.meta.url));
-
-// 字面量 body 直接用（测试）；否则按流读并 JSON.parse
 function readBody(req) {
   if (req.body !== undefined) return Promise.resolve(req.body);
   return new Promise((resolve, reject) => {
@@ -169,8 +157,8 @@ function readBody(req) {
   });
 }
 
-// 版本与 catalog 同根解析（R3-8）：注入 catalogFile 时 version 取其所在根的
-// package.json（opts.piAiVersion 为测试钩子）；生产走 findPiAiInstallation()。
+// 版本与 catalog 同根解析：注入 catalogFile 时 version 取其所在根的 package.json。
+// 可写性分类（ADR 0002）：desktop asar 形态只读——读正常、写必拒，结构化失败。
 function resolveInstall(opts) {
   let install;
   if (opts.catalogFile) {
@@ -187,13 +175,9 @@ function resolveInstall(opts) {
     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);
@@ -214,17 +198,7 @@ function readLocalCatalog(opts) {
   };
 }
 
-// 账号可用模型：现场拉取（显式耦合 0.84.4）→ 任何失败回退凭证缓存 availableModelIds
-async function resolveAvailable(ctx, fetchImpl) {
-  const record = await ctx.credentials.readRecord(CREDENTIAL_KEY);
-  const payload = record?.payload ?? {};
-  if (payload.access) {
-    try {
-      return { ids: await fetchLiveAvailableModelIds({ credential: payload, fetchImpl }), source: "live" };
-    } catch { /* 回退 cache */ }
-  }
-  return { ids: Array.isArray(payload.availableModelIds) ? payload.availableModelIds : [], source: "cache" };
-}
+class InvalidModeError extends Error {}
 
 // R3-3 严格分支：仅 mode==="overlay" 读内置覆盖层；normal npm 失败只回
 // catalogSource:"local"（绝不隐式读 overlay）；未知 mode → 400。
@@ -232,8 +206,6 @@ async function resolveCatalogSource(opts, mode, fetchImpl, allowedKeys) {
   if (mode === "overlay") {
     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: normalized.catalog,
@@ -265,9 +237,8 @@ async function resolveCatalogSource(opts, mode, fetchImpl, allowedKeys) {
   }
 }
 
-// settings raw user 层完整配置视图（R3-2）：digest/baseline/CAS 的唯一取数面。
-// 缺席一律 null 占位（非 undefined），保证 journal JSON 持久化无损、boot 重载后
-// 与现算视图可逐字节比较；「未配置 vs 显式空」由 *Present 标志区分。
+// settings 双视图（T8/T9 取数面）：raw user 层 + base+user 合成层 + 同次 revision。
+// 缺席一律 null 占位（非 undefined），保证持久化无损与逐字节比较可行。
 function viewFromUserLayer(user) {
   let route = {};
   if (user && typeof user === "object" && !Array.isArray(user)) {
@@ -284,39 +255,25 @@ function viewFromUserLayer(user) {
   };
 }
 
-function rawSettingsView(ctx) {
+function describeRouteView(ctx) {
+  const empty = { view: viewFromUserLayer(undefined), effectiveView: viewFromUserLayer(undefined), revision: null };
   try {
     const d = ctx.settings?.describe?.()?.find?.((x) => x?.ns === "llm-pi-ai");
-    return viewFromUserLayer(d?.user);
-  } catch { /* settings 未注入/未注册/读取失败一律按空视图 */ }
-  return viewFromUserLayer(undefined);
-}
-
-// 幂等判定：当前视图是否已等于 target 形状——models 恰好为 targetIds 的纯 {id}
-// 条目（无任何字段定制），且无有效 modelOverrides。
-function viewEqualsTarget(view, targetIds) {
-  if (!view.modelsPresent || !Array.isArray(view.models)) return false;
-  if (view.models.some((m) => !m || typeof m !== "object" || Array.isArray(m) || Object.keys(m).some((k) => k !== "id"))) {
-    return false;
+    if (!d) return empty;
+    return {
+      view: viewFromUserLayer(d.user),
+      effectiveView: viewFromUserLayer(d.value ?? d.user),
+      revision: d.revision,
+    };
+  } catch {
+    return empty;
   }
-  const ids = view.models.map((m) => m.id);
-  if ([...ids].sort().join("\0") !== [...targetIds].sort().join("\0")) return false;
-  if (view.modelOverridesPresent && view.modelOverrides && Object.keys(view.modelOverrides).length > 0) return false;
-  return true;
 }
 
 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 {
@@ -326,14 +283,12 @@ async function servedModelIds(ctx) {
   }
 }
 
-// 用户 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。
+// 诊断口径：已注入条目中，被 settings 引用却没能从路由端出来的 id（ADR 0003）。
 async function registryServedDiagnostics(ctx, overlayIds) {
   const referenced = [...new Set(overlayIds)].filter((id) => configuredModelIds(ctx).has(id));
   if (referenced.length === 0) return { referenced, missing: [] };
@@ -342,386 +297,248 @@ async function registryServedDiagnostics(ctx, overlayIds) {
   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;
+// 净零切换（ADR 0003 增补 v1.2.7）：同值写不改变配置对象身份、宿主快照不重建；
+// 两次真内容变化（displayName 加空格再复原）推动快照重建，净效果＝用户配置一字不改。
+async function touchRouteIdentity(ctx, log) {
+  void log;
+  const describe = () => ctx.settings?.describe?.()?.find?.((x) => x?.ns === "llm-pi-ai");
+  const first = describe();
+  const route = first?.user?.providers?.["github-copilot"];
+  if (!first || !route || typeof route !== "object" || Array.isArray(route)) return false;
+  const hadOwn = Object.prototype.hasOwnProperty.call(route, "displayName");
+  const current = hadOwn ? route.displayName : undefined;
+  const probeBase = typeof current === "string" && current.length > 0 ? current : "GitHub Copilot";
+  const path = ["providers", "github-copilot", "displayName"];
+  await ctx.settings.mutate("llm-pi-ai", [{ op: "set", path, value: `${probeBase} ` }], first.revision);
+  const second = describe();
+  await ctx.settings.mutate("llm-pi-ai", [hadOwn ? { op: "set", path, value: current } : { op: "unset", path }], second?.revision);
+  return true;
 }
 
-// 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 };
+// intentVersion 持久层（T3 契约）：`<dataDir>/auth-intent.json` 原子写；
+// scope 未知时读写一律抛错 → 写路由 503，不伪成功。
+function createIntentIO(scope) {
+  const file = scope?.known ? join(scope.dataDir, "auth-intent.json") : null;
+  return {
+    read() {
+      if (!file) throw new Error("scope-unavailable");
+      const raw = readJson(file);
+      return typeof raw?.intentVersion === "number" ? raw.intentVersion : 0;
+    },
+    bump() {
+      if (!file) throw new Error("scope-unavailable");
+      mkdirSync(scope.dataDir, { recursive: true });
+      const cur = readJson(file);
+      const next = (typeof cur?.intentVersion === "number" ? cur.intentVersion : 0) + 1;
+      writeJsonAtomic(file, { version: 1, intentVersion: next, updatedAt: new Date().toISOString() });
+      return next;
+    },
+  };
 }
 
-// 启动序列（严格按序 boot 0→1→2；整体 try/catch，失败只记 lastError +
-// logger.warn，绝不阻断挂载；所有写入幂等，崩溃现场下个 boot 安全重试）。
-async function bootRefresh(ctx, opts) {
-  const stateFile = opts.stateFile ?? defaultStateFile();
-  let state = loadState(stateFile);
-  try {
-    if (state.lastError === "state-corrupt") {
-      // 损坏已隔离：持久化安全态（/status 稳定可见、激活丢失→自愈停用，🟡-4）
-      saveState(stateFile, state);
-    }
-    if (!state.journal && !state.activated && !state.restartState) return; // R9：未激活不触碰
-    let install = null;
-    try {
-      install = resolveInstall(opts);
-    } catch {
-      install = null;
-    }
-    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;
-    };
+// 服务错误 → HTTP 投影（白名单 code，脱敏）
+function serviceError(res, err) {
+  const map = {
+    SCOPE_UNAVAILABLE: [503, "scope-unavailable"],
+    INVALID_OPERATION: [400, "invalid-operation"],
+    INVALID_REQUEST: [400, "bad-request"],
+    INVALID_CATALOG_SOURCE: [400, "invalid-catalog-source"],
+    INSTALL_UNRESOLVED: [409, "install-unresolved"],
+    PREVIEW_INVALID: [409, "preview-invalid"],
+    PREVIEW_STALE: [409, "preview-stale"],
+    AUTH_CHANGED: [409, "auth-changed"],
+    EVIDENCE_UNAVAILABLE: [409, "evidence-unavailable"],
+    EVIDENCE_STALE: [409, "evidence-stale"],
+    RESOURCE_BUSY: [423, "resource-busy"],
+    STATE_UNKNOWN: [409, "state-unknown"],
+    DEPS_MISSING: [500, "service-not-wired"],
+  };
+  const m = map[err?.code];
+  if (m) {
+    json(res, m[0], { ok: false, error: m[1], reason: err.reason ?? null });
+    return;
+  }
+  // 策略拒绝（empty-intersection-unconfirmed／inherited-overrides-unclearable 等）
+  json(res, 409, { ok: false, error: sanitizeAuthError(err) });
+}
 
-    // boot 0：journal=prepared 崩溃恢复（先于激活门，但先过兼容 gate，R3-1）
-    if (state.journal?.phase === "prepared") {
-      if (!install || install.version !== state.journal.appliedAgainstPiAiVersion) {
-        state = setLastError(state, `prepared-incompatible: journal against ${state.journal.appliedAgainstPiAiVersion}, current ${install?.version ?? "none"} — re-run refresh preview`);
-        saveState(stateFile, state); // 目录零写入、journal 保留
-        return;
-      }
-      const replay = mergeCatalog(readDiskCatalog(), state.journal.pendingOverlay);
-      if (replay.added.length > 0) {
-        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;
-        // 注册表通道：注入只是把条目放进进程内注册表，宿主快照可能已在挂载时按旧目录
-        // 定稿——用宿主 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 = {
-        sourcePiAiVersion: state.journal.source?.piAiVersion ?? null,
-        integrity: state.journal.source?.integrity ?? null,
-        appliedAgainstPiAiVersion: state.journal.appliedAgainstPiAiVersion,
-        catalogSchemaVersion: 1,
-      };
-      state.activated = true;
-      // 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);
-    }
+export function apply(ctx, opts = {}) {
+  const r = routes();
+  const scope = resolveRuntimeScope(ctx);
+  const intentIO = createIntentIO(scope);
+  const legacyPath = opts.stateFile ?? defaultStateFile();
+  const log = (m) => ctx.logger?.info?.(m);
+  let lastSyncError;
+  const refreshMutex = createMutex(); // 预览串行（apply/retire 在服务队列内串行）
+
+  // v2 状态读写层（profile 隔离；unknownVersion 以标记对象上抛给服务层拒绝）
+  const stateIO = {
+    load: () => {
+      const loaded = loadRefreshState(scope, { legacyPath });
+      if (loaded.flags.unknownVersion) return { unknownVersion: true };
+      return loaded.state;
+    },
+    save: (state) => saveRefreshState(scope, state),
+  };
 
-    // boot 1：自愈（仅 activated，且当前 pi-ai 版本==基线才重放；跨版本见 gate）
-    if (state.activated) {
-      const baseline = state.appliedProvenance?.appliedAgainstPiAiVersion;
-      const overlayIds = overlayEntryIds(state.appliedOverlay);
-      if (overlayIds.length > 0 && baseline) {
-        if (!install) {
-          state = setLastError(state, "self-heal-incompatible: pi-ai installation not found");
-          saveState(stateFile, state);
-        } else if (install.version === baseline) {
-          const replay = mergeCatalog(readDiskCatalog(), state.appliedOverlay);
-          if (replay.added.length > 0) {
-            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);
-              // 注入通常落在宿主快照之后（宿主在挂载时即定稿目录解析结果）——用宿主
-              // 自己的 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 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(",")}`);
-            saveState(stateFile, state);
-          }
-          // 条目已原生存在 → 空操作
-        }
-      }
-    }
+  // 模型目录同步只在登录成功（且 handoff 完好）后执行；失败经 /status 暴露 syncError。
+  const runSync = (handoff) => syncAvailableModels(ctx, { ...opts, handoff, handoffIntact: controller.handoffIntact }).then(() => {
+    lastSyncError = undefined;
+  }).catch((err) => {
+    lastSyncError = String(err?.message ?? err);
+    ctx.logger?.warn?.("copilot-auth: model sync failed: %s", lastSyncError);
+  });
 
-    // boot 2：本 boot 未写目录时，两个独立出口（R3-5 职责分离）
-    if (!bootPatched) {
-      // 2a. journal=committed → settings 真 CAS（settings 同步的唯一触发源）
-      if (state.journal?.phase === "catalog-committed-needs-restart") {
-        const j = state.journal;
-        let consumed = false;
-        let failed = null;
-        try {
-          if (!install) throw new Error("pi-ai installation not found");
-          // 语义前置（Y2-3）：targetIds 全部可由当前目录解析；whole-file digest 仅诊断
-          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");
-          if (!desc) throw new Error("settings namespace llm-pi-ai unavailable");
-          const view = viewFromUserLayer(desc.user);
-          if (digest(view) === digest(j.settingsBaseline)) {
-            await ctx.settings.mutate("llm-pi-ai", [
-              { op: "set", path: ["providers", "github-copilot", "models"], value: j.targetIds.map((id) => ({ id })) },
-              { op: "unset", path: ["providers", "github-copilot", "modelOverrides"] },
-            ], desc.revision); // 真 CAS：revision 不符由 settings 抛 SETTINGS_CONFLICT
-            consumed = true;
-          } else if (viewEqualsTarget(view, j.targetIds)) {
-            consumed = true; // 已等于 target → 幂等消费，不再 mutate
-          } else {
-            failed = "settings-conflict: configuration changed since preview; re-run refresh";
-          }
-        } catch (err) {
-          failed = err?.code === "SETTINGS_CONFLICT" || /conflict/i.test(String(err?.message ?? ""))
-            ? `settings-conflict: ${err.message}`
-            : String(err?.message ?? err);
-        }
-        if (consumed) {
-          state.journal = null;
-          state = clearLastError(state);
-          saveState(stateFile, state);
-        } else if (failed) {
-          state = setLastError(state, failed); // 不覆盖、记 conflict、/status 上报
-          saveState(stateFile, state);
-        }
-      }
-      // 2b. restartState 非空且 expected entries 已在目录 → 仅清 restartState
-      // （不携带 settings 意图：单独存在时不得触碰 describe/mutate）
-      if (state.restartState && install) {
-        const ids = await servedIds();
-        if (overlayEntryIds(state.appliedOverlay).every((id) => ids.has(id))) {
-          state.restartState = null;
-          state = clearLastError(state);
-          saveState(stateFile, state);
-        }
-      }
-    }
-  } catch (err) {
-    try {
-      saveState(stateFile, setLastError(state, err));
-    } catch { /* 记录失败不掩盖 */ }
-    ctx.logger?.warn?.("copilot-auth: refresh boot failed: %s", String(err?.message ?? err));
-  }
-}
+  // 授权控制器（T3）：软撤回＋风险锁存；退出/重新授权在当前宿主下统一禁用。
+  const controller = createAuthorizationController(ctx, {
+    scope,
+    intentIO,
+    onAuthorized: (handoff) => { void runSync(handoff); },
+  });
 
-// /status 专用只读读取：不隔离、不写盘（隔离只在 boot 发生一次）
-function peekState(path) {
-  const corrupt = () => ({ ...freshState(), lastError: "state-corrupt" });
-  let raw;
+  // ---- 初始化期能力探测（Q23：GET status 不执行写探针，通道分类来自此处缓存） ----
+  let installInfo = null;
   try {
-    raw = readJson(path);
+    installInfo = resolveInstall(opts);
   } catch {
-    return corrupt();
+    installInfo = null;
   }
-  if (raw === undefined) return freshState();
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return corrupt();
-  return { ...freshState(), ...raw };
-}
-
-// preview 与 apply 共享的输入计算——digest 绑定的正确性依赖两侧走同一代码路径。
-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, 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);
-  const currentIds = Array.isArray(view.models)
-    ? view.models.map((m) => m?.id).filter((x) => typeof x === "string")
-    : [];
-  const diff = diffModels(currentIds, ids, catalogIds);
-  const customizationReset = {
-    modelEntryIds: (Array.isArray(view.models) ? view.models : [])
-      .filter((m) => m && typeof m === "object" && Object.keys(m).some((k) => k !== "id"))
-      .map((m) => m.id),
-    modelOverrideIds:
-      view.modelOverrides && typeof view.modelOverrides === "object" && !Array.isArray(view.modelOverrides)
-        ? Object.keys(view.modelOverrides)
-        : [],
-  };
-  const digests = {
-    settings: digest(view), // raw 完整视图：字段级变化必漂移（R3-2）
-    available: digest([...ids].sort()),
-    catalog: digest(local.bytes), // 本地目录文件字节
-    remote: digest(resolved.catalog), // 实际使用的目录来源对象（与 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) };
+  let catalogMode = "unknown";
+  let blockedReason = installInfo ? null : "install-unresolved";
+  if (installInfo) {
+    if (installInfo.writable === true) {
+      catalogMode = "file";
+    } else {
+      // 只读安装树：注册表面可用性探测（boot 期一次，异步；不写任何文件）
+      void loadRegistryModules(installInfo, log).then((m) => {
+        if (m?.via) catalogMode = "registry";
+        else {
+          catalogMode = "blocked";
+          blockedReason = "inject-unavailable";
+        }
+      }).catch(() => {
+        catalogMode = "blocked";
+        blockedReason = "inject-unavailable";
+      });
     }
-    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;
-  }
-}
+  // ---- 事务内核（T9）与服务（T8）接线 ----
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch?.bind(globalThis);
+  const transaction = installInfo ? createTransaction(ctx, {
+    scope,
+    stateIO,
+    readIntentVersion: () => intentIO.read(),
+    clock: realClock,
+    install: installInfo,
+    deps: {
+      describeConfigView: () => describeRouteView(ctx),
+      mutateSettings: (ops, expectedRevision) => ctx.settings.mutate("llm-pi-ai", ops, expectedRevision),
+      listServedIds: () => servedModelIds(ctx),
+      touchRouteIdentity: () => touchRouteIdentity(ctx, log),
+      readDiskCatalog: () => JSON.parse(readFileSync(installInfo.catalogFile, "utf8")),
+      injectRegistry: (overlay, { allowedKeys }) => (opts.injectRegistry ?? injectCatalogEntries)(installInfo, overlay, { log, allowedKeys }),
+      registryIds: () => (opts.registryIds ?? registryModelIds)(installInfo, log),
+    },
+    log,
+    servedRetry: { attempts: 5, delayMs: 150 },
+  }) : null;
+
+  const resolveCatalogForService = async (catalogSource) => {
+    if (!installInfo) {
+      const err = new Error("install-unresolved");
+      err.code = "INSTALL_UNRESOLVED";
+      throw err;
+    }
+    if (catalogSource !== undefined && !["latest", "local", "overlay"].includes(catalogSource)) {
+      const err = new Error("invalid-catalog-source");
+      err.code = "INVALID_CATALOG_SOURCE";
+      throw err;
+    }
+    const local = readLocalCatalog(opts);
+    let resolved;
+    if (catalogSource === "local") {
+      resolved = { catalog: local.catalog, normalized: null, catalogSource: "local", catalogError: null, provenance: { kind: "local" } };
+    } else {
+      resolved = await resolveCatalogSource(opts, catalogSource === "overlay" ? "overlay" : undefined, fetchImpl, catalogShapeKeys(local.catalog));
+    }
+    const merged = mergeCatalog(local.catalog, resolved.catalog);
+    const resolvableIds = Object.values(merged.merged).flatMap((s) => Object.keys(s ?? {}));
+    return {
+      catalogSource: resolved.catalogSource,
+      catalogError: resolved.catalogError,
+      skipped: merged.skipped,
+      normalized: resolved.normalized,
+      addedOverlay: merged.addedOverlay,
+      resolvableIds,
+      newEntryCount: overlayEntryIds(merged.addedOverlay).length,
+      provenance: resolved.provenance,
+    };
+  };
 
-export function apply(ctx, opts = {}) {
-  const r = routes();
-  let attempt = emptyState();
-  let lastSyncError;
-  const refreshMutex = createMutex(); // 宿主单进程内互斥（不支持多实例，见 README）
+  const refreshService = createRefreshService(ctx, {
+    scope,
+    stateIO,
+    readIntentVersion: () => intentIO.read(),
+    clock: realClock,
+    deps: {
+      resolveCatalog: resolveCatalogForService,
+      describeConfigView: () => describeRouteView(ctx),
+    },
+    transaction,
+    fetchImpl,
+  });
 
-  // 启动序列：prepared 恢复（先过兼容 gate）→ 激活门 → 自愈 → settings 真 CAS。
-  // 绝不阻断挂载；失败仅 lastError + warn。opts.onBootDone 为测试钩子（boot  settle 回调）。
-  void bootRefresh(ctx, opts)
+  // 启动序列（boot 恢复＋保守激活/自愈，T9 bootRecover）；绝不阻断挂载。
+  void refreshService.bootReady()
     .catch((err) => {
       ctx.logger?.warn?.("copilot-auth: refresh boot failed: %s", String(err?.message ?? err));
     })
     .finally(() => opts.onBootDone?.());
 
-  // 模型目录同步只在登录成功后执行（2026-09-05 对齐结论：挂载不再同步）。
-  // 插件启动/重启绝不触碰用户 settings，用户精简过的目录不会被动重置。
-  // 失败不静默：错误经 /status 的 syncError 字段暴露，便于诊断。
-  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);
-  });
+  // ==================== 授权路由（T3/T4） ====================
 
   ctx.webServer.register({
     kind: "exact",
     path: r.start,
     handler: (req, res) => {
       if (!guard(req, res, "POST")) return;
-      if (attempt.status === "running") {
-        json(res, 409, { ok: false, error: "already running" });
+      if (!scope.known) {
+        json(res, 503, { ok: false, error: "scope-unavailable" });
         return;
       }
-      attempt = emptyState();
-      attempt.status = "running";
-      const interaction = {
-        notify: (notice) => {
-          attempt.notices.push(notice);
-        },
-        prompt: (p) => {
-          // 企业域名提问答空串（公司是普通 github.com 组织账号）；
-          // 其余任何 prompt 都是未预期的，拒绝并使 attempt 失败。
-          if (p && typeof p.message === "string" && p.message.includes("Enterprise")) {
-            return Promise.resolve("");
-          }
-          return Promise.reject(new Error("unexpected prompt: " + (p?.message ?? String(p))));
-        },
-      };
-      // 响应先行：begin 以后台任务执行，handler 返回路径不得 await begin。
-      void ctx.authorization
-        .begin({ key: CREDENTIAL_KEY, method: "oauth", interaction })
-        .then((outcome) => {
-          // AuthorizationOutcome.status: 'authorized' | 'cancelled'（types.d.ts L68-71）
-          if (outcome && outcome.status === "authorized") {
-            attempt.status = "authorized";
-            void sync();
-          } else {
-            attempt.status = "failed";
-            attempt.error = "登录已取消";
-          }
-        })
-        .catch((err) => {
-          attempt.status = "failed";
-          attempt.error = String(err?.message ?? err);
-        });
-      json(res, 202, { ok: true });
+      try {
+        const { attemptId } = controller.start();
+        json(res, 202, { ok: true, attemptId });
+      } catch (err) {
+        if (err?.code === "ATTEMPT_RUNNING") {
+          json(res, 409, { ok: false, error: "already running", attemptId: err.attemptId });
+          return;
+        }
+        if (err?.code === "AUTH_UNSAFE") {
+          json(res, 409, { ok: false, error: "auth-unsafe" });
+          return;
+        }
+        json(res, 500, { ok: false, error: sanitizeAuthError(err) });
+      }
+    },
+  });
+
+  ctx.webServer.register({
+    kind: "exact",
+    path: r.cancel,
+    handler: async (req, res) => {
+      if (!guard(req, res, "POST")) return;
+      if (!scope.known) {
+        json(res, 503, { ok: false, error: "scope-unavailable" });
+        return;
+      }
+      try {
+        const { withdrawalDelivery } = await controller.cancel();
+        json(res, 200, { ok: true, withdrawalDelivery });
+      } catch (err) {
+        json(res, 500, { ok: false, error: sanitizeAuthError(err) });
+      }
     },
   });
 
@@ -730,7 +547,7 @@ export function apply(ctx, opts = {}) {
     path: r.state,
     handler: (req, res) => {
       if (!guard(req, res, "GET")) return;
-      json(res, 200, attempt);
+      json(res, 200, controller.snapshot());
     },
   });
 
@@ -740,73 +557,96 @@ export function apply(ctx, opts = {}) {
     handler: async (req, res) => {
       if (!guard(req, res, "GET")) return;
       // describeRecord 只回传 presence，不把含 token 的 GrantRecord 拉进内存。
-      let configured = false;
+      let credential = "absent";
       try {
         const info = await ctx.credentials.describeRecord(CREDENTIAL_KEY);
-        configured = info?.configured === true;
-      } catch {
-        configured = false;
-      }
-      // refresh 状态块：lastError 直读状态文件顶层（R3-6）；pendingRestart 派生自
-      // 状态文件（journal 相位或 restartState），不用模块布尔；piAiVersion /
-      // catalogDigest / catalogFile 来自同根解析，digest 为当前文件字节 sha256
-      // （E2E 据此把被检查文件绑定到实际加载副本，R3-8/R4-5）。
-      let install = null;
-      try {
-        install = resolveInstall(opts);
+        credential = info?.configured === true ? "present" : "absent";
       } catch {
-        install = null;
+        credential = "read-error";
       }
+      const authSnapshot = controller.snapshot();
+      // refresh 块：只读聚合（通道分类来自启动期缓存；GET 不执行写探针，Q23）
+      const loaded = loadRefreshState(scope, { legacyPath });
+      const st = loaded.flags.unknownVersion ? null : loaded.state;
       let catalogDigest = null;
-      if (install) {
+      if (installInfo) {
         try {
-          catalogDigest = digest(readFileSync(install.catalogFile));
+          catalogDigest = digest(readFileSync(installInfo.catalogFile));
         } catch {
           catalogDigest = null;
         }
       }
-      const state = peekState(opts.stateFile ?? defaultStateFile());
+      let registryViaNow = null;
+      let registryMismatch = null;
+      try {
+        registryViaNow = registryVia();
+        registryMismatch = registryInstanceMismatch();
+      } catch { /* 诊断字段缺失不阻断 */ }
       const refresh = {
-        activated: state.activated === true,
-        pendingRestart: state.restartState != null || state.journal?.phase === "catalog-committed-needs-restart",
-        phase: state.journal?.phase ?? null,
-        lastError: state.lastError ?? null,
-        piAiVersion: install?.version ?? null,
+        scopeAvailable: scope.known,
+        catalogWritable: installInfo ? installInfo.writable === true : null,
+        catalogMode,
+        blockedReason,
+        registryInjected: st ? overlayEntryIds(st.appliedOverlay).length : 0,
+        registryVia: registryViaNow,
+        registryInstanceMismatch: registryMismatch,
+        catalogFile: installInfo?.catalogFile ?? null,
+        settingsNotServed: (await registryServedDiagnostics(ctx, st ? overlayEntryIds(st.appliedOverlay) : [])).missing,
+        activated: st?.activated === true,
+        activeOperation: st?.activeOperation ?? null,
+        lastResult: st?.lastResult ?? null,
+        pendingRestart: !!st?.restartState || st?.activeOperation?.phaseResult?.status === "pending-restart",
+        legacyStateDetected: loaded.flags.legacyStateDetected === true,
+        stateUnknownVersion: loaded.flags.unknownVersion === true,
+        piAiVersion: installInfo?.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,
+        lastError: st?.lastError ?? null,
       };
-      // 诊断口径（ADR 0003 增补）：已注入、被 settings 引用、却没能从路由端出来的 id。
-      // "注册表里有了但 picker 里看不到"这类问题的唯一直接证据；宿主 API 不可用时为 null。
-      refresh.settingsNotServed = (await registryServedDiagnostics(ctx, overlayEntryIds(state.appliedOverlay))).missing;
-      json(res, 200, { configured, syncError: lastSyncError, refresh });
+      // GET status 的 operationId 查询三态（active / last / unknown；unknown≠未执行）
+      let operation = null;
+      const opId = typeof req.url === "string" ? new URL(req.url, "http://local").searchParams.get("operationId") : null;
+      if (opId) {
+        try {
+          operation = await refreshService.status({ operationId: opId });
+        } catch {
+          operation = { query: "unknown" };
+        }
+      }
+      json(res, 200, {
+        configured: credential === "present",
+        syncError: lastSyncError,
+        authorization: {
+          credential,
+          attempt: authSnapshot,
+          riskLatch: authSnapshot.riskLatch,
+          capabilities: { logout: false, reauthorize: false },
+        },
+        refresh,
+        ...(operation ? { operation } : {}),
+      });
     },
   });
 
+  // 退出登录：当前宿主桥接无法证明安全退出（D-01），统一拒绝且绝不 deleteRecord。
   ctx.webServer.register({
     kind: "exact",
     path: r.logout,
-    handler: async (req, res) => {
+    handler: (req, res) => {
       if (!guard(req, res, "POST")) return;
-      // 幂等契约：deleteRecord 对不存在记录是 no-op 且正常 resolve，
-      // 真实删除与否由随后的 /status 反映。异常兜底与其余路由对齐
-      // （2026-09-28 审计：无 try/catch 的 reject 会造成连接悬挂/未处理拒绝）。
-      try {
-        await ctx.credentials.deleteRecord(CREDENTIAL_KEY);
-      } catch (err) {
-        json(res, 500, { ok: false, error: String(err?.message ?? err) });
-        return;
-      }
-      json(res, 200, { ok: true });
+      json(res, 403, { ok: false, error: "logout-safety-unavailable" });
     },
   });
 
-  // 手动刷新可用模型目录 · preview：只读，返回 diff + customizationReset + digest 组。
-  // body 可带 { "mode": "overlay" } 用内置覆盖层出 diff（离线 bootstrap）。
+  // ==================== 模型管理路由（协议 v2，T8/T9/T10） ====================
+
+  const requireProtocol = (res, body) => {
+    if (body?.protocolVersion !== PROTOCOL_VERSION) {
+      json(res, 400, { ok: false, error: "upgrade-required" });
+      return false;
+    }
+    return true;
+  };
+
   ctx.webServer.register({
     kind: "exact",
     path: r.refreshPreview,
@@ -819,43 +659,20 @@ export function apply(ctx, opts = {}) {
         json(res, 400, { ok: false, error: "bad-body" });
         return;
       }
-      const mode = body?.mode;
-      if (mode !== undefined && mode !== "latest" && mode !== "overlay") {
-        json(res, 400, { ok: false, error: "invalid-mode" });
-        return;
-      }
+      if (!requireProtocol(res, body)) return;
       try {
-        const inputs = await computeRefreshInputs(ctx, opts, mode);
-        json(res, 200, {
-          ok: true,
-          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,
-          kept: inputs.diff.kept,
-          target: inputs.diff.target,
-          customizationReset: inputs.customizationReset,
-          digests: inputs.digests,
-        });
+        const out = await refreshMutex(() => refreshService.preview(body ?? {}));
+        json(res, 200, out);
       } catch (err) {
         if (err instanceof InvalidModeError) {
           json(res, 400, { ok: false, error: "invalid-mode" });
           return;
         }
-        json(res, 500, { ok: false, error: String(err?.message ?? err) });
+        serviceError(res, err);
       }
     },
   });
 
-  // 手动刷新 · apply：mutex 内重算全部输入 digest 与回传比对（漂移 → 409
-  // preview-stale，client 重新 preview）；一致则 write-ahead：journal(prepared)
-  // → 原子提交目录 → 合入 appliedOverlay + activated → journal 推进 committed。
-  // 重启 dsh web 后由启动序列把 settings 目录镜像重建为 target（见 boot 序列）。
   ctx.webServer.register({
     kind: "exact",
     path: r.refreshApply,
@@ -868,121 +685,38 @@ export function apply(ctx, opts = {}) {
         json(res, 400, { ok: false, error: "bad-body" });
         return;
       }
-      const mode = body?.mode;
-      if (mode !== undefined && mode !== "latest" && mode !== "overlay") {
-        json(res, 400, { ok: false, error: "invalid-mode" });
+      if (!requireProtocol(res, body)) return;
+      try {
+        const out = await refreshService.apply(body ?? {});
+        json(res, 200, out);
+      } catch (err) {
+        serviceError(res, err);
+      }
+    },
+  });
+
+  ctx.webServer.register({
+    kind: "exact",
+    path: r.refreshRetire,
+    handler: async (req, res) => {
+      if (!guard(req, res, "POST")) return;
+      let body;
+      try {
+        body = await readBody(req);
+      } catch {
+        json(res, 400, { ok: false, error: "bad-body" });
         return;
       }
+      if (!requireProtocol(res, body)) return;
       try {
-        const out = await refreshMutex(async () => {
-          const inputs = await computeRefreshInputs(ctx, opts, mode);
-          const got = body?.digests ?? {};
-          for (const k of ["settings", "available", "catalog", "remote"]) {
-            if (got[k] !== inputs.digests[k]) {
-              return { code: 409, payload: { ok: false, error: "preview-stale" } };
-            }
-          }
-          // 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({
-            settingsBaseline: inputs.view,
-            targetIds: inputs.diff.target,
-            pendingOverlay: inputs.merged.addedOverlay, // catalog-shaped 增量（R3-4）
-            appliedAgainstPiAiVersion: install.version,
-            catalogBaselineDigest: inputs.digests.catalog,
-            patchedCatalogDigest: digest(patchedBytes),
-            source: inputs.resolved.provenance,
-          });
-          saveState(stateFile, state); // ① write-ahead：prepared
-          writeJsonAtomic(install.catalogFile, inputs.merged.merged); // ② 目录原子提交
-          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.restartState = restartMarker("refresh", digest(state.appliedOverlay));
-          saveState(stateFile, state); // ③ appliedOverlay/activated 落盘
-          state = loadState(stateFile);
-          state.journal = advanceJournal(state.journal);
-          saveState(stateFile, state); // ④ 相位推进 catalog-committed-needs-restart
-          return { code: 200, payload: { ok: true, restartRequired: true } };
-        });
-        json(res, out.code, out.payload);
-      } catch (err) {
-        if (err instanceof InvalidModeError) {
-          json(res, 400, { ok: false, error: "invalid-mode" });
+        const out = await refreshService.retire(body ?? {});
+        if (out.ok === false) {
+          json(res, 409, { ok: false, error: out.error ?? "not-active" });
           return;
         }
-        json(res, 500, { ok: false, error: String(err?.message ?? err) });
+        json(res, 200, out);
+      } catch (err) {
+        serviceError(res, err);
       }
     },
   });