dsh-session-guard 4.0.2 → 4.1.11

package/src/bridge.js

@@ -1,136 +1,136 @@
-/**
- * dsh-session-guard — sessionGuard 冗余端口（D5/D6/D8）。
- *
- * `ctx.provide('sessionGuard', service)`：
- * - stopNextTurn / resume：会话门（透传 taskControl，或回退锁队列）。
- * - lockQueue / unlockQueue：显式队列锁（供 input-traffic 冻结按钮桥接，
- *   或未来手动触发）。
- * - state(sessionId)：{ queueLocked, lockReason, taskControlAvailable, taskControl }。
- *
- * input-traffic（方案 A，基于 feat/absorb-auto-continue 分支改造）在冻结按钮
- * 触发时调用 stopNextTurn；本服务不存在时 input-traffic 静默跳过（fail-open，D8）。
- */
-import { idleState } from './store.js'
-
-/**
- * @param {object} ctx host context
- * @param {ReturnType<import('./gate.js').createGate>} gate
- * @param {ReturnType<import('./store.js').createStore>} store
- * @param {ReturnType<import('./pause-gate.js').createPauseGate>} [pauseGate]
- * @param {ReturnType<import('./step-gate.js').createStepGate>} [stepGate] step 级门控（v0.2.0）
- */
-export function createBridge(ctx, gate, store, pauseGate, stepGate) {
-  function taskControlState(sessionId) {
-    let tcState = null
-    try {
-      const tc = ctx && typeof ctx.get === 'function' ? ctx.get('taskControl') : undefined
-      if (tc && typeof tc.state === 'function') {
-        const s = tc.state(sessionId)
-        tcState = {
-          status: s && s.status,
-          paused: !!(s && s.paused),
-          forced: !!(s && s.forced),
-        }
-      }
-    } catch {
-      /* 状态读取失败 → 保持 null，fail-open */
-    }
-    return tcState
-  }
-
-  return {
-    /** 停掉 session 下一回合（会话门 / 回退锁队列）。 */
-    stopNextTurn(sessionId, opts) {
-      return gate.stopNextTurn(sessionId, opts)
-    },
-    /** 恢复。 */
-    resume(sessionId, opts) {
-      return gate.resume(sessionId, opts)
-    },
-    /** 显式锁队列（手动触发）。 */
-    lockQueue(sessionId, reason = 'manual') {
-      const next = gate.lockQueue(sessionId, reason)
-      return { ok: true, state: next }
-    },
-    /** 显式解锁队列。 */
-    unlockQueue(sessionId) {
-      const next = gate.unlockQueue(sessionId)
-      return { ok: true, state: next }
-    },
-    /**
-     * 手动请求 step 级暂停（「暂停会话」按钮）。
-     * 不打断当前 step：在下一次 `agent/pre-step` 边界拉门（step 1 也拦，且不受峰谷/provider 限制）。
-     * @param {string} sessionId
-     */
-    stepPause(sessionId) {
-      if (!stepGate || typeof stepGate.requestPause !== 'function') {
-        return { requested: false, held: false, reason: 'no-step-gate' }
-      }
-      try {
-        return stepGate.requestPause(sessionId)
-      } catch {
-        return { requested: false, held: false, reason: 'error' }
-      }
-    },
-    /**
-     * 解开 step 门（v0.2.0）：放行被挂起的 step。
-     * 默认 `bypass=true`（用户手动「继续」）——本高峰窗口内不再拦该会话；
-     * 退峰/非官方切换等自动释放请用 `{ bypass: false }`。
-     * @param {string} sessionId
-     * @param {{bypass?:boolean, reason?:string}} [opts]
-     */
-    stepResume(sessionId, opts = {}) {
-      if (!stepGate || typeof stepGate.release !== 'function') {
-        return { released: false, bypass: false, reason: 'no-step-gate' }
-      }
-      const reason = opts.reason ?? 'manual'
-      let r
-      try {
-        r = stepGate.release(sessionId, reason)
-      } catch {
-        return { released: false, bypass: false, reason }
-      }
-      const released = !!(r && r.released === true)
-      let bypassed = false
-      if (released && opts.bypass !== false && typeof stepGate.markBypass === 'function') {
-        try {
-          stepGate.markBypass(sessionId)
-          bypassed = true
-        } catch {
-          /* ignore */
-        }
-      }
-      return { released, bypass: bypassed, reason }
-    },
-    /** 读一会话状态。 */
-    state(sessionId) {
-      const cur = store.get(sessionId)
-      const base = cur || idleState(sessionId)
-      const pausedState = pauseGate ? (pauseGate.state(sessionId) || {}) : {}
-      let stepState = {}
-      if (stepGate && typeof stepGate.state === 'function') {
-        try {
-          stepState = stepGate.state(sessionId) || {}
-        } catch {
-          stepState = {}
-        }
-      }
-      return {
-        sessionId: String(sessionId),
-        queueLocked: base.queueLocked === true,
-        lockReason: base.lockReason ?? null,
-        // 自研会话门真暂停状态（脱离 task-control）。
-        paused: pausedState.paused === true,
-        pausedForced: pausedState.forced === true,
-        // step 级门控（v0.2.0）：paused 保持布尔以兼容既有消费者，step 态用独立字段。
-        pausedStep: stepState.held === true,
-        stepHeldSince: stepState.since ?? null,
-        stepBypass: stepState.bypass === true,
-        stepManual: stepState.manual === true,
-        taskControlAvailable: gate.taskControlAvailable(),
-        taskControl: taskControlState(sessionId),
-        updatedAt: base.updatedAt ?? null,
-      }
-    },
-  }
-}
+/**
+ * dsh-session-guard — sessionGuard 冗余端口（D5/D6/D8）。
+ *
+ * `ctx.provide('sessionGuard', service)`：
+ * - stopNextTurn / resume：会话门（透传 taskControl，或回退锁队列）。
+ * - lockQueue / unlockQueue：显式队列锁（供 input-traffic 冻结按钮桥接，
+ *   或未来手动触发）。
+ * - state(sessionId)：{ queueLocked, lockReason, taskControlAvailable, taskControl }。
+ *
+ * input-traffic（方案 A，基于 feat/absorb-auto-continue 分支改造）在冻结按钮
+ * 触发时调用 stopNextTurn；本服务不存在时 input-traffic 静默跳过（fail-open，D8）。
+ */
+import { idleState } from './store.js'
+
+/**
+ * @param {object} ctx host context
+ * @param {ReturnType<import('./gate.js').createGate>} gate
+ * @param {ReturnType<import('./store.js').createStore>} store
+ * @param {ReturnType<import('./pause-gate.js').createPauseGate>} [pauseGate]
+ * @param {ReturnType<import('./step-gate.js').createStepGate>} [stepGate] step 级门控（v0.2.0）
+ */
+export function createBridge(ctx, gate, store, pauseGate, stepGate) {
+  function taskControlState(sessionId) {
+    let tcState = null
+    try {
+      const tc = ctx && typeof ctx.get === 'function' ? ctx.get('taskControl') : undefined
+      if (tc && typeof tc.state === 'function') {
+        const s = tc.state(sessionId)
+        tcState = {
+          status: s && s.status,
+          paused: !!(s && s.paused),
+          forced: !!(s && s.forced),
+        }
+      }
+    } catch {
+      /* 状态读取失败 → 保持 null，fail-open */
+    }
+    return tcState
+  }
+
+  return {
+    /** 停掉 session 下一回合（会话门 / 回退锁队列）。 */
+    stopNextTurn(sessionId, opts) {
+      return gate.stopNextTurn(sessionId, opts)
+    },
+    /** 恢复。 */
+    resume(sessionId, opts) {
+      return gate.resume(sessionId, opts)
+    },
+    /** 显式锁队列（手动触发）。 */
+    lockQueue(sessionId, reason = 'manual') {
+      const next = gate.lockQueue(sessionId, reason)
+      return { ok: true, state: next }
+    },
+    /** 显式解锁队列。 */
+    unlockQueue(sessionId) {
+      const next = gate.unlockQueue(sessionId)
+      return { ok: true, state: next }
+    },
+    /**
+     * 手动请求 step 级暂停（「暂停会话」按钮）。
+     * 不打断当前 step：在下一次 `agent/pre-step` 边界拉门（step 1 也拦，且不受峰谷/provider 限制）。
+     * @param {string} sessionId
+     */
+    stepPause(sessionId) {
+      if (!stepGate || typeof stepGate.requestPause !== 'function') {
+        return { requested: false, held: false, reason: 'no-step-gate' }
+      }
+      try {
+        return stepGate.requestPause(sessionId)
+      } catch {
+        return { requested: false, held: false, reason: 'error' }
+      }
+    },
+    /**
+     * 解开 step 门（v0.2.0）：放行被挂起的 step。
+     * 默认 `bypass=true`（用户手动「继续」）——本高峰窗口内不再拦该会话；
+     * 退峰/非官方切换等自动释放请用 `{ bypass: false }`。
+     * @param {string} sessionId
+     * @param {{bypass?:boolean, reason?:string}} [opts]
+     */
+    stepResume(sessionId, opts = {}) {
+      if (!stepGate || typeof stepGate.release !== 'function') {
+        return { released: false, bypass: false, reason: 'no-step-gate' }
+      }
+      const reason = opts.reason ?? 'manual'
+      let r
+      try {
+        r = stepGate.release(sessionId, reason)
+      } catch {
+        return { released: false, bypass: false, reason }
+      }
+      const released = !!(r && r.released === true)
+      let bypassed = false
+      if (released && opts.bypass !== false && typeof stepGate.markBypass === 'function') {
+        try {
+          stepGate.markBypass(sessionId)
+          bypassed = true
+        } catch {
+          /* ignore */
+        }
+      }
+      return { released, bypass: bypassed, reason }
+    },
+    /** 读一会话状态。 */
+    state(sessionId) {
+      const cur = store.get(sessionId)
+      const base = cur || idleState(sessionId)
+      const pausedState = pauseGate ? (pauseGate.state(sessionId) || {}) : {}
+      let stepState = {}
+      if (stepGate && typeof stepGate.state === 'function') {
+        try {
+          stepState = stepGate.state(sessionId) || {}
+        } catch {
+          stepState = {}
+        }
+      }
+      return {
+        sessionId: String(sessionId),
+        queueLocked: base.queueLocked === true,
+        lockReason: base.lockReason ?? null,
+        // 自研会话门真暂停状态（脱离 task-control）。
+        paused: pausedState.paused === true,
+        pausedForced: pausedState.forced === true,
+        // step 级门控（v0.2.0）：paused 保持布尔以兼容既有消费者，step 态用独立字段。
+        pausedStep: stepState.held === true,
+        stepHeldSince: stepState.since ?? null,
+        stepBypass: stepState.bypass === true,
+        stepManual: stepState.manual === true,
+        taskControlAvailable: gate.taskControlAvailable(),
+        taskControl: taskControlState(sessionId),
+        updatedAt: base.updatedAt ?? null,
+      }
+    },
+  }
+}

