dsh-sidecard-ask 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 1.6.0
+
+**主题：最新版 DSH（0.2.1-alpha.2）适配 + 新旧包名共载时的单例护栏。**
+
+十版本真机矩阵（隔离 DSH_HOME、真实安装启动、HTTP/探针双证据）发现并修复：
+
+- **0.2.1-alpha.2 侧边作答引擎失效（真问题）**：该版本把 `subagents.start(provider, request)`
+  重构为受管激活 API `subagents.startActivation({provider, label, request, signal, delivery})`
+  （返回值由 `{id, localAgent, result, dispose}` 变为 `{childId, result, dispose}`）。
+  旧代码的能力门只认 `start()`，导致 provider 明明注册成功（spawn/fork）却自检显示
+  「侧边作答引擎：不可用」，侧答走降级。现按运行时方法面自动选择两代 API：新 API 用
+  `delivery: 'caller'` 保持"答案不进主对话"的旧语义，流式帧改由子会话 id 归因（新运行时不再
+  提供 live Agent 句柄）。0.1.5-rc.3～0.2.1-alpha.1 的调用路径保持不变。
+- **新旧包名同时启用时双重触发（真问题）**：`dsh-selection-followup`（≤1.0.1 旧名）与
+  `dsh-sidecard-ask` 被同时装入一个 profile 时，选区旁叠出两个悬浮按钮，一次 Alt+Q 弹两个
+  提问框。现新增**页面内家族注册表**（`window.__dshSidecardFamily`）：协作的副本按版本号选举
+  唯一领导者（同版本先加载者胜），落选副本保留设置页（显示停用说明横幅）但不挂载任何交互面、
+  不响应快捷键；无法协作的 1.0.x 旧版通过结构特征识别（无 owner 标记的 `dsa-layer`），
+  领导者注入一条样式规则隐藏其整个交互层，并提示卸载旧包。
+- **data-slot 锚点自检结果不稳定（真问题）**：旧逻辑用"当前选区是否落在锚点链内"反推
+  "本版本是否支持锚点"，选区落在直接挂 body 的节点（引导弹窗、第三方裸 DOM 面板）时会把
+  全局判定翻成"缺失"，导致同一次自检两次结果不一致。改为构建级探测（全文档是否存在
+  `[data-slot]`），单个无锚点选区不再影响全局判定。
+
+客户端自检上报新增 `family` 字段（leader/legacy/peers），宿主侧白名单做同样的长度裁剪。
+
+本机实测：verify 53 / contract 323 / float-placement 38 / smoke 163 = **577 项全部通过**；
+另在 0.2.0-rc.2 与 0.2.1-alpha.2 真机（headless）复核：两版引擎均可用、共载单实例、
+锚点判定稳定、better-sidebar 0.25.0 承载面识别正常。
+
+## 1.5.1
+
+**主题：1.5.0 的发布收尾——把发布闸门补全，并把校验记录进版本号。**
+
+功能与 1.5.0 **完全一致，没有任何行为改动**（`client.js` 与 `index.js` 只有版本号字符串不同，
+可用 sha256 逐字节核对）。这个补丁版存在的理由是发布流程本身：
+
+- `README` 第十三节的发布闸门原先只列了 `verify` / `contract-test` / `smoke-test` 三个脚本，
+  **漏掉了 1.5.0 新增的 `float-placement`**——照那一节执行会漏跑浮层几何用例（1.5.0 发布时就漏跑了，
+  事后才补上，38 项通过）。现已把 `node test/float-placement.mjs` 加进闸门，并把 `git tag v1.5.0`
+  改成 `git tag v<package.json 的 version>`，避免照抄上一版的标签号。**1.5.0 的 npm 包内 README 是补全前的版本，这一版起才是补全后的。**
+- 版本号三处同步到 1.5.1：`package.json` 的 `version`、`index.js` 的 `PLUGIN_VERSION`、`client.js` 的 `CLIENT_VERSION`
+  （`test/verify.mjs` 会同时断言这三处一致）。这样 npm 上的 `latest` 带上了完整的闸门说明，
+  下一次发布不会再照着缺一行的清单执行。
+- 1.5.0 的发布过程有个值得记的坑：`npm publish` 返回的是 **HTTP 202 "being processed"**，
+  之后约 2 分钟 registry 文档仍显示 `latest: 1.4.0`、`...-1.5.0.tgz` 还是 404。
+  这**不是失败**，不要立即重发（重发会撞版本已存在）；等 2–5 分钟再查 `npm view dsh-sidecard-ask dist-tags` 即可。
+
+本机实测（四项均 exit 0）：verify 53 / contract 296 / float-placement 38 / smoke 138 = **525 项全部通过**。
+
 ## 1.5.0
 
 **主题：浮层不再压住主对话——「A 胶囊 + C 右栏」定案，一个算宽度的纯函数 + 一个默认收起的形态。**

