Merge remote-tracking branch 'origin/master' into fix/continuable-subagent-policy-inheritance

2026-08-10 19:40:14 +08:00
parent 8ebf02e0ac 243ed09aaf
commit 9e40fc7f6b
158 changed files with 2478 additions and 530 deletions
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -536,7 +536,7 @@ describe('background execution through the task runtime', () => {

    const result = await call(ctx, 'bash', { command: 'sleep 60', description: 'test command', run_in_background: true })
    expect(result.isError).toBe(true)
-    expect(text(result)).toContain('no control surface is attached')
+    expect(text(result)).toContain('no control surface serves this agent')
    // Declare-then-execute: the failed preflight means no process ever ran.
    expect((ctx.bash as CountingStartExecutor).starts).toBe(0)
  })
--- a/packages/bash/tool-pwsh/tests/tools.spec.ts
+++ b/packages/bash/tool-pwsh/tests/tools.spec.ts
@@ -777,7 +777,7 @@ describe('background execution through the task runtime', () => {

    const result = await call(ctx, 'pwsh', { command: 'Start-Sleep -Seconds 60', description: 'test command', run_in_background: true })
    expect(result.isError).toBe(true)
-    expect(text(result)).toContain('no control surface is attached')
+    expect(text(result)).toContain('no control surface serves this agent')
    // Declare-then-execute: the failed preflight means no process ever ran.
    expect(bash.startCalls).toBe(0)
  })
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -218,10 +218,17 @@
 - id: tool-bash
  disabled: true

- id: tool-tasks
-  disabled: true
+# The background-task REGISTRY stays on the host plane; only the model-facing
+# `task_*` controls move. Its producers — `tool-bash` here, `tool-pty` and a
+# non-continuable `tool-subagent` elsewhere — are preset rows that resolve it
+# with `ctx.get`, and an entry-local realm around the registry is invisible to
+# every sibling row outside that realm, so `run_in_background` answered
+# "background tasks unavailable" while the controls sat in the catalog. That is
+# the `goals` criterion read from inside the preset: a Service a row outside its
+# realm READS belongs to the plane both can see. The registry is keyed by owning
+# agent, so one host instance serves every session exactly as before presets.

- id: tasks
+- id: tool-tasks
  disabled: true

 - id: tool-fs
--- a/packages/client/locale/README.i18n.yaml
+++ b/packages/client/locale/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/locale/README.md
-README.md: f1efefde4557e1c29c0556f8b670f1534430ab79
-README.zh.md: a8b5704d28ea121e668cbd500dd3d217d4f96291
+README.md: 5bea46cd4e3ace61bd2251610abdf0812ded9604
+README.zh.md: 2333bc7c2b2f5918c35286064c50131153ee8711
--- a/packages/client/locale/README.md
+++ b/packages/client/locale/README.md
@@ -2,7 +2,7 @@

 English | [中文](README.zh.md)

-Locale plugin: LocaleService — the browser locale preference (`zh`/`en`, persisted under `dsh.locale`; with nothing persisted a fresh browser opens in the language `navigator` asks for — matched on the primary subtag, `zh` when it asks for none this app ships; `locale/change` fires on switches only) plus the ns×locale dictionary registry (typed `register(ns, {zh, en})` checked against `LocaleNamespaceMap`, `bind(ns)`→`TranslateNS<ns>`; lookup chain ns → common → zh → key). The service implements the slot system's `LocaleFace` and installs itself through `ctx.slots.installLocale`, backing the framework-injected `t` standard seat (`Translate`/`TranslateNS` are ui-slots types; import them from there — this package only re-exports for dictionary owners' convenience).
+Locale plugin: LocaleService — the `zh`/`en` preference stored as `locale.preference` in `$DSH_HOME/settings.yaml`; when that explicit Host value is absent, a fresh browser starts provisionally in the language `navigator` asks for (primary-subtag matching, with `zh` when it asks for no language this app ships). The Host read runs after plugin activation so an unavailable settings service cannot block the page; its result replaces the provisional browser value live. Remote browsers retain only a process-local selection because the settings API is loopback-only. `locale/change` fires on switches. The service also owns the ns×locale dictionary registry (typed `register(ns, {zh, en})` checked against `LocaleNamespaceMap`, `bind(ns)`→`TranslateNS<ns>`; lookup chain ns → common → zh → key), implements the slot system's `LocaleFace`, and installs itself through `ctx.slots.installLocale`, backing the framework-injected `t` standard seat (`Translate`/`TranslateNS` are ui-slots types; import them from there — this package only re-exports for dictionary owners' convenience). The [Host-backed preferences decision](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md) owns the persistence boundary.

 ## Model Experience

--- a/packages/client/locale/README.zh.md
+++ b/packages/client/locale/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-locale 插件：LocaleService——浏览器 locale 偏好（`zh`／`en`，以 `dsh.locale` 持久化；未持久化偏好时，全新浏览器以 `navigator` 请求的语言开场——按主子标签匹配，若其请求的语言本应用都不提供则为 `zh`；`locale/change` 仅在切换语言时触发），加上 ns×locale 字典注册表（类型化 `register(ns, {zh, en})` 按 `LocaleNamespaceMap` 校验，`bind(ns)`→`TranslateNS<ns>`；查找链 ns → common → zh → key）。该服务实现 slot 系统的 `LocaleFace` 并经 `ctx.slots.installLocale` 自行安装，支撑框架注入的 `t` 标准席位（`Translate`／`TranslateNS` 是 ui-slots 的类型；请从那里导入——本包的再导出仅为字典所有者提供便利）。
+locale 插件：LocaleService——`zh`／`en` 偏好以 `locale.preference` 存储在 `$DSH_HOME/settings.yaml` 中；若没有显式 Host 值，全新浏览器会暂时使用 `navigator` 请求的语言（按主子标签匹配；若其请求的语言本应用都不提供，则使用 `zh`）。Host 读取在插件激活后执行，因此 settings 服务不可用不会阻塞页面；读取结果会实时替换浏览器暂定值。settings API 仅限回环请求，因此远程浏览器的选择仅保留在进程内。`locale/change` 仅在切换语言时触发。该服务还拥有 ns×locale 字典注册表（类型化 `register(ns, {zh, en})` 按 `LocaleNamespaceMap` 校验，`bind(ns)`→`TranslateNS<ns>`；查找链 ns → common → zh → key），实现 slot 系统的 `LocaleFace`，并经 `ctx.slots.installLocale` 自行安装，支撑框架注入的 `t` 标准席位（`Translate`／`TranslateNS` 是 ui-slots 的类型；请从那里导入——本包的再导出仅为字典所有者提供便利）。该持久化边界由[Host settings 支撑的偏好决策](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md)拥有。

 ## 模型体验

--- a/packages/client/locale/package.json
+++ b/packages/client/locale/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@deepseek-ai/dsh-client-locale",
-  "description": "Locale plugin: LocaleService (zh/en preference with getter/setter/change event + persistence; ns x locale dictionaries, bind(ns) -> t); registers the Language settings row",
+  "description": "Locale plugin: Host-backed zh/en preference, browser-derived fallback, locale snapshots, and typed namespace dictionaries",
  "version": "0.0.1",
  "private": true,
  "type": "module",
@@ -24,6 +24,7 @@
  },
  "dshClient": {
    "inject": [
+      "@deepseek-ai/dsh-client-connection",
      "@deepseek-ai/dsh-client-runtime"
    ],
    "platform": "web",
@@ -31,6 +32,7 @@
  },
  "license": "BSD-3-Clause",
  "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1",
@@ -47,6 +49,10 @@
    "cordis": "^4.0.0-rc.7",
    "react": "^18.2.0"
  },