package/src/client/family-section.tsx

@@ -10,7 +10,7 @@
  * 与 thinking-levels 的 FamilySettingsSection 的差别仅在不需要 thinking-
  * levels 自己的卡（宿主不在了，它的卡也不在）：渲染循环没有 own-tab 特例。
  */
-import { useSyncExternalStore } from 'react'
+import { useEffect, useState } from 'react'
 import type { JSX } from 'react'
 
 /** 与 FamilySectionInjected.hooks.tabs 同形的账本投影（结构化镜像）。 */
@@ -26,19 +26,39 @@ export interface FamilyTabEntry {
   label: string
 }
 
-/** 组件 props：框架注入的子席位 dispatcher + 注册侧 inject 返回的 hooks。 */
+/** 组件 props：hooks 舱（宿主 bindInjectHooks 把 inject 面的 `hooks` 键剥掉
+ * 转成 `useTabs`——0.1.0 起各代皆然，故 useTabs 是正路、raw hooks 只是
+ * 无转换环境的兜底）+ ≤0.1.5 壳缺 renderSlot 时的直接挂载面。 */
 export interface GuardFamilySectionProps {
-  renderSlot: (key: 'dsh-family.tab', owner?: object, opts?: { only?: string; fallback?: JSX.Element | null }) => JSX.Element | null
-  hooks: { tabs: HostObservable<readonly FamilyTabEntry[]> }
+  renderSlot?: (key: 'dsh-family.tab', owner?: object, opts?: { only?: string; fallback?: JSX.Element | null }) => JSX.Element | null
+  /** 宿主转换后的 hooks 舱（`inject.hooks.tabs` → `useTabs`）。 */
+  useTabs?: <S>(selector: (value: readonly FamilyTabEntry[]) => S) => S
+  /** 未被宿主转换时的原始账本投影（防御位，实测各代都会转换走 useTabs）。 */
+  hooks?: { tabs: HostObservable<readonly FamilyTabEntry[]> }
+  /** 直接挂载面（≤0.1.5 壳无 renderSlot 时）：注册侧从账本原始条目
+   * （entries 自带 component + inject）现挂激活卡。失败一律 null。 */
+  renderContributor?: (id: string) => JSX.Element | null
 }
 