package/README.md

@@ -392,11 +392,27 @@ node tools/compat-probe.mjs --json tools/.cache/matrix.json
 | 没有 `data-slot` 锚点 | 检测到选区但槽位路径为空 → 判定"区域锚点不可用"，**停用区域过滤**（否则 `captureZones:chat` 会静默失效）并在设置页自检里标明 | `contract-test`：`shouldOffer(..., {anchors:false})` 断言放宽且返回 `zoneFiltering:'unavailable'` |
 | 路由 kind 不被接受 | `prefix` 注册失败 → 退化为**逐方法精确路由**（`state/ask/cancel/config/reset`），处理器不变 | 前缀路由由 smoke 全流程覆盖；退化分支为纯 fallback（未在真机触发过） |
 
-### 7.3 还没做真机验证的部分（如实标注）
+### 7.3 真机验证记录（1.6.0，2026-10-11）
+
+1.6.0 把 §7.1/§7.2 的产物层证据升级为**真机证据**：最近 10 个发布版（0.1.5-rc.3 → 0.2.1-alpha.2，
+按 npm 发布时间）全部在隔离 `DSH_HOME` 中真实安装、启动并读取运行时能力面；
+0.2.0-rc.2（= npm `latest`）与 0.2.1-alpha.2（= npm `next`）另做无头浏览器真机验证。
+
+- 0.1.5-rc.3 … 0.2.1-alpha.1：引擎可用，provider=spawn/fork，0 启动告警。
+- **0.2.1-alpha.2：1.5.1 真机不可用 → 1.6.0 已修复**。该版本把子代理 API 从 `subagents.start(provider, request)`
+  重构为 `subagents.startActivation({provider, label, request, signal, delivery})`，1.5.1 的能力门只认旧方法
+  （provider 其实注册成功，自检却显示"不可用"）。1.6.0 按运行时方法面自动选择两代 API，新 API 用
+  `delivery:'caller'` 保持"答案不进主对话"，流式帧按子会话 id 归因。
+- 更早的 0.1.2-rc.1 … 0.1.4 仍只有产物层证据（§7.1/§7.2 的降级分支仍保留，双 API 调度不改动旧路径）。
+- 生态侧：25 个侧边卡片/侧边栏类插件做了产物扫描 + 4 组共载真机，localStorage 键 / 路由前缀 / tab kind /
+  patch id / 配置目录 / Alt+Q 零硬冲突；旧名包 `dsh-selection-followup@1.0.1` 共载时的双重触发由
+  1.6.0 的页面内家族单例选举解决。完整矩阵、复现脚本与截图见 `.compat-report/`。
+
+### 7.4 更早版本仍未做真机验证的部分（如实标注）
 
 - 上表所有 ✅/❌ 都是**包内容层面的证据**（字符串/签名存在于该版本的发布产物），不等于"插件在该版本上跑起来过"。
-  唯一跑过真机的是 **0.1.7-rc.2**（见 §10.1 的实测记录）。
-- 在 0.1.2-rc.1 … 0.1.6-alpha.2 这几个版本上，我只验证了"所需 API 是否存在 + 插件有为缺失准备的分支"，
+  真机覆盖为 0.1.5-rc.3 → 0.2.1-alpha.2（1.6.0 实测）与 0.1.7-rc.2（§10.1 的历史实测）。
+- 在 0.1.2-rc.1 … 0.1.4 这几个版本上，只验证了"所需 API 是否存在 + 插件有为缺失准备的分支"，
   **没有**在那些版本上安装并启动过插件。
 - `inputActions` 作为会话槽位标准 prop：13 个版本的 `dsh-client-ui-conversation` 产物里都有该名字，
   0.1.7-rc.2 的槽位目录也把它列为 `conversation.input.right` 的 standardProps；**更早版本是否真的把它下发给该槽位条目未验证**，