+  "dependencies": {
+    "@deepseek-ai/dsh-settings": "workspace:^",
+    "schemastery": "^3.18.0"
+  },
  "files": [
    "lib/index.js",
    "lib/invariant.js",
--- a/packages/client/locale/src/client/index.ts
+++ b/packages/client/locale/src/client/index.ts
@@ -13,7 +13,12 @@ import type { Context } from 'cordis'
 import {
  type BoundActions, type LocaleDictOf, type LocaleNamespaceMap, type Translate, type TranslateNS,
 } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  bindSettingsScope, type ClientContext, type SettingsScope,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, type LocaleId, type LocaleSettings,
+} from '../locale-settings.ts'
 import { en, zh, type CommonKey } from '../locales/index.ts'
 import {
  en as settingsEn, zh as settingsZh, type SettingsLocaleKey,
@@ -26,6 +31,7 @@ export type { LanguageRowComponentProps, LanguageRowInjected } from './LanguageR
 export type { LanguageOptionRow, LanguageRowState } from './settings-store.ts'
 export type { SettingsGeneralItemOwnerProps } from './settings-contract.ts'
 export type { CommonKey } from '../locales/index.ts'
+export type { LocaleId, LocaleSettings } from '../locale-settings.ts'

 // The translate currency lives in ui-slots (the render machinery synthesizes
 // the seat); re-exported here so dictionary owners import one package.
@@ -44,9 +50,6 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 /** Locale dictionary: flat key to template string ({name} placeholders). */
 export type LocaleDict = Record<string, string>

-/** Locale identifier: the two shipped locales. */
-export type LocaleId = 'zh' | 'en'
-
 /** One selectable locale: id plus its self-described display name. */
 export interface LocaleDefinition {
  /** Locale id (persisted; the setLocale argument). */
@@ -91,9 +94,6 @@ export const COMMON_NS = 'common'
 /** Namespace owning this feature's settings-row copy. */
 export const SETTINGS_NS = 'settings.locale'

-/** localStorage key holding the persisted locale id. */
-export const STORAGE_KEY = 'dsh.locale'
-
 /** The two shipped locales. */
 const LOCALES: readonly LocaleDefinition[] = Object.freeze([
  { id: 'zh', label: '中文' },
@@ -116,13 +116,25 @@ export class LocaleService {
  private snapshot: LocaleSnapshot
  private listeners = new Set<() => void>()
  private readonly ctx: Context
+  private readonly host: SettingsScope<LocaleSettings> | undefined
+  /** Browser-derived locale standing wherever no explicit Host selection does. */
+  private readonly provisional: LocaleId

  /**
-   * @param ctx - owning context (change events are emitted on it).
+   * @param ctx - owning context (change events are emitted on it; the scope
+   * listener is released through ctx.effect on dispose).
+   * @param host - durable preference scope owned by the providing plugin;
+   * absent compositions (standalone dictionary registries) stay process-local.
   */
-  constructor(ctx: Context) {
+  constructor(ctx: Context, host?: SettingsScope<LocaleSettings>) {
    this.ctx = ctx
-    this.snapshot = Object.freeze({ active: resolveInitialLocale(), locales: LOCALES, revision: 0 })
+    this.host = host
+    this.provisional = resolveInitialLocale()
+    this.snapshot = Object.freeze({ active: this.provisional, locales: LOCALES, revision: 0 })
+    if (host !== undefined) {
+      ctx.effect(() => host.subscribe(() => { this.adopt(host) }), 'locale: settings scope adoption')
+      this.adopt(host)
+    }
  }

  /**
@@ -155,16 +167,28 @@ export class LocaleService {
  }

  /**
-   * Switch the active locale — the only preference write entry. Persists the
-   * id and emits `locale/change`.
+   * Switch the active locale — the only user preference write entry.
   * @param id - a registered locale id; unknown ids throw.
   */
  setLocale(id: string): void {
    const match = this.snapshot.locales.find(l => l.id === id)
    if (match === undefined) throw new Error(`locale "${id}" is not registered`)
    if (this.snapshot.active === match.id) return
-    persistPreference(match.id)
    this.publish(match.id, true)
+    void this.host?.set(LOCALE_PREFERENCE_FIELD, match.id)
+  }
+
+  /**
+   * Adopt the scope's accepted durable selection without writing it back; an
+   * absent selection returns to the browser-derived locale.
+   * @param host - the constructor-narrowed scope driving this adoption.
+   */
+  private adopt(host: SettingsScope<LocaleSettings>): void {
+    const section = host.getSnapshot().value
+    if (section === undefined) return
+    const target = section.preference ?? this.provisional
+    if (this.snapshot.active === target) return
+    this.publish(target, true)
  }

  /**
@@ -288,27 +312,11 @@ export class LocaleService {
 }

 /**
- * The locale a fresh service opens with: an explicit preference the user
- * already chose wins over the browser's own language, which in turn wins over
- * {@link FALLBACK_LOCALE} (non-browser boots and browsers set to a language
- * this app does not ship).
+ * The browser's own language wins over {@link FALLBACK_LOCALE}; an explicit
+ * Host preference may replace this provisional value after plugin activation.
 */
 function resolveInitialLocale(): LocaleId {
-  return restorePreference() ?? detectBrowserLocale() ?? FALLBACK_LOCALE
-}
-
-/** Read the persisted locale id; unknown or unreadable values read as no preference. */
-function restorePreference(): LocaleId | undefined {
-  // Non-browser runs (node e2e booting the client tree) have no localStorage.
-  if (typeof localStorage === 'undefined') return undefined
-  try {
-    const stored = localStorage.getItem(STORAGE_KEY)
-    if (stored === 'zh' || stored === 'en') return stored
-  } catch {
-    // Storage access can throw (privacy mode); an unreadable store simply
-    // records no preference, and the browser language decides instead.
-  }
-  return undefined
+  return detectBrowserLocale() ?? FALLBACK_LOCALE
 }

 /**
@@ -325,8 +333,7 @@ function detectBrowserLocale(): LocaleId | undefined {
  /* oxlint-disable-next-line typescript/no-unnecessary-condition --
   * The DOM lib types `languages` as always present; embedders and older
   * WebViews ship a Navigator without it, and spreading undefined would
-   * throw at boot. Same environment-boundary distrust as the localStorage
-   * guards below. */
+   * throw at boot. */
  for (const tag of [...(navigator.languages ?? []), navigator.language]) {
    const primary = tag.toLowerCase().split('-')[0]
    const match = LOCALES.find(locale => locale.id === primary)
@@ -335,19 +342,8 @@ function detectBrowserLocale(): LocaleId | undefined {
  return undefined
 }

-/** Persist the locale id; storage failures are non-fatal (preference resets next boot). */
-function persistPreference(id: LocaleId): void {
-  if (typeof localStorage === 'undefined') return
-  try {
-    localStorage.setItem(STORAGE_KEY, id)
-  } catch {
-    // Storage access can throw (privacy mode / quota); the preference simply
-    // does not survive the session.
-  }
-}
-
-/** Required services: the slot registry (the feature registers its own settings row). */
-export const inject = ['slots']
+/** Required services: slot registration plus the settings transport. */
+export const inject = ['slots', 'connection']

 /**
 * Client plugin body: provide the locale service with base dictionaries and
@@ -356,7 +352,8 @@ export const inject = ['slots']
 * @param ctx - client cordis context.
 */
 export function apply(ctx: ClientContext): void {
-  const locale = new LocaleService(ctx)
+  const host = bindSettingsScope<LocaleSettings>(ctx, { namespace: LOCALE_SETTINGS_NAMESPACE })
+  const locale = new LocaleService(ctx, host)
  locale.register(COMMON_NS, { zh, en })
  locale.register(SETTINGS_NS, { zh: settingsZh, en: settingsEn })
  ctx.provide('locale', locale)
--- a/packages/client/locale/src/index.ts
+++ b/packages/client/locale/src/index.ts
@@ -1,4 +1,23 @@
-/** Host loader entry for the browser implementation exported from `./client`. */
+/** Host registration for the browser locale preference. */

-/** Host plugin body — no host-side behavior for the locale plugin. */
-export function apply(): void {}
+import type { Context } from 'cordis'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { LOCALE_SETTINGS_NAMESPACE, LocaleSettingsSchema } from './locale-settings.ts'
+
+export {
+  LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE,
+  type LocaleId, type LocaleSettings,
+} from './locale-settings.ts'
+
+/**
+ * Register the durable locale section when a settings provider exists.
+ * @param ctx - Host context whose optional settings service owns the section.
+ */
+export function apply(ctx: Context): void {
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.register(
+      settingsNamespace(LOCALE_SETTINGS_NAMESPACE),
+      LocaleSettingsSchema,
+    )
+  })
+}
--- a/packages/client/locale/src/locale-settings.ts
+++ b/packages/client/locale/src/locale-settings.ts
@@ -0,0 +1,26 @@
+/** Locale preference stored in the Host user-settings document. */
+
+import z from 'schemastery'
+
+/** Settings namespace owned by the locale plugin. */
+export const LOCALE_SETTINGS_NAMESPACE = 'locale'
+
+/** Field carrying an explicit locale selection; absence delegates to the browser. */
+export const LOCALE_PREFERENCE_FIELD = 'preference'
+
+/** Locale identifiers shipped by the browser client. */
+export const LOCALE_IDS = ['zh', 'en'] as const
+
+/** Shipped locale identifier. */
+export type LocaleId = typeof LOCALE_IDS[number]
+
+/** Durable locale section shared by the Host schema and the browser scope. */
+export interface LocaleSettings {
+  /** Explicit locale selection; absence delegates to the browser. */
+  preference?: LocaleId
+}
+
+/** Durable locale schema; also the wire envelope the browser scope validates against. */
+export const LocaleSettingsSchema: z<LocaleSettings> = z.object({
+  [LOCALE_PREFERENCE_FIELD]: z.union([...LOCALE_IDS]).required(false),
+})
--- a/packages/client/locale/tests/apply.spec.ts
+++ b/packages/client/locale/tests/apply.spec.ts
@@ -4,8 +4,11 @@
 import { Context } from 'cordis'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
-import { apply, inject, SETTINGS_NS } from '@deepseek-ai/dsh-client-locale/client'
+import {
+  apply, inject, SETTINGS_NS,
+} from '@deepseek-ai/dsh-client-locale/client'
 import type { LanguageRowInjected, LocaleService } from '@deepseek-ai/dsh-client-locale/client'
+import { LOCALE_SETTINGS_NAMESPACE, LocaleSettingsSchema } from '../src/locale-settings.ts'
 import { LanguageRow } from '../src/client/LanguageRow.tsx'
 import type { createLanguageRowStore } from '../src/client/settings-store.ts'

@@ -14,7 +17,36 @@ const SLOT = 'settings.general.item'
 async function bench() {
  const ctx = new Context()
  await ctx.plugin(SlotsService).await()
-  return { ctx, slots: ctx.get('slots') as SlotsService }
+  let preference: string | undefined
+  let revision = 0
+  const namespace = () => ({
+    ns: LOCALE_SETTINGS_NAMESPACE,
+    schema: LocaleSettingsSchema.toJSON(),
+    value: preference === undefined ? {} : { preference },
+    applies: 'live' as const,
+    secrets: [],
+    revision,
+  })
+  const describe = vi.fn(async () => ({
+    rpcId: 'locale-describe' as never,
+    result: {
+      ok: true as const,
+      value: { writable: true, hasDocument: true, namespaces: [namespace()] },
+    },
+  }))
+  const mutate = vi.fn(async (request: { ops: { value: string }[] }) => {
+    preference = request.ops[0]!.value
+    revision += 1
+    return {
+      rpcId: 'locale-mutate' as never,
+      result: { ok: true as const, value: namespace() },
+    }
+  })
+  ctx.provide('connection', { api: { settings: { describe, mutate } }, isLoopback: true } as never)
+  return {
+    ctx, slots: ctx.get('slots') as SlotsService, describe, mutate,
+    setHostPreference: (next: string | undefined) => { preference = next; revision += 1 },
+  }
 }

 /** Stand in for the settings shell: declare the General item slot from root. */
@@ -47,7 +79,7 @@ describe('locale apply', () => {
  })

  it('declares the slot service', () => {
-    expect(inject).toEqual(['slots'])
+    expect(inject).toEqual(['slots', 'connection'])
  })

  it('provides the service with base + settings dictionaries and registers the row (declaration before or after apply)', async () => {
@@ -91,6 +123,23 @@ describe('locale apply', () => {
    expect(locale.getLocale().active).toBe('zh')
    expect(instance.getSnapshot().active).toBe('zh')
    expect(locale.bind(SETTINGS_NS)('language.title')).toBe('语言')
+    await vi.waitFor(() => { expect(b.mutate).toHaveBeenCalledTimes(2) })
+  })
+
+  it('loads and refreshes the explicit Host preference after nonblocking activation', async () => {
+    const b = await bench()
+    b.setHostPreference('en')
+    declareItems(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const locale = b.ctx.get('locale') as LocaleService
+    await vi.waitFor(() => { expect(locale.getLocale().active).toBe('en') })
+    b.setHostPreference(undefined)
+    b.ctx.emit('settings/changed', LOCALE_SETTINGS_NAMESPACE)
+    await vi.waitFor(() => { expect(locale.getLocale().active).toBe('zh') })
+    b.setHostPreference('en')
+    b.ctx.emit('settings/changed', LOCALE_SETTINGS_NAMESPACE)
+    await vi.waitFor(() => { expect(locale.getLocale().active).toBe('en') })
+    expect(b.describe).toHaveBeenCalledTimes(3)
  })

  it('recovers after an HMR collapse of the declaring entry (stale disposer must not block)', async () => {
--- a/packages/client/locale/tests/host.spec.ts
+++ b/packages/client/locale/tests/host.spec.ts
@@ -0,0 +1,30 @@
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { Settings, settingsNamespace, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import {
+  LOCALE_SETTINGS_NAMESPACE, apply,
+} from '@deepseek-ai/dsh-client-locale'
+
+class MemorySettings extends Settings {
+  readonly writable = true
+  protected load(): Promise<Record<string, unknown>> { return Promise.resolve({}) }
+  protected persist(_ns: SettingsNamespace, _section: Record<string, unknown>): Promise<void> {
+    return Promise.resolve()
+  }
+}
+
+describe('locale host', () => {
+  it('registers an optional explicit locale preference with the Host settings lifecycle', async () => {
+    const ctx = new Context()
+    await ctx.plugin(MemorySettings).await()
+    const fiber = ctx.plugin({ apply })
+    await fiber.await()
+    const ns = settingsNamespace(LOCALE_SETTINGS_NAMESPACE)
+    expect(ctx.settings.get(ns)).toEqual({})
+    await ctx.settings.update(ns, { preference: 'en' })
+    expect(ctx.settings.get(ns)).toEqual({ preference: 'en' })
+    await expect(ctx.settings.update(ns, { preference: 'fr' })).rejects.toThrow()
+    await fiber.dispose()
+    expect(ctx.settings.describe().map(row => row.ns)).not.toContain(ns)
+  })
+})
--- a/packages/client/locale/tests/invariant.spec.ts
+++ b/packages/client/locale/tests/invariant.spec.ts
@@ -14,16 +14,16 @@ describe('invariant companion', () => {
    await expect(ctx.plugin(LocaleInvariant).await()).resolves.toBeDefined()
  })

-  it('node-half apply is a no-op host placeholder', () => {
-    nodeApply()
-    expect(true).toBe(true) // reaching here without throw is the contract
+  it('node-half apply tolerates a Host without settings', () => {
+    nodeApply(new Context())
  })

  it('client apply provides ctx.locale seeded with the zh/en common namespace', async () => {
    // The feature registers its own Language settings row, hence the slots edge.
-    expect(inject).toEqual(['slots'])
+    expect(inject).toEqual(['slots', 'connection'])
    const ctx = new Context()
    new SlotsService(ctx)
+    ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
    await ctx.plugin({ inject, apply: clientApply }).await()
    const locale = ctx.get('locale')
    expect(locale).toBeInstanceOf(LocaleService)
--- a/packages/client/locale/tests/locale.spec.ts
+++ b/packages/client/locale/tests/locale.spec.ts
@@ -1,14 +1,19 @@
 // @vitest-environment jsdom
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import type { LocaleSnapshot } from '@deepseek-ai/dsh-client-locale/client'
-import { LocaleService, STORAGE_KEY } from '@deepseek-ai/dsh-client-locale/client'
+import { stubSettingsScope, type StubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
+import type { LocaleSettings, LocaleSnapshot } from '@deepseek-ai/dsh-client-locale/client'
+import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'

-const make = (): { ctx: Context; svc: LocaleService; events: LocaleSnapshot[] } => {
+const make = (host?: StubSettingsScope<LocaleSettings>): {
+  ctx: Context
+  svc: LocaleService
+  events: LocaleSnapshot[]
+} => {
  const ctx = new Context()
  const events: LocaleSnapshot[] = []
  ctx.on('locale/change', (snapshot) => { events.push(snapshot) })
-  return { ctx, svc: new LocaleService(ctx), events }
+  return { ctx, svc: new LocaleService(ctx, host?.scope), events }
 }

 /**
@@ -24,7 +29,6 @@ const stubLanguages = (...tags: string[]): void => {

 describe('LocaleService', () => {
  beforeEach(() => {
-    localStorage.clear()
    // A Chinese browser is the baseline these specs assert their zh state on.
    stubLanguages('zh-CN')
  })
@@ -132,16 +136,25 @@ describe('LocaleService', () => {
    expect(svc.getSnapshot().revision).toBe(before + 1)
  })

-  it('setLocale persists, republishes an immutable snapshot, and no-ops on same value', () => {
-    const { svc, events } = make()
+  it('setLocale writes through the scope, republishes an immutable snapshot, and no-ops on same value', () => {
+    const host = stubSettingsScope<LocaleSettings>()
+    const { svc, events } = make(host)
    svc.setLocale('en')
    expect(svc.getLocale().active).toBe('en')
-    expect(localStorage.getItem(STORAGE_KEY)).toBe('en')
+    expect(host.set).toHaveBeenCalledWith('preference', 'en')
    expect(events).toHaveLength(1)
    expect(events[0]).toBe(svc.getLocale())
    expect(events[0]!.revision).toBe(1)
    svc.setLocale('en')
    expect(events).toHaveLength(1)
+    expect(host.set).toHaveBeenCalledOnce()
+  })
+
+  it('setLocale without a host scope stays process-local', () => {
+    const { svc, events } = make()
+    svc.setLocale('en')
+    expect(svc.getLocale().active).toBe('en')
+    expect(events).toHaveLength(1)
  })

  it('throws on unknown locale ids', () => {
@@ -149,14 +162,37 @@ describe('LocaleService', () => {
    expect(() => { svc.setLocale('fr') }).toThrow('not registered')
  })

-  it('restores a persisted locale over the browser language, and garbage reads as no preference', () => {
-    localStorage.setItem(STORAGE_KEY, 'en')
-    expect(make().svc.getLocale().active).toBe('en')
-    localStorage.setItem(STORAGE_KEY, 'fr')
-    expect(make().svc.getLocale().active).toBe('zh')
+  it('adopts a Host preference over the browser language without writing it back', () => {
+    const host = stubSettingsScope<LocaleSettings>()
+    const { svc, events } = make(host)
+    host.publish({ status: 'ready', value: { preference: 'en' }, revision: 1, writable: true })
+    expect(svc.getLocale().active).toBe('en')
+    expect(events).toHaveLength(1)
+    expect(host.set).not.toHaveBeenCalled()
+    host.publish({ value: { preference: 'en' }, revision: 2 })
+    expect(events).toHaveLength(1)
  })

-  it('opens in the browser language when nothing is persisted, matching regional variants on their primary subtag', () => {
+  it('an absent Host preference returns to the browser-derived locale', () => {
+    const host = stubSettingsScope<LocaleSettings>()
+    const { svc } = make(host)
+    host.publish({ status: 'ready', value: { preference: 'en' }, revision: 1, writable: true })
+    expect(svc.getLocale().active).toBe('en')
+    host.publish({ value: {}, revision: 2 })
+    expect(svc.getLocale().active).toBe('zh')
+  })
+
+  it('adopts a section already standing at construction and releases its subscription on dispose', async () => {
+    const host = stubSettingsScope<LocaleSettings>()
+    host.publish({ status: 'ready', value: { preference: 'en' }, revision: 1, writable: true })
+    const { ctx, svc } = make(host)
+    expect(svc.getLocale().active).toBe('en')
+    expect(host.listenerCount()).toBe(1)
+    await ctx.fiber.dispose()
+    expect(host.listenerCount()).toBe(0)
+  })
+
+  it('opens provisionally in the browser language, matching regional variants on their primary subtag', () => {
    stubLanguages('en-GB', 'zh-CN')
    expect(make().svc.getLocale().active).toBe('en')
    stubLanguages('zh-Hant-TW')
@@ -176,8 +212,7 @@ describe('LocaleService', () => {
    expect(make().svc.getLocale().active).toBe('zh')
  })

-  it('runs outside a browser (node boots): the fallback decides, the machine language does not, writes no-op', () => {
-    vi.stubGlobal('localStorage', undefined)
+  it('runs outside a browser (node boots): the fallback decides and the machine language does not', () => {
    vi.stubGlobal('window', undefined)
    // Node exposes its own global navigator; without a window it must not
    // reach the resolution at all.
@@ -188,12 +223,11 @@ describe('LocaleService', () => {
    expect(svc.getLocale().active).toBe('en')
  })

-  it('keeps the browser language out of the way once a preference exists', () => {
+  it('lets an explicit in-process preference replace the browser-derived value', () => {
    stubLanguages('en-US')
    const { svc } = make()
    svc.setLocale('zh')
-    expect(localStorage.getItem(STORAGE_KEY)).toBe('zh')
-    expect(make().svc.getLocale().active).toBe('zh')
+    expect(svc.getLocale().active).toBe('zh')
  })

  it('exposes the two shipped locales with self-described labels', () => {
--- a/packages/client/locale/tsconfig.json
+++ b/packages/client/locale/tsconfig.json
@@ -20,6 +20,9 @@
    {
      "path": "../../../vendor/cordis"
    },
+    {
+      "path": "../../settings/settings"
+    },
    {
      "path": "../../support/invariants"
    }
--- a/packages/client/runtime/README.i18n.yaml
+++ b/packages/client/runtime/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/runtime/README.md
-README.md: 753d1de796ba8ff20217d423555710429e9b7a75
-README.zh.md: 9b5b8ba7ce42875afd4b9b83b9c2f64e95298ca5
+README.md: 1ec6cc38aed1bebff6b6ecb40faee7ae3ba9e412
+README.zh.md: 6602152790a1d433371e27b274a4eb8c9e3cfcd8
--- a/packages/client/runtime/README.md
+++ b/packages/client/runtime/README.md
@@ -4,6 +4,8 @@ English | [中文](README.zh.md)

 Client cordis boot and React-free object services: SlotsService wraps SlotCore and supplies renderer data sources; SessionsService owns Session objects and the Chat-facing list, scope, and event-window state; SessionHistoryService lazily owns independent raw-history ledgers for inspection consumers, loading the current tail first and prepending one older page only when its consumer requests it. Each history snapshot exposes the raw window's absolute base sequence so a consumer detects a prepend even when the page adds no surface-visible node. WorkspacesService depends on SessionsService and owns Workspace objects, list/actions, default-target derivation, and the New Session blank-reuse entry (`connectWorkspace`). The runtime fans the shared Host stream into the Session, Workspace, and activated history owners without routing inspection state through Session or SessionManager, and bridges the registry-invalidation frames to typed ctx events (`commands/changed`, `session/preset-changed`, `settings/changed`, `credentials/changed`, `models/changed`) so surface caches refetch without touching the stream. `host/session-preset-changed` also folds its preset into the session row, because the switch's RPC echo reaches only the client that issued it. Client sessions are always Host-born (Session+Agent+cwd in one `session.create`); the client holds no pre-entity session state — a session's Agent scope (the client mirror of host dsh-scope, keyed by the shared agent/session id) is born when its row enters the list mirror and dies with the prune. Each `Session` holds a generic `ProjectionValueStore` seeded from the history-tail `projections` block and updated by `session/projection` frames under higher-seq-wins; domain keys (including `todos`) are read via `projections.faceOf` / `useProjection`, not via `ConversationSnapshot`. The store also publishes one reference-stable whole-value map through `SessionSummary.projectionValues`, allowing global list consumers to reuse the same projections without creating per-session subscriptions.

+`bindSettingsScope` is the browser mirror of the Host-side settings owner seam for one domain-owned namespace. It subscribes before starting a nonblocking initial read, publishes a uSES snapshot (status, section value, revision, writability, host/memory mode), serializes `set` writes with the latest known namespace revision, suppresses stale publications, recovers a rejected latest write from Host state, and reaches quiescence on plugin disposal. The default decoder validates each section against the namespace's own serialized wire schema (rehydrated through dsh-client-schema-form), so a domain adds a decoder only to narrow beyond that schema. Loopback pages use the Host settings API; remote pages stay in memory mode. Domain packages own the namespace schema, default, and live service rather than putting product policy in runtime.
+
 ## Slot declaration injection

 `ctx.slots.inject(name, callback)` makes a full `SlotMap` key the dependency for a contribution whose plugin can activate independently from the declaring entry. It runs `callback` synchronously when the declaration exists, otherwise waits; declaration collapse disposes the callback effect, and redeclaration reruns it. The controller belongs to the caller's plugin fiber, so unloading the contributor cancels either the wait or its active registrations. A direct `slots.register()` into an undeclared slot still throws.
--- a/packages/client/runtime/README.zh.md
+++ b/packages/client/runtime/README.zh.md
@@ -4,6 +4,8 @@

 客户端 cordis 启动与不依赖 React 的对象服务：SlotsService 包装 SlotCore 并提供 renderer 数据源；SessionsService 拥有 Session 对象以及 Chat 所需的列表、scope 和事件窗口状态；SessionHistoryService 为检查类消费方惰性拥有彼此独立的原始历史账本，先加载当前尾部，并仅在消费方请求时向前补入一页更早历史。每份历史快照都会公开原始窗口的绝对基准序号，因此即使该页没有新增任何 surface 可见节点，消费方仍能检测到向前补页。WorkspacesService 依赖 SessionsService，拥有 Workspace 对象、列表／操作、默认目标派生，以及 New Session 空会话复用入口（`connectWorkspace`）。运行时把共享 Host 流分发给 Session、Workspace 和已激活的历史数据所有者，不让检查状态经过 Session 或 SessionManager，并把注册表失效帧桥接为类型化 ctx 事件（`commands/changed`、`session/preset-changed`、`settings/changed`、`credentials/changed`、`models/changed`），使各表面缓存无需触碰流即可重拉。`host/session-preset-changed` 还会把其中的 preset 折进会话行，因为这次切换的 RPC 回执只会到达发起它的那个客户端。客户端会话一律由 Host 创建（一次 `session.create` 同时产生 Session、agent（智能体）和 cwd）；客户端不持有任何实体化之前的会话状态——agent scope（host dsh-scope 的客户端镜像，以 agent/session 共用 id 为键）在会话行进入列表镜像时创建，并随 prune 销毁。每个 `Session` 持有一个通用的 `ProjectionValueStore`，由历史记录尾部的 `projections` 块播种，并经 `session/projection` 帧按 seq 高者胜更新；领域键（含 `todos`）经 `projections.faceOf`／`useProjection` 读取，不经 `ConversationSnapshot`。该 store 还会通过 `SessionSummary.projectionValues` 发布一份引用稳定的完整值映射，使全局列表消费方无需为每个会话创建订阅，即可复用同一组投影。

+`bindSettingsScope` 面向单个由领域持有的 namespace，是 Host 侧 settings owner seam 的浏览器镜像。它在开始非阻塞初始读取前建立订阅，发布 uSES 快照（状态、分节值、revision、可写性、host／内存模式），使用已知最新 namespace revision 串行执行 `set` 写入，抑制陈旧发布，并在最新写入被拒时从 Host 状态恢复；插件释放时，它会达到完全停稳。默认解码器会对照该 namespace 自身的序列化 wire schema（经 dsh-client-schema-form 还原）校验每个分节，因此领域只有在需要比该 schema 进一步收窄时才添加解码器。回环页面使用 Host settings API，远程页面则停留在内存模式。namespace schema、默认值与实时服务归领域包所有，而非把产品政策放入运行时。
+
 ## Slot 声明注入

 `ctx.slots.inject(name, callback)` 将完整的 `SlotMap` key 作为贡献项的依赖，适用于贡献方插件可独立于声明条目激活的情形。声明存在时，它会同步运行 `callback`，否则等待；声明折叠会 dispose（资源释放）回调 effect，重新声明则会再次运行回调。控制器归调用方的插件 fiber 所有，因此卸载贡献方会取消等待或移除其活跃注册项。直接调用 `slots.register()` 向未声明 slot 注册仍会抛出异常。
--- a/packages/client/runtime/package.json
+++ b/packages/client/runtime/package.json
@@ -35,6 +35,7 @@
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-attachment": "workspace:^",
    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-schema-form": "workspace:^",
    "@deepseek-ai/dsh-commands": "workspace:^",
    "@deepseek-ai/dsh-compact": "workspace:^",
    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
@@ -61,7 +62,8 @@
    "@deepseek-ai/dsh-type-meta": "workspace:^",
    "@deepseek-ai/dsh-typert-registry": "workspace:^",
    "@types/react": "~18.3.1",
-    "cordis": "^4.0.0-rc.7"
+    "cordis": "^4.0.0-rc.7",
+    "schemastery": "^3.18.0"
  },
  "files": [
    "lib/index.js",
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -43,6 +43,8 @@ export type { SessionProvideChannelHost } from './sessions/provide.ts'
 export { createScope } from './agents/scope.ts'
 export type { AgentScopeHandle } from './agents/scope.ts'
 export { DirectoryBrowseError, WorkspaceCreateError, WorkspacesService } from './workspaces/service.ts'
+export { bindSettingsScope, SettingsScopeController } from './settings-scope.ts'
+export type { SettingsScope, SettingsScopeSnapshot, SettingsScopeSpec } from './settings-scope.ts'
 export { resolveWorkspacePath } from './workspaces/path.ts'
 export type { Session } from './sessions/session.ts'
 export type { ISession, ProjectionsFace, SessionFace } from './contract/session.ts'
--- a/packages/client/runtime/src/client/settings-scope.ts
+++ b/packages/client/runtime/src/client/settings-scope.ts
@@ -0,0 +1,261 @@
+/** Host-backed settings-namespace synchronization for browser plugins. */
+
+import type { Context } from 'cordis'
+import type {
+  ConnectionHandle, IApiClient, SettingsNamespaceView,
+} from '@deepseek-ai/dsh-client-connection/client'
+import { rehydrateSchema, validateDraft } from '@deepseek-ai/dsh-client-schema-form'
+import { createSnapshotStore, type SnapshotStore } from './contract/store.ts'
+
+/** Client-side sync state of one settings namespace. */
+export interface SettingsScopeSnapshot<T> {
+  /**
+   * `loading` until the first accepted section, `ready` while one stands, and
+   * `unavailable` when the namespace is not exposed to this client or the
+   * connection keeps preferences process-local (memory mode).
+   */
+  status: 'loading' | 'ready' | 'unavailable'
+  /** Last accepted schema-resolved section; undefined before the first acceptance. */
+  value: T | undefined
+  /** Namespace revision fencing the next write; undefined before the first Host view. */
+  revision: number | undefined
+  /** Whether the Host document accepts writes; memory mode never does. */
+  writable: boolean
+  /** `host` syncs with the Host document; `memory` keeps a remote browser process-local. */
+  mode: 'host' | 'memory'
+}
+
+/** Domain-owned description of one settings namespace consumed by a browser plugin. */
+export interface SettingsScopeSpec<T> {
+  /** Settings namespace registered by the owning Host plugin. */
+  namespace: string
+  /**
+   * Narrow one wire section; undefined keeps the last accepted value. The
+   * default validates the section against the namespace's own serialized wire
+   * schema, so domains add a decoder only to narrow beyond that schema.
+   */
+  decode?: (section: unknown) => T | undefined
+}
+
+/**
+ * Reactive owner handle over one namespace's durable section — the browser
+ * mirror of the Host-side `SettingsScope` owner seam. Domain services read
+ * and observe the snapshot and route explicit user choices through `set`.
+ */
+export interface SettingsScope<T> {
+  /** @returns the current sync snapshot (stable reference until the next change). */
+  getSnapshot(): SettingsScopeSnapshot<T>
+  /**
+   * Observe snapshot replacements.
+   * @param listener - invoked after each snapshot change.
+   * @returns the disposer removing this listener.
+   */
+  subscribe(listener: () => void): () => void
+  /**
+   * Queue one field write. Rapid writes preserve mutation order, each carries
+   * the latest known namespace revision, and only the latest settlement may
+   * publish; a rejected or failed latest write reloads Host state instead.
+   * @param field - scalar field inside the namespace section.
+   * @param value - JSON-shaped value selected by the user.
+   * @returns settlement after the write and any latest-write recovery read.
+   */
+  set(field: string, value: unknown): Promise<void>
+}
+
+type SettingsFace = Pick<IApiClient, 'settings'>
+
+/**
+ * Serializes one namespace's Host reads and writes behind a snapshot store.
+ * Reads never block plugin activation; writes carry the latest known
+ * namespace revision and teardown waits for the operation already crossing
+ * the wire.
+ */
+export class SettingsScopeController<T> implements SettingsScope<T> {
+  private readonly store: SnapshotStore<SettingsScopeSnapshot<T>>
+  private tail: Promise<void> = Promise.resolve()
+  private readGeneration = 0
+  private writeGeneration = 0
+  private disposed = false
+
+  /**
+   * @param api - settings wire face.
+   * @param spec - namespace identity and optional narrowing decoder.
+   * @param persistence - remote browsers remain process-local because settings RPCs are loopback-only.
+   */
+  constructor(
+    private readonly api: SettingsFace,
+    private readonly spec: SettingsScopeSpec<T>,
+    private readonly persistence: 'host' | 'memory' = 'host',
+  ) {
+    this.store = createSnapshotStore<SettingsScopeSnapshot<T>>({
+      status: persistence === 'host' ? 'loading' : 'unavailable',
+      value: undefined,
+      revision: undefined,
+      writable: false,
+      mode: persistence,
+    })
+  }
+
+  /** @returns the current sync snapshot (stable reference until the next change). */
+  getSnapshot(): SettingsScopeSnapshot<T> {
+    return this.store.getSnapshot()
+  }
+
+  /**
+   * Observe snapshot replacements.
+   * @param listener - invoked after each snapshot change.
+   * @returns the disposer removing this listener.
+   */
+  subscribe(listener: () => void): () => void {
+    return this.store.subscribe(listener)
+  }
+
+  /**
+   * Queue a Host refresh; a newer read or user write suppresses stale publication.
+   * @returns settlement after the queued read completes or is skipped.
+   */
+  load(): Promise<void> {
+    const generation = ++this.readGeneration
+    return this.enqueue(() => this.read(generation))
+  }
+
+  /**
+   * Queue one field write; see {@link SettingsScope.set} for the ordering,
+   * revision, and recovery contract.
+   * @param field - scalar field inside the namespace section.
+   * @param value - JSON-shaped value selected by the user.
+   * @returns settlement after the write and any latest-write recovery read.
+   */
+  set(field: string, value: unknown): Promise<void> {
+    this.readGeneration += 1
+    const generation = ++this.writeGeneration
+    return this.enqueue(async () => {
+      const revision = this.getSnapshot().revision
+      let response: Awaited<ReturnType<SettingsFace['settings']['mutate']>>
+      try {
+        response = await this.api.settings.mutate({
+          ns: this.spec.namespace,
+          ops: [{ op: 'set', path: [field], value }],
+          ...(revision === undefined ? {} : { expectedRevision: revision }),
+        })
+      } catch (_settingsWriteFailure) {
+        if (!this.disposed && generation === this.writeGeneration) await this.read(++this.readGeneration)
+        return
+      }
+      if (!response.result.ok) {
+        if (!this.disposed && generation === this.writeGeneration) await this.read(++this.readGeneration)
+        return
+      }
+      this.accept(response.result.value, generation === this.writeGeneration)
+    })
+  }
+
+  /**
+   * Stop queued operations and wait for the current wire call to settle.
+   * @returns settlement after the controller reaches quiescence.
+   */
+  async dispose(): Promise<void> {
+    this.disposed = true
+    this.readGeneration += 1
+    this.writeGeneration += 1
+    await this.tail
+  }
+
+  private enqueue(operation: () => Promise<void>): Promise<void> {
+    if (this.persistence === 'memory' || this.disposed) return Promise.resolve()
+    const task = this.tail.then(async () => {
+      if (this.disposed) return
+      await operation()
+    })
+    // The returned task carries its own settlement to the caller; the queue
+    // tail is kept fulfilled so one failed subscriber cannot strand later operations.
+    this.tail = task.catch(() => {})
+    return task
+  }
+
+  private async read(generation: number): Promise<void> {
+    let response: Awaited<ReturnType<SettingsFace['settings']['describe']>>
+    try {
+      response = await this.api.settings.describe({})
+    } catch (_settingsReadFailure) {
+      return
+    }
+    if (!response.result.ok || this.disposed) return
+    const { namespaces, writable } = response.result.value
+    const view = namespaces.find(candidate => candidate.ns === this.spec.namespace)
+    const publish = generation === this.readGeneration
+    if (view === undefined) {
+      if (publish) {
+        this.store.update((draft) => {
+          draft.status = 'unavailable'
+          draft.writable = writable
+        })
+      }
+      return
+    }
+    this.accept(view, publish, writable)
+  }
+
+  private accept(view: SettingsNamespaceView, publish: boolean, writable?: boolean): void {
+    const decoded = publish ? this.decode(view) : undefined
+    this.store.update((draft) => {
+      draft.revision = view.revision
+      if (writable !== undefined) draft.writable = writable
+      if (decoded === undefined) return
+      draft.status = 'ready'
+      draft.value = decoded
+    })
+  }
+
+  private decode(view: SettingsNamespaceView): T | undefined {
+    if (this.spec.decode !== undefined) return this.spec.decode(view.value)
+    // Sections are plain objects by construction; schemastery alone would
+    // resolve null or an array through object defaults instead of refusing.
+    if (typeof view.value !== 'object' || view.value === null || Array.isArray(view.value)) return undefined
+    let failure: string | undefined
+    try {
+      failure = validateDraft(rehydrateSchema(view.schema), view.value)
+    } catch (_malformedSchemaEnvelope) {
+      // A schema envelope this client cannot rehydrate vouches for no section;
+      // the value is treated exactly like a schema-invalid one.
+      return undefined
+    }
+    return failure === undefined ? view.value as T : undefined
+  }
+}
+
+/**
+ * Bind one namespace scope to settings and connection invalidations on the
+ * caller's plugin lifecycle. Listeners exist before the initial background
+ * read starts, so activation never blocks on the settings transport.
+ * @param ctx - owning browser plugin context.
+ * @param spec - domain-owned namespace contract.
+ * @returns the bound scope consumed by the domain's services and rows.
+ */
+export function bindSettingsScope<T>(
+  ctx: Context,
+  spec: SettingsScopeSpec<T>,
+): SettingsScope<T> {
+  const connection = ctx.get('connection') as ConnectionHandle
+  const controller = new SettingsScopeController<T>(
+    connection.api,
+    spec,
+    connection.isLoopback ? 'host' : 'memory',
+  )
+  ctx.effect(() => {
+    const refresh = (namespace?: string): void => {
+      if (namespace !== undefined && namespace !== spec.namespace) return
+      void controller.load()
+    }
+    const disposers = [
+      ctx.on('settings/changed', refresh),
+      ctx.on('connection/reset', () => { refresh() }),
+    ]
+    void controller.load()
+    return async () => {
+      for (const dispose of disposers) dispose()
+      await controller.dispose()
+    }
+  }, `runtime: ${spec.namespace} settings scope`)
+  return controller
+}
--- a/packages/client/runtime/tests/settings-scope.spec.ts
+++ b/packages/client/runtime/tests/settings-scope.spec.ts
@@ -0,0 +1,352 @@
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { describe, expect, it, vi } from 'vitest'
+import type { RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client'
+import {
+  bindSettingsScope, SettingsScopeController, type SettingsScope,
+} from '../src/client/settings-scope.ts'
+
+interface UiTestSettings {
+  preference: 'light' | 'dark' | 'system'
+}
+
+const ENVELOPE = z.object({
+  preference: z.union(['light', 'dark', 'system']).default('system'),
+}).toJSON()
+
+let rpc = 0
+
+function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: `scope-${rpc++}` as never, result: { ok: true, value } }
+}
+
+function rejected<T>(): RpcResponse<T> {
+  return {
+    rpcId: `scope-${rpc++}` as never,
+    result: {
+      ok: false,
+      error: { code: 'settings-rejected', message: 'conflict', details: { ns: 'ui-test' } },
+    },
+  }
+}
+
+function view(value: unknown, revision = 0): SettingsNamespaceView {
+  return {
+    ns: 'ui-test',
+    schema: ENVELOPE,
+    value,
+    applies: 'live',
+    secrets: [],
+    revision,
+  }
+}
+
+function described(value: unknown, revision = 0) {
+  return ok({ writable: true, hasDocument: true, namespaces: [view(value, revision)] })
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason: unknown) => void
+  const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })
+  return { promise, resolve, reject }
+}
+
+/** Record each distinct published section, starting from the current one. */
+function trackValues(scope: SettingsScope<UiTestSettings>): Array<UiTestSettings | undefined> {
+  const seen: Array<UiTestSettings | undefined> = [scope.getSnapshot().value]
+  scope.subscribe(() => {
+    const value = scope.getSnapshot().value
+    if (value !== seen[seen.length - 1]) seen.push(value)
+  })
+  return seen
+}
+
+describe('SettingsScopeController', () => {
+  it('starts loading and publishes a schema-valid section with revision and writability', async () => {
+    const describeCall = vi.fn().mockResolvedValueOnce(described({ preference: 'dark' }, 3))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall } } as never,
+      { namespace: 'ui-test' },
+    )
+    expect(scope.getSnapshot()).toEqual({
+      status: 'loading', value: undefined, revision: undefined, writable: false, mode: 'host',
+    })
+    await scope.load()
+    expect(scope.getSnapshot()).toEqual({
+      status: 'ready', value: { preference: 'dark' }, revision: 3, writable: true, mode: 'host',
+    })
+  })
+
+  it('keeps the last good value across invalid, rejected, and failed reads while tracking revisions', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(described({ preference: 'dark' }, 3))
+      .mockResolvedValueOnce(described({ preference: 'sepia' }, 4))
+      .mockResolvedValueOnce(described(null, 5))
+      .mockResolvedValueOnce(described('scalar', 6))
+      .mockResolvedValueOnce(described(['queue'], 7))
+      .mockResolvedValueOnce(rejected())
+      .mockRejectedValueOnce(new Error('offline'))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall } } as never,
+      { namespace: 'ui-test' },
+    )
+    const good = trackValues(scope)
+    for (let i = 0; i < 7; i++) await scope.load()
+    expect(scope.getSnapshot()).toMatchObject({
+      status: 'ready', value: { preference: 'dark' }, revision: 7,
+    })
+    expect(good).toEqual([undefined, { preference: 'dark' }])
+  })
+
+  it('treats a schema envelope it cannot rehydrate as vouching for no section', async () => {
+    const broken = { ...view({ preference: 'dark' }, 2), schema: null }
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(ok({ writable: true, hasDocument: true, namespaces: [broken] }))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall } } as never,
+      { namespace: 'ui-test' },
+    )
+    await scope.load()
+    expect(scope.getSnapshot()).toMatchObject({ status: 'loading', value: undefined, revision: 2 })
+  })
+
+  it('suppresses a superseded read of an unexposed namespace', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(ok({ writable: true, hasDocument: true, namespaces: [] }))
+      .mockResolvedValueOnce(described({ preference: 'dark' }, 1))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall } } as never,
+      { namespace: 'ui-test' },
+    )
+    const statuses: string[] = []
+    scope.subscribe(() => { statuses.push(scope.getSnapshot().status) })
+    const stale = scope.load()
+    const fresh = scope.load()
+    await Promise.all([stale, fresh])
+    expect(statuses).not.toContain('unavailable')
+    expect(scope.getSnapshot()).toMatchObject({ status: 'ready', value: { preference: 'dark' } })
+  })
+
+  it('reports an unexposed namespace as unavailable and recovers when it reappears', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(described({ preference: 'light' }, 1))
+      .mockResolvedValueOnce(ok({ writable: true, hasDocument: true, namespaces: [] }))
+      .mockResolvedValueOnce(described({ preference: 'system' }, 2))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall } } as never,
+      { namespace: 'ui-test' },
+    )
+    await scope.load()
+    expect(scope.getSnapshot().status).toBe('ready')
+    await scope.load()
+    expect(scope.getSnapshot()).toMatchObject({ status: 'unavailable', value: { preference: 'light' } })
+    await scope.load()
+    expect(scope.getSnapshot()).toMatchObject({ status: 'ready', value: { preference: 'system' }, revision: 2 })
+  })
+
+  it('applies a custom decode override in place of the wire schema', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(described({ preference: 'light' }, 1))
+      .mockResolvedValueOnce(described({ preference: 'dark' }, 2))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall } } as never,
+      {
+        namespace: 'ui-test',
+        decode: section => (section as UiTestSettings).preference === 'dark'
+          ? section as UiTestSettings
+          : undefined,
+      },
+    )
+    await scope.load()
+    expect(scope.getSnapshot()).toMatchObject({ status: 'loading', value: undefined, revision: 1 })
+    await scope.load()
+    expect(scope.getSnapshot()).toMatchObject({ status: 'ready', value: { preference: 'dark' }, revision: 2 })
+  })
+
+  it('serializes rapid set writes, carries revisions, and publishes only the latest settlement', async () => {
+    const first = deferred<RpcResponse<SettingsNamespaceView>>()
+    const describeCall = vi.fn().mockResolvedValue(described({ preference: 'system' }, 4))
+    const mutate = vi.fn()
+      .mockReturnValueOnce(first.promise)
+      .mockResolvedValueOnce(ok(view({ preference: 'light' }, 6)))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall, mutate } } as never,
+      { namespace: 'ui-test' },
+    )
+    const published = trackValues(scope)
+    await scope.load()
+    const dark = scope.set('preference', 'dark')
+    const light = scope.set('preference', 'light')
+    await vi.waitFor(() => { expect(mutate).toHaveBeenCalledOnce() })
+    first.resolve(ok(view({ preference: 'dark' }, 5)))
+    await Promise.all([dark, light])
+    expect(published.map(section => section?.preference)).toEqual([undefined, 'system', 'light'])
+    expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'light' }, revision: 6 })
+    expect(mutate).toHaveBeenNthCalledWith(1, {
+      ns: 'ui-test',
+      ops: [{ op: 'set', path: ['preference'], value: 'dark' }],
+      expectedRevision: 4,
+    })
+    expect(mutate).toHaveBeenNthCalledWith(2, {
+      ns: 'ui-test',
+      ops: [{ op: 'set', path: ['preference'], value: 'light' }],
+      expectedRevision: 5,
+    })
+  })
+
+  it('recovers the latest rejected or thrown write from Host state', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(described({ preference: 'system' }, 2))
+      .mockResolvedValueOnce(described({ preference: 'light' }, 3))
+    const mutate = vi.fn()
+      .mockResolvedValueOnce(rejected())
+      .mockRejectedValueOnce(new Error('offline'))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall, mutate } } as never,
+      { namespace: 'ui-test' },
+    )
+    const published = trackValues(scope)
+    await scope.set('preference', 'dark')
+    await scope.set('preference', 'system')
+    expect(published.map(section => section?.preference)).toEqual([undefined, 'system', 'light'])
+  })
+
+  it('does not recover superseded rejected or thrown writes', async () => {
+    const describeCall = vi.fn()
+    const mutate = vi.fn()
+      .mockResolvedValueOnce(rejected())
+      .mockRejectedValueOnce(new Error('offline'))
+      .mockResolvedValueOnce(ok(view({ preference: 'light' }, 3)))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall, mutate } } as never,
+      { namespace: 'ui-test' },
+    )
+    const published = trackValues(scope)
+    await Promise.all([
+      scope.set('preference', 'dark'),
+      scope.set('preference', 'system'),
+      scope.set('preference', 'light'),
+    ])
+    expect(describeCall).not.toHaveBeenCalled()
+    expect(published.map(section => section?.preference)).toEqual([undefined, 'light'])
+  })
+
+  it('keeps the write queue usable when a subscriber throws', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(described({ preference: 'dark' }, 1))
+      .mockResolvedValueOnce(described({ preference: 'light' }, 2))
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall } } as never,
+      { namespace: 'ui-test' },
+    )
+    let thrown = false
+    scope.subscribe(() => {
+      if (thrown) return
+      thrown = true
+      throw new Error('subscriber failed')
+    })
+    await expect(scope.load()).rejects.toThrow('subscriber failed')
+    await expect(scope.load()).resolves.toBeUndefined()
+    expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'light' }, revision: 2 })
+  })
+
+  it('cancels queued and post-dispose writes while draining the in-flight mutation', async () => {
+    const first = deferred<RpcResponse<SettingsNamespaceView>>()
+    const mutate = vi.fn().mockReturnValue(first.promise)
+    const describeCall = vi.fn()
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall, mutate } } as never,
+      { namespace: 'ui-test' },
+    )
+    const published = trackValues(scope)
+    const dark = scope.set('preference', 'dark')
+    await vi.waitFor(() => { expect(mutate).toHaveBeenCalledOnce() })
+    const light = scope.set('preference', 'light')
+    let stopped = false
+    const stop = scope.dispose().then(() => { stopped = true })
+    await Promise.resolve()
+    expect(stopped).toBe(false)
+    first.resolve(ok(view({ preference: 'dark' }, 1)))
+    await Promise.all([dark, light, stop])
+    await scope.set('preference', 'system')
+    await scope.load()
+    expect(mutate).toHaveBeenCalledOnce()
+    expect(describeCall).not.toHaveBeenCalled()
+    expect(published).toEqual([undefined])
+  })
+
+  it('keeps a remote browser in memory mode without Host calls', async () => {
+    const describeCall = vi.fn()
+    const mutate = vi.fn()
+    const scope = new SettingsScopeController<UiTestSettings>(
+      { settings: { describe: describeCall, mutate } } as never,
+      { namespace: 'ui-test' },
+      'memory',
+    )
+    expect(scope.getSnapshot()).toEqual({
+      status: 'unavailable', value: undefined, revision: undefined, writable: false, mode: 'memory',
+    })
+    await scope.load()
+    await scope.set('preference', 'dark')
+    await scope.dispose()
+    expect(describeCall).not.toHaveBeenCalled()
+    expect(mutate).not.toHaveBeenCalled()
+  })
+})
+
+describe('bindSettingsScope', () => {
+  it('subscribes before the initial read and converges to the latest queued invalidation', async () => {
+    const initial = deferred<ReturnType<typeof described>>()
+    const describeCall = vi.fn()
+      .mockReturnValueOnce(initial.promise)
+      .mockResolvedValueOnce(described({ preference: 'light' }, 2))
+      .mockResolvedValueOnce(described({ preference: 'system' }, 3))
+    const ctx = new Context()
+    ctx.provide('connection', {
+      api: { settings: { describe: describeCall } },
+      isLoopback: true,
+    } as never)
+    let scope!: SettingsScope<UiTestSettings>
+    const fiber = ctx.plugin({
+      inject: ['connection'],
+      apply: (plugin: Context) => {
+        scope = bindSettingsScope<UiTestSettings>(plugin, { namespace: 'ui-test' })
+      },
+    })
+    await fiber.await()
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledOnce() })
+    ctx.emit('settings/changed', 'unrelated')
+    ctx.emit('settings/changed', 'ui-test')
+    ctx.emit('connection/reset')
+    initial.resolve(described({ preference: 'dark' }, 1))
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(3) })
+    await vi.waitFor(() => {
+      expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'system' }, revision: 3 })
+    })
+    await fiber.dispose()
+    ctx.emit('settings/changed', 'ui-test')
+    await Promise.resolve()
+    expect(describeCall).toHaveBeenCalledTimes(3)
+  })
+
+  it('binds a remote browser in memory mode without starting a settings read', async () => {
+    const describeCall = vi.fn()
+    const ctx = new Context()
+    ctx.provide('connection', {
+      api: { settings: { describe: describeCall } },
+      isLoopback: false,
+    } as never)
+    let scope!: SettingsScope<UiTestSettings>
+    const fiber = ctx.plugin({
+      inject: ['connection'],
+      apply: (plugin: Context) => {
+        scope = bindSettingsScope<UiTestSettings>(plugin, { namespace: 'ui-test' })
+      },
+    })
+    await fiber.await()
+    expect(scope.getSnapshot()).toMatchObject({ status: 'unavailable', mode: 'memory', writable: false })
+    await fiber.dispose()
+    expect(describeCall).not.toHaveBeenCalled()
+  })
+})
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -23,6 +23,9 @@
    {
      "path": "../connection"
    },
