feat: 公共 API 基座化（v0.12.0，纯增量）— 类型/能力/设置 seam 全面补齐

- 类型生态：service 模块 re-export SidebarTab/SidebarState/SidebarStore/
  SidebarSnapshot/SidebarDiffRef/TabType/SessionScope/SidebarPrefs 等公共
  状态词汇（此前 TS2459 无法命名）；context-types 去 Node 依赖（结构镜像
  SidebarHttpRequest/Response/UpgradeSocket/Head），client 可达声明图零
  node:* 引用，外部消费者无 @types/node + skipLibCheck:false 可编译
  （scripts/check-consumer-types.sh 守护）
- 服务能力：version/features 版本与能力探测（单调只增）、getSnapshot/
  subscribeState 状态订阅、updateTab（title/path/meta）、activateTab、
  openFile（路径派生 id 与内置拦截一致）、openTab(seed, scope?) 定向到
  指定 session（store.reduceFor 不扰动 UI）
- TabDescriptor：badge 角标（99+ 封顶，抛错吞掉）、onOpen/onActivate/
  onClose 生命周期回调（service 路径派发，dedupe 聚焦触发 onActivate
  而非 onOpen，抛错不打断流程）；SidebarTab.meta JSON 可序列化跨刷新
  持久化（sanitize 宽松保留）
- 设置 seam 开放：PrefsSchema 增 pluginSettings 开放嵌套 map（z.dict），
  settings.pluginToggles（插件自有行，同 switch/text/number 控件）与
  settings.render（自定义面板，含 store/service/prefs/updatePluginSetting/
  close props）；viewer 卡片 v0.12.0 起也有齿轮设置弹窗
- FileViewerDescriptor.load 增第三参 AbortSignal（EditorHost 生命周期中止）
- UI 接线：tab 激活/关闭改走 service（跨树激活修复 + 回调触发）、+ 菜单
  传 scope、TabBar badge pill 渲染；active-session scope 走原 reduce 路径
  保证 notify
- 测试 +23：生命周期/定向打开/updateTab/activateTab/openFile/meta 持久化/
  reduceFor/能力常量（与 package.json 锁步）、consumer-types.ts 编译门、
  api-surface.spec.ts（client 图零 node 依赖守护）；既有 430 测试全绿
- 文档：AGENTS.md 修 available 三参示例并补全部新 API；external-plugin-
  guide.md 刷新至 v0.12.0（7 tab + 9 viewer、设置 seam 开放、类型导入
  路径建议）；README×2 服务化小节同步

未发版 npm（用户决定）；分支 feat/plugin-api-v012。

src/client/state.ts

@@ -26,13 +26,17 @@ export type SidebarDiffRef =
   | { kind: 'commit'; hash: string; hashFull: string; subject: string }
 
 /** One open tab. `path` carries the file (editor) or is absent (explorer/git);
- *  `diff` carries the change a diff tab shows. */
+ *  `diff` carries the change a diff tab shows; `meta` (v0.12.0+) carries
+ *  plugin-owned JSON-serializable state, preserved across reloads. */
 export interface SidebarTab {
   id: string
   type: TabType
   title: string
   path?: string
   diff?: SidebarDiffRef
+  /** Plugin-owned state (v0.12.0+): MUST be JSON-serializable — it is
+   *  persisted with the layout and restored verbatim on reload. */
+  meta?: unknown
 }
 
 /** A tab group. */
@@ -432,14 +436,14 @@ export function activateTab(state: SidebarState, paneId: string, tabId: string):
   }
 }
 
-/** Update the display fields of one open tab (title / path) without
+/** Update the display fields of one open tab (title / path / meta) without
  *  re-opening it. The browser tab persists its current URL and hostname
  *  title through this reducer so a reload restores the visited page. A
  *  missing tab id is a no-op. The tab may live in either tree. */
 export function patchTab(
   state: SidebarState,
   tabId: string,
-  patch: { title?: string; path?: string },
+  patch: { title?: string; path?: string; meta?: unknown },
 ): SidebarState {
   let changed = false
   const walk = (node: SplitNode): SplitNode => {
@@ -451,6 +455,7 @@ export function patchTab(
           ...tab,
           ...(patch.title !== undefined ? { title: patch.title } : {}),
           ...(patch.path !== undefined ? { path: patch.path } : {}),
+          ...(patch.meta !== undefined ? { meta: patch.meta } : {}),
         }
       })
       return tabs === node.tabs ? node : { ...node, tabs }
@@ -886,11 +891,15 @@ function sanitizeNode(node: unknown, seen: Set<string>, reid: Map<string, string
       // accept any string type here — an unregistered type renders an
       // <OrphanedTab/> at view time and recovers if its plugin loads later.
       if (typeof candidate.type !== 'string') return undefined
+      // `meta` is plugin-owned JSON-serializable state (v0.12.0+): the
+      // persisted value already went through JSON.parse, so it is inherently
+      // serializable — carry it through verbatim (absent on older states).
       tabs.push({
         id: candidate.id,
         type: candidate.type,
         title: candidate.title,
         ...(typeof candidate.path === 'string' ? { path: candidate.path } : {}),
+        ...(candidate.meta !== undefined ? { meta: candidate.meta } : {}),
       })
     }
     const active = typeof record.active === 'string' ? record.active : null
@@ -1020,6 +1029,28 @@ export class SidebarStore {
     this.notify()
   }
 
+  /**
+   * Apply a pure reducer to a TARGET session's state (not the active one),
+   * loading it on demand and persisting the result — WITHOUT switching the
+   * active snapshot or notifying (the UI must not follow along). Used by the
+   * service's targeted `openTab(seed, scope)`: the open lands in the target
+   * session's layout and is visible whenever the user switches to it.
+   */
+  reduceFor(sessionId: string, reducer: (state: SidebarState) => SidebarState): void {
+    let state = this.bySession.get(sessionId)
+    if (state === undefined) {
+      state = loadState(sessionId, this.prefs)
+      this.bySession.set(sessionId, state)
+    } else {
+      // Re-seed the uid counter past THIS session's persisted ids, exactly
+      // like setSession's cache-hit path.
+      nextIdCounter = maxCounterId(state)
+    }
+    const next = reducer(state)
+    this.bySession.set(sessionId, next)
+    this.schedulePersist(sessionId, next)
+  }
+
   private schedulePersist(sessionId: string, state: SidebarState): void {
     window.clearTimeout(this.persistTimer)
     this.persistTimer = window.setTimeout(() => {