Merge remote-tracking branch 'origin/worktree-llm-web-config' into worktree/onboarding-deepseek-config

# Conflicts: # packages/client/ui-models/README.i18n.yaml # packages/client/ui-models/README.md # packages/client/ui-models/README.zh.md # packages/client/ui-models/src/client/store.ts # packages/client/ui-models/tests/components.spec.tsx
2026-07-30 20:55:12 +08:00
parent fc8f992cde f5d21af60b
commit b6130b178d
535 changed files with 12376 additions and 4880 deletions
--- a/packages/client/ui-models/README.i18n.yaml
+++ b/packages/client/ui-models/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-models/README.md
-README.md: eea761859a187b13e08e3cd48e2120cc0cdead15
-README.zh.md: 8fd0f7af3625bfe9cf34425c651b41a8115b74aa
+README.md: aac437a13f6465196fcf1f8908b1d9ea2ccef401
+README.zh.md: 468537ac217a46395f2ec78174efa1f5d75a679d
--- a/packages/client/ui-models/README.md
+++ b/packages/client/ui-models/README.md
@@ -8,7 +8,7 @@ Rows are the *configured* providers (their profile resolves in the owning namesp

 The first-run overlay projects `deepseek-official` readiness from that same joined snapshot. A configured literal `apiKey` secret sidecar or configured credential reference suppresses the prompt, including a read-only launch-environment credential. A mounted adapter with a missing writable reference shows one action that opens Settings on the Models section, whose existing setup card exclusively owns key input and `credentials.set`; the overlay never holds a secret. An absent adapter is skipped because browser navigation cannot mount Cordis plugins, while an unusable settings or credential capability produces a deployment diagnostic with the same route to Models.

-Apply semantics mirror the settings seam: an edit without removals lands as a minimal `settings.update` merge patch, while clearing a fold field back to inherited or deleting a row lands through `settings.replace` of the whole user section so removals actually take effect — safe wholesale, because the section stores key references, never key values. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.
+Every edit lands as `settings.mutate` path ops against the stored section — a set per changed field, an unset per cleared one, and a single unset for a deleted row. The page only ever holds the REDACTED descriptor, so it names the fields it can see rather than rebuilding a section: a stored literal secret it never received is mentioned by no op and survives. Each write carries the `revision` the card opened at, so a concurrent write from another tab or an external `settings.yaml` edit is refused as `settings-conflict` and the card asks the user to reopen instead of replaying its stale snapshot. The page refetches on the pushed invalidations (`settings/changed`, `credentials/changed`, `models/changed`, and `connection/reset`) once it has loaded, so an external `settings.yaml` edit, a second tab, or a settings-born route converges without polling.

 ## Model Experience

@@ -20,8 +20,7 @@ None; this package neither assembles nor sends a provider request.

 ## Known Limitations and Deferred Work

- **A reset can drop a stored literal secret in the same subtree** — a replace-carried removal cannot re-supply secrets the wire never returned; store keys behind `credentials.*` references (the product default) and the case cannot arise.
 - **Only the API key and the curated fold fields are editable on the card** — the hand-written editor traded schema-generic field coverage for the mockup layout ([Agent Note](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)); advanced fields (`models`, retry policy, timeouts…) are edited in `settings.yaml`, which the fold points at. A profile schema without the conventional fields renders the hint alone, and the two curated layouts key on the `llm-deepseek`/`llm-pi-ai` namespaces by name.
- **Deleting a row leaves its stored key in `.env`** — removal replaces the settings profile but deliberately does not unset the derived credential; re-adding the provider finds the key already configured. An explicit key-removal control is deferred.
+- **Deleting a row leaves its stored key in `.env`** — removal unsets the settings profile but deliberately does not unset the derived credential; re-adding the provider finds the key already configured. An explicit key-removal control is deferred.
 - **No per-provider model listing on the page** — the picker surfaces models; this page shows route state only. A models preview per row is deferred until a consumer needs it.
 - **Undeclared live routes render nowhere** — a route registered without a configurable-provider declaration has no settings address; it stays visible in pickers but not on this page's rows.
--- a/packages/client/ui-models/README.zh.md
+++ b/packages/client/ui-models/README.zh.md
@@ -8,7 +8,7 @@

 首次使用浮层从同一个联接快照得出 `deepseek-official` 的就绪状态。若 `apiKey` 字面量对应的 secret 槽位标记为已设置，或凭据引用已配置，浮层就不再显示，其中包括来自启动环境且只读的凭据。适配器已挂载、引用可写但尚未配置时，浮层只显示一个操作按钮，用于打开「设置」的 Models 分区；密钥输入和 `credentials.set` 仅由该分区已有的设置卡片负责，浮层绝不持有 secret。适配器缺失时直接跳过，因为浏览器导航无法挂载 Cordis 插件；设置或凭据能力不可用时则显示部署诊断，并提供同一个前往 Models 的入口。

-「应用」语义与 settings seam 呈镜像：不含删除的编辑以最小的 `settings.update` 合并 patch 落地，把折叠区字段清回继承值或删除整行则经对整个用户分节的 `settings.replace` 落地，使删除真正生效——整体替换是安全的，因为该分节存的是密钥引用，从不存密钥值。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。
+每一次编辑都以 `settings.mutate` 的路径 op 落到已存分节上——每个变更字段一条 set、每个清空字段一条 unset、删除整行则是单独一条 unset。页面自始至终只持有**脱敏后**的 descriptor，因此它点名自己看得见的字段，而不是重建分节：一个它从未收到过的已存字面机密不会被任何 op 提及，也就得以留存。每次写入都携带该卡片打开时的 `revision`，因此来自另一个标签页或对 `settings.yaml` 的外部编辑所产生的并发写入会以 `settings-conflict` 被拒绝，卡片会请用户重新打开，而不是把自己的陈旧快照重放上去。页面加载完成后会在推送的失效事件（`settings/changed`、`credentials/changed`、`models/changed` 与 `connection/reset`）上重拉，因此外部的 `settings.yaml` 编辑、第二个标签页或 settings 新生的路由都无需轮询即可收敛。

 ## 模型体验

@@ -20,8 +20,7 @@

 ## 已知限制与暂缓事项

- **重置可能丢弃同一子树中已存储的字面 secret**：经 replace 承载的删除无法重新提供协议从未返回过的 secret；把密钥放在 `credentials.*` 引用背后（产品默认做法），该情形便不会出现。
 - **卡片上可编辑的只有 API 密钥与精选折叠区字段**：手写编辑器用 schema 通用的字段覆盖面换来了设计稿上的布局（[Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-30-web-config-plane.md)）；进阶字段（`models`、重试策略、超时……）在 `settings.yaml` 中编辑，折叠区会指向它。不带这些约定字段的 profile schema 只渲染该提示，两套精选布局则以 `llm-deepseek`/`llm-pi-ai` 这两个 namespace 的名字为键。
- **删除一行会把它已存储的密钥留在 `.env` 里**：删除替换的是 settings profile，却刻意不清除那条派生凭据；重新添加该提供方时会发现密钥已配置。显式的密钥移除控件暂缓。
+- **删除一行会把它已存储的密钥留在 `.env` 里**：删除取消设置的是 settings profile，却刻意不清除那条派生凭据；重新添加该提供方时会发现密钥已配置。显式的密钥移除控件暂缓。
 - **页面上没有逐提供方的模型列表**：模型由选择器呈现；本页只展示路由状态。逐行的模型预览暂缓，待有消费方需要时再实现。
 - **未声明的存活路由无处渲染**：未附带可配置提供方声明即注册的路由没有 settings 地址；它在各选择器中仍然可见，但不会出现在本页的行里。
--- a/packages/client/ui-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-models/src/client/ModelsSection.tsx
@@ -10,9 +10,9 @@

 import { useState } from 'react'
 import type { ReactNode } from 'react'
-import type { IApiClient, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client'
-import { deletePath } from '@deepseek-ai/dsh-client-schema-form'
+import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
+import { messageOf } from './store.ts'
 import type { ModelsSettingsState, ModelsSettingsStore, ProviderRow } from './store.ts'
 import { ProviderEditor } from './ProviderEditor.tsx'
 import type { en } from './locales.ts'
@@ -45,24 +45,35 @@ interface EditorTarget {
 }

 /**
- * Remove one user-added provider profile from its namespace's user section
- * (wholesale replace — merge cannot express a removal) and reload on success.
+ * Remove one user-added provider profile by unsetting its path in the stored
+ * user section, then reload. The removal names the profile rather than
+ * rebuilding the section: this page only ever holds the redacted descriptor,
+ * so a rebuilt section would drop every literal secret stored elsewhere in
+ * the namespace along with the profile being removed.
 * @param api - settings wire face.
 * @param controller - the page store to refresh.
 * @param target - the provider's settings address.
- * @param namespace - the owning namespace view.
- * @returns settles when the write and any reload finished.
+ * @returns the failure message, or undefined once the write and reload landed.
 */
 export async function removeProviderProfile(
  api: Pick<IApiClient, 'settings'>,
  controller: ModelsSettingsStore,
  target: { settingsNs: string; settingsPath: readonly string[] },
-  namespace: SettingsNamespaceView,
-): Promise<void> {
-  const user = structuredClone((namespace.user ?? {}) as Record<string, unknown>)
-  const next = deletePath(user, [...target.settingsPath])
-  const response = await api.settings.replace({ ns: target.settingsNs, section: next })
-  if (response.result.ok) await controller.load()
+): Promise<string | undefined> {
+  let response
+  try {
+    response = await api.settings.mutate({
+      ns: target.settingsNs,
+      ops: [{ op: 'unset', path: [...target.settingsPath] }],
+    })
+  } catch (error) {
+    // The transport rejected rather than answering; the caller must be able
+    // to say so instead of the row silently staying put.
+    return messageOf(error)
+  }
+  if (!response.result.ok) return response.result.error.message
+  await controller.load()
+  return undefined
 }

 /**
@@ -182,7 +193,11 @@ function Loaded({ injected }: { injected: ModelsSectionInjected }): ReactNode {
                        type="button"
                        className={styles['dangerButton']}
                        disabled={!state.writable}
-                        onClick={() => { void removeProviderProfile(api, controller, target, namespace) }}
+                        onClick={() => {
+                          void removeProviderProfile(api, controller, target).then((failure) => {
+                            if (failure !== undefined) controller.fail(failure)
+                          })
+                        }}
                      >
                        {t('remove')}
                      </button>
--- a/packages/client/ui-models/src/client/ProviderEditor.tsx
+++ b/packages/client/ui-models/src/client/ProviderEditor.tsx
@@ -6,19 +6,19 @@
 * has none, and the pi-ai profile records that derivation as `apiKeyEnv`);
 * the collapsed 自定义设置 area carries the per-family extras (`baseURL` for
 * both families, plus `reasoningEffort` for deepseek / `reasoning` for
- * pi-ai). Everything else stays owned by `settings.yaml`. Profile edits land as a
- * minimal `settings.update` merge patch; clearing a field back to inherited
- * removes its key, so that apply replaces the user section (safe: the section
- * stores references, never key values).
+ * pi-ai). Everything else stays owned by `settings.yaml`. Profile edits land as
+ * minimal `settings.mutate` path ops against the stored section — the card
+ * reads the redacted descriptor, so it names only the fields it can see and a
+ * stored literal secret is never collaterally removed.
 */

 import { useEffect, useMemo, useState } from 'react'
 import type { ReactNode } from 'react'
-import type { CredentialView, IApiClient, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client'
+import type { CredentialView, IApiClient, SettingsNamespaceView, SettingsPathOpView } from '@deepseek-ai/dsh-client-connection/client'
 import {
  deletePath, getPath, nodeAtPath, rehydrateSchema, setPath, validateDraft,
 } from '@deepseek-ai/dsh-client-schema-form'
-import { deriveKeyRef } from './store.ts'
+import { deriveKeyRef, messageOf } from './store.ts'
 import type { en } from './locales.ts'
 import styles from './ModelsSection.module.css'

@@ -70,21 +70,33 @@ function draftAt(namespace: SettingsNamespaceView, path: readonly string[]): Rec
 }

 /**
- * Whether any key present in `before` is absent from `after` (a reset
- * happened somewhere in the draft, so the apply must replace, not merge).
- * @param before - the user-layer subtree the draft started from.
- * @param after - the edited draft.
- * @returns whether a removal exists at any depth.
+ * The minimal path ops carrying `after` over `before`, both as the card sees
+ * them (that is, redacted). Only keys the card observed are named: a stored
+ * `role('secret')` field appears in neither side, so it produces no op and
+ * survives the write — the whole reason edits are path-addressed rather than
+ * a rebuilt section.
+ * @param base - path of the edited subtree inside the user section.
+ * @param before - the subtree as loaded, or undefined when it is new.
+ * @param after - the subtree as edited.
+ * @returns ordered set/unset ops; empty when nothing changed.
 */
-export function removedAny(before: unknown, after: unknown): boolean {
-  if (typeof before !== 'object' || before === null) return false
-  /* v8 ignore next -- the editor edits containers in place; a container cannot become a primitive */
-  if (typeof after !== 'object' || after === null) return true
-  for (const [key, value] of Object.entries(before)) {
-    if (!(key in (after as Record<string, unknown>))) return true
-    if (removedAny(value, (after as Record<string, unknown>)[key])) return true
+export function pathOps(
+  base: readonly string[],
+  before: unknown,
+  after: Record<string, unknown>,
+): SettingsPathOpView[] {
+  const previous = typeof before === 'object' && before !== null && !Array.isArray(before)
+    ? before as Record<string, unknown>
+    : {}
+  const ops: SettingsPathOpView[] = []
+  for (const [key, value] of Object.entries(after)) {
+    if (JSON.stringify(previous[key]) === JSON.stringify(value)) continue
+    ops.push({ op: 'set', path: [...base, key], value })
  }
-  return false
+  for (const key of Object.keys(previous)) {
+    if (!(key in after)) ops.push({ op: 'unset', path: [...base, key] })
+  }
+  return ops
 }

 /** The editor layout the owning namespace selects. */
@@ -115,6 +127,10 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
  const [keyState, setKeyState] = useState<CredentialView | undefined>(undefined)
  const [busy, setBusy] = useState(false)
  const [failure, setFailure] = useState<string | undefined>(undefined)
+  // The revision this card opened at. A write carrying it is refused if
+  // anything else — another tab, an external edit of settings.yaml — moved the
+  // namespace meanwhile, instead of silently overwriting that change.
+  const [openedAt] = useState(() => namespace.revision)
  const root = useMemo(() => rehydrateSchema(namespace.schema), [namespace.schema])
  const node = useMemo(() => nodeAtPath(root, settingsPath), [root, settingsPath])
  const fallback = getPath(namespace.value, settingsPath)
@@ -125,10 +141,17 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
  useEffect(() => {
    let stale = false
    setKeyState(undefined)
-    void api.credentials.describe({ refs: [keyRef] }).then((response) => {
-      if (stale || !response.result.ok) return
-      setKeyState(response.result.value.credentials[keyRef])
-    })
+    // The key state is a placeholder hint, not a precondition for editing:
+    // neither a business rejection nor a transport failure may reach the
+    // browser as an unhandled rejection, so the card simply renders without
+    // the "already configured" hint.
+    void api.credentials.describe({ refs: [keyRef] }).then(
+      (response) => {
+        if (stale || !response.result.ok) return
+        setKeyState(response.result.value.credentials[keyRef])
+      },
+      () => undefined,
+    )
    return () => { stale = true }
  }, [api.credentials, keyRef])

@@ -140,9 +163,14 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
    setDraft(current => next === undefined ? deletePath(current, [key]) : setPath(current, [key], next))
  }

-  const apply = async (): Promise<void> => {
-    setBusy(true)
-    setFailure(undefined)
+  /**
+   * The write for this card, or a failure message. Every edit travels as
+   * path ops against the STORED section: the draft comes from the redacted
+   * descriptor, so a wholesale replace rebuilt from it would delete the
+   * literal secrets the wire never returned. Ops name only the fields this
+   * card can see, so a stored secret is untouched by construction.
+   */
+  const applyOnce = async (): Promise<string | undefined> => {
    const ns = namespace.ns
    const original = getPath(namespace.user, settingsPath)
    // The pi-ai profile must name the reference the key stores under, so a
@@ -151,45 +179,46 @@ export function ProviderEditor(props: ProviderEditorProps): ReactNode {
      && stringAt(fallback, 'apiKeyEnv') === undefined
      ? setPath(draft, ['apiKeyEnv'], keyRef)
      : draft
-    const settingsChanged = JSON.stringify(next) !== JSON.stringify(original ?? {})
-    if (settingsChanged) {
-      const needsReplace = removedAny(original, next)
-      // Merge patches stay minimal (just this profile); a replace must carry
-      // the complete next user section because it lands wholesale.
-      const patch = settingsPath.length === 0 ? next : setPath({}, [...settingsPath], next)
-      /* v8 ignore next 3 -- a subtree apply implies the join served this namespace's user layer */
-      const nextSection = settingsPath.length === 0
-        ? next
-        : setPath(structuredClone((namespace.user ?? {}) as Record<string, unknown>), [...settingsPath], next)
-      /* v8 ignore next -- apply is only reachable from the rendered card, which required a resolved node */
-      if (node !== undefined) {
-        const sectionError = settingsPath.length === 0 ? validateDraft(node, next) : undefined
-        if (sectionError !== undefined) {
-          setBusy(false)
-          setFailure(sectionError)
-          return
-        }
-      }
-      const response = needsReplace
-        ? await api.settings.replace({ ns, section: nextSection })
-        : await api.settings.update({ ns, patch })
+    /* v8 ignore next -- apply is only reachable from the rendered card, which required a resolved node */
+    if (node !== undefined && settingsPath.length === 0) {
+      const sectionError = validateDraft(node, next)
+      if (sectionError !== undefined) return sectionError
+    }
+    const ops = pathOps(settingsPath, original, next)
+    if (ops.length > 0) {
+      const response = await api.settings.mutate({ ns, ops, expectedRevision: openedAt })
      if (!response.result.ok) {
-        setBusy(false)
-        setFailure(response.result.error.message)
-        return
+        return response.result.error.code === 'settings-conflict'
+          ? t('conflict')
+          : response.result.error.message
      }
    }
    if (keyDraft.length > 0) {
      const stored = await api.credentials.set({ ref: keyRef, value: keyDraft })
-      if (!stored.result.ok) {
-        setBusy(false)
-        setFailure(stored.result.error.message)
+      if (!stored.result.ok) return stored.result.error.message
+    }
+    setKeyDraft('')
+    return undefined
+  }
+
+  const apply = async (): Promise<void> => {
+    setBusy(true)
+    setFailure(undefined)
+    try {
+      const failure = await applyOnce()
+      if (failure !== undefined) {
+        setFailure(failure)
        return
      }
-      setKeyDraft('')
+      props.onClose(true)
+    } catch (error) {
+      // A transport failure (disconnect, a request the host refuses) rejects
+      // rather than answering; without this the card would stay busy forever
+      // with no error shown.
+      setFailure(messageOf(error))
+    } finally {
+      setBusy(false)
    }
-    setBusy(false)
-    props.onClose(true)
  }

  if (node === undefined) {
--- a/packages/client/ui-models/src/client/locales.ts
+++ b/packages/client/ui-models/src/client/locales.ts
@@ -16,6 +16,7 @@ export const en = {
  applying: 'Applying…',
  readOnly: 'The settings document is read-only in this deployment.',
  loadFailed: 'Loading the provider directory failed',
+  conflict: 'Someone else changed these settings while this card was open. Close it and reopen to edit the current values.',
  retry: 'Retry',
  keyInput: 'API key',
  keyPlaceholder: 'Enter your API key',
@@ -54,6 +55,7 @@ export const zh: typeof en = {
  applying: '保存中…',
  readOnly: '当前部署的设置文档为只读。',
  loadFailed: '加载提供方目录失败',
+  conflict: '这张卡片打开期间，这些设置已被其他地方改动。请关闭后重新打开，在当前值上编辑。',
  retry: '重试',
  keyInput: 'API 密钥',
  keyPlaceholder: '输入 API 密钥',
--- a/packages/client/ui-models/src/client/store.ts
+++ b/packages/client/ui-models/src/client/store.ts
@@ -44,6 +44,17 @@ export interface ModelsSettingsState {
  namespaces: ReadonlyMap<string, SettingsNamespaceView>
 }

+/**
+ * Human text for a rejected wire call. A transport failure rejects with an
+ * Error; a host or a runtime can reject with anything, and the page still has
+ * to say something.
+ * @param error - the rejection value.
+ * @returns the message to show.
+ */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
 /**
 * Derive the conventional credential reference for a provider route: the v1
 * page never asks for an environment-variable name, so a typed key stores
@@ -77,11 +88,6 @@ function literalApiKeyConfigured(
    && secret.path.every((key, index) => key === secretPath[index]))
 }

-/** Safe display text for a rejected transport or business response. */
-function errorText(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
-}
-
 /** The models settings page controller (one per settings surface). */
 export class ModelsSettingsStore {
  /** The snapshot the section renders from (uSES-safe store). */
@@ -97,6 +103,18 @@ export class ModelsSettingsStore {
   */
  constructor(private readonly api: Pick<IApiClient, 'settings' | 'credentials' | 'llm'>) {}

+  /**
+   * Surface a failure from an operation the page ran outside {@link load} —
+   * a row removal — on the same banner a load failure uses.
+   * @param message - the failure text to show.
+   */
+  fail(message: string): void {
+    this.store.update((s) => {
+      s.status = 'error'
+      s.error = message
+    })
+  }
+
  /**
   * Refresh the whole page snapshot: directory and namespaces in parallel,
   * then one batched credential describe over every referenced ref. A
@@ -151,12 +169,13 @@ export class ModelsSettingsStore {
    if (refs.length > 0) {
      try {
        const response = await this.api.credentials.describe({ refs })
-        // Credential state is an enrichment for the Models page, while the
-        // onboarding readiness projection below reports its failure.
+        // Credential state is an enrichment for the Models page: neither a
+        // business rejection nor a transport failure fails the load. The
+        // onboarding projection below retains the failure distinction.
        if (response.result.ok) credentials = response.result.value.credentials
        else credentialError = response.result.error.message
      } catch (error) {
-        credentialError = errorText(error)
+        credentialError = messageOf(error)
      }
    }
    if (generation !== this.generation) return
--- a/packages/client/ui-models/tests/components.spec.tsx
+++ b/packages/client/ui-models/tests/components.spec.tsx
@@ -7,7 +7,7 @@ import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import type { RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client'
 import { ModelsSection, needsSetup, removeProviderProfile } from '../src/client/ModelsSection.tsx'
 import type { ModelsSectionInjected, ModelsSectionProps } from '../src/client/ModelsSection.tsx'
-import { removedAny } from '../src/client/ProviderEditor.tsx'
+import { pathOps } from '../src/client/ProviderEditor.tsx'
 import { deriveKeyRef, ModelsSettingsStore } from '../src/client/store.ts'
 import type { ProviderRow } from '../src/client/store.ts'
 import { en } from '../src/client/locales.ts'
@@ -44,6 +44,7 @@ function wireNamespaces(): SettingsNamespaceView[] {
      user: { reasoningEffort: 'high' },
      applies: 'live',
      secrets: [{ path: ['apiKey'], set: false }],
+      revision: 0,
    },
    {
      ns: 'llm-plain',
@@ -53,6 +54,7 @@ function wireNamespaces(): SettingsNamespaceView[] {
      value: {},
      applies: 'live',
      secrets: [],
+      revision: 0,
    },
    {
      ns: 'llm-pi-ai',
@@ -61,6 +63,7 @@ function wireNamespaces(): SettingsNamespaceView[] {
      user: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy', headers: { 'X-Team': 'a' } }, zombie: {} } },
      applies: 'live',
      secrets: [{ path: ['token'], set: false }, { path: ['providers', 'openai', 'apiKey'], set: false }],
+      revision: 0,
    },
  ]
 }
@@ -79,10 +82,12 @@ function fail<T>(message: string, code = 'settings-rejected'): RpcResponse<T> {
 function scriptedFace(overrides: {
  update?: ReturnType<typeof vi.fn>
  replace?: ReturnType<typeof vi.fn>
+  mutate?: ReturnType<typeof vi.fn>
  set?: ReturnType<typeof vi.fn>
 } = {}) {
  const update = overrides.update ?? vi.fn(() => Promise.resolve(ok(wireNamespaces()[2])))
  const replace = overrides.replace ?? vi.fn(() => Promise.resolve(ok(wireNamespaces()[2])))
+  const mutate = overrides.mutate ?? vi.fn(() => Promise.resolve(ok(wireNamespaces()[2])))
  const set = overrides.set ?? vi.fn(() => Promise.resolve(ok({})))
  const face = {
    llm: {
@@ -102,6 +107,7 @@ function scriptedFace(overrides: {
      describe: vi.fn(() => Promise.resolve(ok({ writable: true, namespaces: wireNamespaces() }))),
      update,
      replace,
+      mutate,
    },
    credentials: {
      describe: vi.fn((payload: { refs: string[] }) => Promise.resolve(ok({
@@ -115,13 +121,13 @@ function scriptedFace(overrides: {
      unset: vi.fn(() => Promise.resolve(ok({}))),
    },
  }
-  return { face, update, replace, set }
+  return { face, update, replace, mutate, set }
 }

 type WireFace = ConstructorParameters<typeof ModelsSettingsStore>[0]

 async function mountSection(overrides: Parameters<typeof scriptedFace>[0] = {}) {
-  const { face, update, replace, set } = scriptedFace(overrides)
+  const { face, update, replace, mutate, set } = scriptedFace(overrides)
  const controller = new ModelsSettingsStore(face as unknown as WireFace)
  await controller.load()
  const injected: ModelsSectionInjected = {
@@ -131,7 +137,7 @@ async function mountSection(overrides: Parameters<typeof scriptedFace>[0] = {})
    t,
  }
  const view = render(<ModelsSection {...injected} />)
-  return { view, face, update, replace, set, controller }
+  return { view, face, update, replace, mutate, set, controller }
 }

 describe('ModelsSection', () => {
@@ -197,10 +203,15 @@ describe('ModelsSection', () => {
    expect(deriveKeyRef('minimax-cn')).toBe('MINIMAX_CN_API_KEY')
  })

-  it('detects removals at any draft depth', () => {
-    expect(removedAny({ a: { b: 1, c: 2 } }, { a: { b: 1 } })).toBe(true)
-    expect(removedAny({ a: { b: 1 } }, { a: { b: 2 }, d: 3 })).toBe(false)
-    expect(removedAny(undefined, {})).toBe(false)
+  it('names only the fields the card can see, so an unseen secret survives', () => {
+    // `before` is the REDACTED subtree: a stored literal apiKey is in neither
+    // side, so no op mentions it and the seam leaves it alone.
+    expect(pathOps(['providers', 'openai'], { baseURL: 'https://old', reasoning: 'high' }, { reasoning: 'high' }))
+      .toEqual([{ op: 'unset', path: ['providers', 'openai', 'baseURL'] }])
+    expect(pathOps([], { b: 1 }, { b: 2, d: 3 }))
+      .toEqual([{ op: 'set', path: ['b'], value: 2 }, { op: 'set', path: ['d'], value: 3 }])
+    expect(pathOps([], undefined, {})).toEqual([])
+    expect(pathOps([], { a: 1 }, { a: 1 })).toEqual([])
  })

  it('stores a typed key write-only from the setup card without touching settings', async () => {
@@ -213,9 +224,9 @@ describe('ModelsSection', () => {
    await waitFor(() => { expect(face.settings.describe.mock.calls.length).toBeGreaterThan(1) })
  })

-  it('applies customized deepseek fields as a merge patch', async () => {
-    const { update } = await mountSection({
-      update: vi.fn(() => Promise.resolve(ok(wireNamespaces()[0]))),
+  it('applies customized deepseek fields as path ops', async () => {
+    const { mutate } = await mountSection({
+      mutate: vi.fn(() => Promise.resolve(ok(wireNamespaces()[0]))),
    })
    fireEvent.click(screen.getByText(en.customized))
    const baseURL = screen.getByLabelText<HTMLInputElement>(en.baseUrl)
@@ -224,23 +235,33 @@ describe('ModelsSection', () => {
    expect(baseURL.placeholder).toBe('https://api.deepseek.com')
    fireEvent.change(baseURL, { target: { value: 'https://next2' } })
    fireEvent.click(screen.getByText(en.apply))
-    await waitFor(() => { expect(update).toHaveBeenCalledTimes(1) })
-    expect(update.mock.calls[0]?.[0]).toEqual({
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    // Only the field that actually changed: reasoningEffort was already
+    // 'high' in the loaded profile, so it produces no op.
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
      ns: 'llm-deepseek',
-      patch: { reasoningEffort: 'high', baseURL: 'https://next2' },
+      ops: [{ op: 'set', path: ['baseURL'], value: 'https://next2' }],
+      expectedRevision: 0,
    })
  })

-  it('clears an inherited override through replace so the removal lands', async () => {
-    const { replace, update } = await mountSection()
+  it('clears an inherited override with an unset op, never a whole-section replace', async () => {
+    // The data-loss shape: the old path rebuilt the section from the REDACTED
+    // user layer and replaced it wholesale, deleting any stored literal key.
+    const { replace, update, mutate } = await mountSection()
    fireEvent.click(screen.getByText(en.customized))
    const effort = screen.getByLabelText<HTMLSelectElement>(en.effort)
    expect(effort.value).toBe('high')
    fireEvent.change(effort, { target: { value: '' } })
    fireEvent.click(screen.getByText(en.apply))
-    await waitFor(() => { expect(replace).toHaveBeenCalledTimes(1) })
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    expect(replace).not.toHaveBeenCalled()
    expect(update).not.toHaveBeenCalled()
-    expect(replace.mock.calls[0]?.[0]).toEqual({ ns: 'llm-deepseek', section: {} })
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
+      ns: 'llm-deepseek',
+      ops: [{ op: 'unset', path: ['reasoningEffort'] }],
+      expectedRevision: 0,
+    })
  })

  it('pins the deepseek placeholder and clears typed input back to inherited', async () => {
@@ -251,6 +272,7 @@ describe('ModelsSection', () => {
      value: {},
      applies: 'live',
      secrets: [],
+      revision: 0,
    }
    const { ProviderEditor } = await import('../src/client/ProviderEditor.tsx')
    render(<ProviderEditor
@@ -282,7 +304,7 @@ describe('ModelsSection', () => {
  })

  it('edits a pi-ai profile with the curated fields only', async () => {
-    const { update } = await mountSection()
+    const { mutate } = await mountSection()
    fireEvent.click(screen.getAllByText(en.edit)[0] as HTMLElement)
    // The configured credential shows as the stored placeholder.
    const keys = await screen.findAllByLabelText<HTMLInputElement>(en.keyInput)
@@ -297,19 +319,20 @@ describe('ModelsSection', () => {
    const effort = screen.getAllByLabelText<HTMLSelectElement>(en.effort)
    fireEvent.change(effort[effort.length - 1] as HTMLSelectElement, { target: { value: 'xhigh' } })
    fireEvent.click(screen.getAllByText(en.apply)[1] as HTMLElement)
-    await waitFor(() => { expect(update).toHaveBeenCalledTimes(1) })
-    expect(update.mock.calls[0]?.[0]).toEqual({
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    // Only the edited field travels: apiKeyEnv, baseURL and headers were
+    // already stored with these values, so no op restates them — and the
+    // profile's stored literal apiKey, absent from the redacted view the card
+    // read, is named by nothing at all.
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
      ns: 'llm-pi-ai',
-      patch: {
-        providers: {
-          openai: { apiKeyEnv: 'OPENAI_API_KEY', baseURL: 'https://proxy', headers: { 'X-Team': 'a' }, reasoning: 'xhigh' },
-        },
-      },
+      ops: [{ op: 'set', path: ['providers', 'openai', 'reasoning'], value: 'xhigh' }],
+      expectedRevision: 0,
    })
  })

  it('adds a dormant provider with a derived reference and stores its key', async () => {
-    const { update, set } = await mountSection()
+    const { mutate, set } = await mountSection()
    fireEvent.click(screen.getByText(`+ ${en.add}`))
    const pick = await screen.findByLabelText<HTMLSelectElement>(en.provider)
    expect([...pick.options].map(option => option.value)).toEqual(['anthropic', 'broken', 'plain'])
@@ -323,10 +346,11 @@ describe('ModelsSection', () => {
    const addKey = keys[keys.length - 1] as HTMLInputElement
    fireEvent.change(addKey, { target: { value: 'sk-ant' } })
    fireEvent.click(screen.getAllByText(en.apply)[1] as HTMLElement)
-    await waitFor(() => { expect(update).toHaveBeenCalledTimes(1) })
-    expect(update.mock.calls[0]?.[0]).toEqual({
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
      ns: 'llm-pi-ai',
-      patch: { providers: { anthropic: { apiKeyEnv: 'ANTHROPIC_API_KEY' } } },
+      ops: [{ op: 'set', path: ['providers', 'anthropic', 'apiKeyEnv'], value: 'ANTHROPIC_API_KEY' }],
+      expectedRevision: 0,
    })
    await waitFor(() => { expect(set).toHaveBeenCalledWith({ ref: 'ANTHROPIC_API_KEY', value: 'sk-ant' }) })
  })
@@ -349,7 +373,7 @@ describe('ModelsSection', () => {

  it('surfaces a rejected settings write and never stores the key after it', async () => {
    const { set } = await mountSection({
-      update: vi.fn(() => Promise.resolve(fail('llm-pi-ai: unknown pi-ai provider "bogus"'))),
+      mutate: vi.fn(() => Promise.resolve(fail('llm-pi-ai: unknown pi-ai provider "bogus"'))),
    })
    fireEvent.click(screen.getByText(`+ ${en.add}`))
    await screen.findByLabelText(en.provider)
@@ -360,6 +384,57 @@ describe('ModelsSection', () => {
    expect(set).not.toHaveBeenCalled()
  })

+  it('renders the card without the stored-key hint when the credential probe rejects', async () => {
+    // The probe is a placeholder hint, not a precondition: an escaping
+    // rejection would surface in the browser as an unhandled rejection.
+    const { face } = scriptedFace()
+    face.credentials.describe = vi.fn(() => Promise.reject(new Error('connection lost')))
+    const unhandled = vi.fn()
+    process.on('unhandledRejection', unhandled)
+    try {
+      const controller = new ModelsSettingsStore(face as unknown as WireFace)
+      await controller.load()
+      render(<ModelsSection
+        controller={controller}
+        useSnapshot={bindSnapshotSelector(controller.store)}
+        api={face as never}
+        t={t}
+      />)
+      const key = await screen.findByLabelText<HTMLInputElement>(en.keyInput)
+      expect(key.placeholder).toBe(en.keyPlaceholder)
+      await new Promise(resolve => setTimeout(resolve, 10))
+      expect(unhandled).not.toHaveBeenCalled()
+    } finally {
+      process.off('unhandledRejection', unhandled)
+    }
+  })
+
+  it('tells the user to reopen when another writer moved the namespace first', async () => {
+    // The stale-draft overwrite: two tabs open the same card, the other saves,
+    // and this one must be refused rather than replay its opening snapshot.
+    const { set } = await mountSection({
+      mutate: vi.fn(() => Promise.resolve(fail('changed since it was read', 'settings-conflict'))),
+    })
+    fireEvent.click(screen.getByText(en.customized))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>(en.baseUrl), { target: { value: 'https://mine' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await screen.findByText(en.conflict)
+    expect(set).not.toHaveBeenCalled()
+  })
+
+  it('keeps the card usable when the write rejects instead of answering', async () => {
+    // A transport failure (disconnect, or the 403 a non-loopback browser now
+    // gets on the whole configuration plane) rejects rather than returning a
+    // failed envelope: without a catch the card would stay busy forever.
+    await mountSection({ mutate: vi.fn(() => Promise.reject(new Error('connection lost'))) })
+    fireEvent.click(screen.getByText(en.customized))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>(en.baseUrl), { target: { value: 'https://next' } })
+    fireEvent.click(screen.getByText(en.apply))
+    await screen.findByText('connection lost')
+    // Not stuck in `applying…`: the finally cleared busy, so Apply is live again.
+    expect(screen.getByText(en.apply)).toBeTruthy()
+  })
+
  it('surfaces a shadowed credential write on the card', async () => {
    await mountSection({
      set: vi.fn(() => Promise.resolve(fail('credentials: DEEPSEEK_API_KEY is shadowed by the read-only environment', 'credential-rejected'))),
@@ -396,11 +471,15 @@ describe('ModelsSection', () => {
    await waitFor(() => { expect(set).toHaveBeenCalledTimes(1) })
  })

-  it('removes a user-added provider through replace', async () => {
-    const { replace } = await mountSection()
+  it('removes a user-added provider by unsetting its path', async () => {
+    const { replace, mutate } = await mountSection()
    fireEvent.click(screen.getAllByText(en.remove)[0] as HTMLElement)
-    await waitFor(() => { expect(replace).toHaveBeenCalledTimes(1) })
-    expect(replace.mock.calls[0]?.[0]).toEqual({ ns: 'llm-pi-ai', section: { providers: { zombie: {} } } })
+    await waitFor(() => { expect(mutate).toHaveBeenCalledTimes(1) })
+    expect(replace).not.toHaveBeenCalled()
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
+      ns: 'llm-pi-ai',
+      ops: [{ op: 'unset', path: ['providers', 'openai'] }],
+    })
  })

  it('renders the load failure with a retry control', async () => {
@@ -474,30 +553,54 @@ describe('ModelsSection', () => {
    await screen.findByText('DeepSeek')
  })

-  it('removes against a namespace with no user layer as an empty-section replace', async () => {
-    const { face, replace, controller } = await mountSection()
-    const namespace = controller.store.getSnapshot().namespaces.get('llm-plain')
+  it('removes by unsetting the profile path, never by rebuilding the section', async () => {
+    // The section rebuild is what dropped stored literal secrets: this page
+    // only ever holds the redacted descriptor, so the removal names the path.
+    const { face, mutate, replace, controller } = await mountSection()
    await removeProviderProfile(
      face as unknown as Parameters<typeof removeProviderProfile>[0],
      controller,
      { settingsNs: 'llm-plain', settingsPath: ['ghost-profile'] },
-      namespace as NonNullable<typeof namespace>,
    )
-    expect(replace.mock.calls[0]?.[0]).toEqual({ ns: 'llm-plain', section: {} })
+    expect(mutate.mock.calls[0]?.[0]).toEqual({
+      ns: 'llm-plain',
+      ops: [{ op: 'unset', path: ['ghost-profile'] }],
+    })
+    expect(replace).not.toHaveBeenCalled()
  })

-  it('keeps the snapshot untouched when a removal write is refused', async () => {
+  it('keeps the snapshot untouched and reports the message when a removal write is refused', async () => {
    const { face, controller } = await mountSection({
-      replace: vi.fn(() => Promise.resolve(fail('read-only'))),
+      mutate: vi.fn(() => Promise.resolve(fail('read-only'))),
    })
-    const namespace = controller.store.getSnapshot().namespaces.get('llm-pi-ai')
    const before = controller.store.getSnapshot().rows
-    await removeProviderProfile(
+    const failure = await removeProviderProfile(
      face as unknown as Parameters<typeof removeProviderProfile>[0],
      controller,
      { settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
-      namespace as NonNullable<typeof namespace>,
    )
+    expect(failure).toBe('read-only')
    expect(controller.store.getSnapshot().rows).toBe(before)
  })
+
+  it('shows a failed removal on the page banner, including a non-Error rejection', async () => {
+    // The whole click path: the row's Remove button, the transport rejecting
+    // with a non-Error value, and the store surfacing it where a load failure
+    // would appear — rather than the row silently staying put.
+    await mountSection({ mutate: vi.fn(() => Promise.reject(new Error('the host refused'))) })
+    fireEvent.click(screen.getAllByText(en.remove)[0] as HTMLElement)
+    await screen.findByText(`${en.loadFailed}: the host refused`)
+  })
+
+  it('reports a transport rejection instead of failing the removal silently', async () => {
+    const { face, controller } = await mountSection({
+      mutate: vi.fn(() => Promise.reject(new Error('connection lost'))),
+    })
+    const failure = await removeProviderProfile(
+      face as unknown as Parameters<typeof removeProviderProfile>[0],
+      controller,
+      { settingsNs: 'llm-pi-ai', settingsPath: ['providers', 'openai'] },
+    )
+    expect(failure).toBe('connection lost')
+  })
 })
--- a/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
+++ b/packages/client/ui-models/tests/onboarding-dialog.spec.tsx
@@ -70,6 +70,7 @@ function harness(options: {
              : { apiKeyEnv: options.apiKeyEnv ?? 'DEEPSEEK_API_KEY' },
            applies: 'live' as const,
            secrets: [{ path: ['apiKey'], set: options.literal === true }],
+            revision: 0,
          }],
      })),
    },
--- a/packages/client/ui-models/tests/store.spec.ts
+++ b/packages/client/ui-models/tests/store.spec.ts
@@ -1,7 +1,7 @@
 /** Page-store join: directory × namespaces × credentials, with last-good rows on failure. */
 import { describe, expect, it } from 'vitest'
 import type { RpcResponse } from '@deepseek-ai/dsh-client-connection/client'
-import { ModelsSettingsStore } from '../src/client/store.ts'
+import { messageOf, ModelsSettingsStore } from '../src/client/store.ts'

 let nextRpc = 0
 function ok<T>(value: T): RpcResponse<T> {
@@ -26,6 +26,7 @@ const NAMESPACES = [
    base: { baseURL: 'https://base' },
    applies: 'live' as const,
    secrets: [{ path: ['apiKey'], set: false }],
+    revision: 0,
  },
  {
    ns: 'llm-pi-ai',
@@ -34,6 +35,7 @@ const NAMESPACES = [
    user: { providers: { openai: { apiKeyEnv: 'OPENAI_API_KEY' } } },
    applies: 'live' as const,
    secrets: [],
+    revision: 0,
  },
 ]

@@ -121,7 +123,7 @@ describe('ModelsSettingsStore', () => {

  it('stringifies a non-Error credential transport rejection', async () => {
    const { face } = api({
-      // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+      // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the non-Error rejection is the scenario
      describeCredentials: () => Promise.reject('credential transport refusal'),
    })
    const store = new ModelsSettingsStore(face)
@@ -199,6 +201,7 @@ describe('edge joins', () => {
          value: { providers: { weird: 'oops' } },
          applies: 'live' as const,
          secrets: [],
+          revision: 0,
        }] as never,
      })),
      providers: () => Promise.resolve(ok({
@@ -218,7 +221,7 @@ describe('edge joins', () => {
    const { face, seenRefs } = api({
      describeSettings: () => Promise.resolve(ok({
        writable: true,
-        namespaces: [{ ns: 'llm-pi-ai', schema: {}, value: { providers: {} }, applies: 'live' as const, secrets: [] }] as never,
+        namespaces: [{ ns: 'llm-pi-ai', schema: {}, value: { providers: {} }, applies: 'live' as const, secrets: [], revision: 0 }] as never,
      })),
      providers: () => Promise.resolve(ok({
        providers: [
@@ -241,7 +244,7 @@ describe('edge joins', () => {

  it('stringifies a non-Error load failure', async () => {
    // The wire can surface non-Error throwables; the store must stringify them.
-    // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+    // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the non-Error rejection is the scenario
    const { face } = api({ providers: () => Promise.reject('plain refusal') })
    const store = new ModelsSettingsStore(face)
    await store.load()
@@ -272,3 +275,13 @@ describe('edge joins', () => {
    expect(store.store.getSnapshot().rows).toHaveLength(4)
  })
 })
+
+describe('messageOf', () => {
+  it('reads an Error message, and stringifies anything else a rejection may carry', () => {
+    // The wire layer rejects with an Error, but a host or a runtime can reject
+    // with any value, and the page still has to render something.
+    expect(messageOf(new Error('connection lost'))).toBe('connection lost')
+    expect(messageOf('the host refused')).toBe('the host refused')
+    expect(messageOf(undefined)).toBe('undefined')
+  })
+})