dsh-session-guard 4.1.5 → 4.1.15

package/src/client/index.ts

@@ -14,10 +14,12 @@
  *
  * 构建：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 { BridgeDocHandle } from './settings-bridge.ts'
 import { GuardFamilySection, type FamilyTabEntry } from './family-section'
 import type { SessionGuardConfig } from './settings-card'
 import type { SettingsScope } from './scope-face'
@@ -39,8 +41,6 @@ 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' }
   }
 }
 
@@ -48,12 +48,8 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 const FAMILY_SECTION_ID = 'dsh-family'
 /** 家族子席位 key（与 thinking-levels 的声明严格一致）。 */
 const FAMILY_CHILD_KEY = 'dsh-family.tab'
-/**
- * 接管宽限期：等宿主（以及排名更前的贡献方）先落座。下载量排名 guard(1522)
- * 高于 session-steward(1090) → guard 宽限期更短、先尝试接管；并发冲突由
- * ui-slots 的「同 id 同 priority 重复注册抛错」仲裁，后到者放弃即可。
- */
-const FAMILY_HOST_GRACE_MS = 2000
+/** 让位宽限：声明批内 TL 的注册微秒级落账，此延迟后查账本足以分辨「TL 在场」。 */
+const FAMILY_YIELD_MS = 500
 
 /**
  * 客户端所需服务：slots（状态徽标）+ locale。持久设置走双代腰
@@ -66,7 +62,11 @@ export const inject = ['slots', 'locale']
 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
 }
@@ -95,8 +95,9 @@ function safe(tag: string, fn: () => void): void {
 
 /**
  * 双代持久设置腰（移植 input-traffic registerSettingsFaces）：两个 scoped
- * 子注入各自产出同形 scope 后回调；0.2.0 两代并存时以 configForms 先到为准
- * （mounted 位防双挂载，ui-slots 同 id 仲裁兜底）。
+ * 子注入各自产出同形 scope 后回调。M4 P0 重构后本函数**只承担数据臂**——
+ * 回调仅写 scopeRef 活引用（0.1.7+ 原生优先，mounted 位防双挂），卡面注册
+ * 已全部提到 apply 顶层（≤0.1.5 回调永不触发，注册不能关在这里）。
  */
 function registerSettingsFaces(
   ctx: ClientCtx,
@@ -115,8 +116,23 @@ function registerSettingsFaces(
   })
 }
 
-/** 两张配置卡（family tab + bundle 详情页）挂载；scope 由双代腰产出。 */
-function mountConfigCards(ctx: ClientCtx, scope: SettingsScope<SessionGuardConfig>): void {
+/** scope 活引用（perm-gate client/index.ts L166-257 形态）：回调填、卡面现读。 */
+const scopeRef: { scope: SettingsScope<SessionGuardConfig> | undefined } = { scope: undefined }
+
+/** 桥轨惰性单例：≤0.1.5（settingsScope 死路 / 0.1.0-0.1.1 无服务）的数据源。 */
+let bridgeScopeSingleton: BridgeDocHandle<SessionGuardConfig> | undefined
+function bridgeScope(): BridgeDocHandle<SessionGuardConfig> {
+  if (bridgeScopeSingleton === undefined) bridgeScopeSingleton = new BridgeDocHandle<SessionGuardConfig>('session-guard')
+  return bridgeScopeSingleton
+}
+
+/** 卡面现取数据源：原生句柄解到即原生，否则桥兜底（perm-gate 同式）。 */
+function currentScope(): SettingsScope<SessionGuardConfig> {
+  return scopeRef.scope ?? bridgeScope()
+}
+
+/** 两张配置卡（family tab + bundle 详情页）挂载；数据经 currentScope() 现取。 */
+function mountConfigCards(ctx: ClientCtx): void {
   // 插件族共用 tab 贡献卡：读写本插件 entry（`session-guard`）的持久配置。
   ctx.slots.inject('dsh-family.tab', () => ctx.slots.register({
     name: 'dsh-family.tab',
@@ -124,7 +140,7 @@ function mountConfigCards(ctx: ClientCtx, scope: SettingsScope<SessionGuardConfi
     order: 20,
     label: '会话守护门禁',
     locale: 'session-guard',
-    inject: () => ({ scope }),
+    inject: () => ({ scope: currentScope() }),
   }, SessionGuardCard))
 
   // 插件页配置卡（DSH 0.2.0）：Plugins 页不自动渲染 volatile 配置表单，须注册
@@ -133,7 +149,7 @@ function mountConfigCards(ctx: ClientCtx, scope: SettingsScope<SessionGuardConfi
   ctx.slots.inject('plugins.bundle.config', () => ctx.slots.register({
     name: 'plugins.bundle.config',
     key: 'dsh-session-guard',
-    inject: () => ({ scope }),
+    inject: () => ({ scope: currentScope() }),
   }, SessionGuardCard))
 }
 
@@ -155,56 +171,97 @@ export function apply(ctx: ClientCtx) {
     locale: 'session-guard',
   }, StatusBadge)))
 