+    {
+      "path": "../schema-form"
+    },
    {
      "path": "../../host/apiproxy"
    },
--- a/packages/client/test-runtime/README.i18n.yaml
+++ b/packages/client/test-runtime/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/test-runtime/README.md
-README.md: 74da8fde7fd9cc3733d2d1ae03dd3d213e4d553e
-README.zh.md: 1df28f7b25c35333e91476e10480c22a728cdab3
+README.md: 455d6f564cea2cb8f88165a8bba1047c762d2fb0
+README.zh.md: 7c4bd0e552c71f55e3766a0c64580cc178461310
--- a/packages/client/test-runtime/README.md
+++ b/packages/client/test-runtime/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)

 jsdom slot test runtime for client feature specs: a real Cordis `Context`, the production `SlotsService` and web-react renderer, assembled around typed session/workspace doubles. Feature suites exercise declaration, registration, scope, store, inject, rendering, updates, and disposal without hand-building the machinery per suite — and without a second implementation of any production logic.

-The doubles implement the same outward faces features receive through ctx (`TestSessions implements ISessions`, `TestWorkspaces implements IWorkspaces`; each fixture session is a `FixtureSession implements SessionFace`), so a production face change breaks the bench at compile time instead of silently drifting. Provide-bundle materialization runs the production `SessionProvideChannel` — the one implementation shared with `SessionsService`. Fixtures feed plain data: list rows, conversation snapshots (immer-patched via `updateSnapshot`), projection values, and `ISession`-typed behavior stubs that fail loud when a spec calls an unstubbed verb. The typed `provide()` constrains fakes for declared service names to `Partial` of that service's outward face.
+The doubles implement the same outward faces features receive through ctx (`TestSessions implements ISessions`, `TestWorkspaces implements IWorkspaces`; each fixture session is a `FixtureSession implements SessionFace`; `stubSettingsScope` is a `SettingsScope` with test-driven publications and a write spy), so a production face change breaks the bench at compile time instead of silently drifting. Provide-bundle materialization runs the production `SessionProvideChannel` — the one implementation shared with `SessionsService`. Fixtures feed plain data: list rows, conversation snapshots (immer-patched via `updateSnapshot`), projection values, and `ISession`-typed behavior stubs that fail loud when a spec calls an unstubbed verb. The typed `provide()` constrains fakes for declared service names to `Partial` of that service's outward face.

 Local DOM snapshots: `declare(children)` registers an auto frame whose per-key `<div data-slot>` wrappers are snapshot roots; `renderSlot(key, owner)` returns the slot-local view (container, scoped Testing Library queries, in-place `update(owner)`); a registered snapshot serializer folds CSS-module class hashes (`_frame_a1b2c3` → `frame`) to keep `.snap` files structural and collapses `<svg>` internals to a `data-content` fingerprint. Suites needing a custom page frame use `root.declare(children, Frame)` instead; `mount(plugin)` runs a real fiber with fail-loud service prechecks, and `dispose()` tears down views, feature fibers, minted scopes, and persisted store state on one axis.

--- a/packages/client/test-runtime/README.zh.md
+++ b/packages/client/test-runtime/README.zh.md
@@ -4,7 +4,7 @@

 面向客户端功能测试的 jsdom slot 测试运行时：真实 Cordis `Context`、生产 `SlotsService` 与 web-react 渲染器，围绕带类型的 session/workspace 测试替身组装。功能套件无需逐套件手搭机器即可测遍声明、注册、scope、store、inject、渲染、更新与销毁——且不存在任何生产逻辑的第二份实现。

-替身实现的正是功能通过 ctx 获得的对外接口（`TestSessions implements ISessions`、`TestWorkspaces implements IWorkspaces`；每个 fixture session 是 `FixtureSession implements SessionFace`），生产面一旦改形，测试台在编译期即断，而非静默漂移。provide bundle 材料化直接运行生产 `SessionProvideChannel`——与 `SessionsService` 共用同一份实现。fixture 灌入的是普通数据：列表行、会话快照（经 `updateSnapshot` 以 immer 补丁改写）、projection 值，以及按 `ISession` 取型的行为桩——spec 调用未打桩的动词时报错自明。带类型的 `provide()` 将已声明服务名的 fake 约束为该服务对外面的 `Partial` 子集。
+替身实现的正是功能通过 ctx 获得的对外接口（`TestSessions implements ISessions`、`TestWorkspaces implements IWorkspaces`；每个 fixture session 是 `FixtureSession implements SessionFace`；`stubSettingsScope` 是发布由测试驱动、带写入 spy 的 `SettingsScope`），生产面一旦改形，测试台在编译期即断，而非静默漂移。provide bundle 材料化直接运行生产 `SessionProvideChannel`——与 `SessionsService` 共用同一份实现。fixture 灌入的是普通数据：列表行、会话快照（经 `updateSnapshot` 以 immer 补丁改写）、projection 值，以及按 `ISession` 取型的行为桩——spec 调用未打桩的动词时报错自明。带类型的 `provide()` 将已声明服务名的 fake 约束为该服务对外面的 `Partial` 子集。

 局部 DOM 快照：`declare(children)` 注册自动 frame，逐 key 的 `<div data-slot>` 包裹层即快照根；`renderSlot(key, owner)` 返回该 slot 的局部视图（container、限定范围的 Testing Library 查询、原位 `update(owner)`）；注册的快照序列化器把 CSS-module 哈希类名折回语义名（`_frame_a1b2c3` → `frame`）保持 `.snap` 只含结构，并把 `<svg>` 内部折叠为 `data-content` 指纹。需要自定义页面 frame 的套件改用 `root.declare(children, Frame)`；`mount(plugin)` 在真实 fiber 上运行并对缺失服务先行报错；`dispose()` 沿单一轴拆除视图、feature fiber、已铸 scope 与持久化 store 状态。