+const NO_TABS: readonly FamilyTabEntry[] = []
+
 export function GuardFamilySection(props: GuardFamilySectionProps): JSX.Element {
-  const tabs = useSyncExternalStore(props.hooks.tabs.subscribe, props.hooks.tabs.getSnapshot)
+  const raw = props.hooks?.tabs
+  // 账本读取：useTabs 舱优先；raw 投影走 React 订阅。face 选择每代固定，
+  // 两种路径的 hook 数不同但同实例内次序恒定。
+  const [polled, setPolled] = useState<readonly FamilyTabEntry[]>(() => raw?.getSnapshot() ?? NO_TABS)
+  useEffect(() => {
+    if (props.useTabs !== undefined || raw === undefined) return
+    return raw.subscribe(() => setPolled(raw.getSnapshot()))
+  })
+  const tabs = props.useTabs !== undefined ? props.useTabs(value => value) : polled
   return (
     <div style={{ display: 'grid', gap: '12px' }}>
       {tabs.map(row => (
         <div key={row.id}>
-          {props.renderSlot('dsh-family.tab', {}, { only: row.id, fallback: null })}
+          {props.renderSlot
+            ? props.renderSlot('dsh-family.tab', {}, { only: row.id, fallback: null })
+            : props.renderContributor?.(row.id) ?? null}
         </div>
       ))}
     </div>

package/src/client/index.ts

@@ -8,13 +8,21 @@
  *   桥接 host 会话门；本插件客户端不注册任何按钮，避免与 input-traffic 冲突。
  * - 0.1.7：旧的插件设置卡已随席位删除 —— 设置表单由 host
  *   侧 Config 的 `.volatile()` 字段自动生成。
+ * - 跨版本（universal-rc）：持久设置经 configForms(0.1.7+)/settingsScope(≤0.1.5)
+ *   双代腰产出同形 scope；无设置页宿主（0.1.0/0.1.1）经 shell.overlay 浮窗
+ *   齿轮提供配置入口（配置存储全在 host 侧，浮层与宿主设置页解耦）。
  *
  * 构建：tsdown → lib/client.js（__ModuleLoader__.load 注册，与 input-traffic 同构）。
  */
+import { createElement } from 'react'
+import type { JSX } from 'react'
 import { StatusBadge } from './status-badge'
 import { PauseButton } from './pause-button'
 import { SessionGuardCard } from './settings-card'
+import { ShellSettingsEntry } from './shell-overlay'
 import { GuardFamilySection, type FamilyTabEntry } from './family-section'
+import type { SessionGuardConfig } from './settings-card'
+import type { SettingsScope } from './scope-face'
 
 // 起子插件族共用设置节：宿主 dsh-thinking-levels 注册顶级 `settings.section`
 // （id `dsh-family`）并声明 `dsh-family.tab` 子席位，本插件贡献卡片。宿主缺席
@@ -33,6 +41,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * 本卡片改经 inject 工厂拿自己的 scope（与 dsh-family.tab 注册同源）。
      */
     'plugins.bundle.config': { kind: 'keyed'; scope: 'root'; owner: Record<string, unknown> }
+    /** 无设置页宿主（0.1.0/0.1.1）的兜底配置入口（壳级 overlay）。 */
+    'shell.overlay': { kind: 'list'; scope: 'root' }
   }
 }
 
