@wingsky-1/dsh-worktree-sidebar 0.2.5 → 0.2.6

package/README.en.md

@@ -7,6 +7,14 @@ Three tools that let the agent bind a **git worktree** to the current session, s
 This is a **transitional adapter**: if the official product ships native worktree sessions, this plugin retires.
 How it works (five host domains, host/client chains, self-healing rules, the six things to remember) is documented in [docs/architecture/dsh-worktree-sidebar.md](../../docs/architecture/dsh-worktree-sidebar.md).
 
+## Quick install
+
+```sh
+dsh plugin --profile web add @wingsky-1/dsh-worktree-sidebar
+```
+
+> After install / uninstall / update, **restart `dsh web` once** (bundle layers are only composed at startup) for changes to take effect.
+
 ## What it does
 
 The right sidebar's file tree is always rooted at `session.header.cwd`, and that field is immutable once the session is created (adopting a session with a different cwd throws `ApiSessionCwdConflict`). So when a session runs in the main checkout while the actual work happens in a worktree, the tree shows the wrong place.
@@ -140,7 +148,9 @@ Four **UI semantics** cannot be covered by any automated gate (there is no brows
 
 ## Compatibility (read-only coupling)
 
-The plugin does not modify official sources, but it **reads** these contracts (baseline `@deepseek-ai/dsh 0.1.5-rc.1`):
+The plugin does not modify official sources, but it **reads** these contracts from the sole
+supported target runtime, dsh `0.1.7-rc.2`. No compatibility promise is made for any other
+runtime version:
 
 - the host's `typert` `workspaceFileScope` lookup: the plugin registers its resolver via `lookups.configure` and delegates to the **official resolve captured before configuring** on a miss;
 - the client `sidebarRightTabs` type registry and the keyed seat `sidebar.right.pane.tab` (including the `StoredEntry` shape: `component/inject/store/locale`);

package/README.md

@@ -7,6 +7,14 @@
 这是一个**过渡适配层**：官方若推出原生 worktree 会话能力，本插件即退役。
 原理与运行机制（五域装配、宿主/客户端链路、自愈判据、命门清单）见 [架构图解](../../docs/architecture/dsh-worktree-sidebar.md)。
 
+## 一键安装
+
+```sh
+dsh plugin --profile web add @wingsky-1/dsh-worktree-sidebar
+```
+
+> 安装 / 卸载 / 更新后都需**重启一次** `dsh web`（bundle 层只在启动时组合）生效。
+
 ## 它做什么
 
 dsh 的右侧栏文件树根固定取 `session.header.cwd`，且该字段创建后不可变（显式收养不同 cwd 的会话会抛 `ApiSessionCwdConflict`）。于是在「会话开在主 checkout、实际改动在 worktree」这一常见工作方式下，树看的是主 checkout，看错了地方。
@@ -24,7 +32,7 @@ dsh 的右侧栏文件树根固定取 `session.header.cwd`，且该字段创建
 
 子 agent 的会话与**用户 fork 出来的会话**都继承父会话的登记：自己没有登记时，右侧栏的 Files 页签指向父链上**第一个持有登记**的那个会话所绑定的 worktree（父链到顶、那条登记被摘除即回退到自己的 cwd）。判据同在会话 header 的 `parentSession`，本插件刻意不区分这两种形态——fork 的 header 同样拷了父的 cwd，视图根跟着一起继承才与「文件根是会话 cwd 的改写」自洽。
 
-工具对 **git 仓库内的所有 agent（含子 agent）**暴露：每个 agent 注册时按其会话目录判断，不在 git 仓库里就不注册。执行期还有一次兜底校验，环境在两次之间变了也不会按错误前提动作。
+工具对 **git 仓库内的所有 agent（含子 agent）**暴露：每个 agent 注册时按其会话目录判断，不在 git 仓库里就不注册。插件装载前已存在的 agent 会在装载时补注册；后续 `agent/created` 事件会等待本插件返回的 Promise，确保工具注册完成后事件才继续。执行期还有一次兜底校验，环境在两次之间变了也不会按错误前提动作。
 
 三个工具同时带一个可见的返回文本，写明当前指向哪个 worktree、分支是什么 —— 让模型不必额外调一次工具就能确认状态。
 
@@ -144,7 +152,7 @@ pnpm gate:pr                 # 开 PR 前；新增包与 catalog 条目另需 pn
 
 ## 兼容性（只读耦合点）
 
-插件不改官方源码，但**读取**以下官方契约（基线 `@deepseek-ai/dsh 0.1.5-rc.1`）；官方改版时这些点是唯一的失效面：
+插件不改官方源码，但**读取**以下官方契约（基线 `@deepseek-ai/dsh 0.1.7-rc.2`）；官方改版时这些点是唯一的失效面：
 
 - 宿主 `typert` 的 `workspaceFileScope` 查表：本插件用 `lookups.configure` 注册自己的解析器，并在 miss 时委托**配置前捕获到的官方 resolve**；
 - 客户端 `sidebarRightTabs` 类型注册表与键控座位 `sidebar.right.pane.tab`（含 `StoredEntry` 的 `component/inject/store/locale` 形状）；

package/cordis.patch.yml

@@ -5,5 +5,5 @@
 # 浏览器端（exports "./client"）在官方封装就绪后接管 files 页签的目录根。
 # 配置走 schema 默认值（enabled），行内不带 config。
 - insert:
-    - id: ui-dsh-worktree-sidebar
+    - id: dsh-worktree-sidebar
       name: "@wingsky-1/dsh-worktree-sidebar"

package/lib/client/shared/ports.d.ts

@@ -36,17 +36,21 @@ export interface StoredEntryLike {
     readonly locale?: string | undefined;
 }
 /**
- * tab 类型定义，逐字对齐官方 SidebarRightTabDefinition。
+ * tab 类型定义，语义对齐官方 SidebarRightTabDefinition（只读，不改写类型表）。
  *
- * 这里**必须**把所有字段都列全（尤其 `guide`）：类型表用的是官方定义的那一份（本插件只遮蔽
+ * 这里**必须**把在册定义的判据字段列全（尤其 `guide`）：类型表用的是官方定义的那一份（本插件只遮蔽
  * 正文，从不改写类型表），官方注册表 refresh 后会用**在册定义**重算 guide 条目。丢掉 `guide` 的后果不是少一块文案，
  * 而是 guide 归零、所有会话（含从未登记的）默认页签从 Files 变成空的 Guide、文件树打不开。
+ * `multiple`/`keepMounted` 仅作读面声明（本包不写类型表）：可选即双基线可编译；
+ * 隐藏页签无 abort 时仍在册，binding 刷新仍需 reseed（见 inject keepMounted 用例）。
  */
 export interface TabDefinitionLike {
     readonly id: string;
     readonly kind: string;
     readonly patterns?: readonly string[];
-    readonly priority?: string;
+    readonly priority?: "extension" | "builtin" | "fallback";
+    readonly multiple?: boolean;
+    readonly keepMounted?: boolean;
     readonly canOpen?: (address: string) => boolean;
     readonly title: (address: string) => string;
     readonly guide?: readonly unknown[];

package/lib/client/takeover.d.ts

@@ -4,12 +4,13 @@
  * 接管只做一件事：以**官方 id** 为 key、**更低的 priority** 再登记一条正文，组件 / store /
  * locale 全部复用官方那条（inject 面由 `inject.ts` 包一层）。官方 ui-slots 的每个 cell 取
  * 「优先级最低的那条存活项」——它的注册表原话是 register at a different priority to shadow it
- * (lowest renders)（`@deepseek-ai/dsh-client-ui-slots` 的 `lib/index.js:77`；排序 `:130`；取当值项 `:187-200`）。
+ * (lowest renders)（`@deepseek-ai/dsh-client-ui-slots` 的遮蔽语义：同 key 不同 priority 方可并存、
+ * 按 priority 升序、当值取每 cell 首条存活项）。
  *
  * **那个包不在 dsh 安装树里**：它在构建期被内联进 `dsh-web-frontend/dist/assets/index-*.js`，
  * 所以要照注释去读原文时，可读副本在同仓 catalog 锁版处
- * （`node_modules/.pnpm/@deepseek-ai+dsh-client-ui-slots@0.1.5-rc.1_...` 下的
- * `node_modules/@deepseek-ai/dsh-client-ui-slots/lib/index.js`）。
+ * （`node_modules/.pnpm/@deepseek-ai+dsh-client-ui-slots@<catalog 锁版>_...` 下的
+ * `node_modules/@deepseek-ai/dsh-client-ui-slots/lib/index.js`，版本号见 `pnpm-workspace.yaml`，不硬编码）。
  * 树内可读的两处是类型面与运行时入口：`dsh-client-ui-renderer/lib/types/client/registry.d.ts:46/84/154/164`
  * （`class SlotRegistry`、`register`、`entries`、`entriesOfSlot`）与同一包 `lib/client.js:953/1191-1198/1388`。
  *

package/lib/client.js

@@ -42,7 +42,7 @@
   // src/client/inject.ts
   var liveSeedings = /* @__PURE__ */ new Set();
   function releaseAllSeedings() {
-    for (const release of [...liveSeedings]) release();
+    for (const release of [...liveSeedings].reverse()) release();
   }
   function createInjectWrapper(viewFor) {
     return (official) => {
@@ -73,48 +73,54 @@
     const reseed = () => {
       const next = view.root.getSnapshot();
       for (const [tabId, tab] of [...watched]) {
-        if (tab.signal?.aborted === true) continue;
+        if (tab.abort?.signal.aborted === true) continue;
         const root = next ?? tab.fallback;
         if (root === tab.seeded) continue;
         tab.seeded = root;
-        officialStart(tabId, root, tab.signal);
+        officialStart(tabId, root, tab.abort?.signal);
       }
     };
+    const detachAbort = (tab) => {
+      if (tab?.abort === void 0) return;
+      tab.abort.signal.removeEventListener("abort", tab.abort.listener);
+    };
     const release = () => {
-      watched.clear();
-      liveSeedings.delete(release);
-      unsubscribe?.();
-      unsubscribe = void 0;
+      for (const [, tab] of [...watched].reverse()) detachAbort(tab);
       detachVisible?.();
       detachVisible = void 0;
-    };
-    const watchAbort = (tabId, signal) => {
-      signal?.addEventListener(
-        "abort",
-        () => {
-          watched.delete(tabId);
-          if (watched.size === 0) release();
-        },
-        { once: true }
-      );
+      unsubscribe?.();
+      unsubscribe = void 0;
+      watched.clear();
+      liveSeedings.delete(release);
     };
     const attach = (tabId, fallback, seeded, signal) => {
       liveSeedings.add(release);
-      watched.set(tabId, { seeded, fallback, signal });
+      detachAbort(watched.get(tabId));
+      const onAbort = () => {
+        const current = watched.get(tabId);
+        if (current === void 0 || current.abort !== abort) return;
+        detachAbort(current);
+        watched.delete(tabId);
+        if (watched.size === 0) release();
+      };
+      const abort = signal === void 0 ? void 0 : { signal, listener: onAbort };
+      const tab = { seeded, fallback, abort };
+      watched.set(tabId, tab);
       unsubscribe ?? (unsubscribe = view.root.subscribe(reseed));
       detachVisible ?? (detachVisible = refreshWhenVisible(refresh));
-      watchAbort(tabId, signal);
+      if (abort !== void 0) abort.signal.addEventListener("abort", abort.listener, { once: true });
+      return tab;
     };
     const start = (tabId, root, signal) => {
-      attach(tabId, root, root, signal);
+      if (signal?.aborted === true) return;
+      const tab = attach(tabId, root, root, signal);
       officialStart(tabId, root, signal);
       void view.root.refresh().then(() => {
-        if (signal?.aborted === true) return;
+        if (watched.get(tabId) !== tab || tab.abort?.signal.aborted === true) return;
         const seeded = view.root.getSnapshot() ?? root;
-        const tab = watched.get(tabId);
-        if (tab === void 0 || tab.seeded === seeded) return;
+        if (tab.seeded === seeded) return;
         tab.seeded = seeded;
-        officialStart(tabId, seeded, tab.signal);
+        officialStart(tabId, seeded, tab.abort?.signal);
       });
     };
     const load = (tabId, path, signal) => {

package/lib/index.js

@@ -19,8 +19,9 @@ function bindAgents(host) {
     cwd: agent.session.header.cwd
   });
   return {
-    subscribe: (handler) => host.on("agent/created", ({ agent }) => {
-      handler(faceOf(agent));
+    subscribe: (handler) => host.on("agent/created", async ({ agent }) => {
+      await handler(faceOf(agent));
+      return void 0;
     }),
     list: () => host.all().map(faceOf),
     publish: (face, definitions) => {
@@ -364,9 +365,13 @@ function dropBinding(table, sessionId) {
 }
 
 // lib/server/shared/file-io.js
+import { randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
+function temporaryNameFor(file) {
+  return `${file}.tmp-${process.pid}.${Date.now().toString(36)}.${randomBytes(6).toString("hex")}.tmp`;
+}
 function readTextFileSync(file) {
   try {
     return { ok: true, text: readFileSync(file, "utf8") };
@@ -375,7 +380,7 @@ function readTextFileSync(file) {
   }
 }
 async function writeTextAtomic(file, text) {
-  const temporary = `${file}.tmp-${process.pid}`;
+  const temporary = temporaryNameFor(file);
   try {
     await mkdir(dirname(file), { recursive: true });
     await writeFile(temporary, text, "utf8");
@@ -386,9 +391,6 @@ async function writeTextAtomic(file, text) {
   }
 }
 
-// lib/server/shared/paths.js
-import { join as join2 } from "node:path";
-
 // ../../shared/dsh-home.js
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -401,11 +403,17 @@ function dshHome() {
   return env !== void 0 && env.trim().length > 0 ? env : join(userHome(), ".dsh");
 }
 
+// ../../shared/paths.js
+import { join as join2 } from "node:path";
+function pluginHome(base, ...segments) {
+  return join2(base, ...segments);
+}
+
 // lib/server/shared/paths.js
 var PACKAGE_DIR = "@wingsky-1/dsh-worktree-sidebar";
 var BINDINGS_FILE_NAME = "bindings.json";
 function bindingsFile() {
-  return join2(dshHome(), PACKAGE_DIR, BINDINGS_FILE_NAME);
+  return pluginHome(dshHome(), PACKAGE_DIR, BINDINGS_FILE_NAME);
 }
 
 // lib/server/binding/impl/store/index.js
@@ -1474,7 +1482,7 @@ var ToolsService = class {
     const consider = (agent) => this.consider(generation, agent);
     this.unsubscribe = deps.agents.subscribe(consider);
     for (const agent of deps.agents.list())
-      consider(agent);
+      void consider(agent);
   }
   /**
    * 卸载：退订、逐个摘掉每个 agent 的工具、丢掉映射与在飞的异步链，复位装配标记。重复调用无害。
@@ -1503,7 +1511,7 @@ var ToolsService = class {
   }
   /** 判定一个 agent 是否该装工具，该装就装。同一个 agent 只处理一次。 */
   consider(generation, agent) {
-    this.chain = this.chain.then(async () => {
+    const chain = this.chain.then(async () => {
       const deps = this.deps;
       if (deps === void 0)
         return;
@@ -1526,6 +1534,8 @@ var ToolsService = class {
       const reason = cause instanceof Error ? cause.message : String(cause);
       deps.logger.warn("dsh-worktree-sidebar: 工具注册失败 — " + reason);
     });
+    this.chain = chain;
+    return chain;
   }
 };
 var toolsService = new ToolsService();
@@ -1546,7 +1556,11 @@ async function apply(ctx, config = {}) {
     logger: ctx.logger,
     register: (route) => ctx.webServer.register(route),
     agents: bindAgents({
-      on: (event, handler) => ctx.on(event, handler),
+      // 0.1.7-rc.2 serial 会等待 listener：完整等待 tools 域的注册链，再让 agent 创建继续。
+      on: (event, handler) => ctx.on(event, async (payload) => {
+        await handler({ agent: payload.agent });
+        return void 0;
+      }),
       all: () => ctx.agents.list()
     }),
     typert: bindTypert(ctx.typert.lookups),

package/lib/server/host/agents.d.ts

@@ -28,10 +28,15 @@ export interface HostAgentLike {
 }
 /** 宿主事件面与 agent 枚举面：只开本适配器要的两样。 */
 export interface AgentHostPort {
-    /** 订阅 agent 发布。返回退订函数。 */
+    /**
+     * 订阅 agent 发布。返回退订函数。
+     *
+     * 0.1.7-rc.2 用 serial 派发并等待 listener；因此适配器把 tools 域的 thenable 留在返回链上，
+     * 不能在取出 `agent` 后把它截成 `undefined`。
+     */
     on(event: "agent/created", handler: (payload: {
         agent: HostAgentLike;
-    }) => void): () => void;
+    }) => undefined | PromiseLike<undefined>): () => void;
     /** 当前**所有存活** agent 快照（含子 agent）。 */
     all(): readonly HostAgentLike[];
 }

package/lib/server/tools/deps.d.ts

@@ -33,8 +33,8 @@ export interface AgentFace {
  * 谁订事件、从哪枚举、怎么把工具装进某个 agent 的作用域，都是组合根的知识。
  */
 export interface AgentPort {
-    /** 订阅「新 agent 发布」。返回退订函数。 */
-    subscribe(handler: (agent: AgentFace) => void): () => void;
+    /** 订阅「新 agent 发布」。返回退订函数；listener 的 thenable 属于宿主 serial 等待链。 */
+    subscribe(handler: (agent: AgentFace) => void | PromiseLike<void>): () => void;
     /** 当前存活的所有 agent 快照（含子 agent；插件加载前就存在的那些都在里面）。 */
     list(): readonly AgentFace[];
     /** 把工具装进该 agent 的作用域，返回释放函数。 */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wingsky-1/dsh-worktree-sidebar",
-  "version": "0.2.5",
-  "description": "把某个 git worktree 登记给当前会话，使该会话的官方右侧栏文件树根指向该 worktree；会话 cwd 不变。官方提供原生 worktree 会话能力即退役的过渡适配层。",
+  "version": "0.2.6",
+  "description": "Point the current session's right-sidebar file tree at a git worktree without changing the session cwd. 把某个 git worktree 登记给当前会话，使该会话的官方右侧栏文件树根指向该 worktree；会话 cwd 不变。官方提供原生 worktree 会话能力即退役的过渡适配层。",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -20,6 +20,16 @@
       "patch": "./cordis.patch.yml",
       "bannerJs": "import { createRequire as __worktreeSidebarRequire } from \"node:module\";\nconst require = __worktreeSidebarRequire(import.meta.url);"
     },
+    "catalog": {
+      "category": "ui",
+      "summary": {
+        "en": "Point the current session's right-sidebar file tree at a git worktree without changing the session cwd.",
+        "zh": "将会话右侧栏文件树根指向 git worktree，会话 cwd 不变，原生能力上线即退役"
+      },
+      "capabilities": [
+        "ui-sidebar-right"
+      ]
+    },
     "client": {
       "inject": [
         "@deepseek-ai/dsh-client-ui-sidebar-right"
@@ -35,21 +45,21 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-agent": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-api-workspace-files": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-session": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.5-rc.1"
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-workspace-files": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-agent": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-api-workspace-files": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.5-rc.1"
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-workspace-files": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -86,6 +96,7 @@
   "keywords": [
     "dsh",
     "deepseek-harness",
+    "dsh-plugin",
     "plugin",
     "worktree",
     "git",
@@ -97,7 +108,7 @@
   },
   "scripts": {
     "build": "node ../../scripts/build/clean-lib.ts && tsc -p tsconfig.json && node ../../scripts/build/bundle-host.ts .",
-    "test": "node ../../scripts/test/run-vitest.mjs --min 19",
+    "test": "node ../../scripts/test/run-vitest.mjs --min 21",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/shared/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 插件主目录拼装（单一事实源，实现见 `./paths.js`）：等同
+ * `join(base, ...segments)`，默认形态路径逐字节不变。
+ *
+ * 只收敛「包主目录」直拼；以下 7 类排除：legacy/旧根（旧版迁移读面）、
+ * settings 文档（宿主文档读面）、resolve 对比（比较/候选命中顺序是语义）、
+ * 用户输入解析（`~`/相对路径展开）、credentials-userHome（DSH_HOME 域外凭据）、
+ * 展示脱敏（字符串替换不落盘）、包内反推（随包分发不在 DSH home 下）。
+ * provider-registry 的旧 `pluginHome` 保留为包内 facade（公开签名不变）。
+ * 完整理由见 `./paths.js` 函数 JSDoc。
+ */
+export declare function pluginHome(base: string, ...segments: string[]): string;

package/shared/settings-namespace.d.ts

@@ -1,10 +1,10 @@
 /**
  * 宿主端「设置命名空间」注册（单一事实源）。
  *
- * 背景与语义见 settings-namespace.js 顶部注释。要点：DSH rc.7 起设置卡槽
- * `settings.plugin.item` 为 keyed，只有在「宿主 serve 的命名空间 ∩ 卡片 key」
- * 非空时渲染；为让卡片显示，宿主端需用此函数把命名空间注册进 settings 服务。
- * 零包依赖，服务面注入，等值复刻官方 `installSettingsSection`（dsh-settings）。
+ * 背景与语义见 settings-namespace.js 顶部注释。要点：宿主 settings 服务按 `ns`
+ * 定位描述项并合成 `base + user`（无层字段时兼容取 `value`）；写经
+ * update/replace/mutate；热更新经 document-updated 订阅（内部直连，不对外暴露 watch 面）。
+ * 本文件只收窄能力面（全 unknown 结构面，无官方包导入）。
  */
 
 /** `installSettingsNamespace` 的 hooks 面。 */
@@ -13,15 +13,51 @@ export interface SettingsNamespaceHooks {
   setSource(source: () => unknown): void;
   /** 来源切换或命名空间值变化时触发，插件据此刷新/落盘。 */
   onChange(): void;
-  /** 可选自定义校验，透传给 settings.register。 */
-  validate?: unknown;
   /**
-   * 可选；register 返回 owner scope 后立即回调（先于 setSource）。
-   * 供存量配置迁移 / 写路径装配使用；settings 服务缺失时不触发。
+   * 可选；owning fiber ACTIVE 且 canonical namespace 被 settings 服务描述后回调一次。
+   * 供存量配置迁移 / 写路径装配使用；fiber / 服务 / namespace 未就绪时不触发。
    */
   onScope?(scope: unknown, service: unknown): void;
 }
 
+/** 描述项窄面（按 ns 定位，合成 base + user，兼容 value 回退）。 */
+export interface SettingsFormsDescriptor {
+  /** 命名空间键。 */
+  ns?: unknown;
+  /** 运行时解析值（缺少分层字段时的兼容回退）。 */
+  value?: unknown;
+  /** 基础配置层。 */
+  base?: unknown;
+  /** 原始 user 覆盖层。 */
+  user?: unknown;
+  /** 乐观并发修订号。 */
+  revision?: unknown;
+}
+
+/** owner scope 窄面（describe 定位读＋写委托；订阅由接缝内部直连）。 */
+export interface SettingsFormsScope {
+  /** 当前有效值（describe base + user，缺席回落 entry）。 */
+  get(): unknown;
+  /** 委托 settings.update(ns, …)。 */
+  update(patch: object, expectedRevision?: number): Promise<unknown>;
+  /** 委托 settings.replace(ns, …)。 */
+  replace(section: object, expectedRevision?: number): Promise<unknown>;
+  /** 委托 settings.mutate(ns, …)；服务缺失时返回拒绝。 */
+  mutate(ops: readonly unknown[], expectedRevision?: number): Promise<unknown>;
+}
+
+/** settings 服务窄面（describe/写）。 */
+export interface SettingsFormsService {
+  /** 按 entry id 定位描述项。 */
+  describe(options?: { redactSecrets?: boolean }): SettingsFormsDescriptor[];
+  /** 合并写。 */
+  update?(ns: string, patch: object, expectedRevision?: number): Promise<unknown>;
+  /** 整节写。 */
+  replace?(ns: string, section: object, expectedRevision?: number): Promise<unknown>;
+  /** 路径写（可选）。 */
+  mutate?(ns: string, ops: readonly unknown[], expectedRevision?: number): Promise<unknown>;
+}
+
 /**
  * 日志兜底：logger 可能确实没有（极端降级），全部可选调用。
  * 单一事实源（#436）：notifier / lan-proxy 曾各复刻一份，现统一引用本导出。
@@ -30,11 +66,11 @@ export declare function warnLog(ctx: unknown, message: string): void;
 
 /**
  * 注册插件自有 settings 命名空间（服务面注入，无包依赖）。
- * 等值语义参考官方 `installSettingsSection`（@deepseek-ai/dsh-settings@0.1.0-rc.7）。
+ * 对外签名保持不变（调用方零改）。
  * @param ctx - 插件宿主端 apply 收到的 cordis 上下文。
  * @param ns - 插件自有命名空间（小写 kebab，须唯一）。
- * @param schema - schemastery schema，解析该命名空间的值（通常为插件 Config）。
- * @param entry - 组合层配置，作为命名空间的 `base` 层。
+ * @param schema - 占位：schema 由宿主持有，本函数不注册。
+ * @param entry - 组合层配置（describe 缺席时的回落值）。
  * @param hooks - source 收藏与变更通知。
  */
 export declare function installSettingsNamespace(

package/shared/upgrade-tick.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 空步：立即完成，不碰任何存储。调用方把版本号写在自己的步骤表里，run 统一指到本函数。
+ *
+ * @returns {Promise<void>} 恒为完成态的 Promise。
+ */
+export function tickUpgradeVersion(): Promise<void>;
+
+/**
+ * 空步（同步链用）：什么都不做，立即返回。
+ */
+export function tickUpgradeVersionSync(): void;