--- a/packages/client/test-runtime/src/index.ts
+++ b/packages/client/test-runtime/src/index.ts
@@ -36,6 +36,8 @@ import type { Stabilizer } from './fixtures.ts'

 export { domSnapshotSerializer, registerDomSnapshotSerializer } from './snapshot.ts'
 export { FixtureSession, TestSessions } from './sessions.ts'
+export { stubSettingsScope } from './settings-scope.ts'
+export type { StubSettingsScope } from './settings-scope.ts'
 export { TestWorkspaces } from './workspaces.ts'
 export { conversationSnapshot, workspaceListState } from './fixtures.ts'
 export type { SessionBehaviorOverrides, SessionFixture, Stabilizer } from './fixtures.ts'
--- a/packages/client/test-runtime/src/settings-scope.ts
+++ b/packages/client/test-runtime/src/settings-scope.ts
@@ -0,0 +1,48 @@
+/** Test double for the client settings-scope seam. */
+import { vi } from 'vitest'
+import type { SettingsScope, SettingsScopeSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** Handle over one stubbed scope: the scope, its write spy, and publication controls. */
+export interface StubSettingsScope<T> {
+  /** The scope face handed to the service under test. */
+  scope: SettingsScope<T>
+  /** Spy behind `scope.set`; resolves immediately. */
+  set: ReturnType<typeof vi.fn>
+  /** @returns how many listeners are currently subscribed (disposal assertions). */
+  listenerCount(): number
+  /**
+   * Replace part of the snapshot and notify subscribers, as a Host
+   * acceptance would.
+   * @param next - snapshot fields to replace.
+   */
+  publish(next: Partial<SettingsScopeSnapshot<T>>): void
+}
+
+/**
+ * Build an in-memory settings scope for service specs: starts in the host
+ * loading state, records writes, and lets the test publish Host acceptances.
+ * @returns the stub handle.
+ */
+export function stubSettingsScope<T>(): StubSettingsScope<T> {
+  let snapshot: SettingsScopeSnapshot<T> = {
+    status: 'loading', value: undefined, revision: undefined, writable: false, mode: 'host',
+  }
+  const listeners = new Set<() => void>()
+  const set = vi.fn(() => Promise.resolve())
+  return {
+    scope: {
+      getSnapshot: () => snapshot,
+      subscribe: (listener) => {
+        listeners.add(listener)
+        return () => { listeners.delete(listener) }
+      },
+      set,
+    },
+    set,
+    listenerCount: () => listeners.size,
+    publish: (next) => {
+      snapshot = { ...snapshot, ...next }
+      for (const listener of [...listeners]) listener()
+    },
+  }
+}
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
-README.md: 23dbb1a5492afefe9064d86429f21b926f594a53
-README.zh.md: 1d27beed9ca426096692b5710cc8d77396499449
+README.md: 7c4855a75abb982ff55b903808d6a65c42cbc91c
+README.zh.md: c3a5d7beb2e90289f4340fc251fd3527370e3e23
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -32,7 +32,7 @@ The chat flow projects consecutive model-retry nodes across retry turns into one

 The Host's placement-aware `session/queue` snapshot also carries pending steering. QueueDock filters it out, while ChatView projects it as a user-style bubble with Copy at the conversation tail; non-user next-step items (injected context) carry the `context` placement instead and render nowhere until claimed. Fork is absent here as on every user-style bubble. The Host delays steering retirement until the durable `user/message` carrying the steering has entered the mux stream. On that accepted live event, the client runtime retires the first matching current steering occurrence before publishing the snapshot; historical events cannot hide later occurrences that reuse the same `MessageId`. The bubble therefore hands off without a gap or duplicate, immediately restores Copy and the clock from the durable node — a steering bubble, like a user bubble, carries no branch action ([decision](../../../.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)) — and survives reconnect from the same authority.

-Keyboard message submission resolves delivery from the addressed session's running state and steering capability. While idle, Enter and Cmd/Ctrl+Enter both perform an ordinary Queue send. While a primary session is running, the browser-persisted General Settings preference assigns plain Enter to `Queue` (the default) or `Steer`, and Cmd/Ctrl+Enter performs the other behavior; Shift+Enter remains a newline. With an empty draft, Cmd/Ctrl+Enter instead steers every still-pending queued message into the running turn in FIFO order (the dock's per-row strict-steer action applied to the whole queue); plain Enter with an empty draft remains a no-op. While this whole-queue gesture is available, the textarea placeholder advertises it; a placeholder supplied by the owning surface still takes precedence. Addressed subagents keep both gestures on their Queue-only continuation transport even while running. The preference affects only the steer-capable busy-state gesture pair, and the send button and non-keyboard submit actions remain Queue. Composer Steer uses the existing best-effort `session.prompt(mode: 'steer')` contract: if the current next-step window closes before acceptance, AgentLoop admits the message as the next waking Queue turn without surfacing a failure or losing the draft transaction.
+Keyboard message submission resolves delivery from the addressed session's running state and steering capability. While idle, Enter and Cmd/Ctrl+Enter both perform an ordinary Queue send. While a primary session is running, the Host-backed `ui-conversation.busyEnter` General Settings preference assigns plain Enter to `Queue` (the default) or `Steer`, and Cmd/Ctrl+Enter performs the other behavior; the local settings provider stores it in `$DSH_HOME/settings.yaml`, so the choice follows the same user home across Web ports. Shift+Enter remains a newline. With an empty draft, Cmd/Ctrl+Enter instead steers every still-pending queued message into the running turn in FIFO order (the dock's per-row strict-steer action applied to the whole queue); plain Enter with an empty draft remains a no-op. While this whole-queue gesture is available, the textarea placeholder advertises it; a placeholder supplied by the owning surface still takes precedence. Addressed subagents keep both gestures on their Queue-only continuation transport even while running. The preference affects only the steer-capable busy-state gesture pair, and the send button and non-keyboard submit actions remain Queue. Composer Steer uses the existing best-effort `session.prompt(mode: 'steer')` contract: if the current next-step window closes before acceptance, AgentLoop admits the message as the next waking Queue turn without surfacing a failure or losing the draft transaction. The [Host-backed preferences decision](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md) owns the persistence boundary.

 Per-session UI state for selection and the active view lives in the declared chat store (`stores.ts` `createChatStore`); the InputHub owns the composer state machine and mirrors its draft into that store for persistence. Apply passes one store handle to the strict session subtree, chat view, and details registrations, so each session shares one instance and the framework owns its lifecycle. Components are pure: the framework standard kit supplies `useSession`/`sessionId`, global `useSessions`/`useWorkspaces`, and the input machine's `useInput`/`inputActions`; store faces and inject factories supply the remaining state and callbacks.

--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -32,7 +32,7 @@ Think 行默认保持折叠，并在不展开思维链的情况下暴露实时

 Host 带 placement 的 `session/queue` 快照也会携带待处理 steering。QueueDock 会将其过滤掉，ChatView 则把它投影为会话流末尾带复制操作的用户样式气泡；非用户来源的 next-step 项（注入上下文）改以 `context` placement 广播，领取前不在任何界面渲染。与所有用户样式气泡一样，这里不显示 fork。Host 会等携带该 steering 的持久 `user/message` 进入 mux 流之后再退役 steering。客户端运行时接纳该实时事件时，会在发布快照前退役第一个匹配的当前 steering 单次入队项；历史事件无法隐藏后来复用同一 `MessageId` 的单次入队项。气泡交接时因而不会产生空档或重复，会立即从持久节点恢复复制操作与时钟——steering 气泡与 user 气泡一样不带分支操作（[决策](../../../.agents/notes/implemented/simplification/2026-08-06-user-bubbles-drop-the-branch-action.md)）——并能在重连后从同一权威恢复。

-键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，浏览器持久化的 General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；Shift+Enter 仍然换行。草稿为空时，Cmd/Ctrl+Enter 改为按 FIFO 顺序把仍在排队的消息全部插话进运行中的轮次（把 dock 的逐条严格 steer 操作应用于整个队列）；空草稿 + 普通 Enter 仍是无操作。这个整队列手势可用时，文本框 placeholder 会提示该手势；owner 提供的 placeholder 仍然优先。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 契约：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。
+键盘消息提交会根据所寻址会话的运行状态和 steering 能力解析投递方式。空闲时，Enter 和 Cmd/Ctrl+Enter 都执行普通 Queue 发送。主会话运行期间，由 Host settings 支撑的 `ui-conversation.busyEnter` General Settings 偏好会把普通 Enter 分配为 `Queue`（默认值）或 `Steer`，Cmd/Ctrl+Enter 则执行另一种行为；本地 settings 提供方将其存入 `$DSH_HOME/settings.yaml`，因此该选择会跟随同一个用户 home 跨越 Web 端口。Shift+Enter 仍然换行。草稿为空时，Cmd/Ctrl+Enter 改为按 FIFO 顺序把仍在排队的消息全部插话进运行中的轮次（把 dock 的逐条严格 steer 操作应用于整个队列）；空草稿 + 普通 Enter 仍是无操作。这个整队列手势可用时，文本框 placeholder 会提示该手势；owner 提供的 placeholder 仍然优先。已寻址 subagent 即使正在运行，也会让这两个手势都使用其仅支持 Queue 的继续执行传输。该偏好只影响支持 steering 的繁忙态手势对，发送按钮与非键盘提交操作仍使用 Queue。Composer Steer 复用现有尽力而为的 `session.prompt(mode: 'steer')` 约定：如果当前 next-step 窗口在接纳前关闭，AgentLoop 会把消息接纳为下一条唤醒 Queue 轮次，不显示失败，也不会丢失草稿事务。该持久化边界由[Host settings 支撑的偏好决策](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md)拥有。

 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。

--- a/packages/client/ui-conversation/package.json
+++ b/packages/client/ui-conversation/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@deepseek-ai/dsh-client-ui-conversation",
-  "description": "Conversation domain: skeleton, ordered chat flow, composer, and details host",
+  "description": "Conversation domain: skeleton, ordered chat flow, composer with the Host-backed busy-Enter preference, and details host",
  "version": "0.0.1",
  "private": true,
  "type": "module",
