@nimoxie/dsh-ui-tweaks 0.2.1 → 0.2.2

package/lib/index.js

@@ -1,20 +1,18 @@
 /**
  * dsh-ui-tweaks host half.
  *
- * 两条回环路由：
- * - GET  /api/ui-tweaks/local-plugins：返回当前 profile package.json
- *   dependencies 里非 registry 直装（link:/file:/git+/github:/http）的包名清单，
- *   外加运行中的 DSH 版本（`dsh` 字段，读不到为空串）—— 客户端更新面板据此把
- *   「新版要求更高 DSH」的行标成「DSH 不符」，不让人装上去起不来。
- *   浏览器半区的更新面板据此把这些插件标成「本地链接」或「Git 直装」、跳过
- *   registry 比对 —— listBundles 不透传安装来源，而「npm 上恰好也发布过」的
- *   非 registry 源（如 @nimoxie/dsh-model-organizer）在客户端侧没有别的办法认。
- * - POST /api/ui-tweaks/normalize-excludes：手动触发一次下面的归并，回
- *   {ok, changed, kept, removed}；插件加载时也会静默跑一次。
- * - GET  /api/ui-tweaks/restart：只读「重启方案」（shell / relaunch / manual），
- *   POST 同路径才真的执行（先写响应、约 0.4s 后退出进程）；非回环 403、其它方法 405。
- *   故意拆成两个方法：GET 无副作用，浏览器预取或直接粘 URL 都不会把宿主停掉。
- *   三种模式见文件末尾「模块 7」。
+ * 回环路由（只放行 127.0.0.1 / ::1；写操作集中在这里，客户端半区调它们）：
+ * - GET  /local-plugins：profile 里非 registry 直装的包名 + 运行中的 DSH 版本。
+ *   客户端据此把「本地链接 / Git 直装」标出来并跳过 registry 比对，也用来判「DSH 不符」。
+ * - POST /normalize-excludes：手动归并豁免表（加载时也会静默跑一次）。
+ * - POST /precheck-exempt：强制更新前的预检（列出仍在冷静期、会拦住这次安装的包）。
+ * - POST /force-exempt：把 name@version 写成豁免表里该包生效的第一条。
+ * - POST /schedule-exempt-cleanup：登记「到期自动删豁免」（版本满 24h 后清掉）。
+ * - POST /open-path：打开 / 显示位置 / 用指定应用打开（会话释放后改动卡的动作补位）；
+ *   action:"probe" 只诊断子进程能不能起，不弹窗。
+ * - POST /open-apps：系统文件关联枚举（同上，供「打开方式」菜单）。
+ * - GET|POST /restart：GET 只读重启方案（shell / relaunch / manual），POST 才执行。
+ *   故意拆两个方法：GET 无副作用，预取或直粘 URL 都不会把宿主停掉（见文末「模块 7」）。
  *
  * 写操作（全文件只此一处）：归并 profile 的 pnpm-workspace.yaml 里
  * minimumReleaseAgeExclude 序列。为什么必须收敛：
@@ -54,7 +52,7 @@
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 
 export const name = "ui-tweaks";
@@ -116,6 +114,18 @@ function unquote(s) {
   return m ? m[2] : s;
 }
 
+/**
+ * YAML 标量输出：plain scalar **不能**以 `@` / `` ` `` 等指示符开头，而 scoped 包名
+ * （@scope/pkg@1.2.3）全以 @ 开头 —— 直接裸写会让整个 pnpm-workspace.yaml 解析失败
+ * （pnpm 报 bad indentation of a sequence entry），profile 里所有 pnpm 操作全挂。
+ * 安全字符集以外的值一律用单引号包起来（内部单引号翻倍）。
+ */
+function yamlScalar(value) {
+  const s = String(value);
+  if (/^[A-Za-z0-9_][A-Za-z0-9._~\/@+-]*$/.test(s)) { return s; }
+  return "'" + s.replace(/'/g, "''") + "'";
+}
+
 /** 条目原文 → 裸值：去空白、去行尾注释、去引号 */
 function entryValue(raw) {
   const s = String(raw).trim();
@@ -254,7 +264,20 @@ export function normalizeReleaseAgeExcludes(dirOverride) {
 
     const entryIdx = new Set(entries.map((e) => e.idx));
     const keptInOrder = entries.filter((e) => keep.has(e.idx)).map((e) => e.value);
-    const newRaw = lines.filter((line, i) => !entryIdx.has(i) || keep.has(i)).join("");
+    const byIdx = new Map(entries.map((e) => [e.idx, e]));
+    const newRaw = lines.map((line, i) => {
+      if (!entryIdx.has(i)) { return line; }
+      if (!keep.has(i)) { return ""; }
+      /* 顺手修掉历史上「以 @/` 开头的裸标量」：scoped 包名做 plain scalar 会让整个
+         pnpm-workspace.yaml 解析失败（pnpm: bad indentation of a sequence entry），
+         一坏就是 profile 里所有 pnpm 操作全挂。只改确实不安全的那几行，其余保持原字节。 */
+      if (!/^\s*-\s+['"]/.test(line) && /^\s*-\s+[@`]/.test(line)) {
+        const e = byIdx.get(i);
+        const indent = (/^\s*/.exec(line) || [""])[0];
+        return indent + "- " + yamlScalar(e.value) + "\n";
+      }
+      return line;
+    }).join("");
 
     if (newRaw === raw) { return { ok: true, changed: false, kept: keptInOrder, removed: [], path: wsPath }; }
 
@@ -416,11 +439,11 @@ export function forceExemptVersion(name, version, dirOverride) {
     if (blk.keyLine < 0) {
       // 没有这个键：文件末尾追加一段（原字节全部保留）
       const sep = raw.length === 0 || raw.endsWith("\n") ? "" : "\n";
-      newRaw = raw + sep + EXCLUDE_KEY + ":\n  - " + value + "\n";
+      newRaw = raw + sep + EXCLUDE_KEY + ":\n  - " + yamlScalar(value) + "\n";
     } else {
       const first = blk.entries[0];
       const indent = first ? (/^(\s*)-/.exec(first.line) || [])[1] || "  " : "  ";
-      const insert = indent + "- " + value + "\n";
+      const insert = indent + "- " + yamlScalar(value) + "\n";
       const dup = blk.entries.find((e) => e.value === value);
       const lines = blk.lines.slice();
       if (dup) { lines.splice(dup.idx, 1); }        // 已有同值条目：移到块首
@@ -437,6 +460,229 @@ export function forceExemptVersion(name, version, dirOverride) {
   }
 }
 
+/**
+ * 到期清理：把 `name@version` 这一条从豁免表里删掉（幂等：没有就 no-op）。
+ * 用于强制更新的「装完不删、到期再删」—— 见 apply 里的 scheduleCleanup。
+ */
+export function dropExemptVersion(name, version, dirOverride) {
+  try {
+    const dir = dirOverride || findProfileDir();
+    if (!dir) { return { ok: false, code: "profile-not-found" }; }
+    const wsPath = join(dir, WORKSPACE_FILE);
+    let raw;
+    try { raw = readFileSync(wsPath, "utf8"); }
+    catch (e) { return { ok: false, code: "workspace-unreadable: " + String((e && e.code) || e) }; }
+    const value = String(name) + "@" + String(version);
+    const blk = excludeBlockOf(raw);
+    const hit = blk.entries.find((e) => e.value === value);
+    if (!hit) { return { ok: true, changed: false, path: wsPath, entry: value }; }
+    const lines = blk.lines.slice();
+    lines.splice(hit.idx, 1);
+    const newRaw = lines.join("");
+    if (newRaw === raw) { return { ok: true, changed: false, path: wsPath, entry: value }; }
+    const w = atomicWriteWorkspace(dir, wsPath, raw, newRaw);
+    if (!w.ok) { return { ok: false, code: w.code, path: wsPath, backup: w.backup }; }
+    return { ok: true, changed: true, path: wsPath, backup: w.backup, entry: value };
+  } catch (e) {
+    return { ok: false, code: String((e && e.message) || e) };
+  }
+}
+
+/**
+ * Explorer 只认「编码过的 file URI」：它在自己的命令行里按逗号/等号切字段，
+ * 裸路径遇到分隔符会把后半截丢掉（官方 dsh-native-command 同款处理）。
+ * 非 ASCII 的百分号转义要还原（Explorer 拒绝百分号编码的非 ASCII，会打开「文档」目录）。
+ */
+export function explorerTargetOf(windowsPath) {
+  let uri;
+  try { uri = pathToFileURL(windowsPath, { windows: true }).href; }
+  catch { return windowsPath; }
+  return uri
+    .replace(/(?:%[89A-F][0-9A-F])+/gi, (escaped) => { try { return decodeURIComponent(escaped); } catch { return escaped; } })
+    .replace(/,/g, "%2C")
+    .replace(/=/g, "%3D");
+}
+
+/**
+ * 纯函数：把「路径 + 动作」翻成一条原生命令（便于离线单测，不 spawn）。
+ * 只负责「打开 / 定位」这两种；用指定应用打开由官方 native-command 负责。
+ * @returns {{cmd: string, args: string[]} | null} 路径不合法时 null。
+ */
+export function nativeOpenCommand(targetPath, action) {
+  const p = String(targetPath || "");
+  const act = action === "reveal" ? "reveal" : "open";
+  if (!p) { return null; }
+  const windowsAbs = /^[A-Za-z]:[\\/]/.test(p) || p.slice(0, 2) === "\\\\";
+  const posixAbs = p.charAt(0) === "/";
+  if (!windowsAbs && !posixAbs) { return null; }
+  if (process.platform === "win32") {
+    if (act === "reveal") { return { cmd: "explorer.exe", args: ["/select,", explorerTargetOf(p)] }; }
+    return { cmd: "explorer.exe", args: [explorerTargetOf(p)] };
+  }
+  if (process.platform === "darwin") {
+    if (act === "reveal") { return { cmd: "open", args: ["-R", p] }; }
+    return { cmd: "open", args: [p] };
+  }
+  if (act === "reveal") { return { cmd: "xdg-open", args: [dirname(p)] }; }
+  return { cmd: "xdg-open", args: [p] };
+}
+
+/* ========================================================================
+ * 复用官方 @deepseek-ai/dsh-native-command（会话释放后补位的「打开方式」）
+ *
+ * 会话释放后官方 /api/changes.open 只回 404，但「枚举系统关联 + 打开/定位」
+ * 本身是那个包里与 Session 无关的纯工具函数，就住在同一个 Host 进程里。
+ * 这里按 Electron 布局定位到 app.asar 里的那份，动态 import 后直接复用：
+ * 应用列表、默认打开、显示位置、用指定应用打开，全部与官方一致；取不到模块
+ * 才退回本文件自带的 explorer 实现（nativeOpenCommand）。
+ * ===================================================================== */
+const NATIVE_CMD_REL = join("node_modules", "@deepseek-ai", "dsh-native-command", "lib", "index.js");
+let nativeCmdPromise = null;
+
+function officialNativeCommand() {
+  if (nativeCmdPromise !== null) { return nativeCmdPromise; }
+  nativeCmdPromise = (async () => {
+    const exeDir = dirname(process.execPath);
+    const roots = [
+      join(exeDir, "resources", "app.asar", "dsh"),
+      join(exeDir, "resources", "app", "dsh"),
+    ];
+    for (const root of roots) {
+      const file = join(root, NATIVE_CMD_REL);
+      try {
+        if (!existsSync(file)) { continue; }
+        const mod = await import(pathToFileURL(file).href);
+        if (mod && typeof mod.nativeFileApplications === "function") { return mod; }
+      } catch { /* 试下一个布局 */ }
+    }
+    return null;
+  })().catch(() => null);
+  return nativeCmdPromise;
+}
+
+/** 官方应用条目 → 客户端 validator 能接受的形状（icon 只留 data:image，其余置 null）。 */
+function nativeAppEntry(app) {
+  if (!app || typeof app.id !== "string" || !app.id) { return null; }
+  const name = typeof app.name === "string" && app.name ? app.name : app.id;
+  const icon = typeof app.icon === "string" && /^data:image\//.test(app.icon) ? app.icon : null;
+  return { id: app.id, name: name, default: app.default === true, icon: icon };
+}
+
+/** spawn 一个 GUI 启动器：等到 spawn/error 落定再回，别让 ENOENT 静默吞掉。 */
+function spawnGui(cmd, args) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (r) => { if (!settled) { settled = true; resolve(r); } };
+    let child;
+    try {
+      /* windowsHide 必须为 false：GUI 启动器一旦带上 CREATE_NO_WINDOW/SW_HIDE，
+         由它拉起的窗口会继承「隐藏」，看起来就像点了没反应（DSH 自己也用 visible）。 */
+      child = spawn(cmd, args, { detached: true, windowsHide: false, stdio: "ignore" });
+    } catch (e) {
+      done({ ok: false, code: String((e && e.code) || (e && e.message) || e), detail: String((e && e.message) || e) });
+      return;
+    }
+    child.on("error", (e) => done({ ok: false, code: String((e && e.code) || (e && e.message) || e), detail: String((e && e.message) || e) }));
+    child.on("spawn", () => { try { child.unref(); } catch { } done({ ok: true, pid: child.pid }); });
+    const timer = setTimeout(() => done({ ok: false, code: "spawn-timeout" }), 4000);
+    if (timer && typeof timer.unref === "function") { timer.unref(); }
+  });
+}
+
+/**
+ * 「打开方式」的应用列表（给客户端合成 GET /api/changes.open 用）。
+ * 口径与官方完全一致：**只列系统关联里的真实应用**，不再发「系统默认应用」
+ * 「选择其他应用…」这类自造项 —— 官方控件的规则是「主按钮＝列表第一个应用、
+ * chevron 菜单列出全部、底部固定一条『显示文件位置』」，喂真实清单即可对齐。
+ * 枚举不出来就回空数组：控件会退化成「只有显示文件位置」的形态，绝不编造应用。
+ */
+export async function listOpenApplications(targetPath) {
+  const p = String(targetPath || "");
+  if (!p) { return { ok: true, source: "fallback", apps: [] }; }
+  const mod = await officialNativeCommand();
+  if (!mod) { return { ok: true, source: "fallback", code: "native-command-unavailable", apps: [] }; }
+  const ctl = new AbortController();
+  const timer = setTimeout(() => { try { ctl.abort(); } catch { } }, 15000);
+  try {
+    const list = await mod.nativeFileApplications(p, ctl.signal);
+    const apps = [], seen = new Set();
+    for (const raw of Array.isArray(list) ? list : []) {
+      const entry = nativeAppEntry(raw);
+      if (entry && !seen.has(entry.id)) { seen.add(entry.id); apps.push(entry); }
+    }
+    return { ok: true, source: "native", count: apps.length, apps: apps };
+  } catch (e) {
+    return { ok: true, source: "fallback", code: String((e && e.code) || (e && e.message) || e), apps: [] };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 打开 / 定位 / 用指定应用打开。优先用官方实现（与线上会话完全一致），
+ * 失败时把错误码带回去（客户端只看到失败，但日志与本机探测能看到真因）。
+ */
+export async function openNativeTarget(targetPath, action, application) {
+  const p = String(targetPath || "");
+  const act = action === "reveal" ? "reveal" : "open";
+  const app = String(application || "");
+  if (!p) { return { ok: false, code: "path required" }; }
+  const windowsAbs = /^[A-Za-z]:[\\/]/.test(p) || p.slice(0, 2) === "\\\\";
+  const posixAbs = p.charAt(0) === "/";
+  if (!windowsAbs && !posixAbs) { return { ok: false, code: "absolute-path required" }; }
+  if (!existsSync(p)) { return { ok: false, code: "path-not-found", path: p }; }
+  const mod = await officialNativeCommand();
+  if (mod) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => { try { ctl.abort(); } catch { } }, 20000);
+    try {
+      if (act === "reveal") {
+        await mod.revealNativePath(p, ctl.signal);
+      } else if (app) {
+        await mod.openNativeFileApplication(p, app, ctl.signal);
+      } else {
+        await mod.openNativePath(p, ctl.signal);
+      }
+      return { ok: true, source: "native", action: act, application: app || null, path: p };
+    } catch (e) {
+      return { ok: false, source: "native", code: String((e && e.code) || (e && e.message) || e), action: act, application: app || null, path: p };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  const command = nativeOpenCommand(p, act);
+  if (command === null) { return { ok: false, code: "absolute-path required" }; }
+  const r = await spawnGui(command.cmd, command.args);
+  if (!r.ok) { return { ok: false, source: "spawn", code: r.code, detail: r.detail, action: act, application: app || null, path: p }; }
+  return { ok: true, source: "spawn", action: act, application: app || null, path: p, pid: r.pid };
+}
+
+/** 只诊断、不弹窗：Host 进程能不能真正拉起子进程（cmd 输出 "probe" 即算通过）。 */
+export async function probeNativeLaunch() {
+  const out = { ok: false };
+  try {
+    out.nativeCommand = !!(await officialNativeCommand());
+    out.child = await new Promise((resolve) => {
+      let settled = false;
+      const done = (r) => { if (!settled) { settled = true; resolve(r); } };
+      let child;
+      try { child = spawn("cmd.exe", ["/c", "echo", "probe"], { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] }); }
+      catch (e) { done({ spawn: false, code: String((e && e.code) || (e && e.message) || e) }); return; }
+      let stdout = "";
+      if (child.stdout) { child.stdout.on("data", (c) => { stdout += String(c); }); }
+      child.on("error", (e) => done({ spawn: false, code: String((e && e.code) || (e && e.message) || e) }));
+      child.on("close", (code) => done({ spawn: true, exitCode: code, stdout: stdout.trim() }));
+      const timer = setTimeout(() => done({ spawn: false, code: "timeout" }), 5000);
+      if (timer && typeof timer.unref === "function") { timer.unref(); }
+    });
+    out.ok = out.child.spawn === true && out.child.stdout === "probe";
+    return out;
+  } catch (e) {
+    out.code = String((e && e.message) || e);
+    return out;
+  }
+}
+
 // 发布时长缓存：预检要查多个包，10 分钟内复用（发布时刻不会变，缓存只为省流量）
 const PUB_TIME_CACHE = new Map();
 const PUB_TIME_TTL_MS = 10 * 60 * 1000;
@@ -681,7 +927,7 @@ export function apply(ctx) {
   };
   const isLoopback = (req) => LOOPBACK_RE.test(String((req.socket && req.socket.remoteAddress) || ""));
 
-  // 小体积 JSON body 读取（只给下面两条强制更新路由用；上限 8KB，超了当非法）
+  // 小体积 JSON body 读取（只给下面几条强制更新路由用；上限 8KB，超了当非法）
   const readJsonBody = (req, cb) => {
     let buf = "";
     let bad = false;
@@ -693,6 +939,61 @@ export function apply(ctx) {
     req.on("error", () => cb({}));
   };
 
+  /* ---- 强制更新豁免的到期清理 ----------------------------------------------
+   * 「装完立刻删豁免」是错的：pnpm 每次安装都会拿**整个 lockfile** 去校验供应链策略，
+   * 被强制装上的版本还没满 24 小时时删掉豁免，接下来几小时里游 profile 的**所有** pnpm
+   * 操作都会被整体拒绝（ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION），比留着更糟。
+   * 正确时机是「该版本成熟之后」：客户端在强制更新时把到期时刻登记过来，这里落盘 +
+   * 到点删表项；宿重启后按文件记录重新排期（到期未处理的立刻删）。 */
+  const cleanupTimers = new Map();   // name@version → timer
+  const cleanupFile = () => {
+    const dir = findProfileDir();
+    return dir ? join(dir, "ui-tweaks", "exempt-pending.json") : null;
+  };
+  const readCleanupList = () => {
+    const f = cleanupFile();
+    if (!f) { return []; }
+    try {
+      const list = JSON.parse(readFileSync(f, "utf8"));
+      return Array.isArray(list) ? list.filter((it) => it && typeof it.name === "string" && typeof it.version === "string" && isFinite(it.dropAt)) : [];
+    } catch { return []; }
+  };
+  const writeCleanupList = (list) => {
+    const f = cleanupFile();
+    if (!f) { return; }
+    try {
+      mkdirSync(dirname(f), { recursive: true });
+      writeFileSync(f, JSON.stringify(list, null, 2) + "\n", "utf8");
+    } catch { /* 写不了就只在内存里生效 */ }
+  };
+  const runCleanup = (item) => {
+    const key = item.name + "@" + item.version;
+    const timer = cleanupTimers.get(key);
+    if (timer) { try { clearTimeout(timer); } catch { } cleanupTimers.delete(key); }
+    const r = dropExemptVersion(item.name, item.version);
+    const rest = readCleanupList().filter((it) => !(it.name === item.name && it.version === item.version));
+    if (!r.ok) {
+      // 删失败（文件被占用等）：10 分钟后再试，别把记录丢了
+      writeCleanupList(rest.concat([{ name: item.name, version: item.version, dropAt: Date.now() + 10 * 60 * 1000 }]));
+      return;
+    }
+    writeCleanupList(rest);
+  };
+  const armCleanup = (item) => {
+    const key = item.name + "@" + item.version;
+    const prev = cleanupTimers.get(key);
+    if (prev) { try { clearTimeout(prev); } catch { } cleanupTimers.delete(key); }
+    const delay = Math.max(0, Number(item.dropAt) - Date.now());
+    if (!isFinite(delay) || delay > 2147483000) { return; }
+    const timer = setTimeout(() => runCleanup(item), delay);
+    if (timer && typeof timer.unref === "function") { timer.unref(); }
+    cleanupTimers.set(key, timer);
+  };
+  const scheduleCleanup = (item) => {
+    writeCleanupList(readCleanupList().filter((it) => !(it.name === item.name && it.version === item.version)).concat([item]));
+    armCleanup(item);
+  };
+
   const routes = [
     {
       kind: "exact",
@@ -770,6 +1071,73 @@ export function apply(ctx) {
         });
       }
     },
+    {
+      /* 改动卡补位的「打开 / 显示位置 / 选择应用」：会话释放后官方 /api/changes.open
+         只回 404，这里交给 Host 桌面接手（官方 native-command 优先，见 openNativeTarget）。
+         action 还可以是 "probe"：只诊断子进程能不能跑，不弹任何窗口。 */
+      kind: "exact",
+      path: "/api/ui-tweaks/open-path",
+      handler: (req, res) => {
+        const done = respond(res);
+        if (!isLoopback(req)) { done(403, JSON.stringify({ ok: false, code: "forbidden" })); return; }
+        if (req.method !== "POST") { done(405, JSON.stringify({ ok: false, code: "method not allowed" })); return; }
+        readJsonBody(req, (body) => {
+          const target = body && typeof body.path === "string" ? body.path : "";
+          const action = body && (body.action === "reveal" || body.action === "probe") ? body.action : "open";
+          const application = body && typeof body.application === "string" ? body.application : "";
+          if (action === "probe") {
+            probeNativeLaunch().then(
+              (r) => done(200, JSON.stringify(r)),
+              (e) => done(500, JSON.stringify({ ok: false, code: String((e && e.message) || e) })));
+            return;
+          }
+          openNativeTarget(target, action, application).then((r) => {
+            if (r.ok) { done(200, JSON.stringify(r)); return; }
+            const status = r.code === "path-not-found" ? 404
+              : (r.code === "path required" || r.code === "absolute-path required") ? 400 : 500;
+            done(status, JSON.stringify(r));
+          }, (e) => done(500, JSON.stringify({ ok: false, code: String((e && e.message) || e) })));
+        });
+      }
+    },
+    {
+      /* 官方 /api/changes.open 的 GET（应用列表）补位：复用官方 native-command 枚举系统关联 */
+      kind: "exact",
+      path: "/api/ui-tweaks/open-apps",
+      handler: (req, res) => {
+        const done = respond(res);
+        if (!isLoopback(req)) { done(403, JSON.stringify({ ok: false, code: "forbidden" })); return; }
+        if (req.method !== "POST") { done(405, JSON.stringify({ ok: false, code: "method not allowed" })); return; }
+        readJsonBody(req, (body) => {
+          const target = body && typeof body.path === "string" ? body.path : "";
+          listOpenApplications(target).then(
+            (r) => done(200, JSON.stringify(r)),
+            (e) => done(500, JSON.stringify({ ok: false, code: String((e && e.message) || e) })));
+        });
+      }
+    },
+    {
+      /* 登记「强行装上的版本到期后清掉它的豁免」；客户端在强制更新成功后调用 */
+      kind: "exact",
+      path: "/api/ui-tweaks/schedule-exempt-cleanup",
+      handler: (req, res) => {
+        const done = respond(res);
+        if (!isLoopback(req)) { done(403, JSON.stringify({ ok: false, code: "forbidden" })); return; }
+        if (req.method !== "POST") { done(405, JSON.stringify({ ok: false, code: "method not allowed" })); return; }
+        readJsonBody(req, (body) => {
+          const name = body && typeof body.name === "string" ? body.name : "";
+          const version = body && typeof body.version === "string" ? body.version : "";
+          const dropAt = body && isFinite(body.dropAt) ? Number(body.dropAt) : 0;
+          if (!name || !version || !(dropAt > 0)) { done(400, JSON.stringify({ ok: false, code: "name/version/dropAt required" })); return; }
+          try {
+            scheduleCleanup({ name, version, dropAt });
+            done(200, JSON.stringify({ ok: true, name, version, dropAt, at: new Date(dropAt).toISOString() }));
+          } catch (e) {
+            done(500, JSON.stringify({ ok: false, code: String((e && e.message) || e) }));
+          }
+        });
+      }
+    },
     {
       /* 立即重启：GET 只读方案（无副作用），POST 才执行；无法重拉时如实回 manual */
       kind: "exact",
@@ -798,6 +1166,19 @@ export function apply(ctx) {
   // 加载时静默收敛一次（fire-and-forget：异常绝不影响插件加载）
   try { normalizeReleaseAgeExcludes(); } catch { /* 归并自身已吞异常，这里只兜底 */ }
 
+  /* 恢复上次没清完的豁免清理：已到期的立刻删，其余重新排期。
+     清单在 profile/ui-tweaks/exempt-pending.json（跨客户端重启有效）。 */
+  try {
+    for (const it of readCleanupList()) {
+      if (Number(it.dropAt) <= Date.now()) { runCleanup(it); }
+      else { armCleanup(it); }
+    }
+  } catch { /* 记录坏了就当没有 */ }
+  ctx.effect(() => () => {
+    for (const t of cleanupTimers.values()) { try { clearTimeout(t); } catch { } }
+    cleanupTimers.clear();
+  }, "ui-tweaks: exempt cleanup timers");
+
   // 桌面客户端：拉起窗口记忆 helper（非桌面环境内部自动不动作）
   startWindowState(ctx);
 }