@@ -494,8 +510,8 @@ node test/smoke-test.mjs        # 端到端：流式/截断/取消/持久化/失
 ```
 
 四个脚本都以 `process.exitCode` 反映结果，失败会列出具体条目；测试会把 `DSH_HOME` 指向临时目录，不会污染真实配置。
-当前规模（1.5.0 本机实测，四项均 exit 0）：verify **53** 项 + contract **296** 项 + float-placement **38** 项 +
-smoke **138** 项 = **525 项全部通过**。
+当前规模（1.6.0 本机实测，四项均 exit 0）：verify **53** 项 + contract **323** 项 + float-placement **38** 项 +
+smoke **163** 项 = **577 项全部通过**。
 
 > 1.5.0 之前这里还放过 `tools/balance-check.mjs` 与 `tools/i18n-check.mjs` 两个「替代检查」。
 > 它们已被**删除**：前者用「正则字面量 vs 除号」的启发式判断，把 8 个源文件全部误报为残损；
@@ -635,7 +651,9 @@ npm deprecate "<旧包名>@*" "Renamed to <新包名> - <原因>"       # 旧名
 1. **区域归类是启发式的**：`data-slot` 名称来自 harness 自己；其它插件若在自己的面板里不再经由槽位渲染，
    该区域会被归为"其它区域"——用 `captureZones: auto` + `showInUnclassified: true`（默认）仍然可用，或改用 `captureZones` 限制。
    本机实测能识别：`conversation.*`（聊天）、`rightbar` / `sidebar.right.*` / 名字含 task·todo·schedule·team·job·plan 的面板（任务）。
-2. **浏览器内的视觉与交互未在本机验证**：本工作区没有浏览器自动化工具，因此"按钮出现在选区旁""卡片逐字增长""浮层不挡操作"这些**只能由你按第九节点一遍**。
+2. **浏览器内的视觉与交互**：1.6.0 起用无头 Edge（Playwright，系统浏览器 `channel:'msedge'`）做真机验证，
+   脚本见 `.compat-report/scripts/`，截图见 `.compat-report/shots/`——选区浮按钮、Alt+Q 弹层、共载单实例、
+   引擎自检均已在 0.2.0-rc.2 与 0.2.1-alpha.2 上自动核对。桌面 Electron 的视觉观感仍只有 2026-09-30 的人工实测（§5.3）。
    已做的保障是：只使用 `--dsw-alias-*` 主题令牌、只在槽位内渲染（`shell.overlay` / `settings.section` / `conversation.input.right`）、不写 `document.body`、不 import harness 客户端包。
 2b. **1.5.0 的浮层改动：四个测试脚本已在本机实跑通过（各 exit 0），但页面里的观感仍未验证**：
    写这个版本的前半段，本工作区的 shell 工具整体不可用（任何命令都返回

package/client.js

@@ -47,7 +47,7 @@ window.__ModuleLoader__.load({
      * the Host and the module's `api.version` both read it, so a report can
      * never claim a generation the browser is not actually running.
      */
-    const CLIENT_VERSION = '1.5.0'
+    const CLIENT_VERSION = '1.6.0'
 
     /**
      * Tab kind served by the DSH native right rail (also its implementation id).
@@ -294,6 +294,10 @@ window.__ModuleLoader__.load({
         none: '无',
         unsupportedTrigger: '无法识别该快捷键，请用形如 Alt+Q / Ctrl+Shift+K 的写法',
         surfaceUnavailable: '所选侧边承载面不可用',
+        familySuppressed: '检测到同系列更新版本（{version}）已在本页运行，本实例已自动停用划词触发与快捷键，界面由更新版本接管。建议在插件页卸载本旧版本。',
+        familyLegacyToast: '检测到旧版 dsh-selection-followup 同时启用，已由本版本接管；建议卸载旧包',
+        familyLegacyDiag: '旧版共载',
+        familyPeers: '同页实例',
       },
       en: {
         triggerLabel: 'Ask about selection',
@@ -430,6 +434,10 @@ window.__ModuleLoader__.load({
         none: 'none',
         unsupportedTrigger: 'Unrecognized shortcut — use a form like Alt+Q / Ctrl+Shift+K',
         surfaceUnavailable: 'The chosen side surface is unavailable',
+        familySuppressed: 'A newer family build ({version}) is already running on this page; this copy has disabled its trigger and shortcut so only one UI answers. Uninstall this older package.',
+        familyLegacyToast: 'Legacy dsh-selection-followup detected alongside this plugin; this build took over. Uninstall the old package.',
+        familyLegacyDiag: 'Legacy co-load',
+        familyPeers: 'Copies on page',
       },
     }
 
@@ -659,6 +667,12 @@ window.__ModuleLoader__.load({
         zoneAnchors: null,
         /** Which ladder rung each registration actually landed on. */
         slots: {},
+        /** §4.5 family election: this copy owns the interaction surface. */
+        familyLeader: true,
+        /** Other cooperating copies currently live in this page. */
+        familyPeers: [],
+        /** A non-cooperating legacy build (≤1.0.x) is present and suppressed. */
+        familyLegacy: false,
         revision: 0,
       },
       listeners: new Set(),
@@ -686,6 +700,94 @@ window.__ModuleLoader__.load({
       return store.state
     }
 
+    // ─────────────────────────────────────────────────────────────────────
+    // §4.5 family singleton
+    //
+    // The plugin shipped under two npm names (`dsh-selection-followup` ≤1.0.1
+    // and `dsh-sidecard-ask` ≥1.1.0), and a profile can accidentally enable
+    // BOTH bundles — or the same bundle twice. Two live copies used to mean
+    // two trigger buttons stacked on the selection and two Alt+Q popovers.
+    //
+    // Cooperating copies (any build with this section) share one registry on
+    // `window` and elect a single leader by version (ties → first loaded);
+    // non-leaders keep their settings page but mount NO interaction surface.
+    //
+    // The old 1.0.x build cannot cooperate: it is detected structurally (its
+    // overlay carries the same `dsa-layer` class without an owner marker), the
+    // leader hides its UI with one stylesheet rule, and the user is told to
+    // uninstall the old package.
+    // ─────────────────────────────────────────────────────────────────────
+
+    const FAMILY_WINDOW_KEY = '__dshSidecardFamily'
+    const INSTANCE_ID = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+    const OWNER_TOKEN = `${PLUGIN_ID}@${CLIENT_VERSION}#${INSTANCE_ID}`
+
+    /** Compare dotted numeric versions; non-numeric parts sort first. */
+    function compareVersions(a, b) {
+      const parts = v => String(v).split(/[.+-]/).map(part => (/^\d+$/.test(part) ? Number(part) : -1))
+      const pa = parts(a)
+      const pb = parts(b)
+      for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+        const x = pa[i] ?? -1
+        const y = pb[i] ?? -1
+        if (x !== y) return x < y ? -1 : 1
+      }
+      return 0
+    }
+
+    /**
+     * Elect the leader: highest version wins; a tie goes to the member that
+     * joined first (Map insertion order). Pure so the contract test can pin it.
+     * @returns {string} the winning member id.
+     */
+    function electFamilyLeader(members, selfId) {
+      let winner = null
+      for (const member of members) {
+        // Strictly greater version replaces; an equal version keeps the member
+        // that joined earlier (Map insertion order = load order).
+        if (winner === null || compareVersions(member.version, winner.version) > 0) {
+          winner = member
+        }
+      }
+      return winner?.id ?? selfId
+    }
+
+    /** Fetch-or-create the cross-copy registry (survives HMR on `window`). */
+    function familyTable(win) {
+      const existing = win[FAMILY_WINDOW_KEY]
+      if (existing !== undefined && existing !== null && typeof existing.subscribe === 'function') {
+        return existing
+      }
+      const members = new Map()
+      const listeners = new Set()
+      const emit = () => { for (const fn of [...listeners]) { try { fn() } catch { /* peer listener */ } } }
+      const table = {
+        join(member) { members.set(member.id, member); emit() },
+        leave(id) { members.delete(id); emit() },
+        list: () => [...members.values()],
+        subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn) },
+      }
+      try {
+        Object.defineProperty(win, FAMILY_WINDOW_KEY, { value: table, configurable: true, writable: true })
+      } catch {
+        win[FAMILY_WINDOW_KEY] = table
+      }
+      return table
+    }
+
+    /**
+     * Find legacy (≤1.0.x, non-cooperating) family UI: a `dsa-layer` carrying
+     * a trigger button but no owner marker. Every layer this build renders
+     * stamps `data-dsa-owner`, so an unmarked layer can only be the old build.
+     */
+    function findLegacyLayers(root) {
+      if (typeof root.querySelectorAll !== 'function') return []
+      try {
+        return [...root.querySelectorAll('.dsa-layer:not([data-dsa-owner])')]
+          .filter(node => node.querySelector?.('.dsa-trigger, .dsa-pop') !== null)
+      } catch { return [] }
+    }
+
     /**
      * In-session override of the configured floating-layer shape. Deliberately
      * NOT persisted: the settings page owns the durable default, and a reload
@@ -1210,6 +1312,12 @@ window.__ModuleLoader__.load({
           ...(surfaces.better.reason === null ? {} : { reason: String(surfaces.better.reason) }),
           features: surfaces.better.features,
         },
+        // §4.5 family singleton verdict (host-side diagnostics only).
+        family: {
+          leader: state.familyLeader !== false,
+          peers: Array.isArray(state.familyPeers) ? state.familyPeers : [],
+          legacy: state.familyLegacy === true,
+        },
       }
     }
 
@@ -1368,6 +1476,15 @@ window.__ModuleLoader__.load({
 .dsa-check{display:flex;align-items:center;gap:6px;font-size:12px}
 .dsa-diag{display:flex;flex-direction:column;gap:2px;font-size:12px;
   color:var(--dsw-alias-label-secondary, #555)}
+/* §4.5 legacy coexistence: an unmarked dsa-layer can only be the old
+   dsh-selection-followup ≤1.0.x build. When this build is the elected
+   leader it hides the old build's whole interaction surface so exactly
+   one trigger button / popover answers the selection. Our own layer always
+   carries data-dsa-owner, so this never matches current-generation UI. */
+.dsa-layer:not([data-dsa-owner]){display:none!important}
+.dsa-family-notice{padding:8px 10px;border-radius:8px;font-size:12px;
+  border:1px solid var(--dsw-alias-state-warn-primary, #b8860b);
+  color:var(--dsw-alias-state-warn-primary, #b8860b)}
 `
 
     /** Render the stylesheet as a React element (removed with its component). */
@@ -1977,10 +2094,19 @@ window.__ModuleLoader__.load({
     /** The `shell.overlay` entry: styles + trigger + popover + cards + toast. */
     function OverlayRoot({ actions }) {
       const state = useStoreState()
+      // §4.5 a non-leader copy mounts no interaction surface at all (its
+      // settings page stays available to explain the situation).
+      if (state.familyLeader === false) return null
       const config = state.config
       const candidate = state.trigger
       const popover = state.popover
-      return h('div', { className: 'dsa-layer', 'data-dsa-root': '' },
+      return h('div', {
+        className: 'dsa-layer',
+        'data-dsa-root': '',
+        // §4.5 stamps ownership so the legacy-suppression stylesheet can
+        // distinguish this build's layer from an unmarked ≤1.0.x layer.
+        'data-dsa-owner': OWNER_TOKEN,
+      },
         h(Styles, null),
         candidate !== null && popover === null && config.trigger !== 'shortcut'
           ? h(TriggerButton, { candidate, onOpen: () => actions.openPopover(candidate) })
@@ -2060,11 +2186,20 @@ window.__ModuleLoader__.load({
         }
       }
 
+      // §4.5 a non-leader copy explains why its interaction surface is gone.
+      const familyBanner = state.familyLeader === false
+        ? h('div', { className: 'dsa-family-notice', role: 'status' },
+          t('familySuppressed', { version: (state.familyPeers[0]?.version) ?? '?' }))
+        : (state.familyLegacy === true
+          ? h('div', { className: 'dsa-family-notice', role: 'status' }, t('familyLegacyToast'))
+          : null)
+
       return h('div', { className: 'dsa-settings', 'data-dsa-root': '' },
         h(Styles, null),
         h('div', null,
           h('div', { className: 'dsa-title' }, t('settingsTitle')),
           h('div', { className: 'dsa-muted' }, t('settingsDesc'))),
+        familyBanner,
         h('div', { className: 'dsa-grid' },
           field(t('setTrigger'), select('trigger', [
             ['selection', t('setTriggerSelection')],
@@ -2671,20 +2806,30 @@ window.__ModuleLoader__.load({
         // ── selection listeners ──────────────────────────────────────────
         const evaluate = () => {
           pendingTimer = null
+          // §4.5 a non-leader copy must not surface its trigger, even if a
+          // stale selection event arrives.
+          if (store.state.familyLeader === false) return
           const config = store.state.config
           const candidate = readSelection()
           // Zone anchors: the harness stamps every slot outlet with
-          // `data-slot="<key>"`. A build that renders no such marker (or a
-          // selection made outside the frame's own tree) leaves the slot path
-          // empty, and then region filtering is impossible — reported once and
-          // relaxed rather than silently swallowing every trigger.
-          if (candidate !== null) {
-            const anchored = candidate.slotPath.length > 0
-            if (store.state.zoneAnchors !== anchored) {
-              store.set({ zoneAnchors: anchored })
-              if (!anchored) {
-                console.info(`[${PLUGIN_ID}] 该版本没有 data-slot 锚点，区域过滤不可用，已按"全部区域"工作`)
-              }
+          // `data-slot="<key>"`. This is a property of the BUILD, not of the
+          // current selection — a selection on a body-mounted node (an
+          // onboarding modal, another plugin's raw-DOM panel) has an empty
+          // slot path even though the frame is full of anchors. Probe the
+          // whole document instead, or one such selection would flip the
+          // global verdict to "missing" and silently disable zone filtering.
+          if (candidate !== null && store.state.zoneAnchors !== true) {
+            const buildHasAnchors = candidate.slotPath.length > 0
+              || (typeof document !== 'undefined' && document.querySelector('[data-slot]') !== null)
+            if (buildHasAnchors) {
+              if (store.state.zoneAnchors !== true) scheduleReport(0)
+              store.set({ zoneAnchors: true })
+            } else if (store.state.zoneAnchors === null && candidate.slotPath.length === 0) {
+              // Only the build-wide miss (and never a single unanchored
+              // selection) flips the verdict to unavailable.
+              store.set({ zoneAnchors: false })
+              scheduleReport(0)
+              console.info(`[${PLUGIN_ID}] 该版本没有 data-slot 锚点，区域过滤不可用，已按"全部区域"工作`)
             }
           }
           const decision = shouldOffer(candidate, config, { anchors: store.state.zoneAnchors !== false })
@@ -2715,6 +2860,9 @@ window.__ModuleLoader__.load({
         }
 
         const onKeyDown = (event) => {
+          // §4.5 only the leader answers the shortcut; otherwise two copies
+          // would each preventDefault and each open their own popover.
+          if (store.state.familyLeader === false) return
           const config = store.state.config
           const facts = parseShortcut(config.shortcut)
           if (matchesShortcut(event, facts)) {
@@ -3153,6 +3301,61 @@ window.__ModuleLoader__.load({
           // Corrupt-but-parseable history must never block startup.
           console.warn(`[${PLUGIN_ID}] card history restore failed:`, error)
         }
+
+        // §4.5 family singleton: register this copy, (re)elect on every join
+        // or leave, and gate the interaction surface on the verdict.
+        const family = familyTable(window)
+        family.join({ id: INSTANCE_ID, version: CLIENT_VERSION, at: Date.now() })
+        const reelect = () => {
+          const members = family.list()
+          const leaderId = electFamilyLeader(members, INSTANCE_ID)
+          const leader = leaderId === INSTANCE_ID
+          const peers = members
+            .filter(member => member.id !== INSTANCE_ID)
+            .map(member => ({ id: member.id, version: member.version }))
+          store.set({ familyLeader: leader, familyPeers: peers })
+          scheduleReport(0)
+          if (leader) detectLegacy()
+        }
+        const unsubscribeFamily = family.subscribe(reelect)
+
+        // Legacy (≤1.0.x) detection: it never joins the registry, so watch
+        // the overlay tree for an unmarked dsa-layer carrying family UI. The
+        // suppression stylesheet then hides it; we only need detection to
+        // raise the toast/report. Repeated matches are a no-op.
+        let legacyAnnounced = false
+        let legacyObserver = null
+        const detectLegacy = () => {
+          if (store.state.familyLeader !== true || legacyAnnounced === true) return
+          const root = typeof document !== 'undefined' ? document : null
+          if (root === null) return
+          const found = findLegacyLayers(root).length > 0
+          if (found === false) return
+          legacyAnnounced = true
+          // Inject the suppression rule directly: the React stylesheet only
+          // exists while our overlay is mounted, but the legacy layer must
+          // stay hidden even during its own re-renders.
+          try {
+            if (root.getElementById('dsa-family-legacy-style') === null) {
+              const style = root.createElement('style')
+              style.id = 'dsa-family-legacy-style'
+              style.textContent = '.dsa-layer:not([data-dsa-owner]){display:none!important}'
+              root.head?.appendChild(style)
+            }
+          } catch { /* React stylesheet already carries the same rule */ }
+          store.set({ familyLegacy: true })
+          toast(t('familyLegacyToast'))
+          scheduleReport(0)
+        }
+        const legacyTimers = [300, 1200, 3000].map(delay => setTimeout(detectLegacy, delay))
+        if (typeof document !== 'undefined' && typeof MutationObserver === 'function') {
+          legacyObserver = new MutationObserver(() => detectLegacy())
+          try {
+            legacyObserver.observe(document.documentElement ?? document, { childList: true, subtree: true })
+          } catch { /* document without a root yet — timers still cover it */ }
+        }
+
+        reelect()
         void refreshState().catch(() => { /* the settings page shows the failure */ })
         // One report after the slot ladders have had time to settle, so the
         // Host ends up holding the CLIENT's real registration state.
@@ -3170,6 +3373,15 @@ window.__ModuleLoader__.load({
           pendingProofs.clear()
           if (toastTimer !== null) clearTimeout(toastTimer)
           if (reportTimer !== null) clearTimeout(reportTimer)
+          for (const timer of legacyTimers) clearTimeout(timer)
+          try {
+            if (typeof document !== 'undefined' && document.getElementById) {
+              document.getElementById('dsa-family-legacy-style')?.remove()
+            }
+          } catch { /* torn down */ }
+          try { legacyObserver?.disconnect() } catch { /* already gone */ }
+          try { unsubscribeFamily() } catch { /* registry torn down */ }
+          try { family.leave(INSTANCE_ID) } catch { /* registry torn down */ }
           store.set({
             trigger: null,
             popover: null,
@@ -3222,6 +3434,9 @@ window.__ModuleLoader__.load({
           renderRichText,
           pickSurface,
           floatPlacement,
+          compareVersions,
+          electFamilyLeader,
+          findLegacyLayers,
           localizeError,
           errorCodes: ERROR_CODES,
           resolveLanguage,

package/index.js

@@ -42,7 +42,7 @@ export const name = 'dsh-sidecard-ask'
 export const inject = ['webServer']
 
 /** Version of this plugin (kept in step with package.json by test/verify.mjs). */
-export const PLUGIN_VERSION = '1.5.0'
+export const PLUGIN_VERSION = '1.6.0'
 
 /** Route prefix of the plugin's own API. */
 export const ROUTE_PREFIX = '/sidecard-ask/api'
@@ -542,10 +542,64 @@ function createSideEngine(ctx, configOf) {
     }
   }), 'sidecard-ask: durable chunk bridge')
 
-  /** The optional subagents service, or undefined. */
+  /**
+   * The optional subagents service, or undefined.
+   *
+   * 0.2.1-alpha.2 replaced `subagents.start(provider, request)` with the
+   * managed-activations API `subagents.startActivation(spec)`; a build carries
+   * exactly one of the two launch methods, so either one means the service is
+   * present and launchable.
+   */
   function subagentsService() {
     const service = ctx.get('subagents')
-    return service !== undefined && typeof service.start === 'function' ? service : undefined
+    if (service === undefined) return undefined
+    const launchable = typeof service.start === 'function' || typeof service.startActivation === 'function'
+    return launchable ? service : undefined
+  }
+
+  /** Whether this runtime speaks the managed-activations API. */
+  function usesActivationApi(service) {
+    return typeof service?.startActivation === 'function' && typeof service?.start !== 'function'
+  }
+
+  /**
+   * Start one child answer, normalizing both subagents API generations to the
+   * shape the stream bridge consumes (`{id, localAgent?, result, dispose}`).
+   *
+   * Old API (≤0.2.1-alpha.1): `start(provider, request)` returns a SubagentRun.
+   * New API (0.2.1-alpha.2+): `startActivation({provider, label, request,
+   * signal, delivery: 'caller'})` returns `{childId, result, dispose}`; the
+   * caller-delivery policy keeps the child out of the parent's visible
+   * conversation — the same independent-answer semantics the old run had.
+   *
+   * @returns {Promise<{id: string, localAgent?: object, result: Promise<object>,
+   *   dispose: Function, api: 'start'|'activation'}>}
+   */
+  async function startSubagent(service, provider, fields) {
+    if (typeof service.start === 'function') {
+      const run = await service.start(provider, fields)
+      return { id: run.id, localAgent: run.localAgent, result: run.result, dispose: run.dispose, api: 'start' }
+    }
+    const activation = await service.startActivation({
+      provider,
+      label: fields.label,
+      delivery: 'caller',
+      signal: fields.signal,
+      request: {
+        prompt: fields.prompt,
+        parent: fields.parent,
+        ...(fields.persona === undefined ? {} : { persona: fields.persona }),
+        ...(fields.toolFilter === undefined ? {} : { toolFilter: fields.toolFilter }),
+      },
+    })
+    return {
+      id: activation.childId,
+      // No live Agent handle on the activation face; frame attribution falls
+      // back to the child session id (onFrame already matches that path).
+      result: activation.result,
+      dispose: () => activation.dispose(),
+      api: 'activation',
+    }
   }
 
   /** Registered subagent provider names (empty when the service is absent). */
@@ -825,7 +879,7 @@ function createSideEngine(ctx, configOf) {
       const personaSupported = caps?.persona === true
       const toolFilterSupported = caps?.toolFilter === true
       const promptText = personaSupported ? prompt : `${SIDE_PERSONA}\n\n${prompt}`
-      const run = await service.start(provider, {
+      const run = await startSubagent(service, provider, {
         label: `划词追问：${question.slice(0, 40)}`,
         prompt: [{ type: 'text', text: promptText }],
         parent: parent.agent,
@@ -1133,6 +1187,22 @@ export function apply(ctx, patchConfig) {
           .map(feature => feature.slice(0, 40))
       }
     }
+    // §4.5 family singleton verdict (bounded, same hardening as slots).
+    if (raw.family !== null && typeof raw.family === 'object' && !Array.isArray(raw.family)) {
+      out.family = {
+        leader: flag(raw.family.leader) ?? true,
+        legacy: flag(raw.family.legacy) ?? false,
+        peers: Array.isArray(raw.family.peers)
+          ? raw.family.peers
+            .filter(peer => peer !== null && typeof peer === 'object')
+            .slice(0, 8)
+            .map(peer => ({
+              id: short(peer.id, 64) ?? 'peer',
+              ...(short(peer.version, 24) !== undefined ? { version: short(peer.version, 24) } : {}),
+            }))
+          : [],
+      }
+    }
     return out
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-sidecard-ask",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "DSH 划词追问（侧边卡片作答）：在聊天区与任务区选中文本就地追问，答案由独立子代理在侧边卡片里流式呈现，也可选择落回主对话。",
   "type": "module",
   "main": "index.js",