@@ -24,6 +24,7 @@
  },
  "dshClient": {
    "inject": [
+      "@deepseek-ai/dsh-client-connection",
      "@deepseek-ai/dsh-client-locale",
      "@deepseek-ai/dsh-client-runtime",
      "@deepseek-ai/dsh-client-ui-layout"
@@ -36,12 +37,15 @@
  },
  "license": "BSD-3-Clause",
  "dependencies": {
-    "clsx": "^2.0.0"
+    "@deepseek-ai/dsh-settings": "workspace:^",
+    "clsx": "^2.0.0",
+    "schemastery": "^3.18.0"
  },
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-attachment": "^0.0.1",
    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
    "@deepseek-ai/dsh-client-locale": "^0.0.1",
    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
@@ -60,6 +64,7 @@
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-attachment": "workspace:^",
    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
    "@deepseek-ai/dsh-client-locale": "workspace:^",
    "@deepseek-ai/dsh-client-runtime": "workspace:^",
    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -1,7 +1,9 @@
 /** Registers the conversation components, shared store, and service callbacks. */
 import type { Context } from 'cordis'
 import { resolveSlotLabel, type BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
-import { resolveWorkspacePath, type ISessions, type SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  bindSettingsScope, resolveWorkspacePath, type ISessions, type SessionId,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
@@ -33,6 +35,7 @@ import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 import { en, NS, zh, type ConversationKey } from './locales.ts'
 import { registerConversationNodes } from './conversation-nodes/register.ts'
 import { registerChatNodeRenderers } from './chat/register-node-renderers.ts'
+import { CONVERSATION_SETTINGS_NAMESPACE, type ConversationSettings } from '../submission-settings.ts'

 declare module '@deepseek-ai/dsh-client-ui-slots' {
  interface LocaleNamespaceMap {
@@ -43,7 +46,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {

 /** Services required by the conversation plugin. */
 export const inject = [
-  'slots', 'layout', 'sessions', 'workspaces', 'locale',
+  'slots', 'layout', 'sessions', 'workspaces', 'locale', 'connection',
  'conversationEvents', 'conversationViews',
 ]

@@ -124,7 +127,9 @@ export function apply(ctx: Context): void {

  // Apply-time construction keeps store identity bound to this fiber.
  const chatStore = createChatStore()
-  const submissionPolicy = new ComposerSubmissionPolicy()
+  const submissionPolicy = new ComposerSubmissionPolicy(
+    bindSettingsScope<ConversationSettings>(ctx, { namespace: CONVERSATION_SETTINGS_NAMESPACE }),
+  )

  ctx.slots.inject('settings.general.item', () => ctx.slots.register({
    name: 'settings.general.item',
--- a/packages/client/ui-conversation/src/client/contract/composer-submission.ts
+++ b/packages/client/ui-conversation/src/client/contract/composer-submission.ts
@@ -1,10 +1,11 @@
 /** Composer submission vocabulary shared by the input and settings domains. */

-/** Delivery mode requested for one ordinary composer message. */
-export type InputSubmitMode = 'queue' | 'steer'
+import type { BusyEnterBehavior } from '../../submission-settings.ts'

-/** Configurable meaning of plain Enter while the addressed agent is busy. */
-export type BusyEnterBehavior = InputSubmitMode
+export type { BusyEnterBehavior } from '../../submission-settings.ts'
+
+/** Delivery mode requested for one ordinary composer message. */
+export type InputSubmitMode = BusyEnterBehavior

 /** Keyboard gesture whose delivery mode the submission policy resolves. */
 export type ComposerSubmitGesture = 'enter' | 'accelerated'
--- a/packages/client/ui-conversation/src/client/input/submission-policy.ts
+++ b/packages/client/ui-conversation/src/client/input/submission-policy.ts
@@ -1,27 +1,42 @@
 /**
- * Browser-local Composer submission policy. It owns the persisted busy-Enter
+ * Composer submission policy. It owns the live busy-Enter
 * preference and resolves keyboard gestures into queue/steer delivery modes;
 * Host and Agent keep the actual delivery-window authority.
 */
-import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  createSnapshotStore, type SettingsScope, type SnapshotStore,
+} from '@deepseek-ai/dsh-client-runtime/client'
 import type {
  BusyEnterBehavior, ComposerSubmitGesture, InputSubmitMode,
 } from '../contract/composer-submission.ts'
+import { BUSY_ENTER_FIELD, DEFAULT_BUSY_ENTER_BEHAVIOR } from '../../submission-settings.ts'
+import type { ConversationSettings } from '../../submission-settings.ts'

-/** localStorage key holding the busy-Enter preference. */
-export const BUSY_ENTER_STORAGE_KEY = 'dsh.conversation.busyEnter'
-
-/** Default preserves Enter-as-Queue for running conversations. */
-export const DEFAULT_BUSY_ENTER_BEHAVIOR: BusyEnterBehavior = 'queue'
+export { DEFAULT_BUSY_ENTER_BEHAVIOR } from '../../submission-settings.ts'

 /**
- * Persisted policy used by both the composer inject face and its Settings row.
+ * Busy-Enter policy used by both the composer inject face and its Settings row.
 * Direct `steer` is intentionally best-effort: AgentLoop turns a closed-window
 * submission into the next waking Queue item.
 */
 export class ComposerSubmissionPolicy {
  /** Reactive preference source for the Settings row. */
-  readonly busyEnter: SnapshotStore<BusyEnterBehavior> = createSnapshotStore(restoreBusyEnter())
+  readonly busyEnter: SnapshotStore<BusyEnterBehavior> = createSnapshotStore(DEFAULT_BUSY_ENTER_BEHAVIOR)
+  private readonly host: SettingsScope<ConversationSettings> | undefined
+
+  /**
+   * @param host - durable preference scope owned by the providing plugin;
+   * absent compositions stay process-local. The adoption subscription shares
+   * the scope's plugin lifetime — a disposed scope never publishes again, so
+   * the policy needs no release hook.
+   */
+  constructor(host?: SettingsScope<ConversationSettings>) {
+    this.host = host
+    if (host !== undefined) {
+      host.subscribe(() => { this.adopt(host) })
+      this.adopt(host)
+    }
+  }

  /**
   * Resolve one keyboard gesture without changing state.
@@ -42,36 +57,23 @@ export class ComposerSubmissionPolicy {
  }

  /**
-   * Change and persist the plain-Enter behavior used during busy state.
+   * Change the plain-Enter behavior used during busy state; the live value
+   * publishes before the durable write starts.
   * @param behavior - Queue or Steer.
   */
  setBusyEnter(behavior: BusyEnterBehavior): void {
    if (this.busyEnter.getSnapshot() === behavior) return
    this.busyEnter.set(behavior)
-    persistBusyEnter(behavior)
+    void this.host?.set(BUSY_ENTER_FIELD, behavior)
  }
-}

-/** Restore a valid preference; unavailable or corrupt storage uses Queue. */
-function restoreBusyEnter(): BusyEnterBehavior {
-  if (typeof localStorage === 'undefined') return DEFAULT_BUSY_ENTER_BEHAVIOR
-  let stored: string | null
-  try {
-    stored = localStorage.getItem(BUSY_ENTER_STORAGE_KEY)
-  } catch {
-    // Storage access can fail in privacy modes; the default remains usable.
-    return DEFAULT_BUSY_ENTER_BEHAVIOR
-  }
-  if (stored === 'queue' || stored === 'steer') return stored
-  return DEFAULT_BUSY_ENTER_BEHAVIOR
-}
-
-/** Persist a preference when browser storage is available. */
-function persistBusyEnter(behavior: BusyEnterBehavior): void {
-  if (typeof localStorage === 'undefined') return
-  try {
-    localStorage.setItem(BUSY_ENTER_STORAGE_KEY, behavior)
-  } catch {
-    // A storage failure makes the preference session-only; input stays usable.
+  /**
+   * Adopt the scope's accepted durable behavior without writing it back.
+   * @param host - the constructor-narrowed scope driving this adoption.
+   */
+  private adopt(host: SettingsScope<ConversationSettings>): void {
+    const section = host.getSnapshot().value
+    if (section === undefined || this.busyEnter.getSnapshot() === section.busyEnter) return
+    this.busyEnter.set(section.busyEnter)
  }
 }
--- a/packages/client/ui-conversation/src/index.ts
+++ b/packages/client/ui-conversation/src/index.ts
@@ -1,4 +1,23 @@
-/** Host loader entry for the browser-only conversation plugin. */
+/** Host registration for browser conversation preferences. */

-/** Provides no host-side behavior. */
-export function apply(): void {}
+import type { Context } from 'cordis'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { CONVERSATION_SETTINGS_NAMESPACE, ConversationSettingsSchema } from './submission-settings.ts'
+
+export {
+  BUSY_ENTER_BEHAVIORS, BUSY_ENTER_FIELD, CONVERSATION_SETTINGS_NAMESPACE,
+  DEFAULT_BUSY_ENTER_BEHAVIOR, type BusyEnterBehavior, type ConversationSettings,
+} from './submission-settings.ts'
+
+/**
+ * Register the durable conversation section when a settings provider exists.
+ * @param ctx - Host context whose optional settings service owns the section.
+ */
+export function apply(ctx: Context): void {
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.register(
+      settingsNamespace(CONVERSATION_SETTINGS_NAMESPACE),
+      ConversationSettingsSchema,
+    )
+  })
+}
--- a/packages/client/ui-conversation/src/submission-settings.ts
+++ b/packages/client/ui-conversation/src/submission-settings.ts
@@ -0,0 +1,29 @@
+/** Busy-Enter preference stored in the Host user-settings document. */
+
+import z from 'schemastery'
+
+/** Settings namespace owned by the conversation plugin. */
+export const CONVERSATION_SETTINGS_NAMESPACE = 'ui-conversation'
+
+/** Field carrying the delivery mode for plain Enter while an agent is busy. */
+export const BUSY_ENTER_FIELD = 'busyEnter'
+
+/** Busy-Enter behaviors accepted at settings and input boundaries. */
+export const BUSY_ENTER_BEHAVIORS = ['queue', 'steer'] as const
+
+/** Configurable meaning of plain Enter while the addressed agent is busy. */
+export type BusyEnterBehavior = typeof BUSY_ENTER_BEHAVIORS[number]
+
+/** Default preserves Enter-as-Queue for running conversations. */
+export const DEFAULT_BUSY_ENTER_BEHAVIOR: BusyEnterBehavior = 'queue'
+
+/** Durable conversation section shared by the Host schema and the browser scope. */
+export interface ConversationSettings {
+  /** Delivery mode for plain Enter while the addressed agent is busy. */
+  busyEnter: BusyEnterBehavior
+}
+
+/** Durable conversation schema; also the wire envelope the browser scope validates against. */
+export const ConversationSettingsSchema: z<ConversationSettings> = z.object({
+  [BUSY_ENTER_FIELD]: z.union([...BUSY_ENTER_BEHAVIORS]).default(DEFAULT_BUSY_ENTER_BEHAVIOR),
+})
--- a/packages/client/ui-conversation/tests/apply-inject.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.spec.tsx
@@ -47,6 +47,7 @@ function sessionFakeFor() {

 async function bench() {
  const runtime = await SlotTestRuntime.create()
+  runtime.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
  const sessionFake = sessionFakeFor()
  await runtime.sessions.add({
    id: ROOT,
--- a/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx
+++ b/packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx
@@ -50,6 +50,7 @@ function WorkspaceProbe({ open }: EmptyWorkspaceOwnerProps) {

 async function bench(opts?: { blank?: boolean }) {
  const runtime = await SlotTestRuntime.create()
+  runtime.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
  runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
  const locale = new LocaleService(runtime.ctx)
  runtime.provide('locale', locale)
@@ -74,6 +75,7 @@ async function bench(opts?: { blank?: boolean }) {
 describe('resident composer', () => {
  it('renders the locked view state while no session exists at all', async () => {
    const runtime = await SlotTestRuntime.create()
+    runtime.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
    runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
    const locale = new LocaleService(runtime.ctx)
    runtime.provide('locale', locale)
@@ -90,6 +92,7 @@ describe('resident composer', () => {

  it('keeps the complete Hero tree mounted when the first Workspace session appears', async () => {
    const runtime = await SlotTestRuntime.create()
+    runtime.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
    runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
    const locale = new LocaleService(runtime.ctx)
    runtime.provide('locale', locale)
@@ -153,6 +156,7 @@ describe('resident composer', () => {
 describe('prompt rejection through the assembled composer', () => {
  it('renders the promptError alert strip and keeps the draft in the machine', async () => {
    const runtime = await SlotTestRuntime.create()
+    runtime.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
    runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
    const locale = new LocaleService(runtime.ctx)
    runtime.provide('locale', locale)
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -21,6 +21,7 @@ const CHILD = 'child-1' as SessionId

 async function bench() {
  const runtime = await SlotTestRuntime.create()
+  runtime.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
  await runtime.sessions.add({ id: ROOT, summary: { title: 'R', displayTitle: 'R' } }, { current: false })
  await runtime.sessions.add(
    { id: CHILD, summary: { title: 'C', displayTitle: 'C', parentId: ROOT } }, { current: false })
--- a/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
+++ b/packages/client/ui-conversation/tests/coverage-tails.spec.tsx
@@ -1,8 +1,9 @@
 // @vitest-environment jsdom
-// Branch tails the acceptance specs do not reach: the node-half empty apply
-// and AssistantMarkdown reasoning/unknown block arms.
+// Branch tails the acceptance specs do not reach: the node-half apply
+// without a settings service and AssistantMarkdown reasoning/unknown block arms.

 import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
 import { cleanup, render } from '@testing-library/react'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
@@ -16,8 +17,8 @@ const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh)
 afterEach(cleanup)

 describe('tails', () => {
-  it('node-half apply is an intentional no-op', () => {
-    expect(() => { nodeApply() }).not.toThrow()
+  it('node-half apply tolerates a Host without settings', () => {
+    expect(() => { nodeApply(new Context()) }).not.toThrow()
  })

  it('AssistantMarkdown renders reasoning as a Think row and unknown blocks as JSON fallback', () => {
--- a/packages/client/ui-conversation/tests/host.spec.ts
+++ b/packages/client/ui-conversation/tests/host.spec.ts
@@ -0,0 +1,30 @@
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { Settings, settingsNamespace, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import {
+  CONVERSATION_SETTINGS_NAMESPACE, DEFAULT_BUSY_ENTER_BEHAVIOR, apply,
+} from '@deepseek-ai/dsh-client-ui-conversation'
+
+class MemorySettings extends Settings {
+  readonly writable = true
+  protected load(): Promise<Record<string, unknown>> { return Promise.resolve({}) }
+  protected persist(_ns: SettingsNamespace, _section: Record<string, unknown>): Promise<void> {
+    return Promise.resolve()
+  }
+}
+
+describe('ui-conversation host', () => {
+  it('registers, validates, and disposes the durable busy-Enter preference', async () => {
+    const ctx = new Context()
+    await ctx.plugin(MemorySettings).await()
+    const fiber = ctx.plugin({ apply })
+    await fiber.await()
+    const ns = settingsNamespace(CONVERSATION_SETTINGS_NAMESPACE)
+    expect(ctx.settings.get(ns)).toEqual({ busyEnter: DEFAULT_BUSY_ENTER_BEHAVIOR })
+    await ctx.settings.update(ns, { busyEnter: 'steer' })
+    expect(ctx.settings.get(ns)).toEqual({ busyEnter: 'steer' })
+    await expect(ctx.settings.update(ns, { busyEnter: 'invalid' })).rejects.toThrow()
+    await fiber.dispose()
+    expect(ctx.settings.describe().map(row => row.ns)).not.toContain(ns)
+  })
+})
--- a/packages/client/ui-conversation/tests/submission-policy.spec.ts
+++ b/packages/client/ui-conversation/tests/submission-policy.spec.ts
@@ -1,13 +1,10 @@
 // @vitest-environment jsdom
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
+import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
 import {
-  BUSY_ENTER_STORAGE_KEY, ComposerSubmissionPolicy, DEFAULT_BUSY_ENTER_BEHAVIOR,
+  ComposerSubmissionPolicy, DEFAULT_BUSY_ENTER_BEHAVIOR,
 } from '../src/client/input/submission-policy.ts'
-
-afterEach(() => {
-  vi.unstubAllGlobals()
-  localStorage.clear()
-})
+import type { ConversationSettings } from '../src/submission-settings.ts'

 describe('ComposerSubmissionPolicy', () => {
  it('defaults to Queue and only applies the preference while running', () => {
@@ -28,40 +25,42 @@ describe('ComposerSubmissionPolicy', () => {
    expect(policy.resolve(true, 'accelerated', true)).toBe('queue')
    expect(policy.resolve(false, 'enter', true)).toBe('queue')
    expect(policy.resolve(false, 'accelerated', true)).toBe('queue')
-    expect(localStorage.getItem(BUSY_ENTER_STORAGE_KEY)).toBe('steer')
  })

-  it('restores a valid preference and leaves an identical write untouched', () => {
-    localStorage.setItem(BUSY_ENTER_STORAGE_KEY, 'steer')
-    const write = vi.spyOn(Storage.prototype, 'setItem')
-    const policy = new ComposerSubmissionPolicy()
+  it('writes an explicit change through the scope after publishing it locally', () => {
+    const host = stubSettingsScope<ConversationSettings>()
+    const observed: string[] = []
+    let liveBehavior = (): string => 'unconstructed'
+    const scope: typeof host.scope = {
+      ...host.scope,
+      set: (field, value) => {
+        observed.push(`${field}=${String(value)}:${liveBehavior()}`)
+        return host.scope.set(field, value)
+      },
+    }
+    const policy = new ComposerSubmissionPolicy(scope)
+    liveBehavior = () => policy.busyEnter.getSnapshot()
+    policy.setBusyEnter('steer')
+    expect(observed).toEqual(['busyEnter=steer:steer'])
+    expect(host.set).toHaveBeenCalledWith('busyEnter', 'steer')
+    expect(host.set).toHaveBeenCalledOnce()
+  })
+
+  it('adopts a Host preference without writing it back and leaves an identical write untouched', () => {
+    const host = stubSettingsScope<ConversationSettings>()
+    const policy = new ComposerSubmissionPolicy(host.scope)
+    host.publish({ status: 'ready', value: { busyEnter: 'steer' }, revision: 1, writable: true })
    expect(policy.busyEnter.getSnapshot()).toBe('steer')
    policy.setBusyEnter('steer')
-    expect(write).not.toHaveBeenCalled()
-    write.mockRestore()
+    expect(host.set).not.toHaveBeenCalled()
+    host.publish({ value: { busyEnter: 'steer' }, revision: 2 })
+    expect(policy.busyEnter.getSnapshot()).toBe('steer')
  })

-  it('uses Queue for invalid, unavailable, or unreadable storage', () => {
-    localStorage.setItem(BUSY_ENTER_STORAGE_KEY, 'invalid')
-    expect(new ComposerSubmissionPolicy().busyEnter.getSnapshot()).toBe('queue')
-
-    vi.stubGlobal('localStorage', undefined)
-    expect(new ComposerSubmissionPolicy().busyEnter.getSnapshot()).toBe('queue')
-
-    vi.stubGlobal('localStorage', {
-      getItem: () => { throw new Error('blocked') },
-      setItem: vi.fn(),
-    })
-    expect(new ComposerSubmissionPolicy().busyEnter.getSnapshot()).toBe('queue')
-  })
-
-  it('keeps the in-memory preference when persistence throws', () => {
-    vi.stubGlobal('localStorage', {
-      getItem: () => null,
-      setItem: () => { throw new Error('quota') },
-    })
-    const policy = new ComposerSubmissionPolicy()
-    policy.setBusyEnter('steer')
+  it('adopts a section already standing at construction', () => {
+    const host = stubSettingsScope<ConversationSettings>()
+    host.publish({ status: 'ready', value: { busyEnter: 'steer' }, revision: 1, writable: true })
+    const policy = new ComposerSubmissionPolicy(host.scope)
    expect(policy.busyEnter.getSnapshot()).toBe('steer')
  })
 })
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -17,6 +17,9 @@
    {
      "path": "../../../vendor/cordis"
    },
+    {
+      "path": "../connection"
+    },
    {
      "path": "../ui-slots"
    },
@@ -65,6 +68,9 @@
    {
      "path": "../locale"
    },
+    {
+      "path": "../../settings/settings"
+    },
    {
      "path": "../../support/invariants"
    },
--- a/packages/client/ui-deliverables/tests/produced-files.spec.tsx
+++ b/packages/client/ui-deliverables/tests/produced-files.spec.tsx
@@ -340,6 +340,7 @@ describe('plugin registration', () => {
      name: 'root',
      children: { 'conversation.chat.turnTail': { kind: 'chain', scope: 'session' } },
    } as never, () => null)
+    ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
    await ctx.plugin({ inject: ['slots'], apply: applyLocale }).await()

    const fiber = ctx.plugin({ inject: [...inject], apply })
--- a/packages/client/ui-layout/tests/apply.spec.ts
+++ b/packages/client/ui-layout/tests/apply.spec.ts
@@ -22,9 +22,10 @@ beforeEach(() => {
 async function bench() {
  const ctx = new Context()
  const slotsFiber = ctx.plugin(SlotsService)
-  // Theme now injects ['slots', 'locale'] (it registers its Appearance
-  // settings row); seat a real locale service so the theme fiber activates.
+  // Theme registers its Appearance settings row and requires the connection
+  // seam for persistence; model this bench as a remote, memory-only browser.
  ctx.provide('locale', new LocaleService(ctx))
+  ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
  await ctx.plugin({ inject: themeInject, apply: themeApply }).await()
  await slotsFiber.await()
  return { ctx, slots: ctx.get('slots') as SlotsService }
--- a/packages/client/ui-subagent/tests/browser-plugin.spec.ts
+++ b/packages/client/ui-subagent/tests/browser-plugin.spec.ts
@@ -20,7 +20,7 @@ import {
 import type { ComposerChainProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import { SlashService } from '@deepseek-ai/dsh-client-ui-slash/client'
 import type { ClientSessionContext, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
-import { apply as applyLocale } from '@deepseek-ai/dsh-client-locale/client'
+import { apply as applyLocale, inject as localeInject } from '@deepseek-ai/dsh-client-locale/client'
 import {
  SubagentCatalogAction, type SubagentCatalogInjected,
 } from '../src/client/SubagentCatalogAction.tsx'
@@ -86,8 +86,9 @@ async function fullBench(sessions: SessionSummary[]) {
  const face = sessionsWith(sessions)
  ctx.provide('slash', { registerSource: (src: SlashSource) => { captured = src; return () => {} } })
  ctx.provide('sessions', face)
+  ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
  await provideSlotFaces(ctx)
-  await ctx.plugin({ inject: ['slots'], apply: applyLocale }).await()
+  await ctx.plugin({ inject: localeInject, apply: applyLocale }).await()
  await ctx.plugin({ inject: [...inject], apply }).await()
  return { source: captured!, face, ctx }
 }
@@ -121,8 +122,9 @@ describe('apply', () => {
    const ctx = new Context()
    await ctx.plugin(SlashService).await()
    ctx.provide('sessions', sessionsWith(FAMILY))
+    ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
    await provideSlotFaces(ctx)
-    await ctx.plugin({ inject: ['slots'], apply: applyLocale }).await()
+    await ctx.plugin({ inject: localeInject, apply: applyLocale }).await()
    const fiber = ctx.plugin({ inject: [...inject], apply })
    await fiber.await()
    const slash = ctx.get('slash') as SlashService
--- a/packages/client/ui-theme/README.i18n.yaml
+++ b/packages/client/ui-theme/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-theme/README.md
-README.md: 2d576cc16b0b8fef453ad54cacd9cb195dc75e7a
-README.zh.md: b1f17c65749a94f1f48b5f7af9c8b18a5d85eb76
+README.md: 7b81728b02c0dadcbd134a4bca20c49721a3dd52
+README.zh.md: 81b64c356749b6ffe12694b218e92eaa483ff739
--- a/packages/client/ui-theme/README.md
+++ b/packages/client/ui-theme/README.md
@@ -2,7 +2,7 @@

 English | [中文](README.zh.md)

-Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers). The service owns the theme preference (`light`/`dark`/`system`, persisted under `dsh.theme`), resolves `system` through `prefers-color-scheme`, and publishes immutable `ThemeSnapshot`s on the `theme/change` event; it never touches the DOM — ui-layout's presenter applies the resolved snapshot (`html { color-scheme }`, `body[data-ds-dark-theme]`, and inline alias tokens).
+Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers). The service owns the live theme preference (`light`/`dark`/`system`), resolves `system` through `prefers-color-scheme`, and publishes immutable `ThemeSnapshot`s on the `theme/change` event; it never touches the DOM — ui-layout's presenter applies the resolved snapshot (`html { color-scheme }`, `body[data-ds-dark-theme]`, and inline alias tokens). A loopback browser provides the service immediately with `system`, then loads `ui-theme.preference` in the background and writes each built-in selection through the Host settings API, whose local provider stores it in `$DSH_HOME/settings.yaml` by default; pushed settings changes and reconnects refetch it, rapid selections are serialized in gesture order with namespace revisions, and a rejected latest write reloads the durable value. A remote browser cannot access the privileged settings API, so its selection remains process-local. Third-party registered theme ids remain an in-process extension and do not cross the built-in settings schema; removing one never overwrites the last durable built-in preference. The [Host-backed preferences decision](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md) owns the persistence boundary.

 `src/styles/` holds five sheets, all imported by the web shell's `base.css`: `base.css`, `design-platform.css`, `scrollbar.css`, `gradient-shadow-text.css`, and `shiki.css`. `scrollbar.css` is the sole consumer of the `--dsw-alias-scrollbar-*` tokens and must follow `design-platform.css`, which declares them.

--- a/packages/client/ui-theme/README.zh.md
+++ b/packages/client/ui-theme/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。
+主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有实时主题偏好（`light`／`dark`／`system`），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。来自回环地址的浏览器会先以 `system` 立即提供该服务，随后在后台加载 `ui-theme.preference`，并将每次内置主题选择通过 Host settings API 写入；其本地提供方默认将设置存入 `$DSH_HOME/settings.yaml`。收到推送的 settings 变更时或重连后，浏览器都会重新拉取该设置；连续快速选择会按操作顺序携带 namespace revision 串行写入，最新写入被拒时则重新加载持久化值。远程浏览器无法访问特权 settings API，因此它的选择仅保留在进程内。已注册的第三方主题 id 仍是进程内扩展，不会跨越内置 settings schema；移除其中任意一个都绝不会覆盖最后一个持久化的内置偏好。该持久化边界由[Host settings 支撑的偏好决策](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md)拥有。

 `src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。

--- a/packages/client/ui-theme/package.json
+++ b/packages/client/ui-theme/package.json
@@ -25,6 +25,7 @@
  },
  "dshClient": {
    "inject": [
+      "@deepseek-ai/dsh-client-connection",
      "@deepseek-ai/dsh-client-runtime",
      "@deepseek-ai/dsh-client-locale"
    ],
@@ -33,6 +34,7 @@
  },
  "license": "BSD-3-Clause",
  "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
    "@deepseek-ai/dsh-client-locale": "^0.0.1",
    "@deepseek-ai/dsh-client-runtime": "^0.0.1",
    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1",
@@ -64,6 +66,8 @@
    "watch": "tsdown --watch"
  },
  "dependencies": {
-    "clsx": "^2.0.0"
+    "@deepseek-ai/dsh-settings": "workspace:^",
+    "clsx": "^2.0.0",
+    "schemastery": "^3.18.0"
  }
 }
--- a/packages/client/ui-theme/src/client/AppearanceRow.tsx
+++ b/packages/client/ui-theme/src/client/AppearanceRow.tsx
@@ -10,7 +10,7 @@ import {
  IconDarkOutline16, IconFollowsystemOutline16, IconLightOutline16,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ThemePreference } from './index.ts'
+import type { ThemePreference } from '../theme-settings.ts'
 import type { ThemeKey } from './locales.ts'
 import type {} from './settings-contract.ts'
 import type { createAppearanceRowStore } from './settings-store.ts'
--- a/packages/client/ui-theme/src/client/index.ts
+++ b/packages/client/ui-theme/src/client/index.ts
@@ -1,24 +1,32 @@
 /**
 * Browser theme registry over the `--dsw-*` token stylesheets. The service
- * owns the theme preference (light/dark/system), resolves `system` through
+ * owns the live theme preference (light/dark/system), resolves `system` through
 * `prefers-color-scheme`, and publishes immutable snapshots; it never touches
- * the DOM — ui-layout's presenter consumes the resolved snapshot. The plugin
- * also registers the Appearance preference row into the settings General
- * section — the theme feature owns its own settings surface.
+ * the DOM — ui-layout's presenter consumes the resolved snapshot. The Host
+ * settings scope loads and stores the preference in the user-settings
+ * document. The plugin also registers the Appearance preference row into the
+ * settings General section — the theme feature owns its own settings surface.
 */
 import type { Context } from 'cordis'
 import type { BoundActions } from '@deepseek-ai/dsh-client-ui-slots'
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  bindSettingsScope, type ClientContext, type SettingsScope,
+} from '@deepseek-ai/dsh-client-runtime/client'
 // Type-only: pulls the locale plugin's Context merge (ctx.locale).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type { AppearanceRowInjected } from './AppearanceRow.tsx'
 import { AppearanceRow } from './AppearanceRow.tsx'
 import { createAppearanceRowStore } from './settings-store.ts'
 import { en, zh, type ThemeKey } from './locales.ts'
+import {
+  DEFAULT_PREFERENCE, isThemePreference, THEME_PREFERENCE_FIELD, THEME_SETTINGS_NAMESPACE,
+  type ThemePreference, type ThemeSettings,
+} from '../theme-settings.ts'

 export type { AppearanceRowComponentProps, AppearanceRowInjected } from './AppearanceRow.tsx'
 export type { AppearanceRowState } from './settings-store.ts'
 export type { ThemeKey } from './locales.ts'
+export type { ThemePreference, ThemeSettings } from '../theme-settings.ts'

 /** Namespace owning this feature's settings-row copy. */
 export const SETTINGS_NS = 'settings.theme'
@@ -33,9 +41,6 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 /** Theme token dictionary: --dsw-alias-* overrides keyed by variable name. */
 export type ThemeTokens = Record<string, string>

-/** Theme preference: a concrete theme id or follow-the-OS. */
-export type ThemePreference = 'light' | 'dark' | 'system'
-
 /** One selectable theme: id, dark/light semantics, and alias-token overrides. */
 export interface ThemeDefinition {
  /** Theme id (the setTheme argument for concrete themes). */
@@ -76,12 +81,6 @@ declare module 'cordis' {
  }
 }

-/** localStorage key holding the persisted theme preference. */
-export const STORAGE_KEY = 'dsh.theme'
-
-/** Default preference when nothing (or garbage) is persisted. */
-export const DEFAULT_PREFERENCE: ThemePreference = 'system'
-
 const BUILTIN_THEMES: readonly ThemeDefinition[] = Object.freeze([
  Object.freeze({ id: 'light', colorScheme: 'light' as const, tokens: Object.freeze({}) }),
  Object.freeze({ id: 'dark', colorScheme: 'dark' as const, tokens: Object.freeze({}) }),
@@ -98,6 +97,7 @@ const BUILTIN_THEMES: readonly ThemeDefinition[] = Object.freeze([
 */
 export class ThemeService {
  private readonly ctx: Context
+  private readonly host: SettingsScope<ThemeSettings>
  private themes: ThemeDefinition[] = [...BUILTIN_THEMES]
  private preference: ThemePreference
  private revision = 0
@@ -106,11 +106,13 @@ export class ThemeService {

  /**
   * @param ctx - owning context (change events are emitted on it; the
-   * media-query listener is released through ctx.effect on dispose).
+   * media-query and scope listeners are released through ctx.effect on dispose).
+   * @param host - durable preference scope owned by the same plugin.
   */
-  constructor(ctx: Context) {
+  constructor(ctx: Context, host: SettingsScope<ThemeSettings>) {
    this.ctx = ctx
-    this.preference = restorePreference()
+    this.host = host
+    this.preference = DEFAULT_PREFERENCE
    // Non-browser runs (node e2e booting the client tree) have no matchMedia.
    this.media = typeof matchMedia === 'undefined' ? undefined : matchMedia('(prefers-color-scheme: dark)')
    this.snapshot = this.buildSnapshot()
@@ -125,6 +127,8 @@ export class ThemeService {
        return () => { media.removeEventListener('change', onChange) }
      }, 'ui-theme: prefers-color-scheme listener')
    }
+    ctx.effect(() => host.subscribe(() => { this.adopt() }), 'ui-theme: settings scope adoption')
+    this.adopt()
  }

  /**
@@ -136,8 +140,9 @@ export class ThemeService {
  }

  /**
-   * Switch the theme preference — the only preference write entry. Persists
-   * the preference and emits `theme/change`.
+   * Switch the theme preference — the only user preference write entry.
+   * Built-in preferences are written through the settings scope and every
+   * accepted value emits `theme/change`.
   * @param id - a registered theme id or `system`; unknown ids throw.
   */
  setTheme(id: string): void {
@@ -146,7 +151,15 @@ export class ThemeService {
    }
    if (this.preference === id) return
    this.preference = id as ThemePreference
-    persistPreference(this.preference)
+    if (isThemePreference(id)) void this.host.set(THEME_PREFERENCE_FIELD, id)
+    this.publish()
+  }
+
+  /** Adopt the scope's accepted durable preference without writing it back. */
+  private adopt(): void {
+    const section = this.host.getSnapshot().value
+    if (section === undefined || this.preference === section.preference) return
+    this.preference = section.preference
    this.publish()
  }

@@ -170,7 +183,6 @@ export class ThemeService {
      this.themes = this.themes.filter(t => t.id !== definition.id)
      if (this.preference === definition.id) {
        this.preference = DEFAULT_PREFERENCE
-        persistPreference(this.preference)
      }
      this.publish()
    }
@@ -200,32 +212,8 @@ export class ThemeService {
  }
 }

-/** Read the persisted preference; unknown or unreadable values fall back to the default. */
-function restorePreference(): ThemePreference {
-  // Non-browser runs (node e2e booting the client tree) have no localStorage.
-  if (typeof localStorage === 'undefined') return DEFAULT_PREFERENCE
-  try {
-    const stored = localStorage.getItem(STORAGE_KEY)
-    if (stored === 'light' || stored === 'dark' || stored === 'system') return stored
-  } catch {
-    // Storage access can throw (privacy mode); the default below covers it.
-  }
-  return DEFAULT_PREFERENCE
-}
-
-/** Persist the preference; storage failures are non-fatal (preference resets next boot). */
-function persistPreference(preference: ThemePreference): void {
-  if (typeof localStorage === 'undefined') return
-  try {
-    localStorage.setItem(STORAGE_KEY, preference)
-  } catch {
-    // Storage access can throw (privacy mode / quota); the preference simply
-    // does not survive the session.
-  }
-}
-
-/** Required services: slots + locale (the feature registers its own settings row with localized copy). */
-export const inject = ['slots', 'locale']
+/** Required services: settings transport plus slots/locale for the Appearance row. */
+export const inject = ['slots', 'locale', 'connection']

 /**
 * Client plugin body: provide the theme service and register the
@@ -234,7 +222,8 @@ export const inject = ['slots', 'locale']
 * @param ctx - client cordis context.
 */
 export function apply(ctx: ClientContext): void {
-  const theme = new ThemeService(ctx)
+  const host = bindSettingsScope<ThemeSettings>(ctx, { namespace: THEME_SETTINGS_NAMESPACE })
+  const theme = new ThemeService(ctx, host)
  ctx.provide('theme', theme)

  ctx.effect(() => ctx.locale.register(SETTINGS_NS, { zh, en }), 'ui-theme: settings row dictionaries')
--- a/packages/client/ui-theme/src/client/settings-store.ts
+++ b/packages/client/ui-theme/src/client/settings-store.ts
@@ -4,7 +4,7 @@
 * reads via props.useStore.
 */
 import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ThemePreference } from './index.ts'
+import type { ThemePreference } from '../theme-settings.ts'

 /** Store state mirrored from the theme snapshot. */
 export interface AppearanceRowState {
--- a/packages/client/ui-theme/src/index.ts
+++ b/packages/client/ui-theme/src/index.ts
@@ -1,4 +1,23 @@
-/** Host loader entry for the browser implementation exported from `./client`. */
+/** Host registration for the browser theme preference. */

-/** Host plugin body — no host-side behavior for the theme plugin. */
-export function apply(): void {}
+import type { Context } from 'cordis'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { THEME_SETTINGS_NAMESPACE, ThemeSettingsSchema } from './theme-settings.ts'
+
+export {
+  DEFAULT_PREFERENCE, THEME_PREFERENCE_FIELD, THEME_PREFERENCES, THEME_SETTINGS_NAMESPACE,
+  type ThemePreference, type ThemeSettings,
+} from './theme-settings.ts'
+
+/**
+ * Register the durable theme section when a settings provider exists.
+ * @param ctx - Host context whose optional settings service owns the section.
+ */
+export function apply(ctx: Context): void {
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.register(
+      settingsNamespace(THEME_SETTINGS_NAMESPACE),
+      ThemeSettingsSchema,
+    )
+  })
+}
--- a/packages/client/ui-theme/src/invariant.ts
+++ b/packages/client/ui-theme/src/invariant.ts
@@ -15,10 +15,10 @@ export const name = 'client-ui-theme-invariant'
 export const inject = ['invariants']

 /**
- * No runtime invariant: the theme registry publishes immutable snapshots on
- * its own `theme/change` event synchronously with the setter/registry
- * mutation in the same service — snapshot/event agreement is asserted
- * directly by this package's behavior specs.
+ * No runtime invariant: the settings scope validates and publishes the durable
+ * theme section, while the registry emits `theme/change` synchronously with
+ * its own mutations. Store/registry agreement is covered directly by this
+ * package's Host, scope, and service behavior specs.
 */
 const install: InvariantInstaller = () => {}

--- a/packages/client/ui-theme/src/theme-settings.ts
+++ b/packages/client/ui-theme/src/theme-settings.ts
@@ -0,0 +1,38 @@
+/** Theme preferences stored in the Host user-settings document. */
+
+import z from 'schemastery'
+
+/** Built-in preferences accepted at the registry and settings boundaries. */
+export const THEME_PREFERENCES = ['light', 'dark', 'system'] as const
+
+/** Settings namespace owned by the theme plugin. */
+export const THEME_SETTINGS_NAMESPACE = 'ui-theme'
+
+/** Field carrying the selected built-in theme preference. */
+export const THEME_PREFERENCE_FIELD = 'preference'
+
+/** Theme preference persisted by the product Appearance row. */
+export type ThemePreference = typeof THEME_PREFERENCES[number]
+
+/** Default preference when the user-settings document has no override. */
+export const DEFAULT_PREFERENCE: ThemePreference = 'system'
+
+/** Durable theme section shared by the Host schema and the browser scope. */
+export interface ThemeSettings {
+  /** Selected built-in preference. */
+  preference: ThemePreference
+}
+
+/** Durable theme schema; also the wire envelope the browser scope validates against. */
+export const ThemeSettingsSchema: z<ThemeSettings> = z.object({
+  [THEME_PREFERENCE_FIELD]: z.union([...THEME_PREFERENCES]).default(DEFAULT_PREFERENCE),
+})
+
+/**
+ * Narrow one wire or registry value to a persistable preference.
+ * @param value - value crossing the settings or registry boundary.
+ * @returns whether the value is a built-in preference.
+ */
+export function isThemePreference(value: unknown): value is ThemePreference {
+  return THEME_PREFERENCES.some(preference => preference === value)
+}
--- a/packages/client/ui-theme/tests/apply.spec.ts
+++ b/packages/client/ui-theme/tests/apply.spec.ts
@@ -2,12 +2,13 @@
 * locale service, declaration-aware Appearance row registration, snapshot
 * projection into the row store, and HMR collapse recovery. */
 import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject, SETTINGS_NS } from '@deepseek-ai/dsh-client-ui-theme/client'
 import type { AppearanceRowInjected, ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
+import { THEME_SETTINGS_NAMESPACE, ThemeSettingsSchema } from '../src/theme-settings.ts'
 import { AppearanceRow } from '../src/client/AppearanceRow.tsx'
 import type { createAppearanceRowStore } from '../src/client/settings-store.ts'

@@ -17,12 +18,45 @@ usePinnedBrowserLanguages('zh-CN')

 const SLOT = 'settings.general.item'

-async function bench() {
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((done) => { resolve = done })
+  return { promise, resolve }
+}
+
+async function bench(isLoopback = true) {
  const ctx = new Context()
  await ctx.plugin(SlotsService).await()
  const locale = new LocaleService(ctx)
  ctx.provide('locale', locale)
-  return { ctx, slots: ctx.get('slots') as SlotsService, locale }
+  let preference = 'system'
+  const namespace = () => ({
+    ns: THEME_SETTINGS_NAMESPACE,
+    schema: ThemeSettingsSchema.toJSON(),
+    value: { preference },
+    applies: 'live' as const,
+    secrets: [],
+    revision: 0,
+  })
+  const describe = vi.fn(() => Promise.resolve({
+    rpcId: 'theme-describe' as never,
+    result: {
+      ok: true as const,
+      value: { writable: true, hasDocument: true, namespaces: [namespace()] },
+    },
+  }))
+  const mutate = vi.fn((request: { ops: { value: string }[] }) => {
+    preference = request.ops[0]!.value
+    return Promise.resolve({
+      rpcId: 'theme-mutate' as never,
+      result: { ok: true as const, value: namespace() },
+    })
+  })
+  ctx.provide('connection', { api: { settings: { describe, mutate } }, isLoopback } as never)
+  return {
+    ctx, slots: ctx.get('slots') as SlotsService, locale, describe, mutate,
+    setHostPreference: (next: string) => { preference = next },
+  }
 }

 /** Stand in for the settings shell: declare the General item slot from root. */
@@ -45,7 +79,7 @@ function faceOf(slots: SlotsService) {

 describe('ui-theme apply', () => {
  it('declares the slot and locale services', () => {
-    expect(inject).toEqual(['slots', 'locale'])
+    expect(inject).toEqual(['slots', 'locale', 'connection'])
  })

  it('provides the service, registers localized copy, and registers the row (declaration before or after apply)', async () => {
@@ -84,6 +118,57 @@ describe('ui-theme apply', () => {
    face.setTheme('system')
    expect(theme.getTheme().preference).toBe('system')
    expect(instance.getSnapshot().preference).toBe('system')
+    await vi.waitFor(() => { expect(b.mutate).toHaveBeenCalledTimes(2) })
+  })
+
+  it('loads Host settings at boot, refreshes its namespace, and keeps remote browsers process-local', async () => {
+    const b = await bench()
+    b.setHostPreference('dark')
+    declareItems(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const theme = b.ctx.get('theme') as ThemeService
+    await vi.waitFor(() => { expect(theme.getTheme().preference).toBe('dark') })
+    b.ctx.emit('settings/changed', 'unrelated')
+    expect(b.describe).toHaveBeenCalledOnce()
+    b.setHostPreference('light')
+    b.ctx.emit('settings/changed', THEME_SETTINGS_NAMESPACE)
+    await vi.waitFor(() => { expect(theme.getTheme().preference).toBe('light') })
+    b.setHostPreference('dark')
+    b.ctx.emit('connection/reset')
+    await vi.waitFor(() => { expect(theme.getTheme().preference).toBe('dark') })
+
+    const remote = await bench(false)
+    declareItems(remote.slots)
+    await remote.ctx.plugin({ inject: [...inject], apply }).await()
+    const remoteTheme = remote.ctx.get('theme') as ThemeService
+    remoteTheme.setTheme('dark')
+    await Promise.resolve()
+    expect(remote.describe).not.toHaveBeenCalled()
+    expect(remote.mutate).not.toHaveBeenCalled()
+  })
+
+  it('activates before a slow initial settings read and converges when it settles', async () => {
+    const b = await bench()
+    b.setHostPreference('dark')
+    const describe = b.describe.getMockImplementation()!
+    const pending = deferred<Awaited<ReturnType<typeof describe>>>()
+    b.describe.mockImplementationOnce(() => pending.promise)
+    const fiber = b.ctx.plugin({ inject: [...inject], apply })
+    await fiber.await()
+    const theme = b.ctx.get('theme') as ThemeService
+    expect(theme.getTheme().preference).toBe('system')
+    pending.resolve(await describe())
+    await vi.waitFor(() => { expect(theme.getTheme().preference).toBe('dark') })
+    await fiber.dispose()
+  })
+
+  it('ignores an invalid preference crossing the settings wire', async () => {
+    const b = await bench()
+    b.setHostPreference('sepia')
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const theme = b.ctx.get('theme') as ThemeService
+    await vi.waitFor(() => { expect(b.describe).toHaveBeenCalledOnce() })
+    expect(theme.getTheme().preference).toBe('system')
  })

  it('recovers after an HMR collapse of the declaring entry (stale disposer must not block)', async () => {
--- a/packages/client/ui-theme/tests/host.spec.ts
+++ b/packages/client/ui-theme/tests/host.spec.ts
@@ -0,0 +1,30 @@
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import { Settings, settingsNamespace, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import {
+  DEFAULT_PREFERENCE, THEME_SETTINGS_NAMESPACE, apply,
+} from '@deepseek-ai/dsh-client-ui-theme'
+
+class MemorySettings extends Settings {
+  readonly writable = true
+  protected load(): Promise<Record<string, unknown>> { return Promise.resolve({}) }
+  protected persist(_ns: SettingsNamespace, _section: Record<string, unknown>): Promise<void> {
+    return Promise.resolve()
+  }
+}
+
+describe('ui-theme host', () => {
+  it('registers, validates, and disposes the durable theme namespace with its fiber', async () => {
+    const ctx = new Context()
+    await ctx.plugin(MemorySettings).await()
+    const fiber = ctx.plugin({ apply })
+    await fiber.await()
+    const ns = settingsNamespace(THEME_SETTINGS_NAMESPACE)
+    expect(ctx.settings.get(ns)).toEqual({ preference: DEFAULT_PREFERENCE })
+    await ctx.settings.update(ns, { preference: 'dark' })
+    expect(ctx.settings.get(ns)).toEqual({ preference: 'dark' })
+    await expect(ctx.settings.update(ns, { preference: 'sepia' })).rejects.toThrow()
+    await fiber.dispose()
+    expect(ctx.settings.describe().map(row => row.ns)).not.toContain(ns)
+  })
+})
--- a/packages/client/ui-theme/tests/invariant.spec.ts
+++ b/packages/client/ui-theme/tests/invariant.spec.ts
@@ -4,7 +4,7 @@ import { Context } from 'cordis'
 import { apply as nodeApply } from '@deepseek-ai/dsh-client-ui-theme'
 import { apply as clientApply, inject, ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
 import * as ThemeInvariant from '@deepseek-ai/dsh-client-ui-theme/invariant'
-import { apply as localeApply } from '@deepseek-ai/dsh-client-locale/client'
+import { apply as localeApply, inject as localeInject } from '@deepseek-ai/dsh-client-locale/client'
 import { SlotsService } from '@deepseek-ai/dsh-client-runtime/client'
 import InvariantService from '@deepseek-ai/dsh-invariants'

@@ -15,18 +15,25 @@ describe('invariant companion', () => {
    await expect(ctx.plugin(ThemeInvariant).await()).resolves.toBeDefined()
  })

-  it('node-half apply is a no-op host placeholder', () => {
-    nodeApply()
-    expect(true).toBe(true) // reaching here without throw is the contract
+  it('node-half waits for an optional settings provider', () => {
+    nodeApply(new Context())
+    expect(true).toBe(true)
  })

  it('client apply provides ctx.theme over the slots/locale edges', async () => {
    // The feature registers its own Appearance settings row with localized
    // copy, hence the slots + locale edges.
-    expect(inject).toEqual(['slots', 'locale'])
+    expect(inject).toEqual(['slots', 'locale', 'connection'])
    const ctx = new Context()
    new SlotsService(ctx)
-    await ctx.plugin({ inject: ['slots'], apply: localeApply }).await()
+    ctx.provide('connection', {
+      api: { settings: { describe: () => Promise.resolve({
+        rpcId: 'theme-invariant' as never,
+        result: { ok: true, value: { writable: true, hasDocument: false, namespaces: [] } },
+      }) } },
+      isLoopback: true,
+    } as never)
+    await ctx.plugin({ inject: localeInject, apply: localeApply }).await()
    await ctx.plugin({ inject, apply: clientApply }).await()
    expect(ctx.get('theme')).toBeInstanceOf(ThemeService)
  })
--- a/packages/client/ui-theme/tests/theme.spec.ts
+++ b/packages/client/ui-theme/tests/theme.spec.ts
@@ -1,21 +1,23 @@
 // @vitest-environment jsdom
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
-import { STORAGE_KEY, ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'
+import { stubSettingsScope, type StubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
+import type { ThemeSettings, ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
+import { ThemeService } from '@deepseek-ai/dsh-client-ui-theme/client'

-const make = (): { ctx: Context; theme: ThemeService; events: ThemeSnapshot[] } => {
+const make = (host = stubSettingsScope<ThemeSettings>()): {
+  ctx: Context
+  theme: ThemeService
+  events: ThemeSnapshot[]
+  host: StubSettingsScope<ThemeSettings>
+} => {
  const ctx = new Context()
  const events: ThemeSnapshot[] = []
  ctx.on('theme/change', (snapshot) => { events.push(snapshot) })
-  return { ctx, theme: new ThemeService(ctx), events }
+  return { ctx, theme: new ThemeService(ctx, host.scope), events, host }
 }

 describe('ThemeService', () => {
-  beforeEach(() => {
-    localStorage.clear()
-  })
-
  it('defaults to the system preference resolved against prefers-color-scheme', () => {
    const { theme } = make()
    const snapshot = theme.getTheme()
@@ -26,12 +28,12 @@ describe('ThemeService', () => {
    expect(snapshot.themes.map(t => t.id)).toEqual(['light', 'dark'])
  })

-  it('setTheme switches, persists, republishes, and keeps DOM untouched', () => {
-    const { theme, events } = make()
+  it('setTheme switches, writes through the scope, republishes, and keeps DOM untouched', () => {
+    const { theme, events, host } = make()
    theme.setTheme('dark')
    expect(theme.getTheme().preference).toBe('dark')
    expect(theme.getTheme().active.colorScheme).toBe('dark')
-    expect(localStorage.getItem(STORAGE_KEY)).toBe('dark')
+    expect(host.set).toHaveBeenCalledWith('preference', 'dark')
    expect(events).toHaveLength(1)
    expect(events[0]).toBe(theme.getTheme())
    // The service never touches presentation state.
@@ -39,13 +41,24 @@ describe('ThemeService', () => {
    // Same-value set is a no-op (no extra event).
    theme.setTheme('dark')
    expect(events).toHaveLength(1)
+    expect(host.set).toHaveBeenCalledOnce()
  })

-  it('restores a persisted preference and falls back on garbage', () => {
-    localStorage.setItem(STORAGE_KEY, 'dark')
-    expect(make().theme.getTheme().preference).toBe('dark')
-    localStorage.setItem(STORAGE_KEY, 'sepia')
-    expect(make().theme.getTheme().preference).toBe('system')
+  it('adopts a published Host section without writing it back', () => {
+    const { theme, events, host } = make()
+    host.publish({ status: 'ready', value: { preference: 'dark' }, revision: 1, writable: true })
+    expect(theme.getTheme().preference).toBe('dark')
+    expect(events).toHaveLength(1)
+    expect(host.set).not.toHaveBeenCalled()
+    host.publish({ value: { preference: 'dark' }, revision: 2 })
+    expect(events).toHaveLength(1)
+  })
+
+  it('adopts a section already standing at construction', () => {
+    const host = stubSettingsScope<ThemeSettings>()
+    host.publish({ status: 'ready', value: { preference: 'dark' }, revision: 1, writable: true })
+    const { theme } = make(host)
+    expect(theme.getTheme().preference).toBe('dark')
  })

  it('throws on unknown setTheme ids, duplicate registration, and the system id', () => {
@@ -56,7 +69,7 @@ describe('ThemeService', () => {
  })

  it('registered themes join the snapshot; disposing the active one resets to default', () => {
-    const { theme, events } = make()
+    const { theme, events, host } = make()
    const dispose = theme.register({ id: 'sepia', colorScheme: 'light', tokens: { '--dsw-alias-bg-base': 'red' } })
    expect(theme.getTheme().themes.map(t => t.id)).toEqual(['light', 'dark', 'sepia'])
    theme.setTheme('sepia')
@@ -64,7 +77,9 @@ describe('ThemeService', () => {
    dispose()
    expect(theme.getTheme().preference).toBe('system')
    expect(theme.getTheme().themes.map(t => t.id)).toEqual(['light', 'dark'])
-    expect(localStorage.getItem(STORAGE_KEY)).toBe('system')
+    // Custom ids are in-process extension themes; only the built-in product
+    // preferences cross the Host settings schema.
+    expect(host.set).not.toHaveBeenCalled()
    // register + set + dispose = three publishes; disposer is idempotent.
    expect(events.length).toBe(3)
    dispose()
@@ -88,16 +103,11 @@ describe('ThemeService', () => {
    expect(events.map(e => e.revision)).toEqual([1, 2, 3, 4])
  })

-  it('runs without localStorage (node boots): defaults on read, no-op on write', () => {
-    vi.stubGlobal('localStorage', undefined)
-    try {
-      const { theme } = make()
-      expect(theme.getTheme().preference).toBe('system')
-      theme.setTheme('dark')
-      expect(theme.getTheme().preference).toBe('dark')
-    } finally {
-      vi.unstubAllGlobals()
-    }
+  it('context dispose releases the scope subscription', async () => {
+    const { ctx, host } = make()
+    expect(host.listenerCount()).toBe(1)
+    await ctx.fiber.dispose()
+    expect(host.listenerCount()).toBe(0)
  })

  describe('prefers-color-scheme resolution (stubbed matchMedia)', () => {
--- a/packages/client/ui-theme/tsconfig.json
+++ b/packages/client/ui-theme/tsconfig.json
@@ -23,6 +23,9 @@
    {
      "path": "../../../vendor/cordis"
    },
+    {
+      "path": "../../settings/settings"
+    },
    {
      "path": "../../support/invariants"
    }
--- a/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
+++ b/packages/client/ui-tool/tests/assembly-surfaces.spec.tsx
@@ -68,6 +68,7 @@ const LAYOUT_CHILDREN = {

 async function bench(nodes: ToolResultNode[]) {
  const runtime = await SlotTestRuntime.create()
+  runtime.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
  runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
  const locale = new LocaleService(runtime.ctx)
  runtime.provide('locale', locale)
--- a/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.spec.tsx
@@ -155,6 +155,7 @@ async function bench(snapshot: ConversationSnapshot) {
  }
  ctx.provide('workspaces', workspaces)
  ctx.provide('layout', layout)
+  ctx.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
  const locale = new LocaleService(ctx)
  ctx.provide('locale', locale)
  slots.installLocale(locale)
--- a/packages/client/ui-tool/tests/toolview-slot.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.spec.tsx
@@ -64,6 +64,7 @@ const LAYOUT_CHILDREN = {
 */
 async function bench(nodes: ToolResultNode[]) {
  const runtime = await SlotTestRuntime.create()
+  runtime.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
  const layout = { openDetails: vi.fn(), closeDetails: vi.fn() }
  runtime.provide('layout', layout)
  const locale = new LocaleService(runtime.ctx)
@@ -196,6 +197,7 @@ describe('keyed toolview hole through the real machinery', () => {
 describe('registrant declaration injection', () => {
  it('runs a registrant before ui-tool and waits on the actual toolview declaration', async () => {
    const runtime = await SlotTestRuntime.create()
+    runtime.provide('connection', { api: { settings: {} }, isLoopback: false } as never)
    runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
    const locale = new LocaleService(runtime.ctx)
    runtime.provide('locale', locale)
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
-README.md: 64f6ae7bcd92735f821c8f8d2b3b93203dbac17e
-README.zh.md: 680fcee730674a21b5c2407247ce46b1a01cf6f3
+README.md: 03726c6671ec711704870d23722d83c72d9c4d35
+README.zh.md: f001866af2015671ed6429b392e3f880000e6c38
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -52,7 +52,7 @@ The `agentPreset.list` domain exposes the deployment's preset roster so a browse

 The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the composer's menu: it returns every user-invocable skill with its `modelInvocable` flag, so menus can mark user-only (`disable-model-invocation`) entries whose only invocation path is the slash gesture. Listing is the skill domain's only RPC — invocation itself is an ordinary `session.prompt` whose whitespace-bounded `/name` tokens `dsh-tool-skill` recognizes at the pre-step boundary and answers with injected `<skill_content>` context, so every entry point (Web, TUI, and ACP) shares one deterministic path—including for hand-typed text—with no dedicated invocation wire. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the registry-wide catalog invalidation frame: clients refetch `command.list` instead of diffing. `host/session-preset-changed` is its per-session counterpart, framed off the logged `agent-preset/selected` commit: recomposing a blank session's agent re-parents its scope without registering anything, so both catalogs that session's composition decides (`command.list`, `skill.list`) go stale with no registry change to announce it.

-The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves the namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus a small explicit allowlist — the Web preference `permission` and the product-owned `ui-onboarding`; adding a Settings registration alone never makes it remotely readable or writable. Any other namespace answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, the section's `revision`, and the boolean `hasDocument` capability flag. The browser receives no Host path: pathless `settings.openDocument` asks the provider to materialize its document and then hands the Host-resolved result to the native opener, so no browser payload can select an arbitrary filesystem target. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. `llm.discoverModels` interrogates a provider endpoint the page is still drafting: `settingsNs` selects the adapter family that knows how to read the listing, and the endpoint, protocol, and key come from the form rather than from storage. It writes nothing — the reply is candidates, and only a later `settings.mutate` decides what a route serves — so its `apiKey` is the third payload on which a secret may ride, alongside `settings.update`/`mutate` and `credentials.set`. The host never stores or returns it; like the other two it does ride the client's outgoing envelope, which `subscribeEnvelopes()` observers can see, and redacting that tap is a configuration-plane-wide change rather than this method's to make alone. Every refusal (an unserved namespace, a protocol with no readable listing, an unreachable endpoint, a rejected credential) folds into `model-discovery-failed`, whose message is the adapter's own text and whose details name the endpoint asked but never the credential offered. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired by `llm/adapters-updated` and by a change to a configurable-provider namespace, whose settings carry that provider's catalog and endpoint; a `permission` or `ui-onboarding` change emits only its settings invalidation. The browser carrier restricts the whole configuration plane, reads and native actions included (`settings.describe`/`openDocument`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
+The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves the namespaces addressed by registered configurable providers (`ctx.llm.listConfigurableProviders()`) plus a small explicit allowlist — the Web preferences `locale`, `permission`, `ui-conversation`, and `ui-theme`, and the product-owned `ui-onboarding`; adding a Settings registration alone never makes it remotely readable or writable. Any other namespace answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, the section's `revision`, and the boolean `hasDocument` capability flag. The browser receives no Host path: pathless `settings.openDocument` asks the provider to materialize its document and then hands the Host-resolved result to the native opener, so no browser payload can select any filesystem target. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. `llm.discoverModels` interrogates a provider endpoint the page is still drafting: `settingsNs` selects the adapter family that knows how to read the listing, and the endpoint, protocol, and key come from the form rather than from storage. It writes nothing — the reply is candidates, and only a later `settings.mutate` decides what a route serves — so its `apiKey` is the third payload on which a secret may ride, alongside `settings.update`/`mutate` and `credentials.set`. The host never stores or returns it; like the other two it does ride the client's outgoing envelope, which `subscribeEnvelopes()` observers can see, and redacting that tap is a configuration-plane-wide change rather than this method's to make alone. Every refusal (an unserved namespace, a protocol with no readable listing, an unreachable endpoint, a rejected credential) folds into `model-discovery-failed`, whose message is the adapter's own text and whose details name the endpoint asked but never the credential offered. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired by `llm/adapters-updated` and by a change to a configurable-provider namespace, whose settings carry that provider's catalog and endpoint; a `locale`, `permission`, `ui-conversation`, `ui-theme`, or `ui-onboarding` change emits only its settings invalidation. The browser carrier restricts the whole configuration plane, reads and native actions included (`settings.describe`/`openDocument`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.

 ## Carrier layer (`/client` + root)

--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -52,7 +52,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr

 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和 skill（技能）目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于 composer 的菜单：它返回每一个用户可调用的 skill 及其 `modelInvocable` 标志，让菜单能够标出仅限用户（`disable-model-invocation`）的条目——斜杠手势是这类条目唯一的调用路径。列表是 skill 领域唯一的 RPC——调用本身就是一次普通的 `session.prompt`，`dsh-tool-skill` 会在 pre-step 边界识别其中以空白为界的 `/name` token，并以注入的 `<skill_content>` 上下文作答，因此所有入口（Web、TUI 与 ACP（Agent Client Protocol））共享同一条确定性路径，手动键入的文本也走该路径，且没有专设的调用协议。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是注册表级目录失效帧：客户端重新拉取 `command.list` 而不是做差分。`host/session-preset-changed` 是它按会话粒度的对应物，由落账的 `agent-preset/selected` 提交点成帧：重组空会话的 agent 只是重新挂接其 scope，不产生任何注册，因此该会话组成所决定的两份目录（`command.list`、`skill.list`）都会失效，却没有任何注册表变化来宣告它。

-`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `permission` 与产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`permission` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
+`settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域服务于已注册可配置提供方所指向的 namespace（`ctx.llm.listConfigurableProviders()`），并额外服务于一份小型、显式的 allowlist——Web 偏好 `locale`、`permission`、`ui-conversation` 与 `ui-theme`，以及产品持有的 `ui-onboarding`；仅新增一项 Settings 注册，绝不会使其可被远程读取或写入。其他任何 namespace 都只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表、该分节的 `revision`，以及布尔型 `hasDocument` 能力标志。浏览器不会收到 Host 路径：无路径参数的 `settings.openDocument` 会请求提供方准备文档，再把由 Host 解析出的结果交给原生打开器，因此任何浏览器载荷都无法选择任意文件系统目标。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；陈旧的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。`llm.discoverModels` 询问页面尚在起草的提供方端点：`settingsNs` 选出懂得读取该列表的适配器家族，端点、协议与密钥则来自表单而非存储。它什么都不写——回复是候选，只有随后的 `settings.mutate` 才决定路由服务什么——因此其 `apiKey` 是 secret 可以搭乘的第三个载荷（另两个是 `settings.update`/`mutate` 与 `credentials.set`），且绝不被存储或回显。host 从不存储或回传它；与另两者一样，它确实会搭乘客户端的出站信封，`subscribeEnvelopes()` 的观察者能看到——为该 tap 做脱敏是整个配置面的改动，而非本方法一家的事。每一种拒绝（无人服务的 namespace、没有可读列表的协议、不可达端点、被拒凭据）都折叠为 `model-discovery-failed`，其消息是适配器自己的文本，details 点名被询问的端点，绝不点名所提供的凭据。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它由 `llm/adapters-updated` 和可配置提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点；`locale`、`permission`、`ui-conversation`、`ui-theme` 或 `ui-onboarding` 变更只会发出自身的 settings 失效通知。浏览器载体把整个配置面（含读取与原生操作：`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。

 ## 载体层（`/client` + 根路径）

--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -93,7 +93,7 @@ import { canOpenNativePath, openNativePath, openNativeTextFile } from './native-
 const DEFAULT_MAX_MESSAGES = 50

 /** Non-model settings namespaces intentionally served to the Web client. */
-const WEB_SETTINGS_NAMESPACES = ['permission'] as const
+const WEB_SETTINGS_NAMESPACES = ['locale', 'permission', 'ui-conversation', 'ui-theme'] as const

 /** Provider work budget: at most 100 calls and 2,000 inspected hits. */
 const SESSION_SEARCH_PROVIDER_CALL_LIMIT = 100
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -309,8 +309,8 @@ describe('settings domain', () => {
    // The settings seam is general: any plugin may register a namespace for
    // its own configuration. The Web configuration plane remains opt-in, so a
    // future internal plugin cannot become remotely configurable just by
-    // registering; permission and the product onboarding namespace are the
-    // non-model namespaces intentionally admitted by this surface.
+    // registering; locale, permission, conversation, theme, and the product
+    // onboarding namespace are intentionally admitted by this surface.
    const ctx = await harness()
    ctx.settings.register(NS, AdapterConfig)
    ctx.settings.register(settingsNamespace('some-other-plugin'), z.object({ secretPath: z.string() }))
@@ -319,15 +319,41 @@ describe('settings domain', () => {
    }), {
      base: { defaultPreset: 'read-only' },
    })
+    ctx.settings.register(settingsNamespace('ui-theme'), z.object({
+      preference: z.union(['light', 'dark', 'system']).default('system'),
+    }))
+    ctx.settings.register(settingsNamespace('locale'), z.object({
+      preference: z.union(['zh', 'en']).required(false),
+    }))
+    ctx.settings.register(settingsNamespace('ui-conversation'), z.object({
+      busyEnter: z.union(['queue', 'steer']).default('queue'),
+    }))
    const api = createApiProxy(ctx, DEFAULTS)

    const value = expectOk(await api.settings.describe(request({})))
-    expect(value.namespaces.map(view => view.ns)).toEqual(['llm-deepseek', 'permission'])
+    expect(value.namespaces.map(view => view.ns)).toEqual([
+      'llm-deepseek', 'permission', 'ui-theme', 'locale', 'ui-conversation',
+    ])
    const permission = expectOk(await api.settings.mutate(request({
      ns: 'permission',
      ops: [{ op: 'set', path: ['defaultPreset'], value: 'workspace-write' }],
    })))
    expect(permission.value).toEqual({ defaultPreset: 'workspace-write' })
+    const theme = expectOk(await api.settings.mutate(request({
+      ns: 'ui-theme',
+      ops: [{ op: 'set', path: ['preference'], value: 'dark' }],
+    })))
+    expect(theme.value).toEqual({ preference: 'dark' })
+    const locale = expectOk(await api.settings.mutate(request({
+      ns: 'locale',
+      ops: [{ op: 'set', path: ['preference'], value: 'en' }],
+    })))
+    expect(locale.value).toEqual({ preference: 'en' })
+    const conversation = expectOk(await api.settings.mutate(request({
+      ns: 'ui-conversation',
+      ops: [{ op: 'set', path: ['busyEnter'], value: 'steer' }],
+    })))
+    expect(conversation.value).toEqual({ busyEnter: 'steer' })

    for (const response of [
      await api.settings.update(request({ ns: 'some-other-plugin', patch: { secretPath: '/etc/shadow' } })),
@@ -341,19 +367,29 @@ describe('settings domain', () => {
    expect(ctx.settings.describe().find(d => String(d.ns) === 'some-other-plugin')?.value).toEqual({})
  })

-  it('serves the product onboarding namespace without invalidating the model catalog', async () => {
+  it('serves product preference namespaces without invalidating the model catalog', async () => {
    const ctx = await harness()
    ctx.settings.register(settingsNamespace('ui-onboarding'), z.object({ welcomeNoticeVersion: z.string() }))
+    ctx.settings.register(settingsNamespace('ui-theme'), z.object({
+      preference: z.union(['light', 'dark', 'system']).default('system'),
+    }))
    const api = createApiProxy(ctx, DEFAULTS)
    expect(expectOk(await api.settings.describe(request({}))).namespaces.map(view => view.ns))
-      .toEqual(['ui-onboarding'])
-    const frames = await collectHost(api, ['host/settings-changed'], 1, async () => {
+      .toEqual(['ui-onboarding', 'ui-theme'])
+    const frames = await collectHost(api, ['host/settings-changed'], 2, async () => {
      expectOk(await api.settings.mutate(request({
        ns: 'ui-onboarding',
        ops: [{ op: 'set', path: ['welcomeNoticeVersion'], value: 'v1' }],
      })))
+      expectOk(await api.settings.mutate(request({
+        ns: 'ui-theme',
+        ops: [{ op: 'set', path: ['preference'], value: 'dark' }],
+      })))
    })
-    expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'ui-onboarding' }])
+    expect(frames).toEqual([
+      { type: 'host/settings-changed', ns: 'ui-onboarding' },
+      { type: 'host/settings-changed', ns: 'ui-theme' },
+    ])
  })

  it('serves the agent-preset namespace, so a browser preset picker can persist its choice', async () => {
--- a/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -1140,11 +1140,11 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
      },
      {
        signature: 'abstract onTaskDone(listener: TaskDoneListener): () => void',
-        jsDoc: '/**\n * Register an effect-scoped completion listener. Each listener is contained;\n * returned promises are observed but not awaited. No listener runs after\n * service disposal.\n * @param listener - receives each terminal snapshot and its exact owner.\n * @returns disposer that unregisters the listener.\n */',
+        jsDoc: '/**\n * Register an effect-scoped completion listener. It receives the settlements\n * of the owners its registering context\'s scope covers; each listener is\n * contained; returned promises are observed but not awaited. No listener runs\n * after service disposal.\n * @param listener - receives each terminal snapshot and its exact owner.\n * @returns disposer that unregisters the listener.\n */',
      },
      {
        signature: 'abstract attachSurface(name: string): () => void',
-        jsDoc: '/**\n * Attach an effect-scoped surface that can read and stop tasks. {@link start}\n * refuses work while none is attached.\n * @param name - diagnostic label; duplicate names remain independent.\n * @returns disposer that detaches this surface.\n */',
+        jsDoc: '/**\n * Attach an effect-scoped surface that can read and stop tasks. It serves the\n * owners its registering context\'s scope covers, and {@link start} refuses an\n * owner no attached surface serves.\n * @param name - diagnostic label; duplicate names remain independent.\n * @returns disposer that detaches this surface.\n */',
      },
    ],
  },
--- a/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
+++ b/packages/subagent/tool-subagent/tests/tool-subagent.spec.ts
@@ -1027,7 +1027,7 @@ describe('background preflight failure (no orphaned child, by construction)', ()
      agent: parent,
    })
    expect(result.isError).toBe(true)
-    expect(text(result)).toContain('no control surface is attached')
+    expect(text(result)).toContain('no control surface serves this agent')
    // Declare-then-execute: the failed preflight means no child ever existed.
    expect(starts).toBe(0)
  })
--- a/packages/tasks/tasks-local/README.i18n.yaml
+++ b/packages/tasks/tasks-local/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tasks-local/README.md
-README.md: 663ce0d333c6df0f84900a2570d5487d8d7abe55
-README.zh.md: a5d1acaa50f63dc95b7607657b157272c15a4f11
+README.md: 80d7932466188955ade1c14e4968d51b739ba818
+README.zh.md: 5e4263e4685be64f91ec2a7c74edbf89e1148866
--- a/packages/tasks/tasks-local/README.md
+++ b/packages/tasks/tasks-local/README.md
@@ -12,6 +12,8 @@ Service disposal closes listeners, cancels all live tasks, awaits their records,

 Settlement is first-wins: the earliest terminal outcome — producer settlement, a rejected `done` contained as `failed`, or a teardown force-failure — records once, notifies listeners once with per-listener containment, and releases waiters. Pending waits mark the task reported before listeners run so completion surfaces do not duplicate notices.

+Surfaces and listeners are layered by the scope that registered them, in the tools-registry shape: a registration files into its registering context's scope, and a read unions the global layer with the owner's scope chain. One process-wide registry therefore answers per-owner questions per owner — `start()` refuses `background tasks unavailable: no control surface serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)` for an owner whose own composition attaches none, however many other compositions attach theirs, and a settlement reaches only the listeners its owner's composition registered.
+
 ## Model Experience

 Indirectly, through producer plugins and [`dsh-tool-tasks`](../tool-tasks/README.md), which render task ids, output, status, cancellation, and completion notices.
--- a/packages/tasks/tasks-local/README.zh.md
+++ b/packages/tasks/tasks-local/README.zh.md
@@ -12,6 +12,8 @@

 结算遵循首次结算优先原则：最早出现的终止结果（生产方结算、作为 `failed` 隔离处理的 `done` 拒绝，或销毁时的强制失败）只记录一次，也只通知监听器一次；各监听器的故障会单独隔离，随后释放等待方。挂起的等待会在监听器运行前把任务标记为已报告，因此呈现完成情况的表层不会重复发出通知。

+表层与监听器按注册方所在的 scope 分层，形状与 tools 注册表一致：一次注册归档到其注册上下文的 scope，一次读取则把全局层与所有者的 scope 链求并集。因此一个进程级注册表能逐所有者地回答逐所有者的问题——对自身组合未附加任何表层的所有者，无论其他组合附加了多少，`start()` 都会拒绝并抛出 `background tasks unavailable: no control surface serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)`；一次结算也只会抵达其所有者所属组合注册的监听器。
+
 ## 模型体验

 通过生产方插件和 [`dsh-tool-tasks`](../tool-tasks/README.md) 间接影响；它们会呈现任务 id、输出、状态、取消和完成通知。
--- a/packages/tasks/tasks-local/package.json
+++ b/packages/tasks/tasks-local/package.json
@@ -27,6 +27,7 @@
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-scope": "^0.0.1",
    "@deepseek-ai/dsh-tasks": "^0.0.1",
    "@deepseek-ai/dsh-timeout": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
@@ -35,6 +36,7 @@
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-brand": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-scope": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-tasks": "workspace:^",
    "@deepseek-ai/dsh-timeout": "workspace:^",
--- a/packages/tasks/tasks-local/src/index.ts
+++ b/packages/tasks/tasks-local/src/index.ts
@@ -11,6 +11,8 @@

 import { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import { AnonymousEntries, ScopedLayers, scopeOf } from '@deepseek-ai/dsh-scope'
+import type { ScopeLayer } from '@deepseek-ai/dsh-scope'
 import { deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { TaskService, TaskId } from '@deepseek-ai/dsh-tasks'
 import type { TaskDoneListener, TaskKind, TaskOutcome, TaskRead, TaskSnapshot, TaskStart, TaskStatus } from '@deepseek-ai/dsh-tasks'
@@ -49,6 +51,21 @@ function isTerminal(status: TaskStatus): boolean {
  return status === 'completed' || status === 'killed' || status === 'failed'
 }

+/**
+ * One scope's contributions: the control surfaces attached from it and the
+ * completion listeners registered there. Both tables are anonymous because a
+ * contribution is identified by its own disposer, never by a name a second
+ * registrant could shadow.
+ */
+class TaskLayer implements ScopeLayer {
+  readonly surfaces = new AnonymousEntries<symbol>()
+  readonly listeners = new AnonymousEntries<TaskDoneListener>()
+
+  isEmpty(): boolean {
+    return this.surfaces.isEmpty() && this.listeners.isEmpty()
+  }
+}
+
 /**
 * The in-memory `tasks` registry. See the Service Definition contract in
 * `@deepseek-ai/dsh-tasks` for the ownership, isolation, and lifecycle
@@ -57,8 +74,19 @@ function isTerminal(status: TaskStatus): boolean {
 export class LocalTaskService extends TaskService {
  private store = new Map<TaskId, TrackedTask>()
  private counters = new Map<string, number>()
-  private surfaces = new Set<symbol>()
-  private listeners = new Set<TaskDoneListener>()
+  /**
+   * Surfaces and listeners layered by the scope that registered them, in the
+   * tools-registry shape: a contribution files into its registering context's
+   * scope, and a read unions the global layer with the reader's scope chain.
+   *
+   * The registry is one process-wide instance serving every composition, so a
+   * flat table would answer a per-owner question process-wide: one preset's
+   * task controls would hold `start()` open for an agent whose own composition
+   * loads none, and one settlement would reach every preset's notice listener.
+   * Layers make both reads owner-relative. Nothing derives a cache from a
+   * layer, so change notification is a no-op.
+   */
+  private readonly layers = new ScopedLayers<TaskLayer>(() => new TaskLayer(), () => {})
  private listenersClosed = false
  /** Owner agents with attached scope cleanup, mapped to the exact disposer. */
  private ownerCleanups = new Map<Agent, () => Promise<void> | void>()
@@ -72,8 +100,8 @@ export class LocalTaskService extends TaskService {
  }

  start(spec: TaskStart): TaskId {
-    if (this.surfaces.size === 0) {
-      throw new Error('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
+    if (!this.servesOwner(spec.owner)) {
+      throw new Error('background tasks unavailable: no control surface serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)')
    }
    if (spec.kind.length === 0) throw new Error('invalid task kind: expected a non-empty string')
    if (spec.label.length === 0) throw new Error('invalid task label: expected a non-empty string')
@@ -210,21 +238,49 @@ export class LocalTaskService extends TaskService {
  }

  onTaskDone(listener: TaskDoneListener): () => void {
-    const dispose = this.ctx.effect(() => {
-      this.listeners.add(listener)
-      return () => this.listeners.delete(listener)
-    }, 'tasks.onTaskDone()')
-    return () => void dispose()
+    return this.layers.effect(
+      this.ctx,
+      layer => layer.listeners.append(listener),
+      { label: 'tasks.onTaskDone()' },
+    )
  }

  attachSurface(name: string): () => void {
    // One token per call keeps duplicate labels independently disposable.
    const token = Symbol(name)
-    const dispose = this.ctx.effect(() => {
-      this.surfaces.add(token)
-      return () => this.surfaces.delete(token)
-    }, 'tasks.attachSurface()')
-    return () => void dispose()
+    return this.layers.effect(
+      this.ctx,
+      layer => layer.surfaces.append(token),
+      { label: 'tasks.attachSurface()' },
+    )
+  }
+
+  /**
+   * Whether an attached control surface can collect and stop work owned by
+   * `owner`. The global layer holds every surface attached from an unscoped
+   * context — a host composition's own controls — and therefore serves every
+   * owner; a scoped surface serves exactly the agents composed under it.
+   * @param owner - the task's owner, or undefined for unowned work.
+   * @returns whether some reachable surface serves the owner.
+   */
+  private servesOwner(owner?: Agent): boolean {
+    if (!this.layers.global.surfaces.isEmpty()) return true
+    return this.layers.chainLayers(owner === undefined ? undefined : scopeOf(owner.ctx))
+      .some(layer => !layer.surfaces.isEmpty())
+  }
+
+  /**
+   * The completion listeners that own `owner`'s notices: the global layer's
+   * first, then each scoped layer along the owner's chain. A listener outside
+   * that chain belongs to another composition and must not deliver, or the
+   * owner reads one notice per mounted preset.
+   * @param owner - the settled task's owner, or undefined for unowned work.
+   * @returns the listeners to notify, in registration order per layer.
+   */
+  private *listenersFor(owner?: Agent): IterableIterator<TaskDoneListener> {
+    yield* this.layers.global.listeners.values()
+    const scope = owner === undefined ? undefined : scopeOf(owner.ctx)
+    for (const layer of this.layers.chainLayers(scope)) yield* layer.listeners.values()
  }

  /** Look up a task or fail loud. */
@@ -276,7 +332,7 @@ export class LocalTaskService extends TaskService {
    if (task.waiters > 0) task.reported = true
    if (!this.listenersClosed) {
      const snapshot = this.snapshot(task)
-      for (const listener of this.listeners) {
+      for (const listener of this.listenersFor(task.owner)) {
        try {
          const returned = listener(snapshot, task.owner)
          void Promise.resolve(returned).catch((error: unknown) => {
@@ -330,8 +386,9 @@ export class LocalTaskService extends TaskService {
   * effects. Throwing cancels are force-failed to avoid teardown deadlock.
   */
  private async disposeAll(): Promise<void> {
+    // The flag is the whole guard: each layer entry's undo belongs to the fiber
+    // that registered it, so this service may not drop them on its own way out.
    this.listenersClosed = true
-    this.listeners.clear()
    const all = [...this.store.values()]
    this.cancelForTeardown(all, 'tasks service disposed')
    await Promise.all(all.map(task => task.settled))
--- a/packages/tasks/tasks-local/tests/tasks.spec.ts
+++ b/packages/tasks/tasks-local/tests/tasks.spec.ts
@@ -3,6 +3,8 @@ import { Context } from 'cordis'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
 import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import { bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope'
+import type { ScopeKey } from '@deepseek-ai/dsh-scope'
 import { TaskId } from '@deepseek-ai/dsh-tasks'
 import type { TaskHooks, TaskKind, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
 import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
@@ -15,9 +17,18 @@ declare module '@deepseek-ai/dsh-tasks' {

 const agentScopeDisposers = new WeakMap<Agent, () => Promise<void>>()

-function stubAgent(ctx: Context, rawId: string): Agent {
+function stubAgent(ctx: Context, rawId: string, presetScope?: ScopeKey): Agent {
  const id = SessionId(rawId)
  const scopeFiber = ctx.plugin(() => {})
+  // `presetScope` reproduces what `agentPresets.compose` does: the agent gets
+  // its own key parented to the standing mount's, so the registry's chain walk
+  // reaches that preset's layer.
+  let agentCtx = scopeFiber.ctx
+  if (presetScope !== undefined) {
+    const key = {}
+    bindScopeParent(key, presetScope)
+    agentCtx = createScope(scopeFiber.ctx, key).ctx
+  }
  const session = Session.create(id)
  const agent = {
    id,
@@ -25,7 +36,7 @@ function stubAgent(ctx: Context, rawId: string): Agent {
    session,
    inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
    status: 'idle' as const,
-    ctx: scopeFiber.ctx,
+    ctx: agentCtx,
    send: () => {},
    followup: () => {},
    steer: () => ({ outcome: Promise.resolve({ status: 'rejected' as const }) }),
@@ -73,6 +84,21 @@ async function harness() {
  return ctx
 }

+/**
+ * Attach a control surface the way `tool-tasks` does: from a plugin whose own
+ * `inject` resolves `ctx.tasks`, so the service method binds to the REGISTERING
+ * context and the surface files into that context's scope layer. Reading the
+ * service off a bare scoped context instead throws `cannot get property "tasks"
+ * without inject`, which is the same rule the shipped plugin obeys.
+ * @param ctx - the context whose scope should own the surface.
+ */
+async function attachSurfaceIn(ctx: Context): Promise<void> {
+  await ctx.plugin({
+    inject: ['tasks'],
+    apply(pluginCtx: Context) { pluginCtx.tasks.attachSurface('tool-tasks') },
+  })
+}
+
 /** Let the settlement continuation (a `done.then`) run. */
 const tick = () => new Promise<void>(r => setTimeout(r, 0))

@@ -89,11 +115,48 @@ describe('LocalTaskService.start', () => {
    expectTypeOf<TaskSnapshot['ownerSession']>().toEqualTypeOf<SessionId | undefined>()
  })

-  it('refuses to register while no control surface is attached', async () => {
+  it('refuses to register while no control surface serves the owner', async () => {
    const ctx = new Context()
    await ctx.plugin(LocalTaskService)
    expect(() => ctx.tasks.start(producer().spec))
-      .toThrow('background tasks unavailable: no control surface is attached (load @deepseek-ai/dsh-tool-tasks)')
+      .toThrow('background tasks unavailable: no control surface serves this agent (load @deepseek-ai/dsh-tool-tasks in its composition)')
+  })
+
+  it('refuses an owner whose own composition attaches no surface', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(LocalTaskService)
+    // Two standing preset mounts over one registry; only the first loads the
+    // task controls. The second must not inherit the first's open gate.
+    const withControls = createScope(ctx, {})
+    const withoutControls = createScope(ctx, {})
+    await attachSurfaceIn(withControls.ctx)
+
+    const served = stubAgent(ctx, 'served', scopeOf(withControls.ctx))
+    const unserved = stubAgent(ctx, 'unserved', scopeOf(withoutControls.ctx))
+    ctx.agents.register(served)
+    ctx.agents.register(unserved)
+
+    expect(() => ctx.tasks.start(producer({ owner: served }).spec)).not.toThrow()
+    expect(() => ctx.tasks.start(producer({ owner: unserved }).spec))
+      .toThrow('no control surface serves this agent')
+    // An unowned producer has no chain to walk, so only a global surface serves it.
+    expect(() => ctx.tasks.start(producer().spec))
+      .toThrow('no control surface serves this agent')
+  })
+
+  it('lets a surface attached without a scope serve every owner', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(LocalTaskService)
+    // The host-plane composition's own controls: no scope, so the global layer
+    // holds them and every owner's read includes it.
+    await attachSurfaceIn(ctx)
+    const scoped = stubAgent(ctx, 'scoped', scopeOf(createScope(ctx, {}).ctx))
+    ctx.agents.register(scoped)
+
+    expect(() => ctx.tasks.start(producer({ owner: scoped }).spec)).not.toThrow()
+    expect(() => ctx.tasks.start(producer().spec)).not.toThrow()
  })

  it('rejects an empty kind, empty label, and invalid output limit', async () => {
@@ -742,6 +805,30 @@ describe('LocalTaskService disposal', () => {
    expect(ownerEffects()).toHaveLength(0)
  })

+  it('drops a scoped layer when its registrations dispose', async () => {
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(LocalTaskService)
+    const standing = createScope(ctx, {})
+    // One mount contributes both kinds into the same layer, as `tool-tasks`
+    // does; unloading it must leave nothing serving the agents that joined it.
+    const mount = await standing.ctx.plugin({
+      inject: ['tasks'],
+      apply(pluginCtx: Context) {
+        pluginCtx.tasks.attachSurface('tool-tasks')
+        pluginCtx.tasks.onTaskDone(() => {})
+      },
+    })
+    const owner = stubAgent(ctx, 'joined', scopeOf(standing.ctx))
+    ctx.agents.register(owner)
+    expect(() => ctx.tasks.start(producer({ owner }).spec)).not.toThrow()
+
+    await mount.dispose()
+
+    expect(() => ctx.tasks.start(producer({ owner }).spec))
+      .toThrow('no control surface serves this agent')
+  })
+
  it('detaching the last surface re-arms the register fence', async () => {
    const ctx = new Context()
    await ctx.plugin(LocalTaskService)
@@ -757,6 +844,6 @@ describe('LocalTaskService disposal', () => {
    detachA2()
    expect(() => ctx.tasks.start(producer().spec)).not.toThrow() // b remains
    await fiber.dispose() // detaches b with its fiber (HMR safety)
-    expect(() => ctx.tasks.start(producer().spec)).toThrow('no control surface is attached')
+    expect(() => ctx.tasks.start(producer().spec)).toThrow('no control surface serves this agent')
  })
 })
--- a/packages/tasks/tasks-local/tsconfig.json
+++ b/packages/tasks/tasks-local/tsconfig.json
@@ -17,6 +17,9 @@
    {
      "path": "../../core/agent"
    },
+    {
+      "path": "../../core/scope"
+    },
    {
      "path": "../../util/timeout"
    },
--- a/packages/tasks/tasks/README.i18n.yaml
+++ b/packages/tasks/tasks/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tasks/README.md
-README.md: 04ca125580104d0cb5ab0ce8cdd20d104c4a1668
-README.zh.md: b0b079566246549c7acab7a83fcc3c21c44ef868
+README.md: f23a93e3cb1fc5aad5bad053f832bb66baa8eb64
+README.zh.md: c3ea9125c4db9f2d86722cbf490b4f0eecfbe25a
--- a/packages/tasks/tasks/README.md
+++ b/packages/tasks/tasks/README.md
@@ -12,7 +12,9 @@ The background task registry contract (`ctx.tasks`). The abstract `TaskService`
 - `kill(id, caller?, reason?)` invokes producer cancellation before changing status. A cancellation throw leaves the task running; success changes it to `stopping` and marks terminal delivery reported.
 - `wait(id, timeoutMs, caller?, signal?)` returns a terminal snapshot or the live snapshot at timeout. Aborting stops only the wait; settlement wins once it has committed terminal delivery to that waiter.
 - `onTaskDone(listener)` observes each terminal record with the exact owner. Listener throws and rejections are contained; listener work is not awaited.
- `attachSurface(name)` declares a control surface for its effect lifetime. `start()` fails before producer execution when none is attached.
+- `attachSurface(name)` declares a control surface for its effect lifetime. `start()` fails before producer execution when no attached surface serves the spec's owner.
+
+Both registrations are owner-relative, because one registry serves every composition in the process. A surface or listener registered from an unscoped context serves every owner; one registered under an agent composition's scope serves exactly the agents composed under it. So a composition that loads no control surface cannot start background work on the strength of another composition's controls, and one settlement notifies only the listeners its owner's composition registered.

 Owned access compares the task's `SessionId` with the caller's. Ids such as `bash-1` are predictable, so this fence is the boundary. Unowned tasks are open to callers and last until service disposal.

--- a/packages/tasks/tasks/README.zh.md
+++ b/packages/tasks/tasks/README.zh.md
@@ -12,7 +12,9 @@
 - `kill(id, caller?, reason?)` 在更改状态前调用生产方取消。取消抛出异常时任务保持运行；成功则把状态改为 `stopping`，并将终止交付标记为已报告。
 - `wait(id, timeoutMs, caller?, signal?)` 返回终止快照，或在超时时返回存活快照。中止只会停止等待；一旦终止交付已向该等待方提交，终止结果优先。
 - `onTaskDone(listener)` 观察每条终止记录及其精确 owner。监听器抛出的异常和产生的拒绝都会被隔离；系统不会等待监听器工作。
- `attachSurface(name)` 在其 effect 生命周期内声明控制表层。如果没有附加任何表层，`start()` 会在生产方执行前失败。
+- `attachSurface(name)` 在其 effect 生命周期内声明控制表层。当没有任何已附加的表层服务于 spec 的所有者时，`start()` 会在生产方执行前失败。
+
+这两类注册都是相对于所有者的，因为一个注册表要服务进程内的每一套组合。从不带 scope 的上下文注册的表层或监听器服务于每个所有者；在某套 agent 组合的 scope 下注册的，则恰好服务于在该组合下组合出的 agent。因此，未加载任何控制表层的组合无法借另一套组合的控制工具启动后台工作，而一次结算也只会通知其所有者所属组合注册的监听器。

 有 owner 的访问会比较任务的 `SessionId` 与调用方。`bash-1` 等 id 可预测，因此这道隔离是安全边界。无 owner 的任务向调用方开放，并持续到服务释放。

--- a/packages/tasks/tasks/src/index.ts
+++ b/packages/tasks/tasks/src/index.ts
@@ -44,8 +44,13 @@ declare module 'cordis' {
 * - Settlement is first-wins: one terminal record, one round of contained
 *   listener notification, and released waiters, even against a late
 *   producer outcome.
- * - {@link start} refuses work while no control surface is attached, so a
- *   producer cannot start work that callers cannot collect or stop.
+ * - {@link start} refuses work while no attached control surface serves the
+ *   spec's owner, so a producer cannot start work that owner cannot collect
+ *   or stop. One registry serves every composition in the process, so this
+ *   question — and completion-listener delivery — is owner-relative rather
+ *   than process-wide: registrations made from an unscoped context serve
+ *   every owner, and registrations made under an agent composition's scope
+ *   serve exactly the agents composed under it.
 */
 export abstract class TaskService extends Service {
  constructor(ctx: Context) {
@@ -120,17 +125,19 @@ export abstract class TaskService extends Service {
  abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>

  /**
-   * Register an effect-scoped completion listener. Each listener is contained;
-   * returned promises are observed but not awaited. No listener runs after
-   * service disposal.
+   * Register an effect-scoped completion listener. It receives the settlements
+   * of the owners its registering context's scope covers; each listener is
+   * contained; returned promises are observed but not awaited. No listener runs
+   * after service disposal.
   * @param listener - receives each terminal snapshot and its exact owner.
   * @returns disposer that unregisters the listener.
   */
  abstract onTaskDone(listener: TaskDoneListener): () => void

  /**
-   * Attach an effect-scoped surface that can read and stop tasks. {@link start}
-   * refuses work while none is attached.
+   * Attach an effect-scoped surface that can read and stop tasks. It serves the
+   * owners its registering context's scope covers, and {@link start} refuses an
+   * owner no attached surface serves.
   * @param name - diagnostic label; duplicate names remain independent.
   * @returns disposer that detaches this surface.
   */
--- a/packages/tasks/tool-tasks/README.i18n.yaml
+++ b/packages/tasks/tool-tasks/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/tasks/tool-tasks/README.md
-README.md: 6e8e889c2330d6991cb384674b011e4d2e988268
-README.zh.md: 355b6736b476fb2434f17ea3857544f32c40adb3
+README.md: 4e8872b087bac6576a3b48acbf079d3f06f3a131
+README.zh.md: 3beeb1b70c3a757f5935b0621c9648e0a02c7aa5
--- a/packages/tasks/tool-tasks/README.md
+++ b/packages/tasks/tool-tasks/README.md
@@ -20,6 +20,8 @@ When a producer supplies `outputLimitBytes`, `task_output`, terminal `task_kill`

 An unreported completion injects `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` into the exact owner's next-step inbox. When bounded, the stable id prefix and collection command outrank variable label/detail so the notice remains actionable at PTY's supported 64-byte minimum. Injection is durable pending context for a later pre-step claim, not a wake-up; cancellation or owner disposal may discard it before claim. A kill or terminal read/wait marks delivery reported and suppresses the redundant notice.

+One host registry may carry several mounts of this plugin — one per agent preset. The registry routes each settlement to the listeners the owner's scope chain reaches, so a mount under one preset never sees another preset's agents and an agent reads exactly one notice per completion however many presets are mounted. The same routing decides which agents this mount's control surface serves: an agent whose composition loads no `tool-tasks` cannot start background work at all.
+
 ## Config

 | key | default | meaning |
--- a/packages/tasks/tool-tasks/README.zh.md
+++ b/packages/tasks/tool-tasks/README.zh.md
@@ -20,6 +20,8 @@

 一项尚未报告的完成会把 `background task <id> (<kind>: <label>) finished [status: ...]. Read its output with task_output.` 注入到确切所有者的 next-step inbox。应用上限时，即使采用 PTY 支持的 64 字节下限，稳定 id 前缀和收集命令的优先级也高于可变 label/detail，因此通知仍可操作。注入是等待后续 pre-step 领取的持久上下文，并非唤醒；取消或 owner 释放可能在领取前丢弃它。kill 或针对已终止任务的 read/wait 会把交付标为已报告，并抑制重复通知。

+一个宿主注册表可能承载本插件的多份挂载——每个 agent preset 一份。注册表会把每次结算路由给所有者 scope 链所能抵达的监听器，因此某个 preset 下的挂载永远看不到另一个 preset 的 agent，无论挂载了多少 preset，一个 agent 每次完成都只读到一条通知。同一套路由也决定本挂载的控制表层服务哪些 agent：组合中未加载 `tool-tasks` 的 agent 根本无法启动后台工作。
+
 ## 配置

 | key | 默认值 | 含义 |
--- a/packages/tasks/tool-tasks/src/index.ts
+++ b/packages/tasks/tool-tasks/src/index.ts
@@ -230,6 +230,10 @@ export function apply(ctx: Context, config: Config): void {
  // Delivery targets the exact lifecycle owner. The notice waits in its
  // next-step inbox until another step claims it; disposal before that
  // boundary discards it with the owner.
+  //
+  // The registry routes each settlement to the listeners its owner's scope
+  // chain reaches, so a mount under one preset never sees another preset's
+  // agents; this listener owns delivery, not the choice of whom to deliver to.
  ctx.tasks.onTaskDone((snapshot, owner) => {
    if (snapshot.reported || owner === undefined) return
    owner.inject(createUserMessage({
--- a/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
+++ b/packages/tasks/tool-tasks/tests/tool-tasks.spec.ts
@@ -6,6 +6,7 @@ import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import { bindScopeParent, createScope, scopeOf } from '@deepseek-ai/dsh-scope'
 import { TaskId } from '@deepseek-ai/dsh-tasks'
 import LocalTaskService from '@deepseek-ai/dsh-tasks-local'
 import type { TaskHooks, TaskOutcome, TaskSnapshot, TaskStart } from '@deepseek-ai/dsh-tasks'
@@ -85,7 +86,7 @@ describe('tool-tasks setup', () => {
    const { ctx, toolsFiber } = await setup()
    expect(() => ctx.tasks.start(producer().spec)).not.toThrow()
    await toolsFiber.dispose()
-    expect(() => ctx.tasks.start(producer().spec)).toThrow('no control surface is attached')
+    expect(() => ctx.tasks.start(producer().spec)).toThrow('no control surface serves this agent')
  })

  it('rejects a config whose default wait exceeds the cap', async () => {
@@ -445,6 +446,54 @@ describe('tool-owned UI presentation (presentCall)', () => {
  })
 })

+describe('completion notices across scoped mounts', () => {
+  /**
+   * Two agent presets mounting `tool-tasks` over ONE host registry: each mount
+   * registers its own `onTaskDone` listener on the shared service, and
+   * `settle()` broadcasts one snapshot to every listener with no scope filter.
+   * Only the mount whose scope the owner belongs to may deliver the notice.
+   */
+  it('delivers one notice from the owning scope when two mounts share the registry', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(LocalTaskService)
+
+    const standingA = createScope(ctx, {})
+    const standingB = createScope(ctx, {})
+    await standingA.ctx.plugin(ToolTasks)
+    await standingB.ctx.plugin(ToolTasks)
+
+    // The agent joins preset A exactly as `agentPresets.compose` binds it.
+    const agentKey = {}
+    const agentScope = createScope(ctx, agentKey)
+    bindScopeParent(agentKey, scopeOf(standingA.ctx) as object)
+
+    const inject = vi.fn()
+    const owner = {
+      id: SessionId('sess-scoped'),
+      ctx: agentScope.ctx,
+      inject,
+      session: { id: SessionId('sess-scoped'), header: { version: 0, id: SessionId('sess-scoped'), createdAt: 0 } },
+    } as unknown as Agent
+    const dispose = ctx.agents.register(owner)
+
+    try {
+      // No waiter: `settle()` leaves `reported` false, which is the only path
+      // that reaches the notice listeners at all.
+      const p = producer({ owner, label: 'pnpm test' })
+      ctx.tasks.start(p.spec)
+      p.settle({ status: 'completed', detail: 'exit code: 0' })
+      await tick()
+
+      expect(inject).toHaveBeenCalledTimes(1)
+    } finally {
+      dispose()
+    }
+  })
+})
+
 describe('completion notices', () => {
  it('injects a notice into the owning agent when an unreported task settles', async () => {
    const { ctx } = await setup()