-  // 双代腰：scope 就绪后按代挂载（每条宿主线恰好一代服务）。
+  // ── 配置卡三面（M4 P0 重构：注册提到 apply 顶层）────────────────────
+  // 旧形态把注册关在 onScope 回调里——≤0.1.5 settingsScope 死路/0.1.0-0.1.1
+  // 无服务 → 回调永不触发 → 三面永不注册、桥无消费者（perm-gate client/
+  // index.ts L160-165 注释点名的反例）。现注册无条件执行，数据经 currentScope()
+  // 现取：原生句柄解到即原生，否则桥兜底。
+  safe('config-cards/family-tab', () => mountConfigCards(ctx))
+  // 老设置页(≤0.1.5)插件列表配置卡（settings.plugin.item）已于 2026-10-08
+  // 撤除（family-insection 第二轮）：与会话守护门禁家族 tab 重复——家族 tab
+  // 是唯一设置面（TL/free-search/browser-cdp/preset-manager 同批撤各自 item 卡）。
+
+  // 双代腰 = 纯数据臂，**按代分流**（2026-10-08 深夜五格实测裁决，findings「实测裁决」节）：
+  // - configForms（0.1.7+）：句柄写读皆活 → 入 scopeRef（原生优先，桥自动让位）。
+  // - settingsScope（0.1.2/0.1.5）：句柄**写活读死**——set() 落盘持久化，但
+  //   getSnapshot().value 恒 undefined（卡渲染默认值，磁盘是真值）。留空
+  //   scopeRef → currentScope() 落桥：桥 mutate 同样落宿主服务（写行为等价），
+  //   describe 读到持久化真值（读路径痊愈）。0.1.0/0.1.1 无 client 服务，
+  //   同样落桥。
   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 }),
-    )))
+    if (generation === 'configForms') scopeRef.scope = scope
   })
 