@@ -40,91 +50,204 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 const FAMILY_SECTION_ID = 'dsh-family'
 /** 家族子席位 key（与 thinking-levels 的声明严格一致）。 */
 const FAMILY_CHILD_KEY = 'dsh-family.tab'
+/** 让位宽限：声明批内 TL 的注册微秒级落账，此延迟后查账本足以分辨「TL 在场」。 */
+const FAMILY_YIELD_MS = 500
+
 /**
- * 接管宽限期：等宿主（以及排名更前的贡献方）先落座。下载量排名 guard(1522)
- * 高于 session-steward(1090) → guard 宽限期更短、先尝试接管；并发冲突由
- * ui-slots 的「同 id 同 priority 重复注册抛错」仲裁，后到者放弃即可。
+ * 客户端所需服务：slots（状态徽标）+ locale。持久设置走双代腰
+ * （registerSettingsFaces）：configForms 为 0.1.7+ 独有，顶层注入会在
+ * 0.1.0/0.1.1（无此服务）上让整段 apply 静默死。
  */
-const FAMILY_HOST_GRACE_MS = 2000
-
-/** 客户端所需服务：slots（状态徽标）+ locale + configForms（共用 tab 设置卡）。 */
-export const inject = ['slots', 'locale', 'configForms']
+export const inject = ['slots', 'locale']
 
 /** 轻量 ctx 类型（仅本客户端用到的方法；构建时类型被剥离）。 */
 interface SlotsFace {
   inject: (_name: string, _fn: () => unknown) => () => void
   register: (_options: Record<string, unknown>, _component: unknown) => () => void
-  entries: (_name: string) => Array<{ options: { id?: string; order?: number; label?: unknown } }>
+  entries: (_name: string) => Array<{
+    options: { id?: string; order?: number; label?: unknown }
+    component?: unknown
+    inject?: () => unknown
+  }>
   getVersion: (_name: string) => number
   subscribe: (_name: string, _listener: () => void) => () => void
 }
-interface ConfigFormsFace {
-  get: <T>(_entryId: string) => import('./scope-face').SettingsScope<T>
+interface ConfigFormsFactoryFace {
+  get: <T>(_entryId: string) => SettingsScope<T>
+}
+interface SettingsScopeFactoryFace {
+  bind: <T>(_opts: { namespace: string }) => SettingsScope<T>
 }
 interface ClientCtx {
   slots: SlotsFace
-  configForms: ConfigFormsFace
+  inject: (
+    _names: string[],
+    _fn: (sctx: { configForms?: ConfigFormsFactoryFace; settingsScope?: SettingsScopeFactoryFace }) => void,
+  ) => void
 }
 
-export function apply(ctx: ClientCtx) {
-  // 暂停会话按钮（v0.2.0）：step 级门控的状态显示 + 手动解除。
-  // order 20 < input-traffic 冻结按钮的 30 → 排在左侧，两者并列互不取代（ADR-001/002）。
-  ctx.slots.inject('conversation.input.right', () => ctx.slots.register({
-    name: 'conversation.input.right',
-    id: 'session-guard-pause',
-    order: 20,
-    locale: 'session-guard',
-  }, PauseButton))
+/** 单面注册护栏：某条宿主线上未知槽名/缺服务的同步异常不得带走其它面。 */
+function safe(tag: string, fn: () => void): void {
+  try {
+    fn()
+  } catch (error) {
+    console.warn(`dsh-session-guard: client surface '${tag}' failed:`, error)
+  }
+}
 
-  // 状态徽标：输入区右侧，纯展示。
-  ctx.slots.inject('conversation.input.right', () => ctx.slots.register({
-    name: 'conversation.input.right',
-    id: 'session-guard-status',
-    order: 40,
-    locale: 'session-guard',
-  }, StatusBadge))
+/**
+ * 双代持久设置腰（移植 input-traffic registerSettingsFaces）：两个 scoped
+ * 子注入各自产出同形 scope 后回调；0.2.0 两代并存时以 configForms 先到为准
+ * （mounted 位防双挂载，ui-slots 同 id 仲裁兜底）。
+ */
+function registerSettingsFaces(
+  ctx: ClientCtx,
+  onScope: (scope: SettingsScope<SessionGuardConfig>, generation: 'configForms' | 'settingsScope') => void,
+): void {
+  let mounted = false
+  ctx.inject(['configForms'], (sctx) => {
+    if (mounted) return
+    mounted = true
+    onScope(sctx.configForms!.get<SessionGuardConfig>('session-guard'), 'configForms')
+  })
+  ctx.inject(['settingsScope'], (sctx) => {
+    if (mounted) return
+    mounted = true
+    onScope(sctx.settingsScope!.bind<SessionGuardConfig>({ namespace: 'session-guard' }), 'settingsScope')
+  })
+}
 
-  // 插件族共用 tab 贡献卡：读写本插件 entry（`session-guard`）的 volatile 配置。
+/** 两张配置卡（family tab + bundle 详情页）挂载；scope 由双代腰产出。 */
+function mountConfigCards(ctx: ClientCtx, scope: SettingsScope<SessionGuardConfig>): void {
+  // 插件族共用 tab 贡献卡：读写本插件 entry（`session-guard`）的持久配置。
   ctx.slots.inject('dsh-family.tab', () => ctx.slots.register({
     name: 'dsh-family.tab',
     id: 'session-guard',
     order: 20,
     label: '会话守护门禁',
     locale: 'session-guard',
-    inject: () => ({ scope: ctx.configForms.get<Record<string, unknown>>('session-guard') }),
+    inject: () => ({ scope }),
   }, SessionGuardCard))
 
   // 插件页配置卡（DSH 0.2.0）：Plugins 页不自动渲染 volatile 配置表单，须注册
   // `plugins.bundle.config` 席位（key = 包名），配置卡才渲染在 bundle 详情页。
-  // 卡片组件与 props（scope）与上方 dsh-family.tab 注册完全同源：同一张
-  // SessionGuardCard、同一 inject 工厂，配置仍写入 entry `session-guard` 的
-  // volatile config；页面注入的 owner props（form 等）本卡不消费。
+  // 卡片组件与 props（scope）与上方 dsh-family.tab 注册完全同源。
   ctx.slots.inject('plugins.bundle.config', () => ctx.slots.register({
     name: 'plugins.bundle.config',
     key: 'dsh-session-guard',
-    inject: () => ({ scope: ctx.configForms.get<Record<string, unknown>>('session-guard') }),
+    inject: () => ({ scope }),
   }, SessionGuardCard))
+}
+
+export function apply(ctx: ClientCtx) {
+  // 暂停会话按钮（v0.2.0）：step 级门控的状态显示 + 手动解除。
+  // order 20 < input-traffic 冻结按钮的 30 → 排在左侧，两者并列互不取代（ADR-001/002）。
+  safe('conversation.input.right/pause', () => ctx.slots.inject('conversation.input.right', () => ctx.slots.register({
+    name: 'conversation.input.right',
+    id: 'session-guard-pause',
+    order: 20,
+    locale: 'session-guard',
+  }, PauseButton)))
 
-  // 家族节宿主选举：宿主 dsh-thinking-levels 缺席时顶上「起子插件设置」节。
-  // 宽限期后若 `settings.section` 里没有 id `dsh-family` 的条目，则按同一 id
-  // 接管（声明同一个 dsh-family.tab 子席位，节内通用渲染全部贡献卡）。与
-  // session-steward 的并发竞争由 ui-slots 同 id 重复注册抛错仲裁，先到者胜。
-  // 节内各卡（含本插件自己的贡献卡）经子席位 renderSlot 渲染，抽屉默认展开。
-  setTimeout(() => {
-    if (ctx.slots.entries('settings.section').some(e => e.options.id === FAMILY_SECTION_ID)) return
-    try {
-      ctx.slots.register({
-        name: 'settings.section',
-        id: FAMILY_SECTION_ID,
-        order: 40,
-        label: () => '起子插件设置',
-        inject: () => makeGuardFamilyTabsHooks(ctx.slots),
-        children: { [FAMILY_CHILD_KEY]: { kind: 'list', scope: 'root' } },
-      }, GuardFamilySection)
-    } catch {
-      // 并发接管竞争落败（或设置壳未声明席位）：胜出方的节服务整个家族。
-    }
-  }, FAMILY_HOST_GRACE_MS)
+  // 状态徽标：输入区右侧，纯展示。
+  safe('conversation.input.right/status', () => ctx.slots.inject('conversation.input.right', () => ctx.slots.register({
+    name: 'conversation.input.right',
+    id: 'session-guard-status',
+    order: 40,
+    locale: 'session-guard',
+  }, StatusBadge)))
+
+  // 双代腰：scope 就绪后按代挂载（每条宿主线恰好一代服务）。
+  registerSettingsFaces(ctx, (scope, generation) => {
+    safe(`config-cards/${generation}`, () => {
+      // 两代共有：family tab（0.1.7+ 由 thinking-levels 容器渲染）与
+      // bundle 详情页平铺卡（0.1.7+ 的 plugin-manager 槽）。
+      mountConfigCards(ctx, scope)
+      // 老设置页(≤0.1.5)插件列表配置卡;0.1.7+ 无此槽,注册静默闲置。
+      ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
+        name: 'settings.plugin.item',
+        id: 'session-guard',
+        key: 'session-guard',
+        order: 60,
+        locale: 'session-guard',
+        inject: () => ({ scope }),
+      }, SessionGuardCard))
+    })
+    // 无设置页宿主（0.1.0/0.1.1）的兜底配置入口：壳级 overlay 浮窗齿轮。
+    safe('shell.overlay', () => ctx.slots.inject('shell.overlay', () => ctx.slots.register(
+      { name: 'shell.overlay', id: 'session-guard-settings' },
+      () => ShellSettingsEntry({ scope }),
+    )))
+  })
+
+  // 家族节接管（2026-10 对齐 TL route A + bindInjectHooks 实证）：让位选举。
+  // 2026-10-08 T20-a 实证修正：≤0.1.7 壳的设置导航对同 id 异 priority 的遮蔽位
+  // 也各列一行——「TL(p0) 恒头位、本插件 p10 恒阴影不占导航」假设不成立，双注册
+  // = 双「起子插件设置」导航行（0.1.0~0.1.7 五格全现；0.1.0 摘除 guard 实验：
+  // 单行归位、TL 节独座满血）。改为延迟让位：声明批内 TL 同批落账（工厂 fire
+  // 顺序=inject 注册顺序，本插件的 inject 先注册先 fire，TL 同批紧随），延迟
+  // FAMILY_YIELD_MS 再查账本——已有 dsh-family（TL 头位落座）→ 让位退场；仍空
+  // （TL 缺席/落账失败）→ 接管。inject 仍必须 apply 期注册——slots 核只在「声明
+  // 事件」触发工厂，宽限期后注册的 inject 等不到下一次声明（0.1.0 实机日志定案：
+  // 4.1.7/4.1.8 的 grace 后注册工厂零执行）；register 本就是指令式调用，移入
+  // 定时器不改变机制。子席位声明带冲突兜底：TL 先声明 → 去 children 重试（接管
+  // 者不重复声明）；同 id 同 priority 竞争 → 双抛，放弃。register 走本工厂触发
+  // 管道（裸注册的 entry.inject 在 ≤0.1.5 壳上不解，4.1.5「半补位」真相）。
+  safe('family-section-election', () => {
+    console.log('[dsh-session-guard] election: registering settings.section inject (apply-time)')
+    ctx.slots.inject('settings.section', () => {
+      console.log('[dsh-session-guard] election: factory fired (settings.section declared)')
+      setTimeout(() => {
+        if (ctx.slots.entries('settings.section').some(e => e.options.id === FAMILY_SECTION_ID)) {
+          console.log('[dsh-session-guard] election: dsh-family already seated — stand down')
+          return
+        }
+        const base = {
+          name: 'settings.section',
+          id: FAMILY_SECTION_ID,
+          order: 40,
+          priority: 10,
+          label: () => '起子插件设置',
+          inject: () => ({
+            hooks: makeGuardFamilyTabsHooks(ctx.slots),
+            renderContributor,
+          }),
+        }
+        try {
+          ctx.slots.register({
+            ...base,
+            children: { [FAMILY_CHILD_KEY]: { kind: 'list', scope: 'root' } },
+          }, GuardFamilySection)
+          console.log('[dsh-session-guard] family takeover registered (children declared)')
+        } catch (error) {
+          console.log(`[dsh-session-guard] children decl conflict (${error instanceof Error ? error.message : error}); registering without children`)
+          try {
+            ctx.slots.register(base, GuardFamilySection)
+            console.log('[dsh-session-guard] family takeover registered (no children)')
+          } catch (secondary) {
+            console.log(`[dsh-session-guard] family takeover abandoned: ${secondary instanceof Error ? secondary.message : secondary}`)
+          }
+        }
+      }, FAMILY_YIELD_MS)
+    })
+  })
+}
+
+/** 直接挂载面（≤0.1.5 壳无 renderSlot 的降级）：从账本原始条目现挂激活卡。
+ * entries 每代都带 component + inject（ui-slots SlotCore.entries 原始记录）；
+ * 任何失败（条目消失/抛错 inject）降级为 null，不炸接管节。 */
+function renderContributor(id: string): JSX.Element | null {
+  try {
+    const entry = ctx.slots.entries(FAMILY_CHILD_KEY).find(e => e.options.id === id)
+    if (entry === undefined || typeof entry.component !== 'function') return null
+    const injected = typeof entry.inject === 'function' ? entry.inject() : undefined
+    return createElement(
+      entry.component as (props: Record<string, unknown>) => JSX.Element | null,
+      (injected ?? {}) as Record<string, unknown>,
+    )
+  } catch {
+    return null
+  }
 }
 
 /** 接管节的账本投影 hooks（与 thinking-levels 的 FamilySectionInjected 同形）。 */