-  // 家族节宿主选举：仅 configForms 代（0.1.7+；族面容器 thinking-levels 也只在
-  // 该代）。≤0.1.5 的设置壳不渲染 children 子槽，自起只会得到空节（实测），
-  // 故经 configForms 服务探测把选举门在该代之外。宽限期后若 settings.section
-  // 里没有 id `dsh-family` 的条目，则按同一 id 接管；与 session-steward 的
-  // 并发竞争由 ui-slots 同 id 重复注册抛错仲裁，先到者胜。
+  // 家族节接管（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', () => {
-    setTimeout(() => {
-      if (ctx.slots.entries('settings.section').some(e => e.options.id === FAMILY_SECTION_ID)) return
-      ctx.inject(['configForms'], () => {
-        if (ctx.slots.entries('settings.section').some(e => e.options.id === FAMILY_SECTION_ID)) return
+    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({
-            name: 'settings.section',
-            id: FAMILY_SECTION_ID,
-            order: 40,
-            label: () => '起子插件设置',
-            inject: () => makeGuardFamilyTabsHooks(ctx.slots),
+            ...base,
             children: { [FAMILY_CHILD_KEY]: { kind: 'list', scope: 'root' } },
           }, GuardFamilySection)
-        } catch {
-          // 并发接管竞争落败（或设置壳未声明席位）：胜出方的节服务整个家族。
+          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_HOST_GRACE_MS)
+      }, 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 同形）。 */
 function makeGuardFamilyTabsHooks(slots: SlotsFace): {
   getSnapshot: () => readonly FamilyTabEntry[]

package/src/client/settings-bridge.ts

@@ -0,0 +1,202 @@
+/**
+ * BridgeDocHandle — 设置卡双轨数据源的桥轨（M4/T20-b）。
+ *
+ * ≤0.1.5（settingsScope fiber 永不解 / 0.1.0-0.1.1 无 client 服务）时，
+ * 配置卡经本句柄走自家 webServer 桥（describe/mutate）读写宿主 settings 服务。
+ * 与原生 SettingsScope（scope-face.ts）同构：getSnapshot/subscribe/set/unset。
+ * 读 = POST /api/<ns>/settings/describe；写 = POST …/mutate（ops 转发宿主服务），
+ * 成功即用回填描述符刷新快照并通知订阅者（无本地第二份状态——权威值始终在宿主）。
+ *
+ * 与 perm-gate src/client/bridge-scope.ts（T13b/T20-b 泛化模板）的差异：
+ * ① 快照形状对齐本仓 SettingsScope（status: loading/ready/unavailable + mode）；
+ * ② describe 未就绪（settings-unavailable/ns-not-registered）时有限重试
+ *    （宿主 settings 服务解析晚于卡挂载的窗口），重试耗尽才落 'unavailable'。
+ */
+
+/** 与 server 侧 settingsBridgeRoutesFor（src/settings-bridge.js）必须逐字符一致。 */
+function settingsBridgeRoutesFor(ns: string): { describe: string; mutate: string } {
+  return { describe: `/api/${ns}/settings/describe`, mutate: `/api/${ns}/settings/mutate` }
+}
+
+interface Snapshot<T> {
+  status: 'loading' | 'ready' | 'unavailable'
+  value: T | undefined
+  revision: number | undefined
+  writable: boolean
+  base: unknown
+  user: unknown
+  mode: 'bridge'
+}
+
+interface Descriptor {
+  value?: unknown
+  revision?: number
+  [k: string]: unknown
+}
+
+interface BridgeBody {
+  ok?: boolean
+  code?: string
+  message?: string
+  value?: { descriptor?: Descriptor; writable?: boolean }
+}
+
+interface MutateOp {
+  op: 'set' | 'unset'
+  path: string[]
+  value?: unknown
+}
+
+/**
+ * ≤0.1.5 宿主 describe 的 descriptor.value 是「每字段 → {}」骨架（0.1.0/0.1.5
+ * 实测：value={enabled:{},…,officialProviders:{}}，真值拆在 base（合并默认层）
+ * 与 user（用户层））——直接吞 value 会让卡拿到 officialProviders={}，
+ * `?? []` 不兜底（{} 非 nullish）→ ListRow values.join 崩，整族 tab 槽殉葬。
+ * 判特征：对象且每个自有值都是空 plain 对象（guard 字段是标量/数组，不会全空）。
+ * 命中即以 {...base, ...user} 重组有效值（guard 配置全是顶层标量/数组，浅合并即语义）。
+ */
+function isFieldSkeleton(v: unknown): v is Record<string, Record<string, never>> {
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false
+  const values = Object.values(v as Record<string, unknown>)
+  return values.length > 0
+    && values.every((x) => x !== null && typeof x === 'object' && !Array.isArray(x) && Object.keys(x as object).length === 0)
+}
+
+function plainObject(v: unknown): Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) ? { ...(v as Record<string, unknown>) } : {}
+}
+
+/** descriptor → 卡面可用 plain 值：正常代际用 value；骨架代际用 base+user 浅合并。 */
+function descriptorPlainValue(d: Descriptor): unknown {
+  if (!isFieldSkeleton(d.value)) return d.value
+  return { ...plainObject(d.base), ...plainObject(d.user) }
+}
+
+/** describe 不可就绪码：宿主 settings 未解析/未注册——值得重试的瞬态。 */
+const RETRYABLE_CODES = new Set(['settings-unavailable', 'ns-not-registered'])
+const RETRY_DELAY_MS = 1500
+const RETRY_MAX = 4
+
+export class BridgeDocHandle<T> {
+  private snapshot: Snapshot<T>
+  private listeners = new Set<() => void>()
+  private revision: number | undefined
+  private retriesLeft = RETRY_MAX
+  private inflight: Promise<void> | undefined
+  private readonly ns: string
+  private readonly routes: { describe: string; mutate: string }
+
+  constructor(ns: string) {
+    this.ns = ns
+    this.routes = settingsBridgeRoutesFor(ns)
+    this.snapshot = {
+      status: 'loading',
+      value: undefined,
+      revision: undefined,
+      writable: true,
+      base: undefined,
+      user: undefined,
+      mode: 'bridge',
+    }
+    void this.refresh()
+  }
+
+  getSnapshot(): Snapshot<T> {
+    return this.snapshot
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  async set(field: string, value: unknown): Promise<boolean> {
+    return this.mutate([{ op: 'set', path: [field], value }])
+  }
+
+  async unset(field: string): Promise<boolean> {
+    return this.mutate([{ op: 'unset', path: [field] }])
+  }
+
+  private notify(): void {
+    for (const l of [...this.listeners]) l()
+  }
+
+  private applyDescriptor(d: Descriptor, writable: boolean): void {
+    this.revision = typeof d.revision === 'number' ? d.revision : undefined
+    this.snapshot = {
+      status: 'ready',
+      value: descriptorPlainValue(d) as T | undefined,
+      revision: this.revision,
+      writable,
+      base: undefined,
+      user: undefined,
+      mode: 'bridge',
+    }
+  }
+
+  private async request(path: string, body?: unknown): Promise<BridgeBody> {
+    const response = await fetch(path, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body ?? {}),
+    })
+    if (!response.ok) throw new Error(`bridge ${path} HTTP ${response.status}`)
+    return (await response.json()) as BridgeBody
+  }
+
+  /** describe 拉取；瞬态未就绪码在重试预算内延迟重拉，耗尽才落 unavailable。 */
+  refresh(): Promise<void> {
+    if (this.inflight !== undefined) return this.inflight
+    this.inflight = (async () => {
+      try {
+        const body = await this.request(this.routes.describe)
+        if (body.ok && body.value?.descriptor !== undefined) {
+          this.retriesLeft = RETRY_MAX
+          this.applyDescriptor(body.value.descriptor, body.value.writable !== false)
+        } else if (body.code !== undefined && RETRYABLE_CODES.has(body.code) && this.retriesLeft > 0) {
+          this.retriesLeft -= 1
+          this.inflight = undefined
+          setTimeout(() => {
+            void this.refresh()
+          }, RETRY_DELAY_MS)
+          return
+        } else {
+          this.snapshot = { ...this.snapshot, status: 'unavailable', writable: false }
+        }
+      } catch {
+        // 网络异常：按瞬态处理，预算内重试
+        if (this.retriesLeft > 0) {
+          this.retriesLeft -= 1
+          this.inflight = undefined
+          setTimeout(() => {
+            void this.refresh()
+          }, RETRY_DELAY_MS)
+          return
+        }
+        this.snapshot = { ...this.snapshot, status: 'unavailable', writable: false }
+      }
+      // 重试路径已在上面清过 inflight（setTimeout 后由 refresh() 重建）；
+      // 终态路径在此清挂起标记并广播。重试等待期 notify 无害（快照未变）。
+      this.inflight = undefined
+      this.notify()
+    })()
+    return this.inflight
+  }
+
+  private async mutate(ops: MutateOp[]): Promise<boolean> {
+    const body = await this.request(this.routes.mutate, { ops, expectedRevision: this.revision })
+    if (body.ok && body.value?.descriptor !== undefined) {
+      this.applyDescriptor(body.value.descriptor, this.snapshot.writable)
+      this.notify()
+      return true
+    }
+    if (body.code === 'settings-conflict') {
+      await this.refresh() // 乐观并发失败：拉权威值，让下次写入带新 revision
+      return false
+    }
+    throw new Error(`bridge mutate failed: ${body.code ?? 'unknown'} ${body.message ?? ''}`)
+  }
+}

package/src/client/settings-card.tsx

@@ -223,6 +223,12 @@ function SelectRow<T extends string>(props: {
   )
 }
 
+/** 卡面字段消毒：宿主 describe 形态异常（≤0.1.5 骨架残留等）时槽崩会殉葬全族
+ * tab——ListRow 的 values 非 nullish 非数组（如 {}）会让 `?? []` 失守，逐卡硬护栏。 */
+function toList(v: unknown): string[] {
+  return Array.isArray(v) ? v.map(String) : []
+}
+
 /** 插件配置卡片主体：可展开的 <li> + header 按钮 + pill switch 字段体。 */
 export function SessionGuardCard({ scope }: SettingsCardProps): JSX.Element {
   const snapshot = useSyncExternalStore(
@@ -303,7 +309,7 @@ export function SessionGuardCard({ scope }: SettingsCardProps): JSX.Element {
               <ListRow
                 label="追加官方 provider id"
                 description="精确匹配，优先级最高（逗号分隔）"
-                values={value.officialProviders ?? []}
+                values={toList(value.officialProviders)}
                 placeholder="deepseek-official"
                 disabled={readonly}
                 onCommit={(next) => { void scope.set('officialProviders', next) }}
@@ -311,7 +317,7 @@ export function SessionGuardCard({ scope }: SettingsCardProps): JSX.Element {
               <ListRow
                 label="官方端点名单"
                 description="baseURL 归一化后的 host（逗号分隔）"
-                values={value.officialBaseURLs ?? []}
+                values={toList(value.officialBaseURLs)}
                 placeholder="api.deepseek.com"
                 disabled={readonly}
                 onCommit={(next) => { void scope.set('officialBaseURLs', next) }}
@@ -319,7 +325,7 @@ export function SessionGuardCard({ scope }: SettingsCardProps): JSX.Element {
               <SelectRow<'hold' | 'error'>
                 label="拦截方式"
                 description="挂起等待不报错；或报错并记入延后队列"
-                value={value.deferredMode ?? 'hold'}
+                value={value.deferredMode === 'error' ? 'error' : 'hold'}
                 options={[
                   { value: 'hold', label: '挂起等待（退峰自动放行）' },
                   { value: 'error', label: '报错并延后（退峰续跑）' },

package/src/index.js

@@ -24,6 +24,7 @@ import { detectTaskControl } from './detect.js'
 import { makeIsRoot } from './request-guard.js'
 import { createWiring } from './wiring.js'
 import { NS, DEFAULT_SETTINGS, SettingsSchema } from './settings.js'
+import { registerSettingsBridgeRoutes } from './settings-bridge.js'
 
 // 0.1.7：声明式设置 —— volatile 字段即自动表单。
 export const Config = SettingsSchema
@@ -66,10 +67,13 @@ export function apply(ctx, config = {}) {
   // 否则 client 配置卡报「设置命名空间不可用」。两条 legacy 路径按服务能力
   // 自动分派:0.1.2/0.1.5 = 服务实例 installSection;0.1.0/0.1.1 = 模块级
   // installSettingsSection + settingsNamespace。fail-open:失败仅告警。
+  /** 宿主 settings 服务活引用（桥的惰性 getter 用；apply 期注入解到即填）。 */
+  let settingsSvcRef
   try {
     ctx.inject(['settings'], (sctx) => {
       const service = sctx.settings
       if (service === undefined || service === null) return
+      settingsSvcRef = service
       const hooks = {
         setSource: (source) => {
           configSource = typeof source === 'function' ? source() : source
@@ -460,4 +464,16 @@ export function apply(ctx, config = {}) {
       }
     }, 'session-guard: routes')
   }
+
+  // ── settings webServer 桥（M4/T20-b 泛化）：describe/mutate 两端点 ──────
+  // 双轨数据源的桥轨：≤0.1.5（settingsScope 死路/无服务）时 client
+  // BridgeDocHandle 经此读写宿主 settings 服务。getSettingsSvc 惰性取
+  // （cordis ctx.get 永不 throw）——宿主 settings 解析早晚不影响注册。
+  // 置于 prefix 路由之后（routes[0] = /session-guard 前缀，契约与测试锚定）。
+  // fail-open：注册失败 error 告警（对齐 L474 风格），不炸插件加载。
+  try {
+    registerSettingsBridgeRoutes(ctx.webServer, () => settingsSvcRef, NS)
+  } catch (error) {
+    ctx.logger?.error?.(`[session-guard] settings bridge registration failed: ${String(error && error.message || error)}`)
+  }
 }

package/src/settings-bridge.js

@@ -0,0 +1,141 @@
+/**
+ * dsh-session-guard — settings webServer 桥（M4/T20-b 泛化）。
+ *
+ * 设置卡双轨数据源的桥轨：≤0.1.5（settingsScope fiber 永不解 / 0.1.0-0.1.1 无
+ * client 服务）时，client BridgeDocHandle 经 describe/mutate 两端点读写宿主
+ * settings 服务。桥只是 HTTP 皮：读 = svc.describe 取自家 ns 描述符；写 =
+ * svc.mutate 转 ops 落宿主服务（不落第二份状态）；mutate 成功即 describe 回填，
+ * 带 expectedRevision 乐观并发。守卫：POST-only + redactSecrets + 256KB。
+ * 语义与 perm-gate src/bridge.ts（5260fe6 泛化）逐字对齐，本仓为 JS 形态。
+ */
+
+/** 一个 settings ns 的桥路由对——client 侧（src/client/settings-bridge.ts）必须同式派生（测试钉死一致）。 */
+function settingsBridgeRoutesFor(ns) {
+  return { describe: `/api/${ns}/settings/describe`, mutate: `/api/${ns}/settings/mutate` }
+}
+
+function readJsonBody(req, limit = 256 * 1024) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (chunk) => {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      size += buf.length
+      if (size > limit) {
+        reject(new Error('bridge body too large'))
+        if (typeof req.resume === 'function') req.resume()
+        return
+      }
+      chunks.push(buf)
+    })
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf8')
+      if (raw === '') {
+        resolve({})
+        return
+      }
+      try {
+        resolve(JSON.parse(raw))
+      } catch (e) {
+        reject(e instanceof Error ? e : new Error(String(e)))
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+function sendJson(res, code, body) {
+  res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
+  res.end(JSON.stringify(body))
+}
+
+function isConflict(e) {
+  return e instanceof Error && /conflict|revision/i.test(e.message)
+}
+
+function describeNs(svc, ns) {
+  return svc.describe({ redactSecrets: true }).find((d) => d.ns === ns)
+}
+
+/**
+ * 注册 describe/mutate 两端点（kind:'exact'）。
+ * @param {unknown} server 宿主 webServer 服务（须有 register(kind,path,handler)）
+ * @param {() => unknown} getSettingsSvc 惰性取宿主 settings 服务（cordis ctx.get 永不 throw，可安全常取）
+ * @param {string} ns 自家 settings 命名空间
+ * @returns {Array<() => void>} 注销函数数组
+ */
+export function registerSettingsBridgeRoutes(server, getSettingsSvc, ns) {
+  if (typeof server !== 'object' || server === null) return []
+  const ws = typeof server.register === 'function' ? server : undefined
+  if (ws === undefined) return []
+  const offs = []
+  const routes = settingsBridgeRoutesFor(ns)
+
+  offs.push(ws.register({
+    kind: 'exact',
+    path: routes.describe,
+    handler: (req, res) => {
+      if (req.method !== 'POST') {
+        sendJson(res, 405, { ok: false, code: 'method-not-allowed' })
+        return
+      }
+      const svc = getSettingsSvc()
+      if (svc === undefined || svc === null || typeof svc.describe !== 'function') {
+        sendJson(res, 200, { ok: false, code: 'settings-unavailable', message: 'settings service not resolved yet' })
+        return
+      }
+      try {
+        const descriptor = describeNs(svc, ns)
+        if (descriptor === undefined) {
+          sendJson(res, 200, { ok: false, code: 'ns-not-registered', message: `settings namespace "${ns}" is not registered` })
+          return
+        }
+        sendJson(res, 200, { ok: true, value: { descriptor, writable: svc.writable !== false } })
+      } catch (e) {
+        sendJson(res, 200, { ok: false, code: 'internal', message: e instanceof Error ? e.message : String(e) })
+      }
+    },
+  }))
+
+  offs.push(ws.register({
+    kind: 'exact',
+    path: routes.mutate,
+    handler: (req, res) => {
+      if (req.method !== 'POST') {
+        sendJson(res, 405, { ok: false, code: 'method-not-allowed' })
+        return
+      }
+      const svc = getSettingsSvc()
+      if (svc === undefined || svc === null || typeof svc.mutate !== 'function') {
+        sendJson(res, 200, { ok: false, code: 'settings-unavailable', message: 'settings service mutate not available' })
+        return
+      }
+      readJsonBody(req).then((body) => {
+        const ops = body.ops
+        const valid = Array.isArray(ops) && ops.every((op) => op !== null && typeof op === 'object' && (op.op === 'set' || op.op === 'unset'))
+        if (!valid) {
+          sendJson(res, 200, { ok: false, code: 'settings-rejected', message: 'malformed bridge mutate ops' })
+          return
+        }
+        const expectedRevision = typeof body.expectedRevision === 'number' ? body.expectedRevision : undefined
+        svc.mutate(ns, ops, expectedRevision).then(() => {
+          // mutate 成功即 describe 回填（写路径归口宿主服务，无第二份状态）
+          const descriptor = describeNs(svc, ns)
+          if (descriptor === undefined) {
+            sendJson(res, 200, { ok: false, code: 'internal', message: `namespace "${ns}" disposed after mutate` })
+            return
+          }
+          sendJson(res, 200, { ok: true, value: { descriptor } })
+        }).catch((e) => {
+          sendJson(res, 200, isConflict(e)
+            ? { ok: false, code: 'settings-conflict', message: e instanceof Error ? e.message : String(e) }
+            : { ok: false, code: 'internal', message: e instanceof Error ? e.message : String(e) })
+        })
+      }).catch((e) => {
+        sendJson(res, 200, { ok: false, code: 'bad-request', message: e instanceof Error ? e.message : String(e) })
+      })
+    },
+  }))
+
+  return offs
+}