Merge remote-tracking branch 'origin/master' into worktree/plan-review-layout

packages/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/README.md
-README.md: 3f467641bbc9eae14a94aa2d3bff0402116a9d3f
-README.zh.md: c9d11bbf6239b4239a4e037dac63b05d3a9a58f7
+README.md: 11179cf6676d1b4382816e34285529b51152fe8d
+README.zh.md: 100d918287613973604b2f85060572b8ee41d132

packages/README.md

@@ -39,6 +39,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`session-projection/`](session-projection/README.md) | Projection seam: domain fold units serve whole values | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable surface |
 | [`session-title/`](session-title/README.md) | Log-backed session titles: fallback service and opt-in LLM providers | Product — stable surface |
+| [`settings/`](settings/README.md) | User-settings seam + file-backed provider | Product — stable surface |
 | [`telemetry/`](telemetry/README.md) | Session reporting: capture/redact seam, OTel backend | Product — stable surface |
 | [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable surface |
 | [`workspace/`](workspace/README.md) | Workspace entity | Product — stable surface |

packages/README.zh.md

@@ -39,6 +39,7 @@
 | [`session-projection/`](session-projection/README.md) | 投影 seam：领域折叠单元供给全量值 | 产品：稳定表面 |
 | [`session-query/`](session-query/README.md) | 会话检索系列：逻辑语料库、有界读取、血缘、事件关系、语义过滤和 SQLite 全文搜索 | 产品：稳定表面 |
 | [`session-title/`](session-title/README.md) | 日志支撑的会话标题：回退服务与选用 LLM 提供方 | 产品：稳定表面 |
+| [`settings/`](settings/README.md) | 用户设置 seam + 文件 provider | 产品：稳定表面 |
 | [`telemetry/`](telemetry/README.md) | 会话上报：捕获／脱敏 seam、OTel 后端 | 产品：稳定表面 |
 | [`storage/`](storage/README.md) | 非会话存储中枢 + 后端 + 领域形式 | 产品：稳定表面 |
 | [`workspace/`](workspace/README.md) | Workspace 实体 | 产品：稳定表面 |

packages/client/AGENTS.md

@@ -86,7 +86,7 @@ If `test:gui` is red on code you did not touch, neither silently fix nor ignore
 Bringing up a new `packages/client/<name>` plugin package (ui-workspace is the latest walked example; ui-sidebar/ui-question are good skeletons to copy):
 
 1. **Package skeleton**: `package.json` (`@deepseek-ai/dsh-client-<name>`, exports `.`/`./invariant`/`./client`/`./src/*`/`./package.json`, `dshClient` manifest, `files` list), `tsconfig.json` (extends `tsconfig.base.client.json`, one `references` entry per workspace dependency plus `support/invariants`), `tsdown.config.ts` (`clientBundle(id, ['lib/types/index.js', 'lib/types/invariant.js'])`), `src/index.ts` (empty node-half apply), `src/invariant.ts` (companion with a real reason), `src/css-modules.d.ts` when using CSS Modules, `README.md` with the Model Experience section.
-2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dshClient` row in `apps/cli/cordis.yml`; an `apps/cli/package.json` dependency (Loader resolves each config-tree package against the composing app's URL — a row whose package is not an `apps/cli` dependency fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
+2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dshClient` row in `apps/cli/config/web.cordis.yml`; an `apps/cli/package.json` dependency (Loader resolves each config-tree package against the composing app's URL — a row whose package is not an `apps/cli` dependency fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
 3. **dshClient manifest semantics**: `platform: 'web'` always; `immediately: true` only for stage-one-prefetch infrastructure rows. `inject` lists package-name dependency edges — they are **informational only** (preflight display, HMR diffing); they do not sequence entry activation or apply order. Activation order is cordis fiber inject waiting on *services*, nothing else.
 4. **Registering into another package's slot**: if the declaring host provides no waitable service, your apply's order relative to the host's is unconstrained — a bare `slots.register` into its slot races boot (intermittent `slot "..." is not declared` page failures). Register with declaration-aware deferral: check `ctx.slots.spec(name)`, otherwise `ctx.slots.subscribe(name)` and register on the declaration event (SlotCore supports subscribing ahead of declaration); make the registration idempotent, and unsubscribe + dispose in the effect disposer. Only take a service edge in `inject` when the host actually provides one (ui-question → `'conversation'` is that case).
 5. Rebuild the bundle (`pnpm --filter <pkg> bundle`) before probing a live `dsh web` server — the registry serves `lib/client.js`, not sources.

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: 855c42b3377e80b0d8f21a418da0a591782439e1
-README.zh.md: 31cf2c7b5a9a0740c2be9079ce55d897d175a6d0
+README.md: fc466190a744a1c13094ca6ebf62755d5bf49c98
+README.zh.md: f6fbff9c1e5d005b64e928680bbf401d94e4ce79

packages/client/ui-conversation/README.md

@@ -10,6 +10,8 @@ The view ring IS a slot: the conversation registration declares the `'conversati
 
 Approvals take over the composer through the chain this package declares: `ApprovalPanel` registers as a selector-routed `'conversation.composer'` entry (the ui-question pattern) and occupies the composer in place of the InputBar while an approval wait is pending (amber strip, justification headline, paired command line from the running call's args, one-shot refuse/allow). The `PendingApproval` domain face in `contract/slots.ts` owns the wire encoding — the `ApprovalResponsePayload` value with the audit correlation — over the runtime's `PendingWait` carrier; the broadcast `approval/resolved` frame settles the wait and restores the composer. The sidebar mirrors the blocked state through the manager-tracked `waitingApproval` list bit (lit for uninstantiated sessions too), which outranks the running ring until the question resolves. Pending waits leave the message flow entirely: questions (ui-question) and approvals (ApprovalPanel) both answer through the composer takeover, so no display-only placeholder card remains. The composer's bottom-row Access seat mounts `PermissionSelect`, fed by the host-computed `permissions` projection through the standard-kit `useProjection` (key absence hides the chip); the chip opens a Menu-primitive dropdown whose kebab-case preset names render as title-case labels (the `/permission` popup's display transform twin), and a pick submits the `/permission <preset>` command line through the bar's injected `command` callback.
 
+Logged non-user messages render as a default-collapsed `上下文注入` disclosure. It shares the Tool calls header geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded 141px scrollport shows bounded inline JSON for both `content` and `source`, and no tool state, summary, or keyed toolview dispatch is synthesized ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)).
+
 Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is a hover-underline link that opens the file with the host OS default application (`host.openPath`, relative paths resolve against the session cwd). Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.
 
 A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card resident below its summary row; since tool rows are no longer details-panel click targets, the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which is what keeps a summary surface bounded — the panel stays the single-call reading surface. Inline output is licensed for this intent alone; a generic tool's content remains panel-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)).

packages/client/ui-conversation/README.zh.md

@@ -8,6 +8,8 @@
 
 视图环本身就是 slot：会话注册声明 `'conversation.view'` 列表 slot（Session scope），并将其列在 `children` 表中；ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页从环账本的注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的环配置项；其他插件（ui-trajectory）通过普通的 `ctx.slots.register` 贡献标签页。先前包内的视图注册表（`registerView`／`ViewEntry`／`ConversationViewMap` 及 chrome 附加表）已退役，逐视图 chrome 则被拆入视图组件自身。
 
+已记录的非用户消息渲染为默认折叠的 `上下文注入` 展开项。它通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 标题栏的几何与交互，同时保留上下文语义：展开后的 141px 滚动区会以内联 JSON 的形式有界展示 `content` 和 `source`，且不会合成工具状态、摘要或键控 toolview 分发（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)）。
+
 通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是悬停下划线链接，点击后通过宿主操作系统的默认应用打开文件（`host.openPath`，相对路径相对会话 cwd 解析）。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。
 
 声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片常驻在摘要行下方；由于工具行已不再是详情面板的点击目标，卡片的复制与展开控件就是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，正是这一点让摘要面保持有界——面板仍是单次调用的阅读面。内联输出只对该意图开放；通用工具的内容仍然只在面板中呈现（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。
@@ -20,7 +22,7 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插
 
 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
 
-输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `command.hint` locale 命名空间本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar 坑位本身为 `session-maybe`：没有当前会话时，同一个 bar 以惰性态渲染（machine face 缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此 textarea DOM 在选定 workspace 的切换中得以存活；严格会话作用域的控件 seat 在会话存在之前保持为空。
+输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `command.hint` locale 命名空间本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
 
 `src/client/` 按未来的包拆分组织：`contract/` 是唯一的跨领域共享表层（`slots.ts` slot 声明 + 组合后的 slot props，包括工具行契约、`views.ts` 共享原语、`tool-call-model.ts`）；`skeleton/`、`chat/` 和 `toolviews/`（示例注册方）领域目录只导入 contract 文件，彼此绝不导入；`apply.ts` 是唯一允许导入全部三个领域的组装点。`/client` 导出表层只包含契约：`apply`／`inject`、两个服务类和 `contract/` 类型家族；实现组件（骨架、聊天行）与 store factory 保持内部状态，只能通过 apply 的 slot 注册到达页面（测试通过 `./src/*` 子路径获取它们）。
 

packages/client/ui-conversation/src/client/chat/ContextInjectionRow.module.css

@@ -0,0 +1,29 @@
+/* Figma 10:2482: 24px Tool calls header, 4px gap, 141px clipped code block. */
+
+.root {
+  min-width: 0;
+}
+
+.root[data-open] {
+  padding-bottom: 4px;
+}
+
+.chevron {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.body {
+  box-sizing: border-box;
+  width: calc(100% - 22px);
+  height: 141px;
+  margin: 4px 0 0 22px;
+  overflow: auto;
+  padding: 10px 16px 12px 12px;
+  border: none;
+  border-radius: 8px;
+  background: var(--dsw-alias-markdown-code-block);
+  color: var(--dsw-alias-label-tertiary);
+  font: 400 11px/16px var(--ds-font-family-code);
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}

packages/client/ui-conversation/src/client/chat/ContextInjectionRow.tsx

@@ -0,0 +1,81 @@
+import { useMemo, useState } from 'react'
+import type { ContextMessageNode } from '@deepseek-ai/dsh-client-runtime/client'
+import { IconBrowseOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { DisclosureRow } from './DisclosureRow.tsx'
+import css from './ContextInjectionRow.module.css'
+
+const MAX_CHARS = 20_000
+
+function inlineJson(payload: unknown): string {
+  const raw = JSON.stringify(payload)
+  let formatted = ''
+  let quoted = false
+  let escaped = false
+
+  for (let index = 0; index < raw.length; index++) {
+    const char = raw.charAt(index)
+    if (quoted) {
+      formatted += char
+      if (escaped) escaped = false
+      else if (char === '\\') escaped = true
+      else if (char === '"') quoted = false
+      continue
+    }
+    if (char === '"') {
+      quoted = true
+      formatted += char
+      continue
+    }
+    if (char === '{' || char === '[') {
+      formatted += char
+      const close = char === '{' ? '}' : ']'
+      if (raw[index + 1] !== close) formatted += ' '
+      continue
+    }
+    if (char === '}' || char === ']') {
+      const open = char === '}' ? '{' : '['
+      if (raw[index - 1] !== open) formatted += ' '
+      formatted += char
+      continue
+    }
+    formatted += char === ':' || char === ',' ? `${char} ` : char
+  }
+  return formatted
+}
+
+/** Props for the logged non-user message presentation. */
+export interface ContextInjectionRowProps {
+  content: ContextMessageNode['content']
+  source: ContextMessageNode['source']
+}
+
+/**
+ * Render logged context with the Tool calls disclosure chrome from Figma.
+ * @param props - Durable content and source provenance.
+ * @returns A collapsed context row with a bounded JSON body.
+ */
+export function ContextInjectionRow({ content, source }: ContextInjectionRowProps) {
+  const [open, setOpen] = useState(false)
+  const body = useMemo(() => {
+    if (!open) return ''
+    const text = inlineJson({ content, source })
+    return text.length > MAX_CHARS
+      ? `${text.slice(0, MAX_CHARS)}\n… 已截断，共 ${text.length} 字符`
+      : text
+  }, [content, open, source])
+
+  return (
+    <DisclosureRow
+      className={css.root}
+      icon={<IconBrowseOutline16 size={14} />}
+      chevronClassName={css.chevron}
+      title="上下文注入"
+      open={open}
+      expandable
+      expandOnRowClick
+      onToggle={() => { setOpen(value => !value) }}
+    >
+      <pre className={css.body} data-context-injection-body>{body}</pre>
+    </DisclosureRow>
+  )
+}

packages/client/ui-conversation/src/client/chat/DisclosureRow.module.css

@@ -0,0 +1,69 @@
+/* Shared Tool calls disclosure header: [16px leading] gap 6 [title 14/24]. */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  min-width: 0;
+}
+
+.row {
+  position: relative;
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  height: 24px;
+  min-width: 0;
+}
+
+.row[data-expandable] {
+  cursor: pointer;
+}
+
+.leading {
+  position: relative;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-right: 6px;
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+button.leading {
+  cursor: pointer;
+}
+
+.iconIdle {
+  display: inline-flex;
+  opacity: 1;
+  transition: opacity 100ms ease;
+}
+
+.chevronHover {
+  position: absolute;
+  inset: 0;
+  margin: auto;
+  opacity: 0;
+  transition: opacity 100ms ease;
+}
+
+.row:hover .iconIdle {
+  opacity: 0;
+}
+
+.row:hover .chevronHover {
+  opacity: 1;
+}
+
+.title {
+  flex: none;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-secondary);
+}

packages/client/ui-conversation/src/client/chat/DisclosureRow.tsx

@@ -0,0 +1,101 @@
+import { type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
+import clsx from 'clsx'
+import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import css from './DisclosureRow.module.css'
+
+/** Shared 24px disclosure chrome for conversation flow rows. */
+export interface DisclosureRowProps {
+  icon: ReactNode
+  title: string
+  open: boolean
+  expandable: boolean
+  onToggle: () => void
+  /** Makes the complete title row the disclosure target. */
+  expandOnRowClick?: boolean | undefined
+  /** Replaces the collapsed icon with a chevron while the row is hovered. */
+  previewChevron?: boolean | undefined
+  collapsedContent?: ReactNode
+  children?: ReactNode
+  className?: string | undefined
+  rowClassName?: string | undefined
+  leadingClassName?: string | undefined
+  chevronClassName?: string | undefined
+  titleClassName?: string | undefined
+}
+
+/**
+ * Render one disclosure header and its controlled expanded content.
+ * @param props - Visual content, controlled state, and interaction policy.
+ * @returns The disclosure row.
+ */
+export function DisclosureRow({
+  icon,
+  title,
+  open,
+  expandable,
+  onToggle,
+  expandOnRowClick = false,
+  previewChevron = expandable,
+  collapsedContent,
+  children,
+  className,
+  rowClassName,
+  leadingClassName,
+  chevronClassName,
+  titleClassName,
+}: DisclosureRowProps) {
+  const rowExpands = expandable && expandOnRowClick
+  const toggleFromLeading = (event: MouseEvent<HTMLButtonElement>) => {
+    event.stopPropagation()
+    onToggle()
+  }
+  const toggleFromKeyboard = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (!rowExpands || (event.key !== 'Enter' && event.key !== ' ')) return
+    event.preventDefault()
+    onToggle()
+  }
+  const collapsedLeading = previewChevron
+    ? (
+      <>
+        <span className={css.iconIdle}>{icon}</span>
+        <IconChevronDownOutline14 className={clsx(chevronClassName, css.chevronHover)} />
+      </>
+    )
+    : icon
+  const leading = open
+    ? <IconChevronDownOutline14 className={chevronClassName} />
+    : collapsedLeading
+
+  return (
+    <div className={clsx(css.root, className)} data-open={open || undefined}>
+      <div
+        className={clsx(css.row, rowClassName)}
+        data-disclosure-row
+        data-expandable={rowExpands || undefined}
+        role={rowExpands ? 'button' : undefined}
+        tabIndex={rowExpands ? 0 : undefined}
+        aria-expanded={rowExpands ? open : undefined}
+        onClick={rowExpands ? onToggle : undefined}
+        onKeyDown={rowExpands ? toggleFromKeyboard : undefined}
+      >
+        {expandable && !rowExpands ? (
+          <button
+            type="button"
+            className={clsx(css.leading, leadingClassName)}
+            aria-expanded={open}
+            onClick={toggleFromLeading}
+          >
+            {leading}
+          </button>
+        ) : (
+          <span className={clsx(css.leading, leadingClassName)}>
+            {leading}
+          </span>
+        )}
+        <span className={clsx(css.title, titleClassName)}>{title}</span>
+        {!open && collapsedContent}
+      </div>
+      {open && children}
+    </div>
+  )
+}

packages/client/ui-conversation/src/client/chat/MessageItem.tsx

@@ -10,6 +10,7 @@ import type {
   ContextMessageNode, SteeringMessageNode, UnknownSurfaceNode, UserMessageNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import { JsonBlock, MessageText } from '@deepseek-ai/dsh-client-ui-primitives'
+import { ContextInjectionRow } from './ContextInjectionRow.tsx'
 import { MessageIconActions } from './MessageIconActions.tsx'
 import css from './MessageItem.module.css'
 
@@ -94,9 +95,7 @@ export const MessageItem = memo(function MessageItem({ node }: MessageItemProps)
     }
     case 'context':
       return (
-        <div className={css.contextRow}>
-          <JsonBlock label="上下文注入" payload={{ content: node.content, source: node.source }} />
-        </div>
+        <ContextInjectionRow content={node.content} source={node.source} />
       )
     default:
       return (

packages/client/ui-conversation/src/client/chat/ToolRow.module.css

@@ -9,10 +9,6 @@
 .row {
   position: relative; /* sweep-glare overlay anchor */
   overflow: hidden;
-  display: flex;
-  align-items: center;
-  height: 24px;
-  min-width: 0;
 }
 
 /* Running sweep (deepsuite ShimmerText pattern): a fixed-width glare band —
@@ -41,24 +37,8 @@
   90%, 100% { left: 100%; }
 }
 
-/* Expand-on-row (Think / code): pointer only — no row fill hover. */
-.row[data-expandable] {
-  cursor: pointer;
-}
-
 .leading {
-  position: relative; /* .chevronHover overlay anchor */
-  flex: none;
-  width: 16px;
-  height: 16px;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  margin-right: 6px;
-  padding: 0;
-  border: none;
-  background: none;
-  color: var(--dsw-alias-label-tertiary);
+  flex-shrink: 0;
 }
 
 /* Cordis lifecycle tools retain their generic row mechanics while carrying a
@@ -76,40 +56,8 @@
   background: var(--dsw-alias-state-business-primary);
 }
 
-button.leading {
-  cursor: pointer;
-}
-
-/* Hover preview on expandable rows: the idle tool icon crossfades (100ms)
-   into a down chevron before the row is opened. The chevron overlays the
-   icon cell absolutely so both can stay mounted for the opacity transition. */
-.iconIdle {
-  display: inline-flex;
-  opacity: 1;
-  transition: opacity 100ms ease;
-}
-
-.chevronHover {
-  position: absolute;
-  inset: 0;
-  margin: auto;
-  opacity: 0;
-  transition: opacity 100ms ease;
-}
-
-.row:hover .iconIdle {
-  opacity: 0;
-}
-
-.row:hover .chevronHover {
-  opacity: 1;
-}
-
 .title {
-  flex: none;
-  font-size: 14px;
-  line-height: 24px;
-  color: var(--dsw-alias-label-secondary);
+  font-weight: 400;
 }
 
 .sep {

packages/client/ui-conversation/src/client/chat/ToolRow.tsx

@@ -8,11 +8,11 @@
 // component-local view state. File-tool summaries are path links that open
 // through the host; the row itself is not a details-panel control.
 
-import { useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
+import { useState, type MouseEvent, type ReactNode } from 'react'
 import { CodeBlock, StateDot, TerminalBlock } from '@deepseek-ai/dsh-client-ui-primitives'
-import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import { CHAT_TERMINAL_MAX_LINES, type TerminalCardModel } from '../contract/terminal-card-model.ts'
 import type { ToolRowState, ToolRowVariant } from '../contract/tool-call-model.ts'
+import { DisclosureRow } from './DisclosureRow.tsx'
 import css from './ToolRow.module.css'
 
 export interface ToolRowProps {
@@ -82,63 +82,27 @@ export function ToolRow({
   // this substitution never shows.
   const text = body ?? ''
   const open = expanded && expandable
-  const rowExpands = expandable && expandOnRowClick
   const toggleExpand = () => {
     setExpanded(v => !v)
   }
-  const toggleFromLeading = (event: MouseEvent<HTMLButtonElement>) => {
-    event.stopPropagation()
-    toggleExpand()
-  }
-  const toggleFromKeyboard = (event: KeyboardEvent<HTMLDivElement>) => {
-    if (!rowExpands || (event.key !== 'Enter' && event.key !== ' ')) return
-    event.preventDefault()
-    toggleExpand()
-  }
   const openFile = (event: MouseEvent<HTMLButtonElement>) => {
     event.stopPropagation()
     if (filePath !== undefined) onOpenFile?.(filePath)
   }
-  // Expandable rows preview the toggle on hover: the tool icon yields to a
-  // down chevron (CSS swap on .row:hover); state dots still take precedence.
-  const collapsedIcon = expandable
-    ? (
-      <>
-        <span className={css.iconIdle}>{icon}</span>
-        <IconChevronDownOutline14 className={css.chevronHover} />
-      </>
-    )
-    : icon
-  const leading = open
-    ? <IconChevronDownOutline14 />
-    : leadingFor(state, collapsedIcon)
   return (
     <div className={css.root} data-variant={variant} data-tool={toolName} data-state={state}>
-      <div
-        className={css.row}
-        data-expandable={rowExpands || undefined}
-        role={rowExpands ? 'button' : undefined}
-        tabIndex={rowExpands ? 0 : undefined}
-        aria-expanded={rowExpands ? open : undefined}
-        onClick={rowExpands ? toggleExpand : undefined}
-        onKeyDown={rowExpands ? toggleFromKeyboard : undefined}
-      >
-        {expandable && !rowExpands ? (
-          <button
-            type="button"
-            className={css.leading}
-            aria-expanded={open}
-            onClick={toggleFromLeading}
-          >
-            {leading}
-          </button>
-        ) : (
-          <span className={css.leading}>
-            {leading}
-          </span>
-        )}
-        <span className={css.title}>{title}</span>
-        {!open && (
+      <DisclosureRow
+        rowClassName={css.row}
+        leadingClassName={css.leading}
+        titleClassName={css.title}
+        icon={leadingFor(state, icon)}
+        title={title}
+        open={open}
+        expandable={expandable}
+        expandOnRowClick={expandOnRowClick}
+        previewChevron={expandable && state !== 'error' && state !== 'stopped'}
+        onToggle={toggleExpand}
+        collapsedContent={(
           <>
             <span className={css.sep} aria-hidden />
             {fileLink ? (
@@ -154,18 +118,18 @@ export function ToolRow({
             )}
           </>
         )}
-      </div>
-      {/* The terminal presenter's description belongs ABOVE the card per the
-          render-intent contract, so an expanded terminal row keeps showing it
-          even though the collapsed summary is hidden while open. */}
-      {open && terminalBody?.description !== undefined && (
-        <div className={css.terminalDescription}>{terminalBody.description}</div>
-      )}
-      {open && (terminalBody !== null
-        ? <TerminalBlock {...terminalBody.card} maxLines={CHAT_TERMINAL_MAX_LINES} className={css.terminalBody} />
-        : variant === 'code'
-          ? <CodeBlock code={text} lang="typescript" className={css.codeBody} />
-          : <div className={css.body}>{text}</div>)}
+      >
+        {/* The terminal presenter's description belongs above the card per
+            the render-intent contract. */}
+        {terminalBody?.description !== undefined && (
+          <div className={css.terminalDescription}>{terminalBody.description}</div>
+        )}
+        {terminalBody !== null
+          ? <TerminalBlock {...terminalBody.card} maxLines={CHAT_TERMINAL_MAX_LINES} className={css.terminalBody} />
+          : variant === 'code'
+            ? <CodeBlock code={text} lang="typescript" className={css.codeBody} />
+            : <div className={css.body}>{text}</div>}
+      </DisclosureRow>
     </div>
   )
 }

packages/client/ui-conversation/tests/chat-branch-tails.spec.tsx

@@ -107,11 +107,48 @@ describe('MessageItem arms', () => {
     expect(view.queryByRole('button', { name: '复制' })).toBeNull()
   })
 
-  it('context and unknown nodes render their JSON rows', () => {
+  it('context uses the Tool calls disclosure chrome and keeps its JSON collapsed by default', () => {
     const ctxView = render(
-      <MessageItem node={{ kind: 'context', seq: 3, content: [], source: null } as never} />,
+      <MessageItem node={{
+        kind: 'context',
+        seq: 3,
+        content: [{ type: 'text', text: 'x\n"y":,[{}]' }],
+        source: { kind: 'plugin', plugin: 'fixture', empty: {}, list: [] },
+      } as never}
+      />,
     )
-    expect(ctxView.getByText(/上下文注入/)).toBeTruthy()
+    const disclosure = ctxView.getByRole('button', { name: '上下文注入' })
+    expect(disclosure.getAttribute('aria-expanded')).toBe('false')
+    expect(ctxView.container.querySelector('[data-context-injection-body]')).toBeNull()
+    expect(ctxView.container.querySelector('svg')).not.toBeNull()
+
+    fireEvent.click(disclosure)
+    expect(disclosure.getAttribute('aria-expanded')).toBe('true')
+    expect(ctxView.container.querySelector('[data-context-injection-body]')?.textContent).toBe(
+      '{ "content": [ { "type": "text", "text": "x\\n\\"y\\":,[{}]" } ], '
+      + '"source": { "kind": "plugin", "plugin": "fixture", "empty": {}, "list": [] } }',
+    )
+
+    fireEvent.keyDown(disclosure, { key: ' ' })
+    expect(disclosure.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('context preserves the bounded JSON truncation contract', () => {
+    const view = render(
+      <MessageItem node={{
+        kind: 'context',
+        seq: 3,
+        content: [{ type: 'text', text: 'x'.repeat(21_000) }],
+        source: null,
+      } as never}
+      />,
+    )
+    fireEvent.click(view.getByRole('button', { name: '上下文注入' }))
+    expect(view.container.querySelector('[data-context-injection-body]')?.textContent)
+      .toMatch(/… 已截断，共 \d+ 字符$/)
+  })
+
+  it('unknown nodes retain the generic JSON row', () => {
     const unknownView = render(
       <MessageItem node={{ kind: 'unknown', seq: 4, type: 'surface/next', data: { x: 1 } } as never} />,
     )

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -748,6 +748,32 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'settings',
+    summary: 'Abstract settings service.',
+    methods: [
+      {
+        signature: 'register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>',
+        jsDoc: '/**\n * Register a namespace schema and receive its owner scope. The registration\n * is an effect on the calling plugin\'s fiber: disposing that fiber removes\n * the namespace and its observers. An invalid stored section fails the\n * registration itself — the earliest point where the schema can judge it.\n * @param ns - unique namespace; duplicate registration fails loud.\n * @param schema - schemastery schema resolving this namespace\'s value.\n * @param options - composition `base` layer and effect timing.\n * @returns the owner scope for reads, observation, and updates.\n */',
+      },
+      {
+        signature: 'describe(): SettingsDescriptor[]',
+        jsDoc: '/**\n * Describe every registered namespace for configuration surfaces.\n * @returns one descriptor per registered namespace, in registration order.\n */',
+      },
+      {
+        signature: 'get(ns: SettingsNamespace): unknown',
+        jsDoc: '/**\n * Read one registered namespace\'s resolved value.\n * @param ns - the namespace to read.\n * @returns the resolved value, or `undefined` while unregistered.\n */',
+      },
+      {
+        signature: 'async update(ns: SettingsNamespace, patch: object): Promise<void>',
+        jsDoc: '/**\n * Merge a patch into one registered namespace\'s user layer, validate the\n * resolved candidate, persist through the provider, then commit and emit.\n * A validation failure rejects before anything is persisted. Writes to one\n * namespace are serialized: concurrent updates apply in call order, each\n * merging over the previous write\'s committed section.\n * @param ns - the registered namespace to update.\n * @param patch - plain-object patch over the user section.\n */',
+      },
+      {
+        signature: 'async replace(ns: SettingsNamespace, section: object): Promise<void>',
+        jsDoc: '/**\n * Replace one registered namespace\'s user section wholesale, validate,\n * persist, then commit and emit. Keys absent from `section` fall back to the\n * composition `base` and schema defaults — this is the removal/reset path a\n * merge-only patch cannot express (`replace({})` re-inherits everything).\n * @param ns - the registered namespace to replace.\n * @param section - the complete next user section.\n */',
+      },
+    ],
+  },
   {
     key: 'skills',
     summary: 'Registry of skill providers.',
@@ -1315,6 +1341,13 @@ export const EVENT_API: readonly EventApiEntry[] = [
     jsDoc: '/**\n * Awaited parallel durability checkpoint: every listener runs and the\n * caller awaits all of them, with no waterfall veto. Dispatch through\n * {@link SessionStore.flush}. Scope-filtered dispatch\n * (`@deepseek-ai/dsh-scope`) reuses the session\'s owner scope.\n * @param session - the session whose buffered events must reach durable storage.\n * @dshScopeScan unsupported\n * @mode parallel\n */',
     summary: 'Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto.',
   },
+  {
+    name: 'settings/updated',
+    mode: 'emit',
+    signature: '\'settings/updated\'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void',
+    jsDoc: '/**\n * Committed change to one registered namespace\'s resolved value. Emitted\n * after the provider persisted (for `update`) or published (`provider`)\n * the change; never emitted when the resolved value is deep-equal.\n * Listener failures are contained and logged — a sync throw and an async\n * rejection alike — except `INVARIANT`-coded failures, which rethrow\n * after every listener ran; that rethrow reaches the emitter only from\n * synchronous listeners, so invariant checks on this event must not be\n * async functions.\n * @param ns - the namespace whose resolved value changed.\n * @param next - the new resolved value.\n * @param prev - the previous resolved value.\n * @param source - whether the change entered through `update()` or the provider.\n * @mode emit\n */',
+    summary: 'Committed change to one registered namespace\'s resolved value.',
+  },
   {
     name: 'skills/change',
     mode: 'emit',
@@ -2375,6 +2408,26 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionTitleUserMessage',
     declaration: 'export interface SessionTitleUserMessage {\n    readonly seq: number;\n    readonly text: string;\n}',
   },
+  {
+    name: 'SettingsApplies',
+    declaration: 'export type SettingsApplies = \'live\' | \'restart\';',
+  },
+  {
+    name: 'SettingsDescriptor',
+    declaration: 'export interface SettingsDescriptor {\n    ns: SettingsNamespace;\n    schema: unknown;\n    value: unknown;\n    applies: SettingsApplies;\n}',
+  },
+  {
+    name: 'SettingsNamespace',
+    declaration: 'export type SettingsNamespace = Branded<\'SettingsNamespace\'>;',
+  },
+  {
+    name: 'SettingsRegisterOptions',
+    declaration: 'export interface SettingsRegisterOptions<T> {\n    base?: Partial<T>;\n    applies?: SettingsApplies;\n}',
+  },
+  {
+    name: 'SettingsScope',
+    declaration: 'export interface SettingsScope<T> {\n    get(): T;\n    watch(callback: (next: T, prev: T) => void | Promise<void>): () => void;\n    update(patch: object): Promise<void>;\n    replace(section: object): Promise<void>;\n}',
+  },
   {
     name: 'SkillCandidate',
     declaration: 'export interface SkillCandidate extends SkillSummary {\n    readonly rank: number;\n    readonly locator: unknown;\n    readonly path?: string;\n    readonly metadata?: Readonly<Record<string, unknown>>;\n}',

packages/core/agent-loop/src/index.ts

@@ -134,6 +134,15 @@ interface PreparedAgent {
 declare module 'cordis' {
   interface Context {
     agentLoop: AgentLoop
+    /**
+     * Launcher-owned exact session identities for configured agents, keyed by
+     * the agent's config `id` and set with `ctx.provide()` before any Loader
+     * entry mounts (see {@link CONFIGURED_AGENT_IDENTITIES_KEY}). A launcher
+     * owns identity because only it knows whether the session already exists,
+     * while the `cordis.yml` row keeps the model route as ordinary patchable
+     * config. An entry with no matching key keeps its configured identity.
+     */
+    configuredAgentIdentities?: ConfiguredAgentIdentities
   }
   interface Events {
     /**
@@ -151,6 +160,53 @@ declare module 'cordis' {
 
 export { DEFAULT_MAX_PARALLEL_TOOL_CALLS }
 
+/**
+ * One launcher-selected session identity for a configured agent. `resume`
+ * distinguishes rehydrating existing persisted history from creating the
+ * session fresh under that exact id, which the two config keys express as
+ * `resumeSessionId` and `sessionId`.
+ */
+export interface LauncherAgentIdentity {
+  /** Exact session id to create fresh or resume. */
+  id: SessionId
+  /** Resume existing persisted history instead of creating the session fresh. */
+  resume: boolean
+}
+
+/** Launcher-selected identities keyed by the configured agent's `id`. */
+export interface ConfiguredAgentIdentities extends Readonly<Record<string, LauncherAgentIdentity>> {}
+
+/**
+ * Context key a launcher sets before any Loader entry mounts
+ * (`ctx.provide(CONFIGURED_AGENT_IDENTITIES_KEY, identities)`) to fix
+ * configured agents' session identities without a config key, so an overlay
+ * repointing the row's model route cannot drop them.
+ */
+export const CONFIGURED_AGENT_IDENTITIES_KEY = 'configuredAgentIdentities'
+
+/**
+ * Apply launcher-owned identities over the configured agents, replacing both
+ * identity keys for every entry the launcher named so a config-supplied
+ * identity can never survive alongside a launcher-supplied one.
+ * @param agents - the configured agent entries.
+ * @param identities - launcher identities keyed by configured agent `id`, or `undefined`.
+ * @returns the entries with launcher-owned identities applied.
+ */
+function applyLauncherIdentities(
+  agents: Config['agents'],
+  identities: ConfiguredAgentIdentities | undefined,
+): Config['agents'] {
+  if (identities === undefined) return agents
+  return agents.map((agent) => {
+    const identity = identities[agent.id]
+    if (identity === undefined) return agent
+    const { sessionId: _sessionId, resumeSessionId: _resumeSessionId, ...rest } = agent
+    return identity.resume
+      ? { ...rest, resumeSessionId: identity.id }
+      : { ...rest, sessionId: identity.id }
+  })
+}
+
 /** Agent-loop plugin configuration. */
 export interface Config {
   /**
@@ -220,6 +276,7 @@ export class AgentLoop extends Service implements AgentFactory {
     super(ctx, 'agentLoop')
     this.config = {
       ...config,
+      agents: applyLauncherIdentities(config.agents, ctx.get(CONFIGURED_AGENT_IDENTITIES_KEY)),
       maxParallelToolCalls: resolveMaxParallelToolCalls(config.maxParallelToolCalls),
     }
     validateConfiguredAgents(this.config.agents)

packages/core/agent-loop/tests/config-session-id.spec.ts

@@ -11,7 +11,7 @@ import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import AgentLoop, { CONFIGURED_AGENT_IDENTITIES_KEY } from '@deepseek-ai/dsh-agent-loop'
 import { MockAdapter, textResponse } from './mock-adapter.ts'
 
 const dirs: string[] = []
@@ -36,6 +36,26 @@ async function makeCoreContext(): Promise<Context> {
 }
 
 describe('config-driven session id', () => {
+  it('applies launcher identities by configured id without changing unmatched entries', async () => {
+    const ctx = await makeCoreContext()
+    ctx.provide(CONFIGURED_AGENT_IDENTITIES_KEY, {
+      fresh: { id: SessionId('launcher-fresh'), resume: false },
+      resumed: { id: SessionId('launcher-resumed'), resume: true },
+    })
+    await ctx.plugin(AgentLoop, {
+      agents: [
+        { id: 'fresh', sessionId: SessionId('config-fresh'), model: 'mock' },
+        { id: 'resumed', sessionId: SessionId('config-resumed'), model: 'mock' },
+        { id: 'unchanged', sessionId: SessionId('config-unchanged'), model: 'mock' },
+      ],
+    })
+    expect(ctx.agents.get(SessionId('launcher-fresh'))?.session.id).toBe('launcher-fresh')
+    expect(ctx.agents.get(SessionId('launcher-resumed'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('config-resumed'))).toBeUndefined()
+    expect(ctx.agents.get(SessionId('config-unchanged'))?.session.id).toBe('config-unchanged')
+    await ctx.fiber.dispose()
+  })
+
   it('rejects an empty exact id before publishing an agent', async () => {
     const ctx = await makeCoreContext()
     await expect(ctx.plugin(AgentLoop, {

packages/core/session/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/core/session/README.md
-README.md: a9b6905dcf2b8ef1f75595e567273f7a3150a412
-README.zh.md: f1a5e97e32d1ad1abcd6ad96e6c621af9972e989
+README.md: 9fa6cf5251d480be9d2388bdb32393fa2827168c
+README.zh.md: 5170d5d4b362a0f19ff6953e1636adef9aa7e8b8

packages/core/session/README.md

@@ -60,6 +60,7 @@ Providers stream token-sized deltas, so a raw log stores hundreds of `assistant/
 - `SessionSurface` — the readonly live `nodes` and `replaceGeneration` projection exposed by `session.surface`; candidate validation remains private to `Session`.
 - `foldSurface(events)` — replay the canonical surface contract into detached current event sequences and actual replacement ranges. The same pass rejects non-contiguous seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, replacements that fail to cite every shadowed surface entry, and a `tool/result` replacement that changes anything except one current result's `content`; `SurfaceManager` shares the atomic transition while retaining only its incremental sequence cache.
 - `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully formed surface event; the second detects a surface-eligible event missing its marker when validating a seed or loaded log.
+- `isAppendSurfaceEvent(event)` / `isReplacementSurfaceEvent(event)` — split a formed surface event by marker variant. Append-origin events are the durable source for a human transcript, which is not the model-visible surface: a landed replacement shadows the range it summarizes, so projecting a transcript from `session.surface` erases conversation the reader already saw. Consumers that must send exactly what the model sees keep reading `session.surface`.
 
 ### Request-header reconstruction (`request-header.ts`)
 

packages/core/session/README.zh.md

@@ -60,6 +60,7 @@
 - `SessionSurface`：实时只读 `nodes` 和 `replaceGeneration` 投影，由 `session.surface` 暴露；候选校验仍由 `Session` 私有。
 - `foldSurface(events)`：回放规范 surface 契约，得到脱离的当前事件序列与实际替换范围。同一趟处理会拒绝不连续序号、错位或畸形元数据、空或重复溯源信息、来源并非更早事件、无效位置范围，以及没有引用所有已遮蔽 surface 条目的替换。如果一个 `tool/result` 替换修改了当前某个结果的 `content` 之外的任何内容，也会被拒绝；`SurfaceManager` 共享该原子状态转换，但只保留自己的增量序列缓存。
 - `isSurfaceEvent(event)`／`isSurfaceEligibleType(type)`：前者将 `SessionEvent` 收窄为形态完整的 surface 事件；后者在校验种子或已加载日志时，检测缺少标记的可进入 surface 事件。
+- `isAppendSurfaceEvent(event)`／`isReplacementSurfaceEvent(event)`：按标记变体拆分形态完整的 surface 事件。追加来源的事件是人类可读记录（transcript）的持久来源，而该记录并非模型可见的 surface：已落地的替换会遮蔽它所概括的范围，因此从 `session.surface` 投影记录会抹掉读者已经看到的对话。必须准确发送模型所见内容的消费方仍继续读取 `session.surface`。
 
 ### 请求头重建（`request-header.ts`）
 

packages/core/session/src/index.ts

@@ -27,7 +27,7 @@ export { interruptedTurnClosers, lastActivityTime, TOOL_NOT_STARTED, TOOL_OUTCOM
 export { decodeStorageRecord, packChunkRuns } from './chunk-rows.ts'
 export type { ChunkRow, StorageRecord } from './chunk-rows.ts'
 export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
-export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
+export { foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts'
 
 /**
@@ -480,7 +480,8 @@ export class Session {
    *   the ordered surface; `sourceEventSeqs` records provenance (the seq
    *   numbers of events this one derives from). REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
-   *   declare how it joins the surface, the sole source of derived history) and
+   *   declare how it joins the surface, the sole source of derived model
+   *   history) and
    *   rejected by the compiler for non-surface types like `turn/start` or
    *   `assistant/chunk`.
    * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of

packages/core/session/src/surface.ts

@@ -37,6 +37,36 @@ export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent {
   return (event as SessionEvent<SurfaceEventType>).surfaceOp !== undefined
 }
 
+/**
+ * Narrow an event to an append-origin surface event: one that entered the
+ * surface at its own log position and was never itself a replacement copy.
+ *
+ * The model-visible surface deliberately shadows replaced ranges, so it is the
+ * wrong source for a human transcript — a landed replacement would erase
+ * conversation the user already saw. Append-origin events are that transcript's
+ * durable source material; replacement copies stay model-only.
+ * @param event - event to test.
+ * @returns true when the event appended to the surface tail.
+ */
+export function isAppendSurfaceEvent(
+  event: SessionEvent,
+): event is SurfaceEvent & { surfaceOp: 'append' } {
+  return isSurfaceEvent(event) && event.surfaceOp === 'append'
+}
+
+/**
+ * Narrow an event to a surface replacement: a node that shadowed an existing
+ * surface range instead of appending to the tail. The counterpart of
+ * {@link isAppendSurfaceEvent} over the two {@link SurfaceOp} variants.
+ * @param event - event to test.
+ * @returns true when the event replaced a surface range.
+ */
+export function isReplacementSurfaceEvent(
+  event: SessionEvent,
+): event is SurfaceEvent & { surfaceOp: Extract<SurfaceOp, { op: 'replace' }> } {
+  return isSurfaceEvent(event) && event.surfaceOp !== 'append'
+}
+
 /** One replacement operation observed while folding a session surface. */
 export interface SurfaceFoldReplacement {
   /** Seq of the event that replaced the prior surface range. */

packages/core/session/tests/surface.spec.ts

@@ -4,6 +4,8 @@ import {
   Session,
   SessionId,
   foldSurface,
+  isAppendSurfaceEvent,
+  isReplacementSurfaceEvent,
   isSurfaceEligibleType,
   isSurfaceEvent,
 } from '@deepseek-ai/dsh-session'
@@ -861,6 +863,40 @@ describe('surface type guards', () => {
     expect(isSurfaceEligibleType(markerless.type)).toBe(true)
     expect(isSurfaceEvent(markerless)).toBe(false)
   })
+
+  it('splits surface events into append-origin and replacement by their marker', () => {
+    const s = surfaceSession()
+    s.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'checkpoint' }], source: { kind: 'plugin', plugin: 'compact' },
+    }), { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] })
+    const appended = s.events.find(e => e.type === 'user/message')!
+    const replacement = s.events.at(-1)!
+
+    expect(isAppendSurfaceEvent(appended)).toBe(true)
+    expect(isReplacementSurfaceEvent(appended)).toBe(false)
+    expect(isAppendSurfaceEvent(replacement)).toBe(false)
+    expect(isReplacementSurfaceEvent(replacement)).toBe(true)
+  })
+
+  it('rejects log-only and markerless events from both marker guards', () => {
+    const s = surfaceSession()
+    const turnStart = s.events.find(e => e.type === 'turn/start')!
+    // A surface-eligible type whose mandatory marker is absent has no origin at
+    // all: it never entered the surface.
+    const markerless: SessionEvent = {
+      type: 'user/message',
+      seq: 0,
+      time: 0,
+      data: createUserMessage({
+        content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' },
+      }),
+    }
+
+    expect(isAppendSurfaceEvent(turnStart)).toBe(false)
+    expect(isReplacementSurfaceEvent(turnStart)).toBe(false)
+    expect(isAppendSurfaceEvent(markerless)).toBe(false)
+    expect(isReplacementSurfaceEvent(markerless)).toBe(false)
+  })
 })
 
 describe('SurfaceManager.replaceGeneration', () => {

packages/examples/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/examples/README.md
-README.md: c229cef22087ac290bf862d6b3e31fdb533858c4
-README.zh.md: 208b9a138506785ea1dd2d83ddfbba29e4b7968e
+README.md: d3ad432e71036db0d21f059e52f5d32e58010c42
+README.zh.md: 0218e60df2511974b8eb222e23331c5a70c9df60

packages/examples/README.md

@@ -7,12 +7,11 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling
 | Package | npm name | Role |
 |---|---|---|
 | `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin, with fallback session titles and an opt-in persisted-goal stack |
-| `tui-demo/` | `@deepseek-ai/dsh-tui-demo` | Full-screen terminal app bundle: the spine + persisted goals + `/goal` command + JSONL persistence + `dsh-tui` + a pre-created `main` agent; no bin, booted by the [`dsh`](../../apps/cli/README.md) CLI |
 | `cli-demo/` | `@deepseek-ai/dsh-cli-demo` | Headless one-shot app: the spine + JSONL persistence + a pre-created `main` agent, with text and DSH-native JSON output |
 | `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP automation server app: the spine + persisted goals + JSONL persistence + the [`acp`](../acp/acp/README.md) bridge (no stdout logger), with a boot `bin` |
 | `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client |
 
-`agent-spine-demo` is the shared bundle; `tui-demo`, `cli-demo`, and `acp-demo` compose it with full-screen terminal, headless one-shot, and ACP automation front doors. `cli-demo` and `acp-demo` own their boot bins; `tui-demo` ships only the bundle plugin, and the product [`dsh`](../../apps/cli/README.md) CLI is its terminal front door. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.
+`agent-spine-demo` is the shared bundle; `cli-demo` and `acp-demo` compose it with headless one-shot and ACP automation front doors, and own their boot bins. The product [`dsh`](../../apps/cli/README.md) CLI uses no bundle: its TUI and web surfaces are a shared `base.cordis.yml` plus one overlay each. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.
 
 These are **not** product API. The spine pieces they bundle live in [`core/`](../core/README.md), human/SDK channels and boot glue in [`ui/`](../ui/README.md), the automation transport in [`acp/`](../acp/README.md), and swappable backends in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely.
 

packages/examples/README.zh.md

@@ -2,17 +2,16 @@
 
 [English](README.md) | 中文
 
-预先组合的插件 bundle（组合包），供轻量叶节点 `cordis.yml` 加载，无需手工组装主干和前端入口。这些是 **演示／参考** 包（package）；npm 名称的 `-demo` 后缀把每个包标为非产品表层，直接查看包名即可辨认。仓库根目录 [`examples/`](../../examples/AGENTS.md) 下的可运行叶节点与 [Python SDK 运行时](../../python/sdk-runtime/README.md) 是消费方；每个消费方都只包含可替换后端和一个组合包入口。
+预先组合的插件 bundle（组合包），供轻量叶节点 `cordis.yml` 加载，无需手工组装主干和前端入口。这些是 **演示／参考** 包；npm 名称的 `-demo` 后缀把每个包标为非产品表层，直接查看包名即可辨认。仓库根目录 [`examples/`](../../examples/AGENTS.md) 下的可运行叶节点与 [Python SDK runtime](../../python/sdk-runtime/README.md) 是消费方；每个叶节点都只包含可替换后端和一个组合包入口。
 
 | 包 | npm 名称 | 角色 |
 |---|---|---|
-| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | 不含执行器和 UI 的 agent（智能体）主干，打包为一个组合包插件，带后备会话标题和可选择启用的持久化目标栈 |
-| `tui-demo/` | `@deepseek-ai/dsh-tui-demo` | 全屏终端应用组合包：主干 + 持久化目标 + `/goal` 命令 + JSONL 持久化 + `dsh-tui` + 预创建的 `main` agent；没有 bin，由 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）启动 |
+| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | 不含执行器和 UI 的 agent 主干，打包为一个组合包插件，带后备会话标题和选用的持久目标栈 |
 | `cli-demo/` | `@deepseek-ai/dsh-cli-demo` | 无头单次应用：主干 + JSONL 持久化 + 预创建的 `main` agent，提供文本和 DSH 原生 JSON 输出 |
-| `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP（Agent Client Protocol）自动化服务器应用：主干 + 持久化目标 + JSONL 持久化 + [`acp`](../acp/acp/README.md) 桥接层（无 stdout logger），带启动 `bin` |
-| `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | 只有 bin 的运行时，用于启动外部 `cordis.yml`，供 stdio JSON-RPC SDK 客户端使用 |
+| `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP 自动化服务器应用：主干 + 持久目标 + JSONL 持久化 + [`acp`](../acp/acp/README.md) 桥接层（无 stdout logger），带启动 `bin` |
+| `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | 只有 bin 的 runtime，用于启动外部 `cordis.yml`，供 stdio JSON-RPC SDK 客户端使用 |
 
-`agent-spine-demo` 是共享组合包；`tui-demo`、`cli-demo` 和 `acp-demo` 分别将它与全屏终端、无头单次和 ACP 自动化前端入口组合。`cli-demo` 与 `acp-demo` 拥有各自的启动 bin；`tui-demo` 只交付组合包插件，产品 [`dsh`](../../apps/cli/README.md) CLI 是它的终端前端入口。`jsonrpc-demo` 自身不挂载任何组合，而是启动部署的 `cordis.yml` 所指名的任意插件树；Python SDK 运行时会启动它。
+`agent-spine-demo` 是共享组合包；`cli-demo` 和 `acp-demo` 分别将它与无头单次和 ACP 自动化前端入口组合，并拥有各自的启动 bin。产品 [`dsh`](../../apps/cli/README.md) CLI 不使用组合包：其 TUI 与 web surface 都是一份共享的 `base.cordis.yml` 加各自一份 overlay。`jsonrpc-demo` 自身不挂载任何组合，而是启动部署的 `cordis.yml` 所指名的任意插件树；Python SDK runtime 会启动它。
 
 这些 **不是** 产品 API。它们打包的主干组件位于 [`core/`](../core/README.md)，人类／SDK 通道和启动粘合代码位于 [`ui/`](../ui/README.md)，自动化传输位于 [`acp/`](../acp/README.md)，可替换后端位于各自能力组；演示组合包只选定其中一种具体组合。可以自由替换或 fork。
 
@@ -20,4 +19,4 @@
 
 ## jsonrpc bin／exe 名称是历史遗留
 
-`jsonrpc-demo` 已像同级包一样重命名，但其 bin 仍为 `dsh-jsonrpc-agent`，单文件可执行程序仍为 `dsh-jsonrpc-agent-pkg`（在 [Python 分发](../../python/sdk-runtime/README.md)各处被引用）。这些名称属于 SDK 的运行时启动表层；只有 SDK 统一该启动流程时才会协调它们，而不会在此次移动中处理。
+`jsonrpc-demo` 已像同级包一样重命名，但其 bin 仍为 `dsh-jsonrpc-agent`，单文件可执行程序仍为 `dsh-jsonrpc-agent-pkg`（在 [Python 分发](../../python/sdk-runtime/README.md)各处被引用）。这些名称属于 SDK 的 runtime 启动表层；只有 SDK 统一该启动流程时才会协调它们，而不会在此次移动中处理。

packages/examples/agent-spine-demo/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/examples/agent-spine-demo/README.md
-README.md: 6bbd99217bcdce0e8a0e8fd22a8d39d0c64224b9
-README.zh.md: 4a7e7a1b7eced9317f94eeddf2442ded9a3e0e13
+README.md: 34d68b0791746c28528124853a4d8ea82b68138d
+README.zh.md: 1b0a644595e35d8703d0600812268b0950b79182

packages/examples/agent-spine-demo/README.md

@@ -47,7 +47,7 @@ The spine is everything COMMON to every front door. The swappable and front-door
 - **model-backed session-title providers** — the bundle mounts the fallback service with overridable example limits (5 words, 40 fallback bytes, 80 accepted-title bytes); a leaf may opt into exactly one first-message or all-messages LLM provider.
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
-- **front-door + per-app infra** — the terminal TUI or ACP automation transport and `hmr`. App packages ([`dsh-tui-demo`](../tui-demo/README.md), [`dsh-acp-demo`](../acp-demo/README.md)) own those choices. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside.
+- **front-door + per-app infra** — the terminal TUI or ACP automation transport and `hmr`. App packages ([`dsh-cli-demo`](../cli-demo/README.md), [`dsh-acp-demo`](../acp-demo/README.md)) own those choices. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside.
 
 This is the [interface/implementation/consumer seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.
 

packages/examples/agent-spine-demo/README.zh.md

@@ -47,7 +47,7 @@
 - **基于模型的会话标题提供方**：组合包挂载带可覆盖示例限制的后备服务（5 个词、40 个后备字节、80 个可接受标题字节）；叶节点可以恰好选用一个首消息或全消息 LLM 提供方。
 - **bash 执行器**：组合包交付 `tool-bash`（消费方 schema）；叶节点提供 `ctx.bash`（`bash-local` 或沙箱化实现）。
 - **非本地 skill 提供方**：组合包交付 skill 注册表、本地文件系统提供方和 `skill` 工具；部署可以把嵌入式目录或远程目录等其他提供方作为同级插件添加。
-- **前端入口与各应用基础设施**：终端 TUI 或 ACP（Agent Client Protocol）自动化传输，以及 `hmr`。应用包（[`dsh-tui-demo`](../tui-demo/README.md)、[`dsh-acp-demo`](../acp-demo/README.md)）拥有这些选择。`timer` 位于主干中，因为它是共有组件且不写 stdout；前端入口拥有 stdout，因此留在组合包外。
+- **前端入口与各应用基础设施**：终端 TUI 或 ACP（Agent Client Protocol）自动化传输，以及 `hmr`。应用包（[`dsh-cli-demo`](../cli-demo/README.md)、[`dsh-acp-demo`](../acp-demo/README.md)）拥有这些选择。`timer` 位于主干中，因为它是共有组件且不写 stdout；前端入口拥有 stdout，因此留在组合包外。
 
 这把[接口／实现／消费方 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) 提升到组合层：组合包拥有共享主干，叶节点拥有后端，应用包拥有前端入口。
 

packages/examples/tui-demo/README.md

@@ -1,112 +0,0 @@
-# @deepseek-ai/dsh-tui-demo
-
-English | [中文](README.zh.md)
-
-The full-screen terminal app bundle: a Cordis plugin that composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), persisted same-session goals, the human-command registry and `/goal` producer, JSONL persistence, keyboard-backed user interaction, a pre-created `main` agent, and [`@deepseek-ai/dsh-tui`](../../ui/tui/README.md). A `cordis.yml` mounts it as one entry; the [`dsh`](../../../apps/cli/README.md) CLI is the front door that boots such a config.
-
-Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and other non-interactive runs. This bundle requires a TTY pair and has no line-oriented fallback.
-
-## What it bakes in
-
-| Plugin | Why it is here |
-|---|---|
-| `@deepseek-ai/dsh-agent-spine-demo` | Shared services, model-facing tools, and one configured `main` agent |
-| `@deepseek-ai/dsh-commands` | Human-only discovery and dispatch consumed by the TUI and command plugins |
-| `@deepseek-ai/dsh-command-goal` | Direct `/goal` status and mutation over the spine's persisted-goal stack |
-| `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session log under `persistenceRoot` |
-| `@deepseek-ai/dsh-session-checkpoint-policy` | Semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
-| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | Combined exact/FTS session queries and bounded `@session` snapshots consumed by the TUI; model-facing query tools remain a leaf opt-in |
-| `@deepseek-ai/dsh-user-interaction` | Provider-neutral human question service |
-| `@deepseek-ai/dsh-tui` | Full-screen transcript, editor, tool cards, plan, and question overlays |
-| `@deepseek-ai/dsh-tool-ask-user` | Model-facing `ask_user_question` tool |
-
-Swappable LLM, bash, filesystem, and other capability providers remain in the leaf config. `@cordisjs/plugin-hmr` also remains a leaf-only development entry because it requires Loader internals.
-
-## Config
-
-| Key | Default | Routed to |
-|---|---|---|
-| `provider` | required | Configured `main` agent provider |
-| `model` | required | Configured `main` agent model |
-| `maxParallelToolCalls` | agent-loop default | Bundled loop concurrency cap |
-| `persona` | — | System-prompt persona template |
-| `toolOrder` | lexicographic | Explicit model-facing tool order |
-| `tools` | owner default | Tool presentation mode |
-| `dshHome` | owner default | Harness home used by bash and skills |
-| `sessionTitle` | spine example limits | Fallback title word/byte limits |
-| `skills` | owner defaults | Skill registry, local provider, and tool config |
-| `toolBash` | owner defaults | Model-facing bash tool config |
-| `toolTasks` | owner defaults | Background-task control-tool config, or `false` |
-| `goals` | owner defaults | Persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer |
-| `workspaceContext` | required | Workspace-instruction config, or `false` |
-| `persistenceRoot` | `./.sessions` | JSONL persistence root and parent of the derived `session-query.db` index |
-| `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
-| `sessionReferences` | service defaults | Cross-session candidate and snapshot limits routed to `dsh-session-reference` |
-| `welcome` | `ready.` | TUI subtitle |
-| `resumeCommand` | — | Exit and no-host fallback command template; the selector itself uses session query and host handoff |
-| `ui` | owner defaults | TUI presentation settings such as reasoning, color, and card height |
-| `resumeSessionId` | — | Exact persisted session to resume |
-
-Fresh runs mint a `main-session-<uuid>` session id and pass it to both the TUI and configured agent. Resumed runs bind both components to `resumeSessionId`. The TUI mounts before the spine so it can render a matching config-start failure instead of leaving a blank terminal. The app composes persistence and session query for `/resume`; an embedding host may additionally provide `tuiResumeHost` for in-place process handoff.
-
-## Front door
-
-This package ships no bin. The [`dsh`](../../../apps/cli/README.md) CLI is the terminal front door: bare `dsh` boots the shipped `examples/tui-agent/cordis.yml` (which mounts this bundle), and `dsh --config <path-to-cordis.yml>` boots an alternate leaf config that mounts it. It loads the optional cwd `.env`, drives the Cordis Loader, and waits for the full plugin tree. The repository installs Loader's optional native helper, so bare package specifiers resolve under plain Node.
-
-## Example leaf
-
-```yaml
-- id: llm-deepseek
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-- id: bash
-  name: '@deepseek-ai/dsh-bash-local'
-- id: tui-agent
-  name: '@deepseek-ai/dsh-tui-demo'
-  config:
-    provider: deepseek
-    model: deepseek-v4-flash
-    workspaceContext:
-      maxBytes: 65536
-    welcome: 'Coding agent ready.'
-    ui:
-      showReasoning: true
-```
-
-## Model Experience
-
-### Interactive terminal turn
-
-#### What the model sees
-
-Each non-empty non-command editor submission becomes a user message; a submission during a running turn becomes steering. Slash-command input and output remain human-only, while accepted `/goal` mutations append domain-owned model-visible state. The shared spine contributes the configured persona, workspace instructions, skill catalog, goal controls, and visible tool schemas. TUI rendering itself is not model-visible.
-
-#### Token effect
-
-User, assistant, and tool history grows under the normal session and compaction rules. Headers, cards, plans, Markdown styling, and keybindings add no tokens.
-
-#### KV Cache effect
-
-Append-only while the composed prompt, schemas, route, and retained history prefix remain stable. Composition changes and compaction can invalidate reuse from the first changed token.
-
-### Human-question answer
-
-#### What the model sees
-
-`ask_user_question` retains the tool call and the compact answer or stable interruption error defined by `dsh-tool-ask-user`. The question overlay is terminal-only.
-
-#### Token effect
-
-Only the completed or failed tool result adds retained tokens.
-
-#### KV Cache effect
-
-Append-only; the answer follows the reusable request prefix.
-
-## Known Limitations and Deferred Work
-
-- **TTY-only** — stdin and stdout must both be terminals; automation uses `dsh-cli-demo`.
-- **One configured terminal session** — the transcript and editor bind to one exact session id.
-- **The app cluster is fixed** — JSONL persistence and ask-user tooling are baked in; different policy requires another composition.
-- **Approval is separate** — this app answers `ctx.userInteraction`, not `ctx.approval`; permission prompts require an approval service and answerer.

packages/examples/tui-demo/README.zh.md

@@ -1,112 +0,0 @@
-# @deepseek-ai/dsh-tui-demo
-
-[English](README.md) | 中文
-
-全屏终端应用组合包：一个 Cordis 插件，组合 [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)、持久化的同会话目标、人类命令注册表与 `/goal` 生产方、JSONL 持久化、键盘支持的用户交互、预创建的 `main` agent（智能体），以及 [`@deepseek-ai/dsh-tui`](../../ui/tui/README.md)。一份 `cordis.yml` 将它作为一个 Cordis 配置项挂载；[`dsh`](../../../apps/cli/README.md) CLI（命令行界面）是启动此类配置的入口。
-
-管道、脚本和其他非交互式运行应使用 [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md)。此组合包需要一对 TTY，不提供面向行的回退。
-
-## 内置组件
-
-| 插件 | 设置在此处的原因 |
-|---|---|
-| `@deepseek-ai/dsh-agent-spine-demo` | 共享服务、面向模型的工具，以及一个已配置的 `main` agent |
-| `@deepseek-ai/dsh-commands` | 供 TUI 和命令插件消费、仅面向人类的命令发现与分发 |
-| `@deepseek-ai/dsh-command-goal` | 直接在主干的持久化目标栈上提供 `/goal` 状态与变更 |
-| `@deepseek-ai/dsh-session-persistence-jsonl` | 位于 `persistenceRoot` 下的持久会话日志 |
-| `@deepseek-ai/dsh-session-checkpoint-policy` | 模型请求和顶层工具 effect 前的语义持久性屏障，以及已完成步骤的检查点 |
-| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | TUI 消费的组合式精确／FTS 会话查询与有界 `@session` 快照；面向模型的查询工具仍由叶节点选用 |
-| `@deepseek-ai/dsh-user-interaction` | 与提供方无关的人类问题服务 |
-| `@deepseek-ai/dsh-tui` | 全屏 transcript（文本记录）、编辑器、工具卡片、计划与问题 overlay |
-| `@deepseek-ai/dsh-tool-ask-user` | 面向模型的 `ask_user_question` 工具 |
-
-可替换的 LLM（大语言模型）、bash、文件系统和其他能力提供方仍留在叶节点配置中。`@cordisjs/plugin-hmr` 也仍是仅叶节点使用的开发条目，因为它需要 Loader 内部实现。
-
-## 配置
-
-| 键 | 默认值 | 路由目标 |
-|---|---|---|
-| `provider` | 必填 | 已配置 `main` agent 的提供方 |
-| `model` | 必填 | 已配置 `main` agent 的模型 |
-| `maxParallelToolCalls` | agent-loop 默认值 | 组合包内循环的并发上限 |
-| `persona` | 无 | 系统提示词 persona 模板 |
-| `toolOrder` | 字典序 | 显式的面向模型工具顺序 |
-| `tools` | 拥有者默认值 | 工具呈现模式 |
-| `dshHome` | 拥有者默认值 | bash 与 skill（技能）使用的 harness 主目录 |
-| `sessionTitle` | 主干示例限制 | 后备标题词数／字节限制 |
-| `skills` | 拥有者默认值 | skill 注册表、本地提供方和工具配置 |
-| `toolBash` | 拥有者默认值 | 面向模型的 bash 工具配置 |
-| `toolTasks` | 拥有者默认值 | 后台任务控制工具配置，或 `false` |
-| `goals` | 拥有者默认值 | 持久目标领域与模型工具配置；`false` 会移除目标栈与 `/goal` 生产方 |
-| `workspaceContext` | 必填 | Workspace 指令配置，或 `false` |
-| `persistenceRoot` | `./.sessions` | JSONL 持久化根目录，以及派生 `session-query.db` 索引的父目录 |
-| `persistenceCompression` | `'zstd'` | JSONL 产物编码（`'zstd'` 或原始 `'none'`） |
-| `sessionReferences` | 服务默认值 | 路由到 `dsh-session-reference` 的跨会话候选项与快照限制 |
-| `welcome` | `ready.` | TUI 副标题 |
-| `resumeCommand` | 无 | 退出和无宿主回退的命令模板；选择器本身使用会话查询与宿主移交 |
-| `ui` | 拥有者默认值 | 推理（reasoning）、颜色、卡片高度等 TUI 呈现设置 |
-| `resumeSessionId` | 无 | 要恢复的确切持久化会话 |
-
-新运行会创建 `main-session-<uuid>` 会话 id，并将它同时传给 TUI 与已配置的 agent。恢复运行会将两个组件都绑定到 `resumeSessionId`。TUI 先于主干挂载，因此它可以渲染匹配的配置启动失败，而不会留下空白终端。应用为 `/resume` 组合持久化和会话查询；嵌入宿主还可以提供 `tuiResumeHost`，用于原地移交进程。
-
-## 入口
-
-此包（package）不交付 bin。[`dsh`](../../../apps/cli/README.md) CLI 是终端入口：裸 `dsh` 启动已交付的 `examples/tui-agent/cordis.yml`（它挂载此组合包），而 `dsh --config <path-to-cordis.yml>` 启动另一个挂载此组合包的叶节点配置。它加载 cwd 下可选的 `.env`，驱动 Cordis Loader，并等待完整插件树。仓库安装了 Loader 的可选原生辅助程序，因此裸包说明符可以在纯 Node 下解析。
-
-## 叶节点示例
-
-```yaml
-- id: llm-deepseek
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-- id: bash
-  name: '@deepseek-ai/dsh-bash-local'
-- id: tui-agent
-  name: '@deepseek-ai/dsh-tui-demo'
-  config:
-    provider: deepseek
-    model: deepseek-v4-flash
-    workspaceContext:
-      maxBytes: 65536
-    welcome: 'Coding agent ready.'
-    ui:
-      showReasoning: true
-```
-
-## 模型体验
-
-### 交互式终端轮次
-
-#### 模型看到的内容
-
-每次非空、非命令的编辑器提交都会成为用户消息；运行中轮次内的提交成为 steering（中途引导）。斜杠命令输入和输出仍只面向人类，而已接受的 `/goal` 变更会追加领域拥有的模型可见状态。共享主干提供已配置的 persona、workspace 指令、skill 目录、目标控制和可见工具 schema。TUI 渲染本身对模型不可见。
-
-#### Token 影响
-
-用户、assistant 与工具历史按常规会话和压缩（compaction）规则增长。Header、卡片、计划、Markdown 样式和快捷键不增加 token。
-
-#### KV Cache 影响
-
-只要组合后的提示词、schema、路由和保留历史前缀保持稳定，就保持仅追加。组合方式变更与 compaction 可能从第一个变化的 token 起使复用失效。
-
-### 人类问题答案
-
-#### 模型看到的内容
-
-`ask_user_question` 会保留工具调用，以及 `dsh-tool-ask-user` 定义的精简答案或稳定中断错误。问题 overlay 只在终端显示。
-
-#### Token 影响
-
-只有已完成或失败的工具结果会增加保留 token。
-
-#### KV Cache 影响
-
-仅追加；答案跟在可复用请求前缀之后。
-
-## 已知限制与暂缓事项
-
-- **只支持 TTY**：stdin 与 stdout 都必须是终端；自动化使用 `dsh-cli-demo`。
-- **一个已配置的终端会话**：transcript 与编辑器绑定到一个确切会话 id。
-- **应用集群固定不变**：JSONL 持久化与 ask-user 工具内置；不同策略需要另一种组合。
-- **批准机制独立存在**：此应用回答 `ctx.userInteraction`，而不是 `ctx.approval`；权限提示需要批准服务和回答方。

packages/examples/tui-demo/package.json

@@ -1,76 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-tui-demo",
-  "description": "Full-screen TUI app bundle plugin: agent spine + persisted goals + human commands + JSONL persistence + pi-tui front door + pre-created main agent (mounted by the dsh CLI's config)",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
-    "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.0.1",
-    "@deepseek-ai/dsh-commands": "^0.0.1",
-    "@deepseek-ai/dsh-command-goal": "^0.0.1",
-    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1",
-    "@deepseek-ai/dsh-session": "^0.0.1",
-    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
-    "@deepseek-ai/dsh-session-query": "^0.0.1",
-    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1",
-    "@deepseek-ai/dsh-session-reference": "^0.0.1",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
-    "@deepseek-ai/dsh-tui": "^0.0.1",
-    "@deepseek-ai/dsh-tool-ask-user": "^0.0.1",
-    "@deepseek-ai/dsh-tools": "^0.0.1",
-    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
-    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
-    "cordis": "^4.0.0-rc.7",
-    "schemastery": "^3.17.0"
-  },
-  "devDependencies": {
-    "@cordisjs/plugin-loader": "workspace:^",
-    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-agent-loop": "workspace:^",
-    "@deepseek-ai/dsh-commands": "workspace:^",
-    "@deepseek-ai/dsh-command-goal": "workspace:^",
-    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-llm": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
-    "@deepseek-ai/dsh-session-query": "workspace:^",
-    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
-    "@deepseek-ai/dsh-session-reference": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
-    "@deepseek-ai/dsh-tui": "workspace:^",
-    "@deepseek-ai/dsh-tool-ask-user": "workspace:^",
-    "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-user-interaction": "workspace:^",
-    "@deepseek-ai/dsh-workspace-context": "workspace:^",
-    "cordis": "^4.0.0-rc.7",
-    "schemastery": "^3.17.0"
-  }
-}

packages/examples/tui-demo/src/index.ts

@@ -1,162 +0,0 @@
-/**
- * Full-screen terminal app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo})
- * plus persisted goals, human commands, JSONL persistence, keyboard-backed
- * user interaction, and one pre-created agent whose exact session identity the
- * TUI drives. Swappable adapters, executors, optional tools, and HMR stay in the leaf. This Loader plugin
- * intentionally exposes named exports only; a default export would hide its
- * `Config` schema (see docs/postmortem/0001).
- * @module @deepseek-ai/dsh-tui-demo
- */
-
-import type { Context } from 'cordis'
-import { randomUUID } from 'node:crypto'
-import { join } from 'node:path'
-import z from 'schemastery'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
-import CommandService from '@deepseek-ai/dsh-commands'
-import * as commandGoal from '@deepseek-ai/dsh-command-goal'
-import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
-import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
-import SessionPersistenceJsonl, {
-  JsonlCompressionSchema,
-  type JsonlCompression,
-} from '@deepseek-ai/dsh-session-persistence-jsonl'
-import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
-import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
-import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
-import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
-import * as uiTui from '@deepseek-ai/dsh-tui'
-
-export const name = 'tui-demo'
-const DEFAULT_PERSISTENCE_ROOT = './.sessions'
-
-// Each front door keeps a complete Loader contract so its deployment config is
-// readable without a cross-package facade.
-/* jscpd:ignore-start */
-/** App config routed to the spine, TUI, configured agent, and JSONL backend. */
-export interface Config {
-  /** Provider route for the `main` agent. */
-  provider: string
-  /** Model name for the `main` agent; a matching adapter must be registered. */
-  model: string
-  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
-  maxParallelToolCalls?: number
-  /** Deployment persona forwarded to the system-prompt plugin. */
-  persona?: string
-  /** Explicit model-facing tool order forwarded to the system-prompt plugin. */
-  toolOrder?: string[]
-  /** Tool-registry presentation config forwarded through agent-spine-demo. */
-  tools?: ToolsConfig
-  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
-  dshHome?: string
-  /** Fallback session-title limits forwarded through agent-spine-demo. */
-  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
-  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
-  persistenceRoot?: string
-  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
-  persistenceCompression?: JsonlCompression
-  /** Cross-session reference discovery and snapshot byte budgets. */
-  sessionReferences?: SessionReferenceConfig
-  /** TUI transcript's optional first line; absent renders nothing on start. */
-  welcome?: string
-  /**
-   * Shell command template the TUI prints on exit and lists under `/resume`,
-   * with `{session}` replaced by the live session id (forwarded to the front
-   * door). Set it to a command that resumes the session, e.g.
-   * `dsh --resume {session}`.
-   */
-  resumeCommand?: string
-  /** Full-screen TUI presentation settings. */
-  ui?: uiTui.TuiConfig
-  /** Skill registry, local-provider, and model-facing consumer config. */
-  skills?: agentCore.SkillConfig
-  /** Model-facing bash tool config forwarded through agent-spine-demo. */
-  toolBash?: NonNullable<agentCore.Config['toolBash']>
-  /** Generic background-task controls forwarded through agent-spine-demo; set false to omit them. */
-  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
-  /** Persisted same-session goals; owner defaults enable them, or false disables the stack and command. */
-  goals?: agentCore.GoalConfig | false
-  /** Persisted session id to resume instead of creating a fresh session. */
-  resumeSessionId?: string
-  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
-  workspaceContext: agentCore.Config['workspaceContext']
-}
-
-export const Config: z<Config> = z.object({
-  provider: z.string().required(),
-  model: z.string().required(),
-  maxParallelToolCalls: z.number().step(1).min(1),
-  persona: z.string(),
-  // Absent means lexicographic order; schemastery's native array default is [].
-  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
-  tools: ToolRegistry.Config,
-  dshHome: z.string(),
-  sessionTitle: agentCore.SessionTitleConfigSchema,
-  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
-  persistenceCompression: JsonlCompressionSchema,
-  sessionReferences: SessionReferenceService.Config,
-  welcome: z.string(),
-  resumeCommand: z.string(),
-  ui: uiTui.TuiConfigSchema,
-  skills: agentCore.SkillConfigSchema,
-  toolBash: agentCore.ToolBashConfigSchema,
-  toolTasks: z.union([z.const(false), agentCore.ToolTasksConfigSchema]),
-  goals: z.union([z.const(false), agentCore.GoalConfigSchema]),
-  resumeSessionId: z.string(),
-  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
-})
-/* jscpd:ignore-end */
-
-/**
- * Compose the spine, TUI, JSONL persistence, and user-question tool around one
- * exact fresh or resumed session identity. The TUI subscribes to startup
- * failures before the spine creates the agent.
- * @param ctx - context receiving the app's child plugins.
- * @param config - validated app configuration.
- */
-export function composeTuiApp(ctx: Context, config: Config): void {
-  const resumeSessionId = config.resumeSessionId === '' ? undefined : config.resumeSessionId
-  const sessionId = SessionId(resumeSessionId ?? `main-session-${randomUUID()}`)
-  const goals = config.goals ?? {}
-  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
-  ctx.plugin(CommandService)
-  if (goals !== false) ctx.plugin(commandGoal)
-  ctx.plugin(SessionPersistenceJsonl, {
-    root: persistenceRoot,
-    ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
-  })
-  ctx.plugin(sessionCheckpointPolicy)
-  ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') })
-  ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
-  ctx.plugin(UserInteractionService)
-  ctx.plugin(uiTui.TuiPromptService)
-  ctx.plugin(uiTui, {
-    ...config.ui,
-    ...config.welcome === undefined ? {} : { welcome: config.welcome },
-    ...config.resumeCommand === undefined ? {} : { resumeCommand: config.resumeCommand },
-    sessionId,
-  })
-  ctx.plugin(agentCore, {
-    ...agentCore.pickSpineConfig(config),
-    goals,
-    agents: [{
-      id: SessionId('main'),
-      provider: config.provider,
-      model: config.model,
-      cwd: process.cwd(),
-      ...resumeSessionId === undefined ? { sessionId } : { resumeSessionId: sessionId },
-    }],
-  })
-  ctx.plugin(toolAskUser)
-}
-
-/**
- * Compose the configured full-screen terminal app.
- * @param ctx - context receiving the app's child plugins.
- * @param config - validated app configuration.
- */
-export function apply(ctx: Context, config: Config): void {
-  composeTuiApp(ctx, config)
-}

packages/examples/tui-demo/tests/tui-agent.spec.ts

@@ -1,152 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { join } from 'node:path'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
-import * as tuiAgent from '../src/index.ts'
-
-interface PluginCall {
-  readonly name: string
-  readonly config: unknown
-}
-
-function recordingContext(): { readonly ctx: Context; readonly calls: PluginCall[] } {
-  const calls: PluginCall[] = []
-  const ctx = {
-    plugin(plugin: { name?: string }, config?: unknown) {
-      calls.push({ name: plugin.name ?? '', config })
-    },
-  } as unknown as Context
-  return { ctx, calls }
-}
-
-describe('dsh-tui-demo app', () => {
-  it('composes the TUI cluster around one fresh exact session identity', () => {
-    const { ctx, calls } = recordingContext()
-    tuiAgent.composeTuiApp(ctx, {
-      provider: 'mock',
-      model: 'mock-model',
-      maxParallelToolCalls: 3,
-      persona: 'test persona',
-      toolOrder: ['zulu', TOOL_ORDER_REST],
-      tools: { mode: 'code' },
-      dshHome: '/tmp/dsh-home',
-      persistenceRoot: '/tmp/tui-sessions',
-      persistenceCompression: 'none',
-      sessionReferences: {
-        maxReferences: 2,
-        candidateLimit: 7,
-        maxReferenceBytes: 1234,
-      },
-      welcome: 'TUI ready',
-      resumeCommand: 'dsh --resume {session}',
-      ui: { theme: { color: false }, maxToolOutputLines: 3 },
-      skills: { tool: { catalogDescriptionMaxLength: 8 } },
-      toolBash: { enableRunInBackground: false },
-      toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
-      workspaceContext: false,
-    })
-
-    expect(calls.map(call => call.name)).toEqual([
-      'CommandService',
-      'command-goal',
-      'SessionPersistenceJsonl',
-      'session-checkpoint-policy',
-      'SessionQuerySqlite',
-      'SessionReferenceService',
-      'UserInteractionService',
-      'TuiPromptService',
-      'ui-tui',
-      'agent-spine-demo',
-      'tool-ask-user',
-    ])
-    expect(calls[0]?.config).toBeUndefined()
-    expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
-    expect(calls[4]?.config).toEqual({ path: join('/tmp/tui-sessions', 'session-query.db') })
-    expect(calls[5]?.config).toEqual({
-      maxReferences: 2,
-      candidateLimit: 7,
-      maxReferenceBytes: 1234,
-    })
-    const tuiConfig = calls[8]?.config as { sessionId: string }
-    expect(tuiConfig).toMatchObject({
-      welcome: 'TUI ready',
-      resumeCommand: 'dsh --resume {session}',
-      theme: { color: false },
-      maxToolOutputLines: 3,
-    })
-    expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    const spineConfig = calls[9]?.config as {
-      readonly agents: Array<Record<string, unknown>>
-      readonly goals: Record<string, never>
-      readonly maxParallelToolCalls: number
-      readonly persona: string
-      readonly toolOrder: string[]
-      readonly tools: { mode: string }
-    }
-    expect(spineConfig).toMatchObject({
-      maxParallelToolCalls: 3,
-      persona: 'test persona',
-      toolOrder: ['zulu', TOOL_ORDER_REST],
-      tools: { mode: 'code' },
-      goals: {},
-    })
-    expect(spineConfig.agents[0]).toMatchObject({
-      id: 'main',
-      provider: 'mock',
-      model: 'mock-model',
-      cwd: process.cwd(),
-      sessionId: tuiConfig.sessionId,
-    })
-  })
-
-  it('resumes the configured session and applies runtime defaults', () => {
-    const { ctx, calls } = recordingContext()
-    tuiAgent.composeTuiApp(ctx, {
-      provider: 'mock',
-      model: 'mock-model',
-      resumeSessionId: 'persisted-session',
-      workspaceContext: false,
-    })
-
-    expect(calls[2]?.config).toEqual({ root: './.sessions' })
-    expect(calls[5]?.config).toEqual({})
-    // No configured welcome forwards none: the TUI banner sweeps in without a subtitle.
-    expect(calls[8]?.config).toEqual({ sessionId: 'persisted-session' })
-    expect((calls[9]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
-      id: 'main',
-      resumeSessionId: 'persisted-session',
-    })
-  })
-
-  it('normalizes an empty resume id and routes apply through the same composition', () => {
-    const { ctx, calls } = recordingContext()
-    tuiAgent.apply(ctx, {
-      provider: 'mock',
-      model: 'mock-model',
-      resumeSessionId: '',
-      goals: false,
-      workspaceContext: false,
-    })
-
-    const tuiConfig = calls[7]?.config as { sessionId: string }
-    expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    expect((calls[8]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
-      .toMatchObject({ sessionId: tuiConfig.sessionId })
-    expect(calls.map(call => call.name)).not.toContain('command-goal')
-    expect(calls[8]?.config).toMatchObject({ goals: false })
-  })
-
-  it('has the namespace-plugin export shape so the Loader keeps its schema', () => {
-    expect(tuiAgent.name).toBe('tui-demo')
-    expect(tuiAgent.Config).toBeDefined()
-    expect('default' in tuiAgent).toBe(false)
-    expect(typeof tuiAgent.apply).toBe('function')
-
-    const loader = Object.create(Loader.prototype) as Loader
-    const unwrapped = loader.unwrapExports(tuiAgent) as Record<string, unknown>
-    expect(unwrapped).toBe(tuiAgent)
-    expect(unwrapped.name).toBe('tui-demo')
-    expect(unwrapped.Config).toBeDefined()
-  })
-})

packages/examples/tui-demo/tsconfig.json

@@ -1,63 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": [
-    "src"
-  ],
-  "references": [
-    {
-      "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../../vendor/schemastery"
-    },
-    {
-      "path": "../../core/agent"
-    },
-    {
-      "path": "../../core/session"
-    },
-    {
-      "path": "../../session-query/session-query"
-    },
-    {
-      "path": "../../session-query/session-query-sqlite"
-    },
-    {
-      "path": "../../context/session-reference"
-    },
-    {
-      "path": "../../ui/commands"
-    },
-    {
-      "path": "../../goal/command-goal"
-    },
-    {
-      "path": "../agent-spine-demo"
-    },
-    {
-      "path": "../../context/workspace-context"
-    },
-    {
-      "path": "../../ui/user-interaction"
-    },
-    {
-      "path": "../../ui/tui"
-    },
-    {
-      "path": "../../ui/tool-ask-user"
-    },
-    {
-      "path": "../../session-persistence/session-checkpoint-policy"
-    },
-    {
-      "path": "../../session-persistence/session-persistence-jsonl"
-    },
-    {
-      "path": "../../support/invariants"
-    }
-  ]
-}

packages/examples/tui-demo/tsdown.config.ts

@@ -1,19 +0,0 @@
-import { defineConfig } from 'tsdown'
-
-/**
- * tui-demo ships the plugin (`index`) and its invariant companion; the CLI
- * front door is `dsh` (apps/cli), which mounts this bundle through its config.
- * The root tsdown builds only `lib/types/index.js`, so this override adds the
- * invariant entry. Declarations come from `tsc -b` (dts: false), matching
- * every package.
- */
-export default defineConfig({
-  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-})

packages/host/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/README.md
-README.md: d44770f70be16c12f44b78155089e092a3e9bba0
-README.zh.md: 2b6878b08be6489dcd510a0a0e0f0e833c2a8014
+README.md: 0417a1b8aec36d58ec0f690f397edcf9e015f982
+README.zh.md: 46516d187321029ed739d8c071f246bc1755b125

packages/host/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The host side of the dsh web GUI: the API gateway every client shape shares, and the plain HTTP server it rides on. The browser side lives in [`client/`](../client/README.md); the composed application is [`apps/cli`](../../apps/cli/cordis.yml) serving [`apps/web`](../../apps/web/). All **product** packages.
+The host side of the dsh web GUI: the API gateway every client shape shares, and the plain HTTP server it rides on. The browser side lives in [`client/`](../client/README.md); the composed application is [`apps/cli`](../../apps/cli/config/base.cordis.yml) serving [`apps/web`](../../apps/web/). All **product** packages.
 
 | Package | Role | ctx key |
 |---|---|---|

packages/host/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-dsh web GUI 的宿主侧：所有客户端形态共用的 API 网关，以及承载它的纯 HTTP 服务器。浏览器侧位于 [`client/`](../client/README.md)；组合后的应用是 [`apps/cli`](../../apps/cli/cordis.yml)，它负责服务 [`apps/web`](../../apps/web/)。全部为**产品**包。
+dsh web GUI 的宿主侧：所有客户端形态共用的 API 网关，以及承载它的纯 HTTP 服务器。浏览器侧位于 [`client/`](../client/README.md)；组合后的应用是 [`apps/cli`](../../apps/cli/config/base.cordis.yml)，它负责服务 [`apps/web`](../../apps/web/)。全部为**产品**包。
 
 | 包 | 角色 | ctx 键 |
 |---|---|---|

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: bf5d0d762365deae83d004e00b94a0ba805d6a6f
-README.zh.md: 06c2e37d2590c3c75d0a782bcdf4d98e7b398928
+README.md: 8f9deb6add7d30bf1609cc7febcb1febafe392c1
+README.zh.md: 399d45208b6d3f4152c27556523b6944432bec66

packages/host/apiproxy/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`apps/cli/cordis.yml`](../../../apps/cli/cordis.yml).
+The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers (HTTP today, IPC later) wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`apps/cli/config/base.cordis.yml`](../../../apps/cli/config/base.cordis.yml).
 
 ## Contract layer (`/api`)
 
@@ -10,6 +10,8 @@ Wire messages form a four-quadrant discriminated union — who initiates × requ
 
 The layering/protocol decisions are recorded in the [GUI layering and RPC protocol RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md); the browser-side consumption architecture in the [web client architecture RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md).
 
+`session.history` pages on append-origin message boundaries: `maxMessages` counts `user/message`, `assistant/message`, and `steering/message` events that entered the surface by appending, so a model-only replacement copy consumes no quota. Each page stays one contiguous raw event range, which keeps a compaction's log-only provenance on the same page as the replacement that cites it.
+
 `session.history`'s tail page (`beforeSeq` absent) additionally carries an optional `projections` block — the watermark snapshot of every unit registered on `ctx.sessionProjections` (`@deepseek-ai/dsh-session-projection`), with `asOfSeq` = the last event seq the values reflect (`-1` on an empty log). The gateway also subscribes to the registry's change feed and mints a `session/projection` mux frame per changed unit (`{sessionId, key, value, seq}` — live push state, never logged; clients hold one generic per-session value store under higher-seq-wins). The carrier holds zero domain knowledge (each value passed its unit's own schema inside the registry; the wire schemas keep `values`/`value` wide); loadOlder pages never carry the block, and a composition without the registry serves histories without either surface.
 
 Session titles ride the generic projection pair like every other domain — the history-tail `projections` block plus `session/projection` frames under the `title` key (the bespoke `session/title` frame is retired). Titles do not join `session.list`; cold sessions remain metadata-only there until opening or resuming attaches their logs. `session.rename` accepts an explicit user title (resuming a cold session first), delegating to `ctx.sessionTitle.rename` — the accepted `session/title` event pins the title against automatic regeneration — and returns the normalized title plus its event seq so a client settles its `title` projection cell ahead of the push frame; a title that normalizes to empty returns `title-invalid`.

packages/host/apiproxy/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包（package）在设计上与传输方式无关，不注册任何路由；载体（目前为 HTTP，未来可以是 IPC）自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`apps/cli/cordis.yml`](../../../apps/cli/cordis.yml)。
+所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包（package）在设计上与传输方式无关，不注册任何路由；载体（目前为 HTTP，未来可以是 IPC）自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`apps/cli/config/base.cordis.yml`](../../../apps/cli/config/base.cordis.yml)。
 
 ## 契约层（`/api`）
 
@@ -10,6 +10,8 @@
 
 分层与协议决策记录在 [GUI 分层与 RPC 协议 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)中；浏览器侧消费架构记录在 [Web 客户端架构 RFC](../../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)中。
 
+`session.history` 按追加来源的消息边界分页：`maxMessages` 统计以追加方式进入 surface 的 `user/message`、`assistant/message` 和 `steering/message` 事件，因此仅供模型使用的替换副本不占用配额。每一页仍是一段连续的原始事件区间，从而让压缩（compaction）的仅日志溯源信息与引用它的替换留在同一页。
+
 `session.history` 的尾页（不带 `beforeSeq`）额外携带一个可选的 `projections` 块——`ctx.sessionProjections`（`@deepseek-ai/dsh-session-projection`）上每个已注册单元的水位线快照，`asOfSeq` = 这些值共同反映到的最后一个事件 seq（空日志为 `-1`）。网关还订阅注册表的变更流，为每个状态发生变化的单元铸造一个 `session/projection` mux 帧（`{sessionId, key, value, seq}`——实时推送状态，绝不入日志；客户端按 seq 高者胜维护一个按会话的通用值仓）。载体不持有任何领域知识（每个值在注册表内部已过其单元自己的 schema；协议 schema 对 `values`/`value` 保持宽松）；loadOlder 页永不携带该块，未装注册表的组合则两个面都不提供。
 
 会话标题与其他所有领域一样搭乘这对通用投影机制——历史尾页的 `projections` 块外加 `title` 键下的 `session/projection` 帧（专设的 `session/title` 帧已下线）。标题不会加入 `session.list`；冷会话在其中仍只有元数据，直到打开或恢复操作附加其日志。`session.rename` 接受用户显式标题（冷会话先恢复），委托给 `ctx.sessionTitle.rename`——被接受的 `session/title` 事件将标题钉住、不再被自动生成覆盖——并返回规范化后的标题及其事件 seq，让 client 在推送帧到达前就结算自己的 `title` 投影格；规范化后为空的标题返回 `title-invalid`。

packages/host/apiproxy/src/api-proxy.ts

@@ -14,7 +14,7 @@ import type {
 import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import { errorChain } from '@deepseek-ai/dsh-llm'
 import type { MessageSource } from '@deepseek-ai/dsh-llm'
-import { lastActivityTime } from '@deepseek-ai/dsh-session'
+import { isAppendSurfaceEvent, lastActivityTime } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader, SessionId, UserMessage } from '@deepseek-ai/dsh-session'
 import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
 import type { Workspace, WorkspaceRecord } from '@deepseek-ai/dsh-workspace'
@@ -60,14 +60,18 @@ import { openNativePath } from './native-path-opener.ts'
 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50
 
-/** Surface message event types (the pagination counting unit). */
+/** Conversation message event types (the pagination counting unit). */
 const MESSAGE_TYPES = new Set(['user/message', 'assistant/message', 'steering/message'])
 
 /**
- * Message-boundary pagination: count maxMessages surface messages backwards from
- * the window tail; the cut is the starting seq of the oldest message group
- * (chunks group via sourceEventSeqs — never cut mid-message). The tail page
- * naturally includes the in-progress partial.
+ * Message-boundary pagination: count maxMessages append-origin messages
+ * backwards from the window tail. Replacement copies never entered the
+ * conversation a reader sees — they restate a shadowed range for the model
+ * alone — so they consume no quota; the page stays one contiguous raw range,
+ * which keeps a compaction's log-only provenance on the same page as its
+ * replacement. The cut is the starting seq of the oldest message group (chunks
+ * group via sourceEventSeqs — never cut mid-message). The tail page naturally
+ * includes the in-progress partial.
  */
 function paginate(
   events: readonly SessionEvent[],
@@ -79,7 +83,7 @@ function paginate(
   let cut = 0
   for (let i = window.length - 1; i >= 0; i--) {
     const event = window[i] as SessionEvent
-    if (!MESSAGE_TYPES.has(event.type)) continue
+    if (!MESSAGE_TYPES.has(event.type) || !isAppendSurfaceEvent(event)) continue
     count++
     const sources = (event as { sourceEventSeqs?: number[] }).sourceEventSeqs
     const groupStart = sources !== undefined && sources.length > 0 ? Math.min(event.seq, ...sources) : event.seq

packages/host/apiproxy/src/api/sessions.ts

@@ -186,9 +186,11 @@ export interface SessionsApi {
   Promise<RpcResponse<{ sessionId: SessionId }>>
 
   /**
-   * Reads a window of history events; page boundaries align to message boundaries: one page =
-   * all raw events owned by a whole number of messages (including their chunk / tool events),
-   * never cut mid-message. The tail page (beforeSeq absent) additionally carries the in-flight
+   * Reads a window of history events; page boundaries align to append-origin message
+   * boundaries: one page = all raw events owned by a whole number of such messages (including
+   * their chunk / tool events), never cut mid-message. Model-only replacement copies consume no
+   * `maxMessages`, so a compaction's provenance stays on the page of its replacement. The tail
+   * page (beforeSeq absent) additionally carries the in-flight
    * partial — chunk events already emitted for the last unfinalized message.
    * Each entry pairs the raw SessionEvent with the host-computed view (tool events whose
    * presenter produced one, evaluated against the registry at pagination time); the client

packages/host/apiproxy/tests/api-proxy-view.spec.ts

@@ -14,7 +14,7 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
-import { CallId, createToolResultMessage } from '@deepseek-ai/dsh-llm'
+import { CallId, createMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
@@ -35,6 +35,35 @@ function tool(name: string, presenters: Pick<ToolDefinition, 'presentCall' | 'pr
   })
 }
 
+/** Append a production-shaped human prompt to the session surface. */
+function appendUserText(session: Session, text: string): SessionEvent {
+  return session.append('user/message', createUserMessage({
+    content: [{ type: 'text', text }], source: { kind: 'user' },
+  }), { surfaceOp: 'append' })
+}
+
+/** Append a production-shaped assistant message to the session surface. */
+function appendAssistantText(session: Session, text: string, step: number): SessionEvent {
+  return session.append('assistant/message', {
+    turn: 1,
+    step,
+    message: createMessage({
+      role: 'assistant',
+      content: [{ type: 'text', text }],
+      source: { kind: 'model', provider: 'p', model: 'm' },
+    }),
+  }, { surfaceOp: 'append' })
+}
+
+/**
+ * Append a plugin-owned log-only event. The host proxy is projection-only, so it
+ * declares no compaction vocabulary; the cast writes the real event shape without
+ * depending on the owning package.
+ */
+function appendExtension(session: Session, type: string, data: unknown): SessionEvent {
+  return (session.append as unknown as (type: string, data: unknown) => SessionEvent)(type, data)
+}
+
 async function harness(): Promise<{ ctx: Context }> {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
@@ -207,6 +236,55 @@ describe('mux live view computation', () => {
     expect('view' in (byKey.get('tool/result:h-plain') ?? {})).toBe(false)
   })
 
+  it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
+    const { ctx } = await harness()
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const session = ctx.sessions.create()
+    ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const first = appendUserText(session, 'first prompt')
+    appendAssistantText(session, 'first reply', 1)
+    const third = appendUserText(session, 'second prompt')
+    appendAssistantText(session, 'second reply', 2)
+    const shadowed = [...session.surface.nodes]
+    // A compaction transaction: log-only provenance immediately followed by the
+    // replacement that shadows the range.
+    const summary = appendExtension(session, 'compact/summary', {
+      summary: [{ type: 'text', text: 'summary' }],
+      shadowedRange: { start: shadowed[0], end: shadowed.at(-1) },
+      shadowedSeqs: shadowed,
+      shadowedTokenCount: 0,
+      provider: 'p',
+      model: 'm',
+    })
+    session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: '<context_checkpoint>summary</context_checkpoint>' }],
+      source: { kind: 'plugin', plugin: 'compact' },
+    }), {
+      surfaceOp: { op: 'replace', start: shadowed[0] as number, end: shadowed.at(-1) as number },
+      sourceEventSeqs: [...shadowed, summary.seq],
+    })
+
+    const response = await api.sessions.history({
+      rpcId: RpcId('t-hist-compact'),
+      payload: { sessionId: session.id, maxMessages: 2 },
+    })
+    if (!response.result.ok) throw new Error('unreachable')
+    const page = response.result.value.events.map(entry => entry.event)
+    // Two append-origin messages fill the page even though a replacement copy of
+    // the same event type sits in the window: the copy is model-only.
+    const messages = page.filter(event => event.type === 'user/message' || event.type === 'assistant/message')
+    expect(messages.map(event => event.seq)).toEqual([third.seq, third.seq + 1, third.seq + 3])
+    expect(page.some(event => event.seq === first.seq)).toBe(false)
+    expect(response.result.value.hasMore).toBe(true)
+    // The range stays contiguous, so the checkpoint's provenance is readable on
+    // the same page as the checkpoint itself.
+    const summaryIndex = page.findIndex(event => event.seq === summary.seq)
+    expect(summaryIndex).toBeGreaterThan(-1)
+    expect(page[summaryIndex + 1]?.seq).toBe(summary.seq + 1)
+    expect(page.map(event => event.seq)).toEqual(page.map((_event, index) => third.seq + index))
+  })
+
   it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
     const { ctx } = await harness()
     const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })

packages/host/directory-picker-browse/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/directory-picker-browse/README.md
-README.md: 318380405214d5f25ad77e348c4e134a8981ffb3
-README.zh.md: 2f88f64cc2974b8535e34eb9798f512ea109b754
+README.md: 52b5fe7e89f915be3b50324628e9d5c48f1ef94c
+README.zh.md: 742da39470083887a71ddba4a7c8012f0ce0ea1f

packages/host/directory-picker-browse/README.md

@@ -6,7 +6,7 @@ The **in-app browsing backend** of the [directory-picker seam](../directory-pick
 
 Behavior facts: listings return **directories only**, name-sorted, with symlinks-to-directories followed (broken/cyclic links skipped — the probe `stat` failing means "not enterable") and a host-owned `hidden` flag (POSIX dot convention) left for the client to act on; `crumbs` is the root-to-target ancestor chain, the root crumb labeled by its full path (`/`, `C:\`); an absent `list` path means the host account's home directory. `createDirectory` is non-recursive (a missing parent is a real failure, not a level to invent) and validates the name as a single non-blank segment even when called directly, mirroring the wire schema's fence. Both primitives reject an explicit path that is not fully qualified — relative forms, and on Windows the rooted drive-less forms (`\foo`, `/foo`) and incomplete UNC prefixes (`\\`, `\\server`) that `isAbsolute` accepts — with `directory-unreadable`/`directory-create-failed`, instead of letting `resolve` rebase it under the host process cwd or current drive. One `list` call returns at most `maxEntries` rows (config, default 1000 — the bound GitHub's web UI applies to directory listings), and the level streams through a bounded window so memory stays O(maxEntries) no matter how many children the directory holds: a cut level keeps the name-sorted head, counts hidden rows against the bound, probes only windowed candidates, and reports `truncated: true` so the client can say the level is incomplete (a windowed broken symlink is not backfilled from beyond the window — the eviction already marks the level truncated); window insertion is binary with an O(1) full-window tail rejection, and `list` threads the caller's `AbortSignal` so a disconnect or timeout stops the scan instead of letting it outlive the caller. Failures throw the seam's typed `DirectoryPickerError`. Policy rationale: [the directory-picker capability seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md).
 
-**Dual-face package**: the browser half (`./client`) fills [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes with the in-app **Select Workspace Directory** dialog (figma `Harness` 813-23126 family — Miller two-column view, breadcrumb with a click-to-edit path zone, nested New-folder dialog), driving `host.listDirectory`/`host.createDirectory` and registering its own locale namespace (`directory-browser`, zh default / en). One cordis.yml row therefore composes both sides of the browse interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind).
+**Dual-face package**: the browser half (`./client`) fills [ui-workspace's](../../client/ui-workspace/README.md) two directory-flow holes with the in-app **Select Workspace Directory** dialog (figma `Harness` 813-23126 family — Miller two-column view whose navigations land selection-anchored and quiet: the previous view keeps rendering while a crumb jump or a submitted path is scanned (a "Loading…" pill floats over it only once the scan outlives a 300ms silence window, never shifting the columns), then target and parent legs land as one two-pane frame with the target re-selected as its actual parent-level entry — so stepping back never collapses and no intermediate frame flashes (a parent leg outliving its 200ms wait bound lands the target alone and upgrades in place; a failed or truncated parent leg keeps the single-pane landing; the display root keeps the single wide level); breadcrumb with a click-to-edit path zone whose editor seeds a trailing separator, prefix-filters the listed level from the draft's final segment while typing (case-insensitively, over the listed — possibly truncated — rows only; Enter still navigates by the exact text), and cancels on Escape or when focus leaves the dialog card (window/tab switches and in-card focus moves keep the draft); a fixed-label show-hidden footer toggle over the host's `hidden` flags, with a dot-led typed prefix revealing its matches and the current selection exempt from both filters; nested New-folder dialog), driving `host.listDirectory`/`host.createDirectory` and registering its own locale namespace (`directory-browser`, zh default / en). One cordis.yml row therefore composes both sides of the browse interaction; the client carries no capability-kind branching, and mounting a second flow package fails at load (the holes are `single` kind).
 
 ## Model Experience
 

packages/host/directory-picker-browse/README.zh.md

@@ -6,7 +6,7 @@
 
 行为事实：列举**只返回目录**、按名称排序，指向目录的符号链接会被跟随（断链／循环链接被跳过——探测 `stat` 失败即"不可进入"），并携带宿主判定的 `hidden` 标志（POSIX 点前缀约定），展示决策留给客户端；`crumbs` 是从根到目标的祖先链，根 crumb 以完整路径标注（`/`、`C:\`）；`list` 不带路径即列举宿主账户的家目录。`createDirectory` 不递归（父目录缺失是真实失败，不是要补造的层级），且即便被直接调用也把名称校验为单个非空段，与协议 schema 的栅栏一致。两个原语都拒绝非完全限定的显式路径——相对形态，以及 Windows 上 `isAbsolute` 会放行的无盘符有根形态（`\foo`、`/foo`）与不完整的 UNC 前缀（`\\`、`\\server`）——报 `directory-unreadable`／`directory-create-failed`，而不是任由 `resolve` 把它重定位到宿主进程 cwd 或当前盘符之下。单次 `list` 至多返回 `maxEntries` 行（配置项，默认 1000——GitHub 网页端对目录列举采用的同一上限），且层级以流式方式经过一个有界窗口，无论目录有多少子项内存都保持 O(maxEntries)：被截断的层级保留按名排序的头部、隐藏行计入上限、只探测窗口内候选，并报告 `truncated: true`，供客户端提示层级不完整（窗口内的断链符号链接不会从窗口外回填——发生过驱逐本身已把层级标记为截断）；窗口插入为二分查找、满窗尾部单次比较即拒绝，且 `list` 透传调用方的 `AbortSignal`，断连或超时会停止扫描而不是让它在调用方离开后继续。失败抛出 seam 的类型化 `DirectoryPickerError`。策略依据：[目录选择能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.md)。
 
-**双面包**：browser half（`./client`）以应用内 **选择工作区目录** 对话框（figma `Harness` 813-23126 家族——Miller 双列视图、带点击即编辑路径区的面包屑、嵌套新建文件夹对话框）填入 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞，驱动 `host.listDirectory`／`host.createDirectory`，并注册自己的 locale 命名空间（`directory-browser`，zh 默认／en）。因此一行 cordis.yml 同时组合浏览交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。
+**双面包**：browser half（`./client`）以应用内 **选择工作区目录** 对话框（figma `Harness` 813-23126 家族——Miller 双列视图，其导航以选中项为锚、安静落地：扫描 crumb 跳转或提交的路径期间，先前视图持续渲染（"Loading…" 胶囊仅在扫描超出 300ms 静默窗口后才浮于其上，绝不挪动各列），随后目标与父层级两程以单个双栏帧落地，目标被重新选中为其在父层级中的实际条目——因此后退绝不塌缩，也没有中间帧闪现（父层级这一程超出其 200ms 等待上限时，目标单独落地，随后就地升级；父层级这一程失败或被截断时保持单栏落地；展示根保持单个宽层级）；带点击即编辑路径区的面包屑，其编辑器预填尾随分隔符、输入时以草稿末段对所列层级做前缀过滤（不区分大小写，且仅作用于已列出、可能被截断的行；Enter 仍按确切文本导航）、按 Escape 或焦点离开对话框卡片即取消（窗口／标签页切换与卡片内焦点移动保留草稿）；基于宿主 `hidden` 标志、标签固定的"显示隐藏"footer 开关，键入以点开头的前缀会显出其匹配项，且当前选中项不受这两种过滤影响；嵌套新建文件夹对话框）填入 [ui-workspace](../../client/ui-workspace/README.md) 的两个目录流洞，驱动 `host.listDirectory`／`host.createDirectory`，并注册自己的 locale 命名空间（`directory-browser`，zh 默认／en）。因此一行 cordis.yml 同时组合浏览交互的两侧；client 侧不含任何能力 kind 分支，挂载第二个流程包会在加载期失败（洞为 `single` kind）。
 
 ## 模型体验
 

packages/host/directory-picker-browse/src/client/DirectoryBrowser.module.css

@@ -1,6 +1,7 @@
 /* Directory-browser dialog (figma 813-23126 family). The shared Modal renders
  * headless here — mask, card, Escape only — and this module owns the figma
- * frame: 600×420 card (viewport-clamped), header (title + crumbs, l3 separator),
+ * frame: 680×500 card (viewport-clamped; upsized from the figma 600×420),
+ * header (title + crumbs, l3 separator),
  * the one-or-two-column Miller content, and the bordered footer. */
 
 /* Doubled class beats Modal's own .dialog regardless of stylesheet order. */
@@ -8,19 +9,32 @@
  * columns scroll, so shrinking the height keeps Open/Cancel reachable
  * instead of clipping them below a fixed overlay. */
 .dialog.dialog {
-  width: min(600px, 100%);
-  height: min(420px, calc(100dvh - 32px));
+  width: min(680px, 100%);
+  height: min(500px, calc(100dvh - 32px));
   padding: 0;
   gap: 0;
+  /* The Modal card is an l2 surface and the columns below scroll on it:
+   * rebind the scrollbar indirection to the elevation pair here, on the
+   * surface, so it inherits down to whichever descendant scrolls (the
+   * rebinding contract in ui-theme styles/scrollbar.css). */
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
 }
 
-/* Header block: pl24 pr14 pt22 pb12, 8px between title row and crumb row. */
+/* Card-scope wrapper hosting the path editor's Escape and focus-leave
+ * observers; display:contents keeps header/content/footer as direct flex
+ * children of the Modal card. */
+.editorScope {
+  display: contents;
+}
+
+/* Header block: pl24 pr14 pt16 pb8, 8px between title row and crumb row. */
 .header {
   display: flex;
   flex-direction: column;
   gap: 8px;
   flex: none;
-  padding: 22px 14px 12px 24px;
+  padding: 16px 14px 8px 24px;
   border-bottom: 1px solid var(--dsw-alias-border-l3);
 }
 
@@ -54,8 +68,12 @@
   align-items: stretch;
   flex: 1 1 0;
   min-height: 0;
-  gap: 20px;
+  /* 12px of row gap on each side of the divider; the left side reads wider
+   * by the column's trailing 8px scrollbar clearance, which is deliberate —
+   * the thumb needs that room, the right pane's rows do not. */
+  gap: 12px;
   overflow-x: auto;
+  scrollbar-width: none;
 }
 
 .crumbTrail {
@@ -126,28 +144,36 @@
   color: var(--dsw-alias-label-primary);
 }
 
-/* Miller content: pt16 px24; columns are 256 wide (or full width solo) with
- * the hairline divider centered between them; each column scrolls alone. */
+/* Miller content: symmetric 16px vertical padding so the divider clears the
+ * header and footer rules evenly; each column scrolls alone (column widths
+ * live at .column). */
 .content {
   display: flex;
   flex-direction: column;
   flex: 1 1 0;
   min-height: 0;
-  padding: 16px 24px 0;
+  /* Anchors the floating loading pill (.loadingFloat). */
+  position: relative;
+  /* Right inset is slimmer than the left: the trailing column's own 8px
+   * scrollbar clearance makes up the optical difference. */
+  padding: 16px 16px 16px 24px;
 }
 
+/* Columns split the row evenly around the divider (a solo column takes the
+ * whole row); 256px is the floor below which the row scrolls (scrollbar
+ * hidden, the effect pins the child pane into view) instead of squeezing
+ * the panes. */
 .column {
   display: flex;
   flex-direction: column;
   gap: 2px;
-  width: 256px;
-  flex: none;
-  overflow-y: auto;
-}
-
-.columnWide {
-  width: 100%;
   flex: 1 1 0;
+  min-width: 256px;
+  overflow-y: auto;
+  /* The themed scrollbar occupies the column's edge (styled scrollbars are
+   * classic, gutter-taking ones); the extra clearance keeps the row pills
+   * clear of the thumb. */
+  padding-right: 8px;
 }
 
 .divider {
@@ -216,6 +242,10 @@
 .status,
 .error {
   padding: 4px;
+  /* The loading pill occupies the opposite corner while a stale status stays
+   * visible. Reserve its widest localized footprint so wrapped text cannot
+   * run underneath it on a narrow card. */
+  padding-right: 120px;
   font-size: 12px;
   line-height: 18px;
 }
@@ -228,8 +258,25 @@
   color: var(--dsw-alias-state-error-primary);
 }
 
-/* Footer: l3 separator on top, pt12 px24, New-folder pinned left; the fixed
- * card leaves the figma 28px below the 36px buttons. */
+/* The slow-scan indicator floats over the content's bottom-RIGHT corner on
+ * the card background instead of occupying a row: a scan must never shift
+ * the columns' height, and the stale view keeps rendering beneath it (it
+ * only appears at all once a scan outlives SLOW_SCAN_DELAY_MS). Right,
+ * not left: the truncated/error status rows flow at the bottom LEFT and
+ * stay on screen through a scan, with their reserved right padding keeping
+ * both legible even on a narrow card. After .status in the cascade — the
+ * element carries both classes and this padding must win the
+ * same-specificity race. */
+.loadingFloat {
+  position: absolute;
+  right: 16px;
+  bottom: 8px;
+  padding: 2px 8px;
+  background: var(--dsw-alias-bg-layer-2);
+}
+
+/* Footer: l3 separator on top, symmetric padding so the row sits vertically
+ * centered in the bar; New-folder and the show-hidden toggle pin left. */
 .footerBar {
   display: flex;
   align-items: center;
@@ -238,10 +285,42 @@
   flex-wrap: wrap;
   gap: 8px;
   flex: none;
-  padding: 12px 24px 28px;
+  padding: 16px 24px;
   border-top: 1px solid var(--dsw-alias-border-l3);
 }
 
+/* Show-hidden toggle: a subtle fixed-label text button left of the gap;
+ * the pressed state seats a check glyph after the label (Menu's selected
+ * vocabulary; trailing so the label never shifts) instead of flipping the
+ * wording. */
+.showHiddenToggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  border: none;
+  background: transparent;
+  padding: 0;
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.showHiddenToggle:hover {
+  color: var(--dsw-alias-label-primary);
+}
+
+.showHiddenToggle:disabled {
+  color: var(--dsw-alias-label-caption);
+  cursor: default;
+}
+
+.showHiddenToggleActive {
+  color: var(--dsw-alias-label-primary);
+}
+
 .footerGap {
   flex: 1 1 0;
 }

packages/host/directory-picker-browse/src/client/DirectoryBrowser.tsx

@@ -1,22 +1,32 @@
 /**
  * The in-app workspace-directory browser (figma Harness 813-23126 family): a
- * 600×420 dialog (clamped to short/narrow viewports — the Miller row scrolls
+ * 680×500 dialog (clamped to short/narrow viewports — the Miller row scrolls
  * sideways, the columns scroll down) whose header carries the title, the selection-path
  * breadcrumb, and a click-to-edit path zone; below it a Miller view — one
- * full-width level until a row is selected, then two 256px columns (level |
- * selected folder's children) around a hairline divider. Selecting in the
+ * full-width level until a row is selected, then two columns splitting the
+ * row evenly (256px floor; level | selected folder's children) around a
+ * hairline divider. Navigations land selection-anchored and quiet: the
+ * previous view keeps rendering while a crumb jump or a submitted path is
+ * scanned, then target and parent legs land as one two-pane frame (a slow
+ * parent leg falls back to landing the target alone and upgrading in
+ * place), so stepping back keeps two panes away from the display root and
+ * navigation never flashes an intermediate frame. Selecting in the
  * right column shifts the view one level deeper. "New folder" opens a nested
  * create dialog targeting the selected folder (or the level itself) and
  * selects the created folder. Open adopts the selected folder, falling back
  * to the listed level. Pure consumer of the injected browse calls — the
  * owning flow decides what "Open" means and owns the workspace-creation
- * error surface. Hidden entries are host-flagged and filtered here (a
- * show-hidden toggle is deferred work, client-side only).
+ * error surface. Hidden entries are host-flagged and hidden by default; the
+ * footer's fixed-label "Show hidden files" toggle (aria-pressed, check when
+ * on) reveals them (client-side only). The path editor opens seeded with a
+ * trailing separator, and while the draft's directory part names a listed
+ * level, its final segment prefix-filters that level's rows (a dot-led
+ * prefix also reveals the hidden entries it names).
  */
 import { useCallback, useEffect, useRef, useState } from 'react'
 import clsx from 'clsx'
 import {
-  Button, IconChevronRightOutline14, IconFolderClose16, IconFolderOpen16, IconPlusOutline16, Modal,
+  Button, IconCheckOutline16, IconChevronRightOutline14, IconFolderClose16, IconFolderOpen16, IconPlusOutline16, Modal,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { DirectoryEntry, DirectoryListing } from '@deepseek-ai/dsh-client-runtime/client'
 import { DirectoryBrowseError } from '@deepseek-ai/dsh-client-runtime/client'
@@ -47,6 +57,24 @@ function failureText(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+/**
+ * How long a scan may stay visually silent before the floating "Loading…"
+ * pill appears. The stale view keeps rendering while a scan is in flight, so
+ * a listing that settles inside this window swaps the panes with no
+ * intermediate frame at all; only a genuinely slow host (a network mount, a
+ * cold disk) surfaces the indicator.
+ */
+const SLOW_SCAN_DELAY_MS = 300
+
+/**
+ * How long a navigation landing waits for its parent leg before committing
+ * the target alone. Inside the window both legs land as ONE two-pane frame —
+ * no single-pane flash between them; past it the target commits single-pane
+ * at once (an Enter-submitted navigation is never held hostage by a stalled
+ * parent) and the late parent leg upgrades the landing in place.
+ */
+const PARENT_LEG_WAIT_MS = 200
+
 /**
  * Breadcrumb rows for display: inside the home subtree the chain starts at a
  * localized Home crumb; outside it the full ancestry shows, the root labeled
@@ -59,17 +87,59 @@ function displayCrumbs(listing: DirectoryListing, homeLabel: string): DirectoryE
   return [{ name: homeLabel, path: listing.home, hidden: false }, ...tail]
 }
 
+/**
+ * The listing's platform separator, inferred from the home path the host
+ * stamped — never from typed text or entry paths, where a backslash is a
+ * legal POSIX name character. Still a heuristic at the last step: a POSIX
+ * home directory whose own name contains a backslash would misread.
+ * TODO: replace with a host-stamped `separator` field on the wire
+ * DirectoryListing so the platform fact travels verbatim (the trade-off is
+ * recorded in the directory-picker capability seam Agent Note).
+ */
+function separatorOf(listing: DirectoryListing): '\\' | '/' {
+  return listing.home.includes('\\') ? '\\' : '/'
+}
+
+/**
+ * The path draft's final segment, when its directory part is exactly the
+ * level `listing` lists — the segment the level prefix-filters on while the
+ * user types. Any other draft (no separator yet, or naming some other
+ * directory) leaves the level unfiltered. The directory part compares
+ * exactly (it is the host's own path text, reached by seeding or erasing);
+ * only the name filter downstream is case-insensitive.
+ */
+function draftPrefixFor(listing: DirectoryListing, draft: string | null): string | null {
+  if (draft === null) return null
+  const sep = separatorOf(listing)
+  const cut = draft.lastIndexOf(sep)
+  if (cut === -1) return null
+  const level = listing.path.endsWith(sep) ? listing.path : `${listing.path}${sep}`
+  return draft.slice(0, cut + 1) === level ? draft.slice(cut + 1) : null
+}
+
 /** One column of folder rows (the Miller view renders one or two of these). */
-function LevelColumn({ entries, selectedPath, busy, onPick, wide }: {
+function LevelColumn({ entries, selectedPath, busy, onPick, showHidden, filterPrefix, pathEditing }: {
   entries: readonly DirectoryEntry[]
   selectedPath: string | null
   busy: boolean
   onPick: (entry: DirectoryEntry) => void
-  wide: boolean
+  showHidden: boolean
+  filterPrefix: string | null
+  pathEditing: boolean
 }) {
+  const visible = entries.filter((entry) => {
+    // The selection is exempt from both filters: it anchors the two-pane
+    // view (crumbs and the child pane point at it), so neither the hidden
+    // filter after a dot-reveal pick nor a prefix miss may orphan it.
+    if (entry.path === selectedPath) return true
+    if (filterPrefix !== null && !entry.name.toLowerCase().startsWith(filterPrefix.toLowerCase())) return false
+    // A dot-led prefix names hidden entries explicitly, so matching ones
+    // surface even while the toggle keeps the rest hidden.
+    return showHidden || !entry.hidden || filterPrefix?.startsWith('.') === true
+  })
   return (
-    <div className={clsx(css.column, wide && css.columnWide)} role="list">
-      {entries.filter(entry => !entry.hidden).map((entry) => {
+    <div className={css.column} role="list">
+      {visible.map((entry) => {
         const selected = entry.path === selectedPath
         return (
           // The wrapper carries the list semantics; the row keeps its NATIVE
@@ -80,6 +150,15 @@ function LevelColumn({ entries, selectedPath, busy, onPick, wide }: {
               aria-current={selected || undefined}
               className={clsx(css.row, selected && css.rowSelected)}
               disabled={busy}
+              // While the path editor is open, keep focus in it: a focus
+              // steal on mousedown would blur the editor and (in engines
+              // where the blur lands before our guards) drop this click.
+              // Outside editing, rows keep native focus behavior.
+              onMouseDown={pathEditing ? (event) => { event.preventDefault() } : undefined}
+              // Editing-time focus parking happens after commit (the
+              // DirectoryBrowser refocus effect): a right-pane pick replaces
+              // this very column, so focusing the clicked node here would
+              // still fall to body.
               onClick={() => { onPick(entry) }}
             >
               {selected
@@ -107,9 +186,19 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
   const [selected, setSelected] = useState<DirectoryEntry | null>(null)
   const [child, setChild] = useState<DirectoryListing | null>(null)
   const [loading, setLoading] = useState(false)
+  // Derived from `loading` and `scanWindow` by the slow-scan effect below:
+  // true only once the current listing call has been in flight for
+  // SLOW_SCAN_DELAY_MS, so fast listings never render the indicator at all.
+  const [slowScan, setSlowScan] = useState(false)
+  // Every listing call owns a fresh silence window. `loading` may stay true
+  // across a superseding row pick or across a navigation's target and parent
+  // legs, so its boolean edge cannot identify the start of each scan.
+  const [scanWindow, setScanWindow] = useState(0)
   const [error, setError] = useState<string | null>(null)
   // Path-edit state: null = breadcrumb mode; a string = the draft being typed.
   const [pathDraft, setPathDraft] = useState<string | null>(null)
+  // Show-hidden toggle state (pure client-side filter, reset on each open).
+  const [showHidden, setShowHidden] = useState(false)
   // Create-folder state: null = closed; a string = the nested dialog's draft.
   const [folderDraft, setFolderDraft] = useState<string | null>(null)
   const [creatingFolder, setCreatingFolder] = useState(false)
@@ -148,36 +237,128 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
     return ++requestSeq.current
   }, [])
 
+  /** Hide any prior indicator and start a fresh silence window for one listing call. */
+  const restartSlowScanWindow = useCallback((): void => {
+    setSlowScan(false)
+    setScanWindow(value => value + 1)
+  }, [])
+
   /** Launch one listing under a fresh controller so a later supersession can abort it. */
   const launchListing = useCallback((path: string | undefined): { seq: number; scan: Promise<DirectoryListing> } => {
     const seq = supersede()
     const controller = new AbortController()
     scanController.current = controller
+    restartSlowScanWindow()
     return { seq, scan: listDirectory(path, controller.signal) }
-  }, [supersede, listDirectory])
+  }, [supersede, restartSlowScanWindow, listDirectory])
 
-  /** Replace the whole view with one freshly listed level (no selection). */
+  /**
+   * Launch a follow-up listing under the CURRENT supersession seq: a newer
+   * intent aborts it like the leg it continues, and it supersedes nothing.
+   */
+  const continueScan = useCallback((path: string): Promise<DirectoryListing> => {
+    const controller = new AbortController()
+    scanController.current = controller
+    restartSlowScanWindow()
+    return listDirectory(path, controller.signal)
+  }, [restartSlowScanWindow, listDirectory])
+
+  /**
+   * Replace the whole view with a freshly navigated level. Away from the
+   * display root — the same collapse the crumb header renders, so crumbs and
+   * pane shape never disagree — the landing is two-pane: the target's ACTUAL
+   * parent-level entry re-selected (left pane = parent, right pane = the
+   * target), so a crumb jump reads as stepping back one pane. Both legs land
+   * as one frame when the parent leg settles within
+   * {@link PARENT_LEG_WAIT_MS}; past that bound (or at the display root) the
+   * target commits alone — single wide level, the editor closes, loading
+   * ends — and a late parent leg still upgrades the landing in place. A
+   * failed parent leg, or a truncated parent window that lacks the target,
+   * leaves the single-pane landing — the upgrade must never orphan the
+   * selection it exists to anchor. Until whichever commit comes first, the
+   * previous view keeps rendering: navigation swaps the panes, it never
+   * blanks them.
+   */
   const navigate = useCallback((path?: string) => {
     const { seq, scan } = launchListing(path)
     setLoading(true)
     setError(null)
-    scan.then((next) => {
+    scan.then((target) => {
       if (seq !== requestSeq.current) return
-      setParent(next)
-      setSelected(null)
-      setChild(null)
-      setLoading(false)
-      setPathDraft(null)
+      // The single-pane landing; `landed` makes it first-commit-only, while
+      // the two-pane commit below may still upgrade an already-landed view.
+      let landed = false
+      const landSingle = (): void => {
+        if (landed || seq !== requestSeq.current) return
+        landed = true
+        setParent(target)
+        setSelected(null)
+        setChild(null)
+        setLoading(false)
+        setPathDraft(null)
+      }
+      // Arity is label-independent: only the collapsed chain's depth decides.
+      if (displayCrumbs(target, '').length < 2) { landSingle(); return }
+      const parentCrumb = target.crumbs.at(-2)
+      /* v8 ignore next -- narrowing: a two-deep display chain implies a parent crumb (root-to-target inclusive). */
+      if (parentCrumb === undefined) { landSingle(); return }
+      continueScan(parentCrumb.path).then((parentLevel) => {
+        if (seq !== requestSeq.current) return
+        // Windows resolves a typed path preserving its case; anchor on the
+        // parent level's actual entry so selection comparisons hold.
+        const sep = separatorOf(parentLevel)
+        const fold = (value: string): string => (sep === '\\' ? value.toLowerCase() : value)
+        const match = parentLevel.entries.find(entry => fold(entry.path) === fold(target.path))
+        if (match === undefined) { landSingle(); return }
+        landed = true
+        setParent(parentLevel)
+        setSelected(match)
+        setChild(target)
+        // Idempotent on a late upgrade of a timed-out landing: reopening the
+        // editor or starting a newer scan supersedes this seq, so reaching
+        // here means the draft is closed and the loading flag is this
+        // navigation's own.
+        setLoading(false)
+        setPathDraft(null)
+      }, () => {
+        // The parent-leg failure (its abort included) never surfaces: the
+        // target listed fine, and nobody asked to see the parent level.
+        landSingle()
+      })
+      window.setTimeout(landSingle, PARENT_LEG_WAIT_MS)
     }, (reason: unknown) => {
       if (seq !== requestSeq.current) return
       setLoading(false)
       setError(failureText(reason))
     })
-  }, [launchListing])
+  }, [launchListing, continueScan])
 
-  /** Select a row of the listed level and preview its children on the right. */
+  // Editor-close focus parking (consumed by the refocus effect below the
+  // miller-row ref): a pick parks on the selection's row, Enter and an
+  // input-focused Escape park on the crumb edit zone that replaces the
+  // input. Pointer-out cancels never set (or clear) these — yanking focus
+  // back from wherever the user clicked would be worse than the fall.
+  const refocusPick = useRef(false)
+  const refocusEditZone = useRef(false)
+  const pathInputRef = useRef<HTMLInputElement | null>(null)
+  const editZoneRef = useRef<HTMLButtonElement | null>(null)
+
+  /**
+   * Select a row of the listed level and preview its children on the right.
+   * Deliberately NOT one-frame like navigate(): a pick's first duty is the
+   * immediate selected state on the clicked row, and the pane split IS that
+   * feedback (aria-current pill, crumbs following the selection) — holding
+   * it back for the child listing would make clicks feel dropped. The quiet
+   * rule governs whole-view replacement, where nothing acknowledges the
+   * click but the swap itself.
+   */
   const select = useCallback((entry: DirectoryEntry) => {
     const { seq, scan } = launchListing(entry.path)
+    // A pick while the path editor is open adopts the (filtered) row and
+    // closes the editor — the draft served its purpose. Focus re-parks on
+    // the selection after commit (see the refocus effect below).
+    if (pathDraft !== null) refocusPick.current = true
+    setPathDraft(null)
     setSelected(entry)
     setChild(null)
     setLoading(true)
@@ -193,8 +374,31 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
       // An unreadable selection cannot be the committing target while the
       // breadcrumb still names the level: fall back to the single pane.
       setSelected(null)
+      // Clearing the selection can unmount the very row the pick parked
+      // focus on (a dot-revealed hidden row re-hides); the refocus effect
+      // re-parks on the edit zone only if focus actually fell to body.
+      refocusEditZone.current = true
     })
-  }, [launchListing])
+  }, [launchListing, pathDraft])
+
+  /** Abandon path editing (Escape or clicking away) and restore the crumb view. */
+  const cancelPathEdit = useCallback(() => {
+    // Cancel also withdraws a navigation the editor already launched: its
+    // late success must not jump to the cancelled path, so the pending
+    // request is superseded and the view leaves the loading state.
+    supersede()
+    setLoading(false)
+    setPathDraft(null)
+    setError(null)
+    // Editing may have superseded the selection's preview request; a
+    // selection with no preview would render a half-empty two-pane view, so
+    // cancel falls back to the single-pane level.
+    if (child === null) setSelected(null)
+    // With no level listed yet (the editor superseded the initial home
+    // listing), plain cancellation would leave a permanently blank picker:
+    // restart the home listing.
+    if (parent === null) navigate()
+  }, [supersede, child, parent, navigate])
 
   /** A right-column pick advances the view one level: child becomes the level. */
   const advance = useCallback((entry: DirectoryEntry) => {
@@ -213,14 +417,24 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
       setSelected(null)
       setChild(null)
       setCreatingFolder(false)
+      setShowHidden(false)
       navigate()
       return
     }
     supersede()
+    // Closing mid-scan leaves nothing to load: without this edge the
+    // slow-scan effect keeps arming while hidden and the reopened dialog
+    // would show the indicator on its first frame instead of waiting out a
+    // fresh silence window (reopen's navigate() produces no loading edge).
+    setLoading(false)
     setError(null)
     setPathDraft(null)
     setFolderDraft(null)
     setCreateError(null)
+    // A close mid-flight (failed Enter, then Cancel) may leave refocus
+    // flags armed; retire them so a later render cannot consume them.
+    refocusPick.current = false
+    refocusEditZone.current = false
   }, [open, navigate, supersede])
 
   /** The folder a create or Open acts on: the selection, else the listed level. */
@@ -249,6 +463,10 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
       // create target becomes the listed level and the new folder its selection.
       const { seq, scan } = launchListing(targetPath)
       setLoading(true)
+      // Symmetric with navigate/select: a launched scan clears the stale
+      // failure text (and keeps the floating indicator's corner the only
+      // occupant of the content's right edge while it shows).
+      setError(null)
       scan.then((level) => {
         /* v8 ignore next -- same fence as navigate/select; the modal blocks superseding input */
         if (seq !== requestSeq.current) return
@@ -268,6 +486,19 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
     })
   }
 
+  // The slow-scan gate for the loading indicator: each listing call restarts
+  // the timer even when a superseding scan or a navigation's parent leg keeps
+  // `loading` continuously true. A settle inside its own window means the swap
+  // happened with nothing shown.
+  useEffect(() => {
+    if (!loading) {
+      setSlowScan(false)
+      return
+    }
+    const timer = window.setTimeout(() => { setSlowScan(true) }, SLOW_SCAN_DELAY_MS)
+    return () => { window.clearTimeout(timer) }
+  }, [loading, scanWindow])
+
   // After the hooks: a closed dialog renders nothing and evaluates no copy.
   const crumbSource = child ?? parent
   const crumbs = crumbSource === null ? [] : displayCrumbs(crumbSource, t('browser.home'))
@@ -285,6 +516,37 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
     const row = millerRowRef.current
     if (row !== null && childPath !== undefined) row.scrollLeft = row.scrollWidth
   }, [childPath])
+  // Every editor exit that would drop focus to body re-parks it after
+  // commit, so keyboard traversal stays inside the dialog (the Modal has no
+  // focus trap): a pick lands on the selection's row — aria-current in the
+  // freshly rendered left pane, which survives even a right-pane advance
+  // replacing the picked button's column — while Enter and an input-focused
+  // Escape land on the crumb edit zone that replaces the input.
+  useEffect(() => {
+    if (pathDraft !== null) return
+    if (refocusPick.current) {
+      refocusPick.current = false
+      refocusEditZone.current = false
+      const rowHost = millerRowRef.current
+      /* v8 ignore next -- narrowing guard: the miller row is mounted whenever a pick just committed. */
+      if (rowHost === null) return
+      const row = rowHost.querySelector<HTMLButtonElement>('button[aria-current="true"]')
+      /* v8 ignore next -- narrowing guard: the pick that set the flag just rendered its aria-current row. */
+      if (row === null) return
+      row.focus()
+      return
+    }
+    if (refocusEditZone.current) {
+      refocusEditZone.current = false
+      // Re-park only when the close actually dropped focus to body; focus
+      // the user parked elsewhere (a surviving row) stays theirs.
+      if (document.activeElement !== document.body) return
+      const zone = editZoneRef.current
+      /* v8 ignore next -- narrowing guard: crumb mode renders the edit zone whenever the editor just closed. */
+      if (zone === null) return
+      zone.focus()
+    }
+  })
 
   if (!open) return null
   const twoPane = selected !== null
@@ -310,149 +572,220 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
       className={clsx(css.dialog)}
       headless
     >
-      <div className={css.header}>
-        <h2 className={css.title}>{t('browser.title')}</h2>
-        <div className={css.crumbBar}>
-          {pathDraft === null
-            ? (
-              <>
-                <span className={css.crumbTrail} role="navigation" ref={crumbTrailRef}>
-                  {crumbs.map((crumb, index) => (
-                    <span key={crumb.path} className={css.crumbSeat}>
-                      {index > 0 && <IconChevronRightOutline14 size={12} className={css.crumbChevron} />}
-                      <button
-                        type="button"
-                        className={css.crumb}
-                        disabled={parentInert}
-                        onClick={() => { navigate(crumb.path) }}
-                      >
-                        {crumb.name}
-                      </button>
-                    </span>
-                  ))}
-                </span>
-                {/* The empty zone right of the crumbs is the path-edit affordance. */}
-                <button
-                  type="button"
-                  className={css.crumbEditZone}
-                  aria-label={t('browser.editPath')}
-                  // Stays available with no listed level: when the home
-                  // listing itself fails, typing an absolute path is the one
-                  // remaining way forward.
-                  disabled={parentInert}
-                  onClick={() => {
+      {/* Path-edit cancellation is observed at the card scope, not the
+        * input: once Tab parks focus on a filtered row the input is off the
+        * event path, yet Escape must still collapse the editor (not the
+        * dialog) and a further focus move out of the card must still
+        * cancel. display:contents keeps header/content/footer as direct
+        * flex children of the Modal card. */}
+      <div
+        className={css.editorScope}
+        onKeyDown={(event) => {
+          if (event.key !== 'Escape' || pathDraft === null) return
+          // stopPropagation keeps the card-scope Escape from the Modal's
+          // document listener — the same containment the input previously
+          // provided for itself.
+          event.stopPropagation()
+          // Escape while the input holds focus is about to unmount it; with
+          // focus already parked on a row, that row survives the cancel and
+          // keeps focus naturally. Assignment (not a conditional set) also
+          // retires a stale flag a failed or still-upgrading Enter left.
+          refocusEditZone.current = document.activeElement === pathInputRef.current
+          cancelPathEdit()
+        }}
+        // Focus leaving THIS dialog card while editing cancels like Escape.
+        // Guarded non-cancel paths: window/tab focus loss (document no
+        // longer focused); a focus move that stays inside the card (Tab
+        // onto the filtered rows or the footer toggle); and pointer paths,
+        // where rows and the toggle suppress focus steal on mousedown while
+        // editing so their click lands first. Enter keeps focus in the
+        // input while its navigation is in flight, so a submitted path is
+        // never withdrawn here. Anchored to this card via closest, not any
+        // [role="dialog"], so focus escaping into a sibling overlay cancels.
+        onBlur={(event) => {
+          if (pathDraft === null) return
+          if (!document.hasFocus()) return
+          const card = event.currentTarget.closest('[role="dialog"]')
+          /* v8 ignore next -- narrowing guard: this scope always renders inside the Modal card. */
+          if (card === null) return
+          if (event.relatedTarget instanceof Node && card.contains(event.relatedTarget)) return
+          // The user moved focus out of the card themselves: cancel without
+          // re-parking (a lingering Enter-failure flag must not yank focus
+          // back either).
+          refocusEditZone.current = false
+          cancelPathEdit()
+        }}
+      >
+        <div className={css.header}>
+          <h2 className={css.title}>{t('browser.title')}</h2>
+          <div className={css.crumbBar}>
+            {pathDraft === null
+              ? (
+                <>
+                  <span className={css.crumbTrail} role="navigation" ref={crumbTrailRef}>
+                    {crumbs.map((crumb, index) => (
+                      <span key={crumb.path} className={css.crumbSeat}>
+                        {index > 0 && <IconChevronRightOutline14 size={12} className={css.crumbChevron} />}
+                        <button
+                          type="button"
+                          className={css.crumb}
+                          disabled={parentInert}
+                          onClick={() => { navigate(crumb.path) }}
+                        >
+                          {crumb.name}
+                        </button>
+                      </span>
+                    ))}
+                  </span>
+                  {/* The empty zone right of the crumbs is the path-edit affordance. */}
+                  <button
+                    type="button"
+                    className={css.crumbEditZone}
+                    aria-label={t('browser.editPath')}
+                    // Stays available with no listed level: when the home
+                    // listing itself fails, typing an absolute path is the one
+                    // remaining way forward.
+                    disabled={parentInert}
+                    ref={editZoneRef}
+                    onClick={() => {
                     // Opening the editor supersedes any pending listing: a
                     // settlement landing before the first keystroke would
                     // otherwise close the editor via navigate's draft reset.
-                    supersede()
-                    setLoading(false)
-                    setPathDraft(selected?.path ?? parent?.path ?? '')
-                  }}
-                />
-              </>
-            )
-            : (
-              <input
-                className={css.pathInput}
-                value={pathDraft}
-                aria-label={t('browser.editPath')}
-                autoFocus
-                disabled={parentInert}
-                onChange={(event) => {
+                      supersede()
+                      setLoading(false)
+                      // Seed with a trailing separator so typing immediately
+                      // continues into child names (and prefix-filters below).
+                      // No listed level means nothing to seed from (the editor
+                      // is the recovery path for a failed home listing).
+                      if (parent === null) {
+                        setPathDraft('')
+                        return
+                      }
+                      const base = selected?.path ?? parent.path
+                      const sep = separatorOf(parent)
+                      setPathDraft(base.endsWith(sep) ? base : `${base}${sep}`)
+                    }}
+                  />
+                </>
+              )
+              : (
+                <input
+                  className={css.pathInput}
+                  value={pathDraft}
+                  aria-label={t('browser.editPath')}
+                  autoFocus
+                  ref={pathInputRef}
+                  disabled={parentInert}
+                  onChange={(event) => {
                   // Editing the draft supersedes any in-flight navigation:
                   // its completion must neither clear the newer text nor
                   // repopulate the view with the older path.
-                  supersede()
-                  setLoading(false)
-                  setPathDraft(event.target.value)
-                }}
-                {...compositionGuard}
-                onKeyDown={(event) => {
-                  if (event.key === 'Enter' && !composingRef.current) {
-                    event.preventDefault()
-                    // Trim only detects a blank draft; the Host gets the
-                    // original text — a real directory name may end in
-                    // whitespace, and trimming would list its sibling.
-                    if (pathDraft.trim() !== '') navigate(pathDraft)
-                  }
-                  if (event.key === 'Escape') {
-                    event.stopPropagation()
-                    // Cancel also withdraws a navigation the editor already
-                    // launched: its late success must not jump to the
-                    // cancelled path, so the pending request is superseded
-                    // and the view leaves the loading state.
                     supersede()
                     setLoading(false)
-                    setPathDraft(null)
-                    setError(null)
-                    // Editing may have superseded the selection's preview
-                    // request; a selection with no preview would render a
-                    // half-empty two-pane view, so cancel falls back to the
-                    // single-pane level.
-                    if (child === null) setSelected(null)
-                    // With no level listed yet (the editor superseded the
-                    // initial home listing), plain cancellation would leave a
-                    // permanently blank picker: restart the home listing.
-                    if (parent === null) navigate()
-                  }
-                }}
+                    setPathDraft(event.target.value)
+                  }}
+                  {...compositionGuard}
+                  // Escape and focus-leave cancellation live on the card-scope
+                  // wrapper above (they must work after focus Tabs onto the
+                  // rows); this handler owns only submission.
+                  onKeyDown={(event) => {
+                    if (event.key === 'Enter' && !composingRef.current) {
+                      event.preventDefault()
+                      // Trim only detects a blank draft; the Host gets the
+                      // original text — a real directory name may end in
+                      // whitespace, and trimming would list its sibling.
+                      if (pathDraft.trim() !== '') {
+                        // Success will unmount the still-focused input; park
+                        // focus on the returning crumb edit zone (a failure
+                        // keeps the editor, so the flag waits until close).
+                        refocusEditZone.current = true
+                        navigate(pathDraft)
+                      }
+                    }
+                  }}
+                />
+              )}
+          </div>
+        </div>
+        <div className={css.content}>
+          <div className={css.millerRow} ref={millerRowRef}>
+            {parent !== null && (
+              <LevelColumn
+                entries={parent.entries}
+                selectedPath={selected?.path ?? null}
+                busy={parentInert}
+                onPick={select}
+                showHidden={showHidden}
+                filterPrefix={draftPrefixFor(parent, pathDraft)}
+                pathEditing={draftPending}
               />
             )}
-        </div>
-      </div>
-      <div className={css.content}>
-        <div className={css.millerRow} ref={millerRowRef}>
-          {parent !== null && (
-            <LevelColumn
-              entries={parent.entries}
-              selectedPath={selected?.path ?? null}
-              busy={parentInert}
-              onPick={select}
-              wide={!twoPane}
-            />
-          )}
-          {twoPane && <span className={css.divider} />}
-          {twoPane && child !== null && (
-            <LevelColumn
-              entries={child.entries}
-              selectedPath={null}
-              busy={parentInert}
-              onPick={advance}
-              wide={false}
-            />
-          )}
-        </div>
-        {loading && <div className={css.status} role="status">{t('browser.loading')}</div>}
-        {/* The backend bounds a level at its complete-result limit; say so
+            {twoPane && <span className={css.divider} />}
+            {twoPane && child !== null && (
+              <LevelColumn
+                entries={child.entries}
+                selectedPath={null}
+                busy={parentInert}
+                onPick={advance}
+                showHidden={showHidden}
+                filterPrefix={draftPrefixFor(child, pathDraft)}
+                pathEditing={draftPending}
+              />
+            )}
+          </div>
+          {loading && slowScan
+          && <div className={clsx(css.status, css.loadingFloat)} role="status">{t('browser.loading')}</div>}
+          {/* The backend bounds a level at its complete-result limit; say so
           * whenever a visible pane was cut instead of letting the tail of a
-          * huge directory go silently missing. */}
-        {(parent?.truncated === true || child?.truncated === true) && !loading
+          * huge directory go silently missing. The note describes the panes
+          * on screen, so an in-flight scan leaves it alone — hiding it while
+          * the stale view still shows the cut level would shift the columns
+          * on every navigation away from it. */}
+          {(parent?.truncated === true || child?.truncated === true)
           && <div className={css.status} role="status">{t('browser.truncated')}</div>}
-        {error !== null && <div className={css.error} role="alert">{error}</div>}
-      </div>
-      <div className={css.footerBar}>
-        <Button
-          variant="outline"
-          icon={<IconPlusOutline16 size={14} />}
-          disabled={parent === null || loading || parentInert || draftPending}
-          onClick={() => {
-            setFolderDraft('')
-            setCreateError(null)
-          }}
-        >
-          {t('browser.newFolder')}
-        </Button>
-        <span className={css.footerGap} />
-        <Button variant="outline" className={clsx(css.footerAction)} disabled={parentInert} onClick={onClose}>{t('browser.cancel')}</Button>
-        <Button
-          variant="primary"
-          className={clsx(css.footerAction)}
-          disabled={targetPath === null || loading || parentInert || draftPending}
-          /* v8 ignore next -- narrowing guard: Open disables while no target exists. */
-          onClick={() => { if (targetPath !== null) onOpen(targetPath) }}
-        >
-          {t('browser.open')}
-        </Button>
+          {error !== null && <div className={css.error} role="alert">{error}</div>}
+        </div>
+        <div className={css.footerBar}>
+          <Button
+            variant="outline"
+            icon={<IconPlusOutline16 size={14} />}
+            disabled={parent === null || loading || parentInert || draftPending}
+            onClick={() => {
+              setFolderDraft('')
+              setCreateError(null)
+            }}
+          >
+            {t('browser.newFolder')}
+          </Button>
+          <button
+            type="button"
+            className={clsx(css.showHiddenToggle, showHidden && css.showHiddenToggleActive)}
+            aria-pressed={showHidden}
+            disabled={parentInert}
+            // The toggle composes with the path editor (dot-led prefixes and
+            // this filter interleave): while editing, don't steal focus, so
+            // toggling never blur-cancels a draft mid-thought. Outside editing
+            // it keeps native focus behavior.
+            onMouseDown={draftPending ? (event) => { event.preventDefault() } : undefined}
+            onClick={() => { setShowHidden(prev => !prev) }}
+          >
+            {t('browser.showHidden')}
+            {/* Trailing check (Menu's selected vocabulary): the label never
+              * shifts when the pressed state toggles. */}
+            {showHidden && <IconCheckOutline16 size={14} />}
+          </button>
+          <span className={css.footerGap} />
+          <Button variant="outline" className={clsx(css.footerAction)} disabled={parentInert} onClick={onClose}>{t('browser.cancel')}</Button>
+          <Button
+            variant="primary"
+            className={clsx(css.footerAction)}
+            disabled={targetPath === null || loading || parentInert || draftPending}
+            /* v8 ignore next -- narrowing guard: Open disables while no target exists. */
+            onClick={() => { if (targetPath !== null) onOpen(targetPath) }}
+          >
+            {t('browser.open')}
+          </Button>
+        </div>
       </div>
       {/* Nested create dialog (figma 813:23278): names one folder inside the target. */}
       <Modal

packages/host/directory-picker-browse/src/client/index.ts

@@ -46,6 +46,7 @@ export function apply(ctx: ClientContext): void {
         'browser.editPath': '编辑路径',
         'browser.loading': '加载中…',
         'browser.truncated': '文件夹过多，仅显示开头部分。',
+        'browser.showHidden': '显示隐藏文件',
       }],
       ['en', {
         'browser.title': 'Select Workspace Directory',
@@ -60,6 +61,7 @@ export function apply(ctx: ClientContext): void {
         'browser.editPath': 'Edit path',
         'browser.loading': 'Loading…',
         'browser.truncated': 'Too many folders to list; only the beginning is shown.',
+        'browser.showHidden': 'Show hidden files',
       }],
     ]
     try {

packages/host/directory-picker-browse/tests/client-flow.spec.tsx

@@ -162,6 +162,7 @@ describe('directory-picker-browse client half', () => {
     // zh is the shipped default locale.
     expect(injected.t('browser.title')).toBe('选择工作区目录')
     expect(injected.t('browser.newFolder')).toBe('新建文件夹')
+    expect(injected.t('browser.showHidden')).toBe('显示隐藏文件')
   })
 
   it('drives the injected browse calls through the hole entry', async () => {

packages/host/directory-picker-browse/tests/directory-browser.spec.tsx

@@ -29,6 +29,25 @@ function listingFor(path?: string): DirectoryListing {
       ],
       truncated: false,
     },
+    '/': {
+      path: '/',
+      home: HOME,
+      crumbs: [{ name: '/', path: '/', hidden: false }],
+      entries: [{ name: 'home', path: '/home', hidden: false }],
+      truncated: false,
+    },
+    [`${HOME}/.config`]: {
+      path: `${HOME}/.config`,
+      home: HOME,
+      crumbs: [
+        { name: '/', path: '/', hidden: false },
+        { name: 'home', path: '/home', hidden: false },
+        { name: 'u', path: HOME, hidden: false },
+        { name: '.config', path: `${HOME}/.config`, hidden: true },
+      ],
+      entries: [],
+      truncated: false,
+    },
     [DOCS]: {
       path: DOCS,
       home: HOME,
@@ -92,6 +111,12 @@ function rowButton(item: HTMLElement): HTMLButtonElement {
 }
 
 describe('DirectoryBrowser', () => {
+  it('renders nothing and launches no listing while initially closed', () => {
+    const b = mount({ open: false })
+    expect(screen.queryByRole('dialog')).toBeNull()
+    expect(b.listDirectory).not.toHaveBeenCalled()
+  })
+
   it('opens at the Host home as one wide column, hides hidden entries, and roots the crumbs at Home', async () => {
     const b = mount()
     await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
@@ -103,6 +128,28 @@ describe('DirectoryBrowser', () => {
     expect(screen.queryByRole('button', { name: '/' })).toBeNull()
   })
 
+  it('shows hidden entries when the toggle is on and hides them again on close', async () => {
+    const b = mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    expect(screen.queryByText('.config')).toBeNull()
+    // The fixed-label toggle reports its state through aria-pressed. Its
+    // mousedown never steals focus (so it composes with the path editor).
+    const toggle = screen.getByRole('button', { name: 'browser.showHidden' })
+    expect(toggle.getAttribute('aria-pressed')).toBe('false')
+    fireEvent.mouseDown(toggle)
+    fireEvent.click(toggle)
+    expect(toggle.getAttribute('aria-pressed')).toBe('true')
+    expect(screen.getByText('.config')).toBeTruthy()
+    fireEvent.click(toggle)
+    expect(toggle.getAttribute('aria-pressed')).toBe('false')
+    expect(screen.queryByText('.config')).toBeNull()
+    // Close resets the toggle.
+    b.view.rerender(<DirectoryBrowser {...b.props} open={false} />)
+    b.view.rerender(<DirectoryBrowser {...b.props} open />)
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    expect(screen.queryByText('.config')).toBeNull()
+  })
+
   it('selects a row into the two-pane view: children preview right, crumbs follow the selection', async () => {
     const b = mount()
     await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
@@ -153,7 +200,7 @@ describe('DirectoryBrowser', () => {
     expect(signals[2]?.aborted).toBe(true)
   })
 
-  it('jumps back through a crumb into a fresh single-column level', async () => {
+  it('a crumb jump to the display root (home) lands the single wide level', async () => {
     mount()
     await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
     fireEvent.click(rowButton(screen.getByRole('listitem')))
@@ -164,6 +211,393 @@ describe('DirectoryBrowser', () => {
     expect(rowButton(screen.getByRole('listitem')).getAttribute('aria-current')).toBeNull()
   })
 
+  it('a crumb jump away from the root lands two-pane with the target selected', async () => {
+    mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(rowButton(screen.getByRole('listitem')))
+    await waitFor(() => { expect(columns()).toHaveLength(2) })
+    fireEvent.click(rowButton(within(columns()[1]!).getByRole('listitem')))
+    await waitFor(() => { expect(screen.getByRole('button', { name: 'harness' })).toBeTruthy() })
+    // Jumping to the Documents crumb is a step BACK one pane, not a
+    // collapse: Documents stays selected in the home level, its children
+    // stay on the right.
+    fireEvent.click(screen.getByRole('button', { name: 'Documents' }))
+    await waitFor(() => {
+      expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true')
+    })
+    expect(columns()).toHaveLength(2)
+    expect(within(columns()[0]!).getByText('Documents')).toBeTruthy()
+    expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
+  })
+
+  it('a navigation to the filesystem root keeps the single wide level', async () => {
+    mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: '/' } })
+    fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
+    // A one-crumb chain has no parent level to show on the left.
+    await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('home') })
+    expect(columns()).toHaveLength(1)
+  })
+
+  it('lands the target single-pane at the wait bound, aborts a superseded parent leg on the wire, and drops its late resolution', async () => {
+    vi.useFakeTimers()
+    try {
+      const signals: (AbortSignal | undefined)[] = []
+      const settlers: ((value: DirectoryListing) => void)[] = []
+      // Only the FIRST explicit HOME request (the parent leg) hangs; the
+      // later home crumb jump lists normally.
+      let homeCalls = 0
+      const listDirectory = vi.fn((path?: string, signal?: AbortSignal) => {
+        signals.push(signal)
+        if (path === HOME && ++homeCalls === 1) {
+          return new Promise<DirectoryListing>((resolve) => { settlers.push(resolve) })
+        }
+        return Promise.resolve(listingFor(path))
+      })
+      mount({ listDirectory })
+      await act(async () => {})
+      fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+      fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: DOCS } })
+      fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
+      // The target settled but the parent leg hangs: inside the wait bound
+      // nothing commits yet.
+      await act(async () => {})
+      expect(settlers).toHaveLength(1)
+      expect(screen.getByLabelText('browser.editPath', { selector: 'input' })).toBeTruthy()
+      // The wait bound expires: the target commits alone — editor closed,
+      // single-pane DOCS level.
+      await act(async () => { vi.advanceTimersByTime(200) })
+      expect(screen.getByRole('listitem').textContent).toBe('harness')
+      expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+      expect(columns()).toHaveLength(1)
+      // A newer jump aborts the pending parent leg ON THE WIRE, not merely
+      // dropping its settlement.
+      fireEvent.click(screen.getByRole('button', { name: 'browser.home' }))
+      expect(signals[2]?.aborted).toBe(true)
+      await act(async () => {})
+      expect(screen.getByRole('listitem').textContent).toBe('Documents')
+      // Its late resolution changes nothing either.
+      await act(async () => { settlers[0]!(listingFor(HOME)) })
+      expect(columns()).toHaveLength(1)
+      expect(rowButton(screen.getByRole('listitem')).getAttribute('aria-current')).toBeNull()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  /**
+   * Listing fake whose explicit-path scans stay pending until the test
+   * settles them by path; the absent-path form (the initial home listing)
+   * resolves normally so mounting is a one-flush setup.
+   */
+  function manualLister() {
+    const settlers = new Map<string, (value: DirectoryListing) => void>()
+    const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => {
+      if (path === undefined) return Promise.resolve(listingFor(path))
+      return new Promise<DirectoryListing>((resolve) => { settlers.set(path, resolve) })
+    })
+    return { settlers, listDirectory }
+  }
+
+  it('lands a navigation as ONE two-pane frame: the stale view holds until both legs arrive', async () => {
+    vi.useFakeTimers()
+    try {
+      const { settlers, listDirectory } = manualLister()
+      mount({ listDirectory })
+      await act(async () => {})
+      fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+      fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: DOCS } })
+      fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
+      // The target settles while the parent leg is still in flight: nothing
+      // commits yet — the editor stays open over the stale home level, and no
+      // single-pane DOCS frame ever renders.
+      await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) })
+      expect(screen.getByLabelText('browser.editPath', { selector: 'input' })).toBeTruthy()
+      expect(screen.queryByText('harness')).toBeNull()
+      // The parent leg settles inside the wait bound: one commit straight to
+      // the two-pane landing, editor closed.
+      await act(async () => { settlers.get(HOME)!(listingFor(HOME)) })
+      expect(columns()).toHaveLength(2)
+      expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true')
+      expect(within(columns()[0]!).getByText('Documents')).toBeTruthy()
+      expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
+      expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+      // The wait-bound timer firing after the landing is a no-op.
+      await act(async () => { vi.advanceTimersByTime(200) })
+      expect(columns()).toHaveLength(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('a stalled parent leg lands the target alone at the wait bound, then upgrades in place', async () => {
+    vi.useFakeTimers()
+    try {
+      const { settlers, listDirectory } = manualLister()
+      mount({ listDirectory })
+      await act(async () => {})
+      fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+      fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: DOCS } })
+      fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
+      // The target can consume most of the outer scan's silence window.
+      await act(async () => { vi.advanceTimersByTime(250) })
+      await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) })
+      // Its parent leg gets a fresh silence window. Crossing the original
+      // scan's 300ms deadline therefore cannot flash the indicator during the
+      // bounded landing wait.
+      await act(async () => { vi.advanceTimersByTime(199) })
+      expect(screen.queryByText('browser.loading')).toBeNull()
+      // The parent leg outlives PARENT_LEG_WAIT_MS: the target lands alone.
+      await act(async () => { vi.advanceTimersByTime(1) })
+      expect(columns()).toHaveLength(1)
+      expect(screen.getByRole('listitem').textContent).toBe('harness')
+      expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+      // The late parent leg still upgrades the landing in place, exactly as
+      // if it had made the bound. (Reopening the editor meanwhile would
+      // supersede the upgrade — the editor-open handler withdraws pending
+      // listings — so a late upgrade can never close a resumed draft.)
+      await act(async () => { settlers.get(HOME)!(listingFor(HOME)) })
+      expect(columns()).toHaveLength(2)
+      expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true')
+      expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('Escape inside the landing window withdraws the submitted navigation', async () => {
+    vi.useFakeTimers()
+    try {
+      const { settlers, listDirectory } = manualLister()
+      mount({ listDirectory })
+      await act(async () => {})
+      fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+      const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+      fireEvent.change(input, { target: { value: DOCS } })
+      fireEvent.keyDown(input, { key: 'Enter' })
+      await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) })
+      // Nothing has committed yet; Escape supersedes the landing entirely.
+      fireEvent.keyDown(input, { key: 'Escape' })
+      await act(async () => { vi.advanceTimersByTime(200) })
+      expect(columns()).toHaveLength(1)
+      expect(screen.queryByText('harness')).toBeNull()
+      expect(within(columns()[0]!).getByText('Documents')).toBeTruthy()
+      expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('shows the loading indicator only once a scan outlives its silence window, floating over the stale view', async () => {
+    vi.useFakeTimers()
+    try {
+      // The home level is truncated so its note is on screen when the slow
+      // scan starts: dropping the note's old !loading guard means it must
+      // keep rendering through the scan, coexisting with the indicator.
+      const settlers = new Map<string, (value: DirectoryListing) => void>()
+      const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => {
+        if (path === undefined) return Promise.resolve({ ...listingFor(path), truncated: true })
+        return new Promise<DirectoryListing>((resolve) => { settlers.set(path, resolve) })
+      })
+      mount({ listDirectory })
+      await act(async () => {})
+      expect(screen.queryByText('browser.loading')).toBeNull()
+      expect(screen.getByText('browser.truncated')).toBeTruthy()
+      fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+      fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: DOCS } })
+      fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
+      // In flight but still inside the silence window: no indicator, and the
+      // stale level's truncated note stays put (no layout churn on launch).
+      expect(screen.queryByText('browser.loading')).toBeNull()
+      expect(screen.getByText('browser.truncated')).toBeTruthy()
+      await act(async () => { vi.advanceTimersByTime(300) })
+      // Past it: the indicator floats while the stale level — truncated note
+      // included — keeps rendering beneath it.
+      expect(screen.getByText('browser.loading')).toBeTruthy()
+      expect(screen.getByText('browser.truncated')).toBeTruthy()
+      expect(screen.getByText('Documents')).toBeTruthy()
+      // Landing (both legs) retires the indicator with the scan, and the
+      // fresh listings' own truncated state replaces the stale note.
+      await act(async () => { settlers.get(DOCS)!(listingFor(DOCS)) })
+      await act(async () => { settlers.get(HOME)!(listingFor(HOME)) })
+      expect(screen.queryByText('browser.loading')).toBeNull()
+      expect(screen.queryByText('browser.truncated')).toBeNull()
+      expect(columns()).toHaveLength(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('restarts the silence window when a row pick supersedes a pending scan', async () => {
+    vi.useFakeTimers()
+    try {
+      const pending: ((value: DirectoryListing) => void)[] = []
+      const listDirectory = vi.fn((path?: string, _signal?: AbortSignal) => {
+        if (path === undefined) return Promise.resolve(listingFor(path))
+        return new Promise<DirectoryListing>((resolve) => { pending.push(resolve) })
+      })
+      mount({ listDirectory })
+      await act(async () => {})
+      const documents = rowButton(screen.getByRole('listitem'))
+      fireEvent.click(documents)
+      await act(async () => { vi.advanceTimersByTime(300) })
+      expect(screen.getByText('browser.loading')).toBeTruthy()
+      // The same row remains actionable while its preview is pending. A second
+      // pick starts a new listing without a false `loading` edge.
+      fireEvent.click(documents)
+      expect(screen.queryByText('browser.loading')).toBeNull()
+      await act(async () => { vi.advanceTimersByTime(299) })
+      expect(screen.queryByText('browser.loading')).toBeNull()
+      await act(async () => { vi.advanceTimersByTime(1) })
+      expect(screen.getByText('browser.loading')).toBeTruthy()
+      await act(async () => { pending.at(-1)!(listingFor(DOCS)) })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('a close mid-scan resets the slow-scan gate: reopening waits a fresh silence window', async () => {
+    vi.useFakeTimers()
+    try {
+      // Every home listing hangs: the initial open's scan is the one the
+      // close interrupts, and the reopen's scan proves the fresh window.
+      const settlers: ((value: DirectoryListing) => void)[] = []
+      const listDirectory = vi.fn((_path?: string, _signal?: AbortSignal) =>
+        new Promise<DirectoryListing>((resolve) => { settlers.push(resolve) }))
+      const { view, props } = mount({ listDirectory })
+      await act(async () => { vi.advanceTimersByTime(300) })
+      expect(screen.getByText('browser.loading')).toBeTruthy()
+      // Close while the scan is in flight, then reopen: the first frame must
+      // wait out a fresh silence window, not inherit the armed indicator.
+      view.rerender(<DirectoryBrowser {...props} open={false} />)
+      view.rerender(<DirectoryBrowser {...props} open />)
+      await act(async () => {})
+      expect(screen.queryByText('browser.loading')).toBeNull()
+      await act(async () => { vi.advanceTimersByTime(300) })
+      expect(screen.getByText('browser.loading')).toBeTruthy()
+      // The reopened scan settles normally.
+      await act(async () => { settlers.at(-1)!(listingFor(undefined)) })
+      expect(screen.queryByText('browser.loading')).toBeNull()
+      expect(screen.getByText('Documents')).toBeTruthy()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('keeps the single-pane landing when the truncated parent level lacks the target', async () => {
+    const listDirectory = vi.fn(async (path?: string) => {
+      // The parent leg names HOME explicitly; serve it a truncated window
+      // that misses Documents (the initial open uses the absent-path form).
+      if (path === HOME) return { ...listingFor(HOME), entries: [], truncated: true }
+      return listingFor(path)
+    })
+    mount({ listDirectory })
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: DOCS } })
+    fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
+    await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') })
+    // The upgrade would orphan the selection (no source row): it stays off.
+    await act(async () => {})
+    expect(columns()).toHaveLength(1)
+    expect(screen.queryByText('browser.truncated')).toBeNull()
+  })
+
+  it('anchors the upgrade on the parent level actual entry under Windows case folding', async () => {
+    const ROOT = 'C:\\'
+    const TYPED = 'c:\\users'
+    const winRoot: DirectoryListing = {
+      path: ROOT,
+      home: ROOT,
+      crumbs: [{ name: 'C:\\', path: ROOT, hidden: false }],
+      entries: [{ name: 'Users', path: 'C:\\Users', hidden: false }],
+      truncated: false,
+    }
+    const winUsers: DirectoryListing = {
+      path: TYPED,
+      home: ROOT,
+      crumbs: [{ name: 'C:\\', path: ROOT, hidden: false }, { name: 'users', path: TYPED, hidden: false }],
+      entries: [],
+      truncated: false,
+    }
+    mount({ listDirectory: vi.fn(async (path?: string) => (path === TYPED ? winUsers : winRoot)) })
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: TYPED } })
+    fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
+    // The typed case differs from the real entry; the upgrade selects the
+    // parent level's ACTUAL entry so aria-current and exemptions hold.
+    await waitFor(() => {
+      expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true')
+    })
+    expect(within(columns()[0]!).getByText('Users')).toBeTruthy()
+  })
+
+  it('re-parks focus on the edit zone when a failed pick unmounts a dot-revealed row', async () => {
+    const listDirectory = vi.fn(async (path?: string) => {
+      if (path === `${HOME}/.config`) {
+        throw new DirectoryBrowseError({ code: 'directory-unreadable', message: 'denied', details: { path } })
+      }
+      return listingFor(path)
+    })
+    mount({ listDirectory })
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: `${HOME}/.co` } })
+    const row = rowButton(screen.getByRole('listitem'))
+    fireEvent.mouseDown(row)
+    fireEvent.click(row)
+    // The failed selection re-hides the picked row; focus fell to body and
+    // re-parks on the crumb edit zone.
+    await screen.findByRole('alert')
+    expect(screen.queryByText('.config')).toBeNull()
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'browser.editPath' }))
+  })
+
+  it('leaves focus on a surviving row when its pick fails', async () => {
+    const listDirectory = vi.fn(async (path?: string) => {
+      if (path === DOCS) {
+        throw new DirectoryBrowseError({ code: 'directory-unreadable', message: 'denied', details: { path } })
+      }
+      return listingFor(path)
+    })
+    mount({ listDirectory })
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: `${HOME}/do` } })
+    const row = rowButton(screen.getByRole('listitem'))
+    row.focus()
+    fireEvent.mouseDown(row)
+    fireEvent.click(row)
+    // Documents survives the cleared selection (it is not hidden): the
+    // user's focus on it is not yanked to the edit zone.
+    await screen.findByRole('alert')
+    expect(document.activeElement).toBe(row)
+  })
+
+  it('falls back to the single-pane landing when the parent leg of a navigation fails', async () => {
+    const listDirectory = vi.fn(async (path?: string) => {
+      // The initial open lists home through the absent-path form; only the
+      // parent leg names HOME explicitly.
+      if (path === HOME) {
+        throw new DirectoryBrowseError({ code: 'directory-unreadable', message: 'parent gone', details: { path } })
+      }
+      return listingFor(path)
+    })
+    mount({ listDirectory })
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    fireEvent.change(screen.getByLabelText<HTMLInputElement>('browser.editPath'), { target: { value: DOCS } })
+    fireEvent.keyDown(screen.getByLabelText('browser.editPath'), { key: 'Enter' })
+    // The target listed fine; the failed parent leg neither blocks the
+    // landing nor surfaces an error for a level nobody asked to see.
+    await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') })
+    expect(columns()).toHaveLength(1)
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+
   it('opens the selection, else the listed level; Cancel closes; busy freezes Open', async () => {
     const b = mount()
     await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
@@ -186,18 +620,221 @@ describe('DirectoryBrowser', () => {
     await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
     fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
     const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
-    expect(input.value).toBe(HOME)
+    // The editor seeds with a trailing separator so typing continues into
+    // child names.
+    expect(input.value).toBe(`${HOME}/`)
     fireEvent.change(input, { target: { value: DOCS } })
     fireEvent.keyDown(input, { key: 'Enter' })
-    await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') })
-    expect(columns()).toHaveLength(1)
+    // Away from the root a navigation lands two-pane: the target selected
+    // in its parent level, its own children on the right.
+    await waitFor(() => { expect(columns()).toHaveLength(2) })
+    expect(rowButton(within(columns()[0]!).getByRole('listitem')).getAttribute('aria-current')).toBe('true')
+    expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
+    // The submitted navigation unmounted the focused input; focus parks on
+    // the crumb edit zone that replaced it.
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'browser.editPath' }))
     fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
     const again = screen.getByLabelText<HTMLInputElement>('browser.editPath')
     fireEvent.change(again, { target: { value: '   ' } })
     fireEvent.keyDown(again, { key: 'Enter' })
-    expect(b.listDirectory).toHaveBeenCalledTimes(2)
+    // Initial home + the DOCS target leg + its parent leg; the blank draft
+    // added none.
+    expect(b.listDirectory).toHaveBeenCalledTimes(3)
     fireEvent.keyDown(again, { key: 'Escape' })
     expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+    // Escape with focus in the input parks focus on the returning edit zone.
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'browser.editPath' }))
+  })
+
+  it('prefix-filters the listed level from the draft tail, dot revealing hidden matches', async () => {
+    mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+    // The seeded empty segment leaves the level as-is: hidden stays hidden.
+    expect(screen.getByRole('listitem').textContent).toBe('Documents')
+    // Case-insensitive prefix narrows the rows.
+    fireEvent.change(input, { target: { value: `${HOME}/do` } })
+    expect(screen.getByRole('listitem').textContent).toBe('Documents')
+    // A dot-led prefix names hidden entries, so it reveals the match.
+    fireEvent.change(input, { target: { value: `${HOME}/.co` } })
+    expect(screen.getByRole('listitem').textContent).toBe('.config')
+    // A prefix matching nothing empties the level (no stale rows linger).
+    fireEvent.change(input, { target: { value: `${HOME}/zzz` } })
+    expect(screen.queryByRole('listitem')).toBeNull()
+    // A draft naming some other directory (or none) leaves the level whole.
+    fireEvent.change(input, { target: { value: 'no-separator' } })
+    expect(screen.getByRole('listitem').textContent).toBe('Documents')
+  })
+
+  it('filters the child pane in two-pane mode and follows the draft back up a level', async () => {
+    mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(rowButton(screen.getByRole('listitem')))
+    await waitFor(() => { expect(columns()).toHaveLength(2) })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+    // The seed comes from the selection, so the draft tail addresses the
+    // RIGHT pane (the selection's children).
+    expect(input.value).toBe(`${DOCS}/`)
+    fireEvent.change(input, { target: { value: `${DOCS}/h` } })
+    expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
+    fireEvent.change(input, { target: { value: `${DOCS}/zzz` } })
+    expect(within(columns()[1]!).queryAllByRole('listitem')).toHaveLength(0)
+    expect(within(columns()[0]!).getByText('Documents')).toBeTruthy()
+    // Erasing back into the parent's own path moves the filter to the LEFT
+    // pane and releases the right one. The selected row is exempt (it
+    // anchors the two-pane view), so it alone survives the miss.
+    fireEvent.change(input, { target: { value: `${HOME}/zz` } })
+    expect(within(columns()[0]!).getAllByRole('listitem').map(item => item.textContent)).toEqual(['Documents'])
+    expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
+  })
+
+  it('keeps the draft and filter through window focus loss and in-dialog focus moves', async () => {
+    mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+    fireEvent.change(input, { target: { value: `${HOME}/do` } })
+    // A blur while the document itself lost focus (window switch, dev-tools
+    // focus) must not discard the draft: value and filter both survive.
+    const hasFocus = vi.spyOn(document, 'hasFocus').mockReturnValue(false)
+    fireEvent.focusOut(input)
+    hasFocus.mockRestore()
+    expect(screen.getByLabelText<HTMLInputElement>('browser.editPath', { selector: 'input' }).value).toBe(`${HOME}/do`)
+    expect(screen.getByRole('listitem').textContent).toBe('Documents')
+    // A keyboard focus move that stays inside the dialog (Tab onto the
+    // filtered row) keeps the draft too — the results stay reachable.
+    fireEvent.focusOut(input, { relatedTarget: rowButton(screen.getByRole('listitem')) })
+    expect(screen.getByLabelText<HTMLInputElement>('browser.editPath', { selector: 'input' }).value).toBe(`${HOME}/do`)
+    // Toggling show-hidden mid-edit suppresses focus steal: the draft and
+    // its filter survive the toggle in both directions.
+    const toggle = screen.getByRole('button', { name: 'browser.showHidden' })
+    fireEvent.mouseDown(toggle)
+    fireEvent.click(toggle)
+    expect(toggle.getAttribute('aria-pressed')).toBe('true')
+    expect(screen.getByLabelText<HTMLInputElement>('browser.editPath', { selector: 'input' }).value).toBe(`${HOME}/do`)
+    expect(screen.getByRole('listitem').textContent).toBe('Documents')
+    // Focus landing outside the dialog cancels like Escape — even when the
+    // departure happens from a row the user had Tabbed onto, not the input
+    // (the observer lives on the card scope, not the input).
+    fireEvent.focusOut(rowButton(screen.getByRole('listitem')), { relatedTarget: document.body })
+    expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+    // Outside editing the card-scope observer is inert.
+    fireEvent.focusOut(screen.getByRole('button', { name: 'browser.showHidden' }))
+    expect(screen.getByRole('button', { name: 'browser.editPath' })).toBeTruthy()
+  })
+
+  it('Escape with focus on a filtered row collapses the editor, not the dialog', async () => {
+    const b = mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+    fireEvent.change(input, { target: { value: `${HOME}/do` } })
+    // Tab parked focus on the result row; Escape must still mean "leave
+    // path editing", not "close the whole dialog".
+    const row = rowButton(screen.getByRole('listitem'))
+    row.focus()
+    fireEvent.keyDown(row, { key: 'Escape' })
+    expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+    expect(b.onClose).not.toHaveBeenCalled()
+    // Focus was already on a surviving row, so nothing re-parks it.
+    expect(document.activeElement).toBe(row)
+    // With no draft left, Escape falls through to the Modal and closes.
+    fireEvent.keyDown(row, { key: 'Escape' })
+    expect(b.onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('a picked dot-revealed hidden row stays visible as the selection', async () => {
+    mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+    fireEvent.change(input, { target: { value: `${HOME}/.co` } })
+    const row = rowButton(screen.getByRole('listitem'))
+    expect(row.textContent).toBe('.config')
+    fireEvent.mouseDown(row)
+    fireEvent.click(row)
+    // The pick cleared the draft (and with it the dot-reveal), but the
+    // selection is exempt from the hidden filter: the anchor row survives.
+    expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+    await waitFor(() => { expect(columns()).toHaveLength(2) })
+    expect(within(columns()[0]!).getByText('.config')).toBeTruthy()
+  })
+
+  it('picking a filtered row adopts it and closes the path editor', async () => {
+    mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+    fireEvent.change(input, { target: { value: `${HOME}/do` } })
+    // The row suppresses focus steal on mousedown (no blur-cancel unmounts
+    // the filtered rows mid-gesture), then the click both selects the row
+    // and closes the editor.
+    const row = rowButton(screen.getByRole('listitem'))
+    fireEvent.mouseDown(row)
+    fireEvent.click(row)
+    expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+    // Focus parks on the picked row (the editor's input just unmounted and
+    // the Modal has no focus trap to catch a fall to body).
+    expect(document.activeElement).toBe(row)
+    await waitFor(() => { expect(columns()).toHaveLength(2) })
+    expect(screen.getByRole('button', { name: 'browser.home' })).toBeTruthy()
+  })
+
+  it('a right-pane pick while editing parks focus on the advanced selection', async () => {
+    mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(rowButton(screen.getByRole('listitem')))
+    await waitFor(() => { expect(columns()).toHaveLength(2) })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+    fireEvent.change(input, { target: { value: `${DOCS}/h` } })
+    // The advance replaces BOTH panes (the picked button's own column
+    // unmounts), so focus is re-parked on the selection's aria-current row
+    // in the freshly rendered left pane rather than the clicked node.
+    const row = rowButton(within(columns()[1]!).getByRole('listitem'))
+    fireEvent.mouseDown(row)
+    fireEvent.click(row)
+    expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+    await waitFor(() => { expect(document.activeElement?.textContent).toBe('harness') })
+    expect(document.activeElement?.getAttribute('aria-current')).toBe('true')
+  })
+
+  it('seeds and filters with backslashes on a Windows-rooted listing', async () => {
+    const ROOT = 'C:\\'
+    const windowsListing: DirectoryListing = {
+      path: ROOT,
+      home: ROOT,
+      crumbs: [{ name: 'C:\\', path: ROOT, hidden: false }],
+      entries: [
+        { name: 'Program Files', path: `${ROOT}Program Files`, hidden: false },
+        { name: 'Users', path: `${ROOT}Users`, hidden: false },
+      ],
+      truncated: false,
+    }
+    mount({ listDirectory: vi.fn(async () => windowsListing) })
+    await waitFor(() => { expect(screen.getAllByRole('listitem')).toHaveLength(2) })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+    // The root already ends in its separator: no doubled backslash.
+    expect(input.value).toBe(ROOT)
+    fireEvent.change(input, { target: { value: `${ROOT}u` } })
+    expect(screen.getByRole('listitem').textContent).toBe('Users')
+  })
+
+  it('clicking away from the path editor cancels it back to the crumb view', async () => {
+    mount()
+    await waitFor(() => { expect(screen.getByRole('listitem')).toBeTruthy() })
+    fireEvent.click(screen.getByRole('button', { name: 'browser.editPath' }))
+    const input = screen.getByLabelText<HTMLInputElement>('browser.editPath')
+    fireEvent.change(input, { target: { value: '/somewhere/else' } })
+    // Focus moving anywhere outside the editor abandons the draft like Escape.
+    fireEvent.focusOut(input)
+    expect(screen.queryByLabelText('browser.editPath', { selector: 'input' })).toBeNull()
+    // The crumb view is back and the abandoned draft was never navigated to.
+    expect(screen.getByRole('button', { name: 'browser.editPath' })).toBeTruthy()
+    expect(screen.getByRole('listitem').textContent).toBe('Documents')
   })
 
   it('restarts the home listing when Escape cancels an edit opened before any level listed', async () => {
@@ -713,11 +1350,13 @@ describe('DirectoryBrowser', () => {
     b.listDirectory.mockReturnValueOnce(slow)
     fireEvent.click(screen.getByRole('button', { name: 'browser.home' }))
     fireEvent.click(within(screen.getByRole('navigation')).getByRole('button', { name: 'Documents' }))
-    await waitFor(() => { expect(screen.getByRole('listitem').textContent).toBe('harness') })
+    // The newer jump lands two-pane: Documents selected at home, children right.
+    await waitFor(() => { expect(within(columns()[1]!).getByText('harness')).toBeTruthy() })
     resolveSlow(listingFor(undefined))
     await new Promise(settle => setTimeout(settle, 0))
-    // The stale home listing did not replace the newer Documents level.
-    expect(screen.getByRole('listitem').textContent).toBe('harness')
+    // The stale home listing did not replace the newer Documents landing.
+    expect(columns()).toHaveLength(2)
+    expect(within(columns()[1]!).getByText('harness')).toBeTruthy()
   })
 
   it('names the create target by its path when the level reports no crumbs', async () => {

packages/session-query/session-query-sqlite/src/index.ts

@@ -62,6 +62,16 @@ export {
   type JournalMode,
 } from './schema.ts'
 
+/** Boot-context slot for a launcher-owned absolute path to this process's derived query index. */
+export const SESSION_QUERY_SQLITE_PATH_KEY = 'launcherSessionQueryPath'
+
+declare module 'cordis' {
+  interface Context {
+    /** Launcher-owned absolute path to this process's disposable derived query index. */
+    launcherSessionQueryPath?: string
+  }
+}
+
 /** Default result page size. */
 export const SESSION_QUERY_SQLITE_DEFAULT_LIMIT = 20
 /** Maximum accepted result page size. */

packages/settings/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # 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/examples/tui-demo/README.md
-README.md: 058ebe87af5f041bd19fbfb205a97753ccacf6b9
-README.zh.md: 43681e9c77cbd77459ec0539b69e0ab73274d2c1
+#   pnpm run verify-translation-pairing --write packages/settings/README.md
+README.md: 7a91355dd01805938944f0abce77765021288e6d
+README.zh.md: 2df40b67eb8ce6cfc693ed6bf3574815c0219ec0

packages/settings/README.md

@@ -0,0 +1,12 @@
+# settings/ — user-settings capability family
+
+English | [中文](README.zh.md)
+
+The user-settings seam and its providers. The interface package owns the abstract `Settings` service — namespace registration, layered resolution, and change commits; providers implement raw-document storage and push external edits through the seam. All **product** packages.
+
+| Package | Role | ctx key |
+|---|---|---|
+| `settings/` | Settings seam: namespace registry, layered resolution, commit events | `ctx.settings` |
+| `settings-local/` | File-backed provider (`settings.yaml`/`.json`) with hot reload and comment-preserving write-back | (registers `ctx.settings`) |
+
+The interface lives at `settings/settings/`; providers are flat siblings. A network configuration-center provider (for example a nacos-style backend) joins here and registers on `ctx.settings`. Composition config stays in `cordis.yml`: a settings namespace carries only the user-editable subset, resolved as schema defaults, then the registrant's composition `base`, then the user document.

packages/settings/README.zh.md

@@ -0,0 +1,12 @@
+# settings/ — 用户设置能力族
+
+[English](README.md) | 中文
+
+用户设置 seam 及其 provider。接口包拥有抽象 `Settings` 服务——namespace 注册、分层解析与变更提交；provider 实现原始文档存储并把外部修改推入 seam。全部为**产品**包。
+
+| 包 | 角色 | ctx key |
+|---|---|---|
+| `settings/` | 设置 seam：namespace 注册表、分层解析、提交事件 | `ctx.settings` |
+| `settings-local/` | 文件 provider（`settings.yaml`/`.json`），热重载与保留注释的写回 | （注册 `ctx.settings`） |
+
+接口位于 `settings/settings/`；provider 平级并列。网络配置中心 provider（例如 nacos 类后端）加入本组并注册到 `ctx.settings`。组合配置仍留在 `cordis.yml`：settings namespace 只承载用户可编辑子集，解析顺序为 schema 默认值、注册方的组合 `base`、用户文档。

packages/settings/settings-local/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/settings/settings-local/README.md
+README.md: 2c0817afd2f2fd35fda2d22cd7f7ef3772fe2257
+README.zh.md: 547abb035368f07d4478a5c3a1793cdaa6743c68

packages/settings/settings-local/README.md

@@ -0,0 +1,43 @@
+# @deepseek-ai/dsh-settings-local
+
+English | [中文](README.zh.md)
+
+File-backed settings provider. One YAML or JSON document carries every namespace section; external edits hot-publish through `ctx.settings`, and `update()` re-reads the document under a writer lock before writing back atomically, preserving the user's YAML comments, any section owned by a plugin that is not currently loaded, and any on-disk change this process has not observed yet.
+
+## Config
+
+| Field | Meaning | Default |
+|---|---|---|
+| `path` | Settings document path; extension picks the format (`.yaml`/`.yml`/`.json`) | `settings.yaml` under the harness home |
+| `dshHome` | Harness home used when `path` is omitted | `$DSH_HOME` or `~/.dsh` |
+| `watch` | Watch the document and hot-publish external edits | `true` |
+| `debounceMs` | Watcher write-settle window in milliseconds | `100` |
+
+Defaulting is one explicit `resolveSpec(config)` step; an unsupported extension fails at load.
+
+## Behavior
+
+- **Boot fails loud, reload keeps last-good.** An existing-but-invalid document fails plugin load; once live, an unreadable or unparsable edit warns and keeps the last good sections. A missing document resolves every namespace from defaults and `base`; deleting it publishes the same empty state.
+- **Every write is a read-modify-write.** A persist first re-reads the document and publishes any difference into the seam — an external edit still inside the watcher debounce window, a change the watcher missed, or another process's write — then renders against that fresh text, so a write can never resurrect a stale document or drop an unobserved sibling section. If the on-disk document turned invalid, the write rejects loud instead of overwriting the user's manual edit.
+- **Writes hold a cross-process writer lock.** The read-render-rename cycle runs under a `wx`-created `<file>.lock` sibling with exponential backoff, a 2 s acquisition deadline (the write rejects), and stale-lock takeover after 5 s (a crashed holder, broken with a warning). Readers never take the lock: the rename commit is atomic, so reloads are always consistent.
+- **Write-back is atomic, owner-only, and symlink-proof.** The render exclusive-creates a random-suffix temp sibling with mode `0600` (`wx` refuses to follow a planted symlink) and renames over the target, cleaning the temp up on failure.
+- **YAML edits are leaf-level diffs.** A write sets only the values that changed and deletes only the keys that were removed, so comments, anchors, and formatting survive on every untouched node and on the key of every changed pair; a changed array (or other non-map value) replaces wholesale, taking comments inside it along. JSON re-serializes without comments.
+- **Reloads and writes share one operation chain.** Watcher refreshes and persists from every namespace queue run one at a time in queue order; each render sees the text the previous operation committed.
+- **The watcher's ready signal reconciles once.** The initial load races the watcher's own setup, so a change written in between never fires an event; the reconcile at ready closes that startup gap.
+- **Dispose quiesces.** Teardown stops accepting watcher events, closes the watcher, then waits out any queued or in-flight operation, so nothing publishes after disposal.
+- **Self-write suppression by content.** The provider caches the last good text; a watcher event whose content equals the cache (its own write included) is a no-op.
+
+## Model Experience
+
+Indirectly, through consumers of `ctx.settings`: this provider only stores and publishes namespace sections, and each consumer's own surface documents any model effect.
+
+#### KV Cache effect
+
+No direct invalidation; the consuming plugin owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Same-namespace conflicts stay last-write-wins** — the writer lock and read-modify-write keep concurrent writers from dropping each other's namespaces, but two writers editing one namespace still resolve to the later write; there is no per-value merge or revision check.
+- **A missed watcher event stays unseen until the next signal** — reads never re-stat the file, so a change the watcher fails to report is only folded in by the next event, the next write, or a restart.
+- **Comment preservation is YAML-only and map-shaped** — JSON documents re-serialize without comments (JSON has none), and comments inside a changed array (or attached inline to a changed scalar value) go with the value they described.
+- **No value indirection** — sections hold literal values; `${env:VAR}`-style references for secrets are a deferred seam-level feature.

packages/settings/settings-local/README.zh.md

@@ -0,0 +1,43 @@
+# @deepseek-ai/dsh-settings-local
+
+[English](README.md) | 中文
+
+文件 settings provider。一个 YAML 或 JSON 文档承载全部 namespace 分节；外部编辑经 `ctx.settings` 热发布，`update()` 在写锁下先重读文档再原子写回，保留用户的 YAML 注释、当前未加载插件所拥有的分节，以及任何本进程尚未观察到的磁盘变更。
+
+## 配置
+
+| 字段 | 含义 | 默认 |
+|---|---|---|
+| `path` | 设置文档路径；扩展名决定格式（`.yaml`/`.yml`/`.json`） | harness home 下的 `settings.yaml` |
+| `dshHome` | `path` 省略时使用的 harness home | `$DSH_HOME` 或 `~/.dsh` |
+| `watch` | 监听文档并热发布外部编辑 | `true` |
+| `debounceMs` | watcher 写入稳定窗口（毫秒） | `100` |
+
+默认值解析是一步显式的 `resolveSpec(config)`；不支持的扩展名在加载时报错。
+
+## 行为
+
+- **启动报错响亮，重载保留最后可用值。** 存在但非法的文档使插件加载失败；运行中不可读或不可解析的编辑只告警并保留最后可用分节。文档缺失时所有 namespace 按默认值与 `base` 解析；删除文档发布同样的空状态。
+- **每次写入都是一次读-改-写。** persist 先重读文档并把任何差异发布进 seam——无论是仍在 watcher 防抖窗口内的外部编辑、watcher 漏掉的变更，还是另一个进程的写入——再基于这份新鲜文本渲染，因此写入绝不会复活陈旧文档，也不会丢掉未观察到的同级分节。若磁盘上的文档已变为非法，写入响亮拒绝，而不是覆盖用户的手工编辑。
+- **写入持有跨进程写锁。** 读-渲染-rename 流程在 `wx` 创建的 `<file>.lock` 同级文件下运行，带指数退避、2 s 的获取期限（到期则写入拒绝）与 5 s 后的陈旧锁接管（持有者已崩溃，破锁并告警）。读取方从不取锁：rename 提交是原子的，重载因此始终一致。
+- **写回原子、仅属主可读、抗符号链接。** 渲染以 `0600` 权限独占创建随机后缀临时同级文件（`wx` 拒绝跟随预埋符号链接）后 rename 覆盖目标，失败时清理临时文件。
+- **YAML 编辑是叶子级 diff。** 写入只设置发生变化的值、只删除被移除的键，因此注释、锚点与排版在每个未触碰的节点上以及每个被改键值对的键上都得以保留；被改的数组（或其他非 map 值）整体替换，其中的注释随之一同被换掉。JSON 重新序列化，无注释。
+- **重载与写入共享一条操作链。** watcher 刷新与来自各 namespace 队列的 persist 按队列顺序逐个执行；每次渲染都基于上一次操作提交后的文本。
+- **watcher 的 ready 信号做一次对账。** 初始加载与 watcher 自身的建立存在竞态，因此其间写入的变更绝不会触发事件；ready 时的对账补上这个启动缺口。
+- **Dispose 保证静止。** 卸载先停止接收 watcher 事件、关闭 watcher，再等完排队与进行中的操作，之后不再有任何发布。
+- **按内容抑制自写。** provider 缓存最后可用文本；watcher 事件内容与缓存相同（含自己的写入）即为 no-op。
+
+## Model Experience
+
+间接生效：本 provider 只存储并发布 namespace 分节，模型效果经由 `ctx.settings` 的消费插件产生，由各消费者自己的文档描述。
+
+#### KV Cache effect
+
+无直接失效；请求前缀的变更由消费插件拥有。
+
+## Known Limitations and Deferred Work
+
+- **同 namespace 冲突仍是后写胜出** — 写锁加读-改-写让并发写入者不会丢掉彼此的 namespace，但两个写入者编辑同一个 namespace 时仍以较后的写入为准；没有按值合并，也没有修订检查。
+- **漏掉的 watcher 事件在下一个信号前保持不可见** — 读取从不重新 stat 文件，因此 watcher 漏报的变更只会在下一个事件、下一次写入或重启时被并入。
+- **注释保留仅限 YAML 且仅限 map 形状** — JSON 文档重新序列化，无注释（JSON 本身没有），且被改数组内部的注释（或行内附着在被改标量值上的注释）随其所描述的值一同被换掉。
+- **无值间接引用** — 分节存字面值；面向密钥的 `${env:VAR}` 式引用是 seam 层的延后特性。

packages/settings/settings-local/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@deepseek-ai/dsh-settings-local",
+  "description": "File-backed settings provider (settings.yaml) for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-paths": "^0.0.1",
+    "@deepseek-ai/dsh-settings": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "schemastery": "^3.18.0",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-paths": "workspace:^",
+    "@deepseek-ai/dsh-settings": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/settings/settings-local/src/index.ts

@@ -0,0 +1,411 @@
+/**
+ * File-backed settings provider. One YAML or JSON document under the user's
+ * harness home carries every namespace section; external edits hot-publish
+ * through the seam, and every write re-reads the document under a
+ * cross-process writer lock before patching it as a comment-preserving
+ * leaf-level diff.
+ * @module @deepseek-ai/dsh-settings-local
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import { watch as chokidarWatch } from 'chokidar'
+import { randomBytes } from 'node:crypto'
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { dirname, extname, join, resolve } from 'node:path'
+import { Document, parseDocument } from 'yaml'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { Settings, deepEqualJson, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
+
+/** Plugin config: file location and hot-reload behavior. */
+export interface Config {
+  /** Settings document path; defaults to `settings.yaml` under the harness home. */
+  path?: string
+  /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Watch the document and hot-publish external edits; defaults to true. */
+  watch?: boolean
+  /** Watcher write-settle window in milliseconds; defaults to 100. */
+  debounceMs?: number
+}
+
+/** Document format derived from the configured file extension. */
+type SettingsFormat = 'yaml' | 'json'
+
+const FORMATS: Record<string, SettingsFormat> = {
+  '.yaml': 'yaml',
+  '.yml': 'yaml',
+  '.json': 'json',
+}
+
+/** Fully resolved provider parameters; defaulting happens here, never inline. */
+interface ResolvedSpec {
+  filename: string
+  format: SettingsFormat
+  watch: boolean
+  debounceMs: number
+}
+
+/**
+ * Resolve the runtime spec from plugin config: an explicit `path` wins,
+ * otherwise the document lives at `<harness home>/settings.yaml`.
+ * @param config - raw plugin config.
+ * @returns the resolved file location, format, and watch behavior.
+ */
+export function resolveSpec(config: Config): ResolvedSpec {
+  const filename = resolve(config.path ?? join(resolveDshHome(config.dshHome), 'settings.yaml'))
+  const format = FORMATS[extname(filename)]
+  if (format === undefined) {
+    throw new Error(`settings-local: extension "${extname(filename)}" is not supported (use .yaml, .yml, or .json)`)
+  }
+  return {
+    filename,
+    format,
+    watch: config.watch ?? true,
+    debounceMs: config.debounceMs ?? 100,
+  }
+}
+
+/** Whether a parsed YAML value is a map for diffing purposes. */
+function isMapLike(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Apply the difference between one node's stored and next value as minimal
+ * `setIn`/`deleteIn` edits, recursing through maps, so every untouched node —
+ * and the key node of every changed pair — keeps its comments, anchors, and
+ * formatting. Non-map values (arrays and scalars) replace wholesale when
+ * unequal, taking any comments inside them along.
+ */
+function patchNode(document: Document, path: readonly string[], current: unknown, next: unknown): void {
+  if (isMapLike(current) && isMapLike(next)) {
+    for (const key of Object.keys(current)) {
+      if (!(key in next)) document.deleteIn([...path, key])
+    }
+    for (const [key, value] of Object.entries(next)) {
+      patchNode(document, [...path, key], current[key], value)
+    }
+    return
+  }
+  if (!deepEqualJson(current, next)) document.setIn([...path], next)
+}
+
+/** Whether a filesystem error means absence; every non-ENOENT failure must surface. */
+function isENOENT(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT'
+}
+
+/** Whether an exclusive create failed because the path already exists. */
+function isEEXIST(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | null)?.code === 'EEXIST'
+}
+
+/**
+ * Writer-lock protocol constants. These are robustness invariants of the
+ * cross-process write protocol, not deployment tunables: a holder rewrites one
+ * small document in milliseconds, so contention resolves well inside the
+ * retry deadline, and a lock older than the stale age can only belong to a
+ * crashed holder.
+ */
+const LOCK_RETRY_INITIAL_MS = 20
+const LOCK_RETRY_MAX_MS = 200
+const LOCK_TIMEOUT_MS = 2_000
+const LOCK_STALE_MS = 5_000
+
+/** File-backed settings provider (`settings.yaml`/`.json`). */
+export class SettingsLocal extends Settings {
+  static Config: z<Config> = z.object({
+    path: z.string(),
+    dshHome: z.string(),
+    watch: z.boolean().default(true),
+    debounceMs: z.number().min(0).default(100),
+  })
+
+  private readonly spec: ResolvedSpec
+  /**
+   * Raw text of the last successfully parsed or persisted document;
+   * `undefined` while the file is absent. Watcher events whose content equals
+   * this cache are no-ops, which is also the self-write suppression.
+   */
+  private text: string | undefined
+  /**
+   * Single exclusive operation chain: watcher reloads and document writes run
+   * one at a time in queue order (settled tail), so a write can never render
+   * from text a concurrent reload is busy replacing, and a reload can never
+   * read a half-committed write.
+   */
+  private operations: Promise<void> = Promise.resolve()
+  /** Set at dispose: refuse new watcher events and let in-flight work no-op. */
+  private closed = false
+
+  /** Opaque read of {@link closed}: control flow cannot narrow it across awaits. */
+  private isClosed(): boolean {
+    return this.closed
+  }
+
+  constructor(ctx: Context, public config: Config) {
+    super(ctx)
+    // Programmatic construction may bypass Schemastery normalization; resolve
+    // the same defaults in one explicit step either way.
+    this.spec = resolveSpec(config)
+  }
+
+  /** The local document is always writable through {@link Settings.update}. */
+  get writable(): boolean {
+    return true
+  }
+
+  protected async load(): Promise<Record<string, unknown>> {
+    let text: string
+    try {
+      text = await readFile(this.spec.filename, 'utf8')
+    } catch (error) {
+      if (!isENOENT(error)) throw error
+      this.text = undefined
+      return {}
+    }
+    const doc = this.parse(text)
+    this.text = text
+    return doc
+  }
+
+  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    // One document backs every namespace, so writes from different namespace
+    // queues serialize with each other and with watcher reloads on the one
+    // operation chain: each render must see the text the previous operation
+    // committed, or a sibling section silently vanishes from disk.
+    return this.enqueue(() => this.persistSection(ns, section))
+  }
+
+  /** Queue one exclusive document operation behind every earlier one. */
+  private enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const task = this.operations.then(operation)
+    this.operations = task.then(() => undefined, () => undefined)
+    return task
+  }
+
+  /** Queue a reload; only an invariant violation escaping a commit can reject it. */
+  private queueRefresh(): void {
+    void this.enqueue(() => this.refresh()).catch((error: unknown) => {
+      // Only an invariant violation escaping the commit path can reject a
+      // refresh; keep the operation queue alive and surface it as an error so
+      // one poisoned commit cannot silently end hot reloading forever.
+      this.ctx.logger.error('settings-local: reload commit failed at %s', this.spec.filename)
+      this.ctx.logger.error(error)
+    })
+  }
+
+  private async persistSection(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    await mkdir(dirname(this.spec.filename), { recursive: true })
+    await this.withWriterLock(async () => {
+      // Read-modify-write: fold in any on-disk state this process has not
+      // observed yet — an external edit still inside the watcher debounce
+      // window, a change the watcher missed, or another process's write — so
+      // the render below can never resurrect a stale document. An unparsable
+      // on-disk document fails the write loud instead of silently overwriting
+      // a user's manual edit.
+      await this.reconcileFromDisk()
+      const output = this.spec.format === 'yaml'
+        ? this.renderYaml(ns, section)
+        : this.renderJson(ns, section)
+      // Exclusive-create (`wx`) a random-suffix sibling: the open refuses to
+      // follow any planted symlink at a guessable temp path, and the fresh inode
+      // carries owner-only permissions that survive the rename — a document that
+      // may hold personal values is never world-readable and never a symlink.
+      const temp = `${this.spec.filename}.${randomBytes(6).toString('hex')}.tmp`
+      // TODO(settings-atomic-durability): Use a replacement that fsyncs the file
+      // and parent directory and preserves owner-only permissions on Windows.
+      try {
+        await writeFile(temp, output, { mode: 0o600, flag: 'wx' })
+        await rename(temp, this.spec.filename)
+      } catch (error) {
+        await rm(temp, { force: true })
+        throw error
+      }
+      this.text = output
+    })
+  }
+
+  /**
+   * Hold the cross-process writer lock around one read-render-rename cycle.
+   * The lock is a `wx`-created sibling (`<file>.lock`); the rename-based
+   * commit keeps readers lock-free, so only writers contend. A lock older
+   * than {@link LOCK_STALE_MS} is a crashed holder and is broken with a
+   * warning; a live holder past {@link LOCK_TIMEOUT_MS} fails the write.
+   */
+  private async withWriterLock<T>(operation: () => Promise<T>): Promise<T> {
+    const lockPath = `${this.spec.filename}.lock`
+    const deadline = Date.now() + LOCK_TIMEOUT_MS
+    let delay = LOCK_RETRY_INITIAL_MS
+    for (;;) {
+      try {
+        await writeFile(lockPath, `${process.pid}\n`, { mode: 0o600, flag: 'wx' })
+        break
+      } catch (error) {
+        if (!isEEXIST(error)) throw error
+      }
+      const ageMs = await this.lockAgeMs(lockPath)
+      // The holder released between the failed create and the stat: the lock
+      // is free right now, so retry without burning backoff or deadline.
+      if (ageMs === undefined) continue
+      if (ageMs > LOCK_STALE_MS) {
+        // TODO(settings-lock-ownership): Replace age-only takeover with ownership-safe
+        // acquisition and release so a slow writer cannot remove a successor's lock.
+        this.ctx.logger.warn('settings-local: breaking a stale writer lock at %s', lockPath)
+        await rm(lockPath, { force: true })
+        continue
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`settings-local: timed out waiting for the writer lock at ${lockPath}`)
+      }
+      await new Promise(resolve => setTimeout(resolve, delay))
+      delay = Math.min(delay * 2, LOCK_RETRY_MAX_MS)
+    }
+    try {
+      return await operation()
+    } finally {
+      await rm(lockPath, { force: true })
+    }
+  }
+
+  /** Age of the writer lock, or `undefined` when it vanished after a failed create. */
+  private async lockAgeMs(lockPath: string): Promise<number | undefined> {
+    try {
+      return Date.now() - (await stat(lockPath)).mtimeMs
+    } catch (error) {
+      if (!isENOENT(error)) throw error
+      return undefined
+    }
+  }
+
+  override async* [Service.init](): AsyncGenerator<() => Promise<void> | void, void, void> {
+    // The base init loads and publishes; a parse failure there is a boot
+    // failure: an existing-but-invalid document must fail loud, never be
+    // silently ignored or overwritten.
+    yield* super[Service.init]()
+    if (!this.spec.watch) return
+    const watcher = chokidarWatch(this.spec.filename, {
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: this.spec.debounceMs,
+        pollInterval: Math.max(1, Math.min(this.spec.debounceMs, 10)),
+      },
+    })
+    watcher.on('all', () => {
+      if (this.closed) return
+      this.queueRefresh()
+    })
+    watcher.on('ready', () => {
+      // The base init's load raced the watcher's own setup: a change written
+      // between that read and the watcher becoming active never fires an
+      // event. One reconcile at ready closes the gap.
+      if (this.closed) return
+      this.queueRefresh()
+    })
+    watcher.on('error', (error) => {
+      this.ctx.logger.warn('settings-local: watcher error on %s', this.spec.filename)
+      this.ctx.logger.warn(error)
+    })
+    yield async () => {
+      // Quiesce: stop accepting events, close the watcher, then wait out any
+      // queued or in-flight operation so nothing publishes after disposal.
+      this.closed = true
+      await watcher.close()
+      await this.operations
+    }
+  }
+
+  /** Parse one document text into raw sections, failing on a non-map root. */
+  private parse(text: string): Record<string, unknown> {
+    let root: unknown
+    if (this.spec.format === 'yaml') {
+      const document = parseDocument(text, { prettyErrors: true })
+      if (document.errors.length > 0) {
+        throw new Error(`settings-local: invalid document at ${this.spec.filename}: ${
+          document.errors.map(error => error.message).join('; ')}`)
+      }
+      root = document.toJS() ?? {}
+    } else {
+      root = text.trim().length === 0 ? {} : JSON.parse(text)
+    }
+    if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+      throw new TypeError(`settings-local: ${this.spec.filename} must be a map of namespace sections`)
+    }
+    return root as Record<string, unknown>
+  }
+
+  /**
+   * Re-read the document after a watcher event. Unchanged content (including
+   * this provider's own writes) is a no-op; an unreadable or unparsable
+   * document keeps the last good sections and warns — a live hot-reload must
+   * never take the process down. An invariant violation escaping a commit is
+   * not a reload failure and propagates to the queue's error surface.
+   */
+  private async refresh(): Promise<void> {
+    if (this.closed) return
+    try {
+      await this.reconcileFromDisk()
+    } catch (error) {
+      if ((error as { code?: unknown } | null)?.code === 'INVARIANT') throw error
+      this.ctx.logger.warn('settings-local: reload failed at %s; keeping the last good document', this.spec.filename)
+      this.ctx.logger.warn(error)
+    }
+  }
+
+  /**
+   * Compare the on-disk text against the cache and publish any difference
+   * into the seam. Absence publishes the empty document; an unreadable or
+   * unparsable file throws, so each caller picks its policy — a reload warns
+   * and keeps the last good document, a write fails loud.
+   */
+  private async reconcileFromDisk(): Promise<void> {
+    let text: string | undefined
+    try {
+      text = await readFile(this.spec.filename, 'utf8')
+    } catch (error) {
+      if (!isENOENT(error)) throw error
+      text = undefined
+    }
+    if (text === this.text || this.isClosed()) return
+    if (text === undefined) {
+      this.text = undefined
+      this.publish({})
+      return
+    }
+    const doc = this.parse(text)
+    this.text = text
+    this.publish(doc)
+  }
+
+  /**
+   * Render the next YAML text by patching one namespace in the
+   * comment-preserving document. The next section lands as a leaf-level diff
+   * against the stored one — only changed values set, only removed keys
+   * delete — so comments inside the section survive edits to their siblings,
+   * not just comments outside it.
+   */
+  private renderYaml(ns: SettingsNamespace, section: Record<string, unknown>): string {
+    if (this.text === undefined) {
+      return new Document({ [ns]: section }).toString()
+    }
+    // this.text only ever caches content that parsed successfully, so this
+    // re-parse (for the mutable comment-preserving tree) cannot fail, and
+    // parse() already rejected any non-map root.
+    const document = parseDocument(this.text)
+    const root: unknown = document.toJS()
+    patchNode(document, [ns], isMapLike(root) ? root[ns] : undefined, section)
+    return document.toString()
+  }
+
+  /** Render the next JSON text by replacing one namespace key. */
+  private renderJson(ns: SettingsNamespace, section: Record<string, unknown>): string {
+    const root = this.text === undefined
+      ? {}
+      : this.parse(this.text)
+    root[ns] = section
+    return `${JSON.stringify(root, null, 2)}\n`
+  }
+}
+
+export default SettingsLocal

packages/settings/settings-local/src/invariant.ts

@@ -1,22 +1,23 @@
 /**
- * Package-owned invariant companion for `@deepseek-ai/dsh-tui-demo`.
- * @module @deepseek-ai/dsh-tui-demo/invariant
+ * Package-owned invariant companion for `@deepseek-ai/dsh-settings-local`.
+ * @module @deepseek-ai/dsh-settings-local/invariant
  */
 
 /* jscpd:ignore-start */
 import type { Context } from 'cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 
-const PACKAGE_NAME = '@deepseek-ai/dsh-tui-demo'
+const PACKAGE_NAME = '@deepseek-ai/dsh-settings-local'
 
 /** Cordis companion plugin name. */
-export const name = 'tui-demo-invariant'
+export const name = 'settings-local-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
 /**
- * No runtime invariant: this composition-only package delegates mutable state and event streams
- * to the agent spine, persistence, and TUI packages that own their checks.
+ * No runtime invariant: this provider's contracts are file round-trip,
+ * watcher timing, and atomic-write behavior — IO effects proven by package
+ * tests; the in-process commit relation is owned by `@deepseek-ai/dsh-settings`.
  */
 const install: InvariantInstaller = () => {}
 

packages/settings/settings-local/tests/concurrency.spec.ts

@@ -0,0 +1,103 @@
+// Cross-instance and writer-lock behavior: two providers on one document are
+// the in-process equivalent of two dsh processes sharing a harness home —
+// neither knows the other's cache, so only the read-modify-write cycle under
+// the `<file>.lock` sibling keeps both namespaces alive on disk.
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { chmod, mkdtemp, readFile, rm, utimes, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { SettingsLocal } from '../src/index.ts'
+
+const AlphaSchema: z<{ value: number }> = z.object({ value: z.number().default(0) })
+const BetaSchema: z<{ value: number }> = z.object({ value: z.number().default(0) })
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  while (cleanups.length > 0) await cleanups.pop()!()
+})
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-settings-lock-'))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function boot(config: ConstructorParameters<typeof SettingsLocal>[1]): Promise<Context> {
+  const ctx = new Context()
+  const fiber = ctx.plugin(SettingsLocal, config)
+  cleanups.push(async () => { await fiber.dispose() })
+  await fiber
+  return ctx
+}
+
+describe('cross-instance writes', () => {
+  it('keeps both namespaces when two providers write the same document concurrently', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const first = await boot({ path, watch: false })
+    const second = await boot({ path, watch: false })
+    const alpha = first.settings.register(settingsNamespace('alpha'), AlphaSchema)
+    const beta = second.settings.register(settingsNamespace('beta'), BetaSchema)
+    const rounds = [1, 2, 3, 4, 5]
+    await Promise.all([
+      (async () => { for (const value of rounds) await alpha.update({ value }) })(),
+      (async () => { for (const value of rounds) await beta.update({ value }) })(),
+    ])
+    const text = await readFile(path, 'utf8')
+    expect(text).toContain('alpha:')
+    expect(text).toContain('beta:')
+    // A third instance resolves both final values from the shared document.
+    const third = await boot({ path, watch: false })
+    expect(third.settings.register(settingsNamespace('alpha'), AlphaSchema).get()).toEqual({ value: 5 })
+    expect(third.settings.register(settingsNamespace('beta'), BetaSchema).get()).toEqual({ value: 5 })
+  })
+})
+
+describe('writer lock', () => {
+  it('waits for a busy writer lock instead of failing', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema)
+    await writeFile(`${path}.lock`, 'holder\n')
+    const release = setTimeout(() => { void rm(`${path}.lock`, { force: true }) }, 120)
+    cleanups.push(async () => { clearTimeout(release) })
+    await scope.update({ value: 7 })
+    expect(await readFile(path, 'utf8')).toContain('value: 7')
+  })
+
+  it('breaks a stale writer lock with a warning and writes through', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema)
+    await writeFile(`${path}.lock`, 'crashed-holder\n')
+    const past = (Date.now() - 60_000) / 1000
+    await utimes(`${path}.lock`, past, past)
+    await scope.update({ value: 9 })
+    expect(await readFile(path, 'utf8')).toContain('value: 9')
+  })
+
+  it('times out on a lock a live holder never releases', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema)
+    await writeFile(`${path}.lock`, 'busy-holder\n')
+    await expect(scope.update({ value: 1 })).rejects.toThrow(/timed out waiting for the writer lock/)
+  }, 10_000)
+
+  it('surfaces a non-contention lock failure as the write error', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema)
+    await chmod(dir, 0o500)
+    cleanups.push(() => chmod(dir, 0o700))
+    await expect(scope.update({ value: 1 })).rejects.toThrow(/EACCES|permission/)
+  })
+})

packages/settings/settings-local/tests/loader-composition.spec.ts

@@ -0,0 +1,145 @@
+/**
+ * Real-composition guard: the provider and a consumer plugin boot from a
+ * test-only cordis.yml through the actual Loader + Include path, an external
+ * edit of settings.yaml hot-publishes into the consumer's scope, and the same
+ * consumer booted WITHOUT a settings entry keeps its entry-config resolution —
+ * the documented optional-inject fallback.
+ */
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+import z from 'schemastery'
+import { settingsNamespace, type SettingsScope } from '@deepseek-ai/dsh-settings'
+import SettingsLocal from '../src/index.ts'
+
+interface ThemeConfig {
+  theme: 'dark' | 'light'
+  fontSize: number
+}
+
+const ThemeSchema: z<ThemeConfig> = z.object({
+  theme: z.union(['dark', 'light']).default('dark'),
+  fontSize: z.number().default(14),
+})
+
+let root: string | undefined
+let context: Context | undefined
+
+afterEach(async () => {
+  await context?.fiber.dispose()
+  context = undefined
+  if (root !== undefined) await rm(root, { recursive: true, force: true })
+  root = undefined
+})
+
+interface ConsumerState {
+  scope: SettingsScope<ThemeConfig> | undefined
+  seen: ThemeConfig[]
+  /** What the consumer is actually running with, settings or not. */
+  applied: ThemeConfig | undefined
+}
+
+async function loadComposition(
+  options?: { withSettings?: boolean },
+): Promise<{ ctx: Context; state: ConsumerState; settingsPath: string }> {
+  const withSettings = options?.withSettings ?? true
+  root = await mkdtemp(join(tmpdir(), 'dsh-settings-composition-'))
+  const settingsPath = join(root, 'settings.yaml')
+  await writeFile(settingsPath, 'ui-theme:\n  theme: light\n')
+
+  const state: ConsumerState = { scope: undefined, seen: [], applied: undefined }
+  const consumer = {
+    name: 'settings-consumer',
+    apply: (ctx: Context) => {
+      // The documented consumer shape: no hard dependency — entry config alone
+      // is the running state, and the scoped inject overlays the user layer
+      // only while a settings service exists.
+      const base: Partial<ThemeConfig> = { fontSize: 16 }
+      state.applied = ThemeSchema(base as ThemeConfig)
+      ctx.inject(['settings'], (child: Context) => {
+        const scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema, { base })
+        state.scope = scope
+        state.applied = scope.get()
+        scope.watch((next) => {
+          state.seen.push(next)
+          state.applied = next
+        })
+      })
+    },
+  }
+
+  const configPath = join(root, 'cordis.yml')
+  await writeFile(configPath, [
+    ...withSettings
+      ? [
+        '- id: settings',
+        "  name: '@deepseek-ai/dsh-settings-local'",
+        '  config:',
+        `    path: ${JSON.stringify(settingsPath)}`,
+        '    debounceMs: 10',
+      ]
+      : [],
+    '- id: consumer',
+    '  name: test-settings-consumer',
+    '',
+  ].join('\n'))
+
+  const ctx = new Context()
+  context = ctx
+  ctx.baseUrl = pathToFileURL(root).href + '/'
+  await ctx.plugin(Loader)
+  ctx.loader.builtins.include = Include
+  const modules = new Map<string, unknown>([
+    ['@deepseek-ai/dsh-settings-local', SettingsLocal],
+    ['test-settings-consumer', consumer],
+  ])
+  ctx.loader.internal = {
+    version: 'v2',
+    async import(specifier: string) {
+      if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+      return modules.get(specifier)
+    },
+  } as unknown as NonNullable<typeof ctx.loader.internal>
+  await ctx.loader.create({
+    name: 'cordis:include',
+    config: { path: pathToFileURL(configPath).href },
+  })
+  await ctx.loader.await()
+  return { ctx, state, settingsPath }
+}
+
+describe('settings-local real composition', () => {
+  it('boots from cordis.yml and hot-publishes an external settings edit', async () => {
+    const { ctx, state, settingsPath } = await loadComposition()
+
+    // Composition resolution: user layer over the consumer's composition base.
+    await vi.waitFor(() => {
+      expect(state.scope!.get()).toEqual({ theme: 'light', fontSize: 16 })
+    })
+    expect(ctx.get('settings')!.describe().map(entry => entry.ns)).toEqual(['ui-theme'])
+
+    await writeFile(settingsPath, 'ui-theme:\n  theme: dark\n  fontSize: 20\n')
+    await vi.waitFor(() => {
+      expect(state.scope!.get()).toEqual({ theme: 'dark', fontSize: 20 })
+    }, { timeout: 5000 })
+    expect(state.seen.at(-1)).toEqual({ theme: 'dark', fontSize: 20 })
+  })
+
+  it('boots the same consumer without a settings entry and keeps entry-config resolution', async () => {
+    const { ctx, state } = await loadComposition({ withSettings: false })
+
+    // No settings service anywhere in the composition…
+    expect(ctx.get('settings')).toBeUndefined()
+    // …so the consumer runs on schema defaults plus its composition base, and
+    // never receives a scope.
+    expect(state.applied).toEqual({ theme: 'dark', fontSize: 16 })
+    expect(state.scope).toBeUndefined()
+    expect(state.seen).toEqual([])
+  })
+})

packages/settings/settings-local/tests/local.spec.ts

@@ -0,0 +1,401 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { chmod, lstat, mkdtemp, readFile, readdir, rm, stat, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { SettingsLocal, resolveSpec } from '../src/index.ts'
+
+interface ThemeConfig {
+  theme: 'dark' | 'light'
+  fontSize: number
+}
+
+const ThemeSchema: z<ThemeConfig> = z.object({
+  theme: z.union(['dark', 'light']).default('dark'),
+  fontSize: z.number().default(14),
+})
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  while (cleanups.length > 0) await cleanups.pop()!()
+})
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-settings-local-'))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function boot(config: ConstructorParameters<typeof SettingsLocal>[1]): Promise<Context> {
+  const ctx = new Context()
+  const fiber = ctx.plugin(SettingsLocal, config)
+  cleanups.push(async () => { await fiber.dispose() })
+  await fiber
+  return ctx
+}
+
+describe('resolveSpec', () => {
+  it('defaults watch and debounce when construction bypasses schema normalization', () => {
+    const spec = resolveSpec({ path: '/tmp/anywhere/settings.yaml' })
+    expect(spec.watch).toBe(true)
+    expect(spec.debounceMs).toBe(100)
+  })
+})
+
+describe('boot and reads', () => {
+  it('resolves defaults over an absent file and reports writable', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, 'settings.yaml'), watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, {
+      base: { fontSize: 16 },
+    })
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 16 })
+    expect(ctx.settings.writable).toBe(true)
+  })
+
+  it('reads sections from an existing yaml document', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(scope.get()).toEqual({ theme: 'light', fontSize: 14 })
+  })
+
+  it('reads sections from a json document', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.json')
+    await writeFile(path, JSON.stringify({ 'ui-theme': { fontSize: 18 } }))
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 18 })
+  })
+
+  it('defaults the file location under the configured harness home', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ dshHome: dir, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ theme: 'light' })
+    const written = await readFile(join(dir, 'settings.yaml'), 'utf8')
+    expect(written).toContain('theme: light')
+  })
+
+  it('reads an empty yaml document as no sections', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, '')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 })
+  })
+
+  it('reads an empty json document as no sections', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.json')
+    await writeFile(path, '')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 })
+  })
+
+  it('fails loud at boot when the document exists but is unreadable', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    await chmod(path, 0o000)
+    cleanups.push(() => chmod(path, 0o600))
+    await expect(boot({ path, watch: false })).rejects.toThrow(/EACCES|permission/i)
+  })
+
+  it('fails loud on an unsupported extension', async () => {
+    const dir = await tempDir()
+    await expect(boot({ path: join(dir, 'settings.toml'), watch: false }))
+      .rejects.toThrow(/not supported/)
+  })
+
+  it('fails loud at boot on unparsable yaml', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme: [unclosed\n')
+    await expect(boot({ path, watch: false })).rejects.toThrow()
+  })
+
+  it('fails loud at boot when the root is not a map of sections', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, '- just\n- a list\n')
+    await expect(boot({ path, watch: false })).rejects.toThrow(/map of namespace sections/)
+  })
+})
+
+describe('persist', () => {
+  it('writes the merged section, creating the file with owner-only permissions', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ theme: 'light' })
+
+    const written = await readFile(path, 'utf8')
+    expect(written).toContain('theme: light')
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    // Atomic replace leaves no temp artifact behind.
+    expect((await readdir(dir)).sort()).toEqual(['settings.yaml'])
+  })
+
+  it('serializes cross-namespace writes into one on-disk document', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, watch: false })
+    const alpha = ctx.settings.register(settingsNamespace('alpha'), ThemeSchema)
+    const beta = ctx.settings.register(settingsNamespace('beta'), ThemeSchema)
+    await Promise.all([
+      alpha.update({ theme: 'light' }),
+      beta.update({ fontSize: 20 }),
+    ])
+    const text = await readFile(path, 'utf8')
+    expect(text).toContain('alpha:')
+    expect(text).toContain('beta:')
+    expect(alpha.get().theme).toBe('light')
+    expect(beta.get().fontSize).toBe(20)
+  })
+
+  it('never follows a planted symlink at a temp path and never leaves the document a symlink', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const victim = join(dir, 'victim.txt')
+    await writeFile(victim, 'precious')
+    // A hostile sibling plants the historic fixed temp name as a symlink.
+    await symlink(victim, `${path}.tmp`)
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ theme: 'light' })
+
+    expect(await readFile(victim, 'utf8')).toBe('precious')
+    expect((await lstat(path)).isSymbolicLink()).toBe(false)
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect(await readFile(path, 'utf8')).toContain('theme: light')
+  })
+
+  it('preserves comments and unregistered sections across updates', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, [
+      '# personal settings',
+      'ui-theme:',
+      '  theme: light',
+      '# owned by a plugin that is not loaded right now',
+      'future-plugin:',
+      '  keep: me',
+      '',
+    ].join('\n'))
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ fontSize: 18 })
+
+    const written = await readFile(path, 'utf8')
+    expect(written).toContain('# personal settings')
+    expect(written).toContain('# owned by a plugin that is not loaded right now')
+    expect(written).toContain('keep: me')
+    expect(written).toContain('fontSize: 18')
+    expect(written).toContain('theme: light')
+  })
+
+  it('keeps comments inside the section when a sibling key changes', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, [
+      'ui-theme:',
+      '  # chosen during onboarding',
+      '  theme: light',
+      '  fontSize: 12',
+      '',
+    ].join('\n'))
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ fontSize: 18 })
+    const written = await readFile(path, 'utf8')
+    expect(written).toContain('# chosen during onboarding')
+    expect(written).toContain('theme: light')
+    expect(written).toContain('fontSize: 18')
+  })
+
+  it('keeps a changed key\'s own-line comment while replacing its value', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, [
+      'ui-theme:',
+      '  # chosen during onboarding',
+      '  theme: light',
+      '',
+    ].join('\n'))
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ theme: 'dark' })
+    const written = await readFile(path, 'utf8')
+    expect(written).toContain('# chosen during onboarding')
+    expect(written).toContain('theme: dark')
+  })
+
+  it('deletes only the removed key on replace, keeping sibling comments', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, [
+      'ui-theme:',
+      '  # chosen during onboarding',
+      '  theme: light',
+      '  fontSize: 12',
+      '',
+    ].join('\n'))
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.replace({ theme: 'light' })
+    const written = await readFile(path, 'utf8')
+    expect(written).toContain('# chosen during onboarding')
+    expect(written).toContain('theme: light')
+    expect(written).not.toContain('fontSize')
+  })
+
+  it('keeps an unchanged array\'s comments and replaces a changed array wholesale', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const TagsSchema: z<{ tags: string[]; label: string }> = z.object({
+      tags: z.array(z.string()).default([]),
+      label: z.string().default(''),
+    })
+    await writeFile(path, [
+      'workspace:',
+      '  tags:',
+      '    # pinned by hand',
+      '    - alpha',
+      '  label: draft',
+      '',
+    ].join('\n'))
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('workspace'), TagsSchema)
+    await scope.update({ label: 'final' })
+    const untouched = await readFile(path, 'utf8')
+    expect(untouched).toContain('# pinned by hand')
+    expect(untouched).toContain('label: final')
+    // A changed array replaces wholesale; comments inside it go with it.
+    await scope.update({ tags: ['beta'] })
+    const replaced = await readFile(path, 'utf8')
+    expect(replaced).not.toContain('# pinned by hand')
+    expect(replaced).toContain('- beta')
+  })
+
+  it('keeps a comment-only document\'s comment when the first section lands', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    // Parses to a null root: the document exists but holds no sections yet.
+    await writeFile(path, '# reserved for future settings\n')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ theme: 'light' })
+    const written = await readFile(path, 'utf8')
+    expect(written).toContain('# reserved for future settings')
+    expect(written).toContain('theme: light')
+  })
+
+  it('creates a json document from scratch', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.json')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ theme: 'light' })
+    const written = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>
+    expect(written).toEqual({ 'ui-theme': { theme: 'light' } })
+  })
+
+  it('rejects and leaves no temp residue when the directory turns unwritable', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await chmod(dir, 0o500)
+    cleanups.push(() => chmod(dir, 0o700))
+    await expect(scope.update({ theme: 'dark' })).rejects.toThrow()
+    await chmod(dir, 0o700)
+    expect((await readdir(dir)).sort()).toEqual(['settings.yaml'])
+    expect(scope.get().theme).toBe('light')
+    // The failed persist must not poison the document write chain.
+    await scope.update({ theme: 'dark' })
+    expect(scope.get().theme).toBe('dark')
+  })
+
+  it('round-trips a json document', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.json')
+    await writeFile(path, JSON.stringify({ other: { keep: true } }, null, 2))
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ theme: 'light' })
+    const written = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>
+    expect(written).toEqual({ other: { keep: true }, 'ui-theme': { theme: 'light' } })
+  })
+})
+
+describe('watch', () => {
+  it('publishes an external edit to registered scopes', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, debounceMs: 10 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(scope.get().theme).toBe('light')
+
+    await writeFile(path, 'ui-theme:\n  theme: dark\n  fontSize: 20\n')
+    await vi.waitFor(() => {
+      expect(scope.get()).toEqual({ theme: 'dark', fontSize: 20 })
+    }, { timeout: 5000 })
+  })
+
+  it('keeps the last good document over an invalid edit, then recovers', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, debounceMs: 10 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+
+    await writeFile(path, 'ui-theme: [unclosed\n')
+    // The bad edit must never take the live tree down or reset the value.
+    await new Promise(resolve => setTimeout(resolve, 300))
+    expect(scope.get()).toEqual({ theme: 'light', fontSize: 14 })
+
+    await writeFile(path, 'ui-theme:\n  theme: dark\n')
+    await vi.waitFor(() => {
+      expect(scope.get().theme).toBe('dark')
+    }, { timeout: 5000 })
+  })
+
+  it('treats file removal as an empty document', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, debounceMs: 10 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+
+    await rm(path)
+    await vi.waitFor(() => {
+      expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 })
+    }, { timeout: 5000 })
+  })
+
+  it('does not republish its own persisted write', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, debounceMs: 10 })
+    const events: unknown[] = []
+    ctx.on('settings/updated', (ns, _next, _prev, source) => {
+      events.push({ ns, source })
+    })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ theme: 'light' })
+    await new Promise(resolve => setTimeout(resolve, 300))
+    expect(events).toEqual([{ ns: 'ui-theme', source: 'update' }])
+  })
+})

packages/settings/settings-local/tests/lock-race.spec.ts

@@ -0,0 +1,100 @@
+// Writer-lock races that cannot be timed from outside: a contender whose lock
+// vanishes between the failed exclusive create and the stat, a stat failing
+// for a reason other than absence, and a temp-file write failing mid-cycle.
+// The fs/promises seam is partially mocked to inject exactly one failure at a
+// chosen path suffix; everything else passes through to the real filesystem.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { access, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { SettingsLocal } from '../src/index.ts'
+
+const state = vi.hoisted(() => ({
+  /** One-shot failure injections keyed by operation, matched on a path suffix. */
+  failures: [] as Array<{ op: 'writeFile' | 'stat'; suffix: string; code: string }>,
+}))
+
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs/promises')>()
+  const inject = (op: 'writeFile' | 'stat', path: unknown): void => {
+    const index = state.failures.findIndex(f => f.op === op && String(path).endsWith(f.suffix))
+    if (index === -1) return
+    const [failure] = state.failures.splice(index, 1)
+    throw Object.assign(new Error(`${failure!.code}: injected ${op} failure`), { code: failure!.code })
+  }
+  return {
+    ...actual,
+    writeFile: (async (path: unknown, ...rest: never[]) => {
+      inject('writeFile', path)
+      return (actual.writeFile as (path: unknown, ...args: never[]) => Promise<void>)(path, ...rest)
+    }) as typeof actual.writeFile,
+    stat: (async (path: unknown, ...rest: never[]) => {
+      inject('stat', path)
+      return (actual.stat as (path: unknown, ...args: never[]) => Promise<unknown>)(path, ...rest)
+    }) as typeof actual.stat,
+  }
+})
+
+const AlphaSchema: z<{ value: number }> = z.object({ value: z.number().default(0) })
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  state.failures.length = 0
+  while (cleanups.length > 0) await cleanups.pop()!()
+})
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-settings-lockrace-'))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function boot(config: ConstructorParameters<typeof SettingsLocal>[1]): Promise<Context> {
+  const ctx = new Context()
+  const fiber = ctx.plugin(SettingsLocal, config)
+  cleanups.push(async () => { await fiber.dispose() })
+  await fiber
+  return ctx
+}
+
+describe('writer-lock races', () => {
+  it('retries immediately when the contending lock vanished before the stat', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema)
+    // The exclusive create loses to a holder that releases before the stat:
+    // no lock file actually exists, so the stat sees honest absence and the
+    // very next attempt takes the lock.
+    state.failures.push({ op: 'writeFile', suffix: '.lock', code: 'EEXIST' })
+    await scope.update({ value: 3 })
+    expect(await readFile(path, 'utf8')).toContain('value: 3')
+  })
+
+  it('propagates a stat failure that does not mean absence', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema)
+    state.failures.push({ op: 'writeFile', suffix: '.lock', code: 'EEXIST' })
+    state.failures.push({ op: 'stat', suffix: '.lock', code: 'EACCES' })
+    await expect(scope.update({ value: 3 })).rejects.toThrow(/EACCES/)
+  })
+
+  it('cleans up the temp file and releases the lock when the write fails mid-cycle', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'alpha:\n  value: 1\n')
+    const ctx = await boot({ path, watch: false })
+    const scope = ctx.settings.register(settingsNamespace('alpha'), AlphaSchema)
+    state.failures.push({ op: 'writeFile', suffix: '.tmp', code: 'ENOSPC' })
+    await expect(scope.update({ value: 9 })).rejects.toThrow(/ENOSPC/)
+    // The document is untouched and the writer lock was released on the way out.
+    expect(await readFile(path, 'utf8')).toContain('value: 1')
+    await expect(access(`${path}.lock`)).rejects.toThrow()
+  })
+})

packages/settings/settings-local/tests/watcher.spec.ts

@@ -0,0 +1,225 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { SettingsLocal } from '../src/index.ts'
+
+// chokidar is the nondeterministic OS boundary: faking it lets these tests
+// drive the event pipeline (error events, races with unreadable files)
+// deterministically. Real end-to-end watching stays covered by local.spec.ts.
+vi.mock('chokidar', async () => {
+  const { EventEmitter } = await import('node:events')
+  class FakeWatcher extends EventEmitter {
+    close = vi.fn(() => Promise.resolve())
+  }
+  const instances: Array<{ path: string; options: unknown; watcher: InstanceType<typeof FakeWatcher> }> = []
+  return {
+    watch: vi.fn((path: string, options: unknown) => {
+      const watcher = new FakeWatcher()
+      instances.push({ path, options, watcher })
+      return watcher
+    }),
+    __instances: instances,
+  }
+})
+
+interface FakeChokidar {
+  __instances: Array<{
+    path: string
+    options: { awaitWriteFinish: { stabilityThreshold: number; pollInterval: number } }
+    watcher: import('node:events').EventEmitter
+  }>
+}
+
+async function fakeInstances(): Promise<FakeChokidar['__instances']> {
+  const chokidar = await import('chokidar') as unknown as FakeChokidar
+  return chokidar.__instances
+}
+
+const ThemeSchema: z<{ theme: string }> = z.object({
+  theme: z.string().default('dark'),
+})
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  while (cleanups.length > 0) await cleanups.pop()!()
+  ;(await fakeInstances()).length = 0
+})
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-settings-watch-'))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function boot(config: ConstructorParameters<typeof SettingsLocal>[1]): Promise<Context> {
+  const ctx = new Context()
+  const fiber = ctx.plugin(SettingsLocal, config)
+  cleanups.push(async () => { await fiber.dispose() })
+  await fiber
+  return ctx
+}
+
+describe('watcher pipeline', () => {
+  it('clamps the write-settle poll interval for a zero debounce', async () => {
+    const dir = await tempDir()
+    await boot({ path: join(dir, 'settings.yaml'), debounceMs: 0 })
+    const [instance] = await fakeInstances()
+    expect(instance!.options.awaitWriteFinish).toEqual({ stabilityThreshold: 0, pollInterval: 1 })
+  })
+
+  it('survives a watcher error and keeps publishing later edits', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const [instance] = await fakeInstances()
+
+    instance!.watcher.emit('error', new Error('watch backend failure'))
+    expect(scope.get()).toEqual({ theme: 'dark' })
+
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    instance!.watcher.emit('all', 'change', path)
+    await vi.waitFor(() => {
+      expect(scope.get()).toEqual({ theme: 'light' })
+    })
+  })
+
+  it('keeps the last good document when the file turns unreadable at runtime', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+
+    await chmod(path, 0o000)
+    cleanups.push(() => chmod(path, 0o600))
+    const [instance] = await fakeInstances()
+    instance!.watcher.emit('all', 'change', path)
+    // The warn-and-keep path is asynchronous; give the serialized refresh a turn.
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(scope.get()).toEqual({ theme: 'light' })
+  })
+
+  it('keeps the reload queue alive after an invariant violation escapes a commit', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    let arm = true
+    ctx.on('settings/updated', () => {
+      if (!arm) return
+      throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' })
+    })
+    const [instance] = await fakeInstances()
+
+    await writeFile(path, 'ui-theme:\n  theme: broken-commit\n')
+    instance!.watcher.emit('all', 'change', path)
+    await vi.waitFor(() => {
+      expect(scope.get().theme).toBe('broken-commit')
+    })
+
+    arm = false
+    await writeFile(path, 'ui-theme:\n  theme: recovered\n')
+    instance!.watcher.emit('all', 'change', path)
+    await vi.waitFor(() => {
+      expect(scope.get().theme).toBe('recovered')
+    })
+  })
+
+  it('quiesces the refresh pipeline before dispose completes', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = new Context()
+    const fiber = ctx.plugin(SettingsLocal, { path, debounceMs: 5 })
+    await fiber
+    ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    let disposed = false
+    let postDisposeCommits = 0
+    ctx.on('settings/updated', () => {
+      if (disposed) postDisposeCommits += 1
+    })
+
+    await writeFile(path, 'ui-theme:\n  theme: darker\n')
+    const [instance] = await fakeInstances()
+    // Two queued refreshes: dispose interrupts one mid-flight and the other
+    // before it starts, so both closed guards must hold.
+    instance!.watcher.emit('all', 'change', path)
+    instance!.watcher.emit('all', 'change', path)
+    await fiber.dispose()
+    disposed = true
+    instance!.watcher.emit('all', 'change', path)
+    instance!.watcher.emit('ready')
+    await new Promise(resolve => setTimeout(resolve, 100))
+    expect(postDisposeCommits).toBe(0)
+  })
+
+  it('treats an event for a still-absent file as a no-op', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const [instance] = await fakeInstances()
+    instance!.watcher.emit('all', 'add', path)
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(scope.get()).toEqual({ theme: 'dark' })
+  })
+
+  it('folds an unobserved external edit into a write instead of overwriting it', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const theme = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const editor = ctx.settings.register(settingsNamespace('editor'), z.object({
+      tabWidth: z.number().default(2),
+    }))
+    // The external edit has landed on disk but its watcher event has not
+    // fired yet (a debounce window, or a missed event): the write must fold
+    // it in, not resurrect the stale document.
+    await writeFile(path, 'ui-theme:\n  theme: light\neditor:\n  tabWidth: 8\n')
+    await theme.update({ theme: 'darker' })
+    const text = await readFile(path, 'utf8')
+    expect(text).toContain('tabWidth: 8')
+    expect(text).toContain('theme: darker')
+    // The fold published the unobserved section before the write committed.
+    expect(editor.get()).toEqual({ tabWidth: 8 })
+  })
+
+  it('reconciles at watcher ready so a change during setup is not missed', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    // Written after the initial load but before the watcher became active:
+    // no 'all' event will ever fire for it.
+    await writeFile(path, 'ui-theme:\n  theme: written-before-ready\n')
+    const [instance] = await fakeInstances()
+    instance!.watcher.emit('ready')
+    await vi.waitFor(() => {
+      expect(scope.get().theme).toBe('written-before-ready')
+    })
+  })
+
+  it('fails a write loud when the on-disk document turned invalid unobserved', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'settings.yaml')
+    await writeFile(path, 'ui-theme:\n  theme: light\n')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const broken = 'ui-theme: [unclosed\n  flow: {\n'
+    await writeFile(path, broken)
+    await expect(scope.update({ theme: 'darker' })).rejects.toThrow(/invalid document/)
+    // The user's manual edit stays on disk untouched and the cache keeps the
+    // last good value.
+    expect(await readFile(path, 'utf8')).toBe(broken)
+    expect(scope.get()).toEqual({ theme: 'light' })
+  })
+})

packages/settings/settings-local/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../util/paths"
+    },
+    {
+      "path": "../settings"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/settings/settings/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/settings/settings/README.md
+README.md: ec9f0e09c47015edd8495dac48beb610e0b5cdc5
+README.zh.md: 6d0a760f9b1bbef21881a03933d0fe5b9fc3cd0d

packages/settings/settings/README.md

@@ -0,0 +1,37 @@
+# @deepseek-ai/dsh-settings
+
+English | [中文](README.zh.md)
+
+Abstract user-settings seam (`ctx.settings`). One provider holds a raw document of per-namespace sections; plugins register a namespace schema and read a resolved value layered as schema defaults, then the registrant's composition `base` (its cordis.yml entry-config subset), then the user document section. Without a mounted provider nothing changes for consumers: they keep resolving entry config alone, so every composition works with or without settings.
+
+## Service API
+
+- `register(ns, schema, { base?, applies? })` — returns the owner `SettingsScope` (`get`/`watch`/`update`). The registration is an effect on the calling plugin's fiber: disposing that fiber removes the namespace and its observers. A stored section the schema rejects fails the registration itself; a duplicate namespace fails loud.
+- `describe()` — one descriptor per namespace (`schema.toJSON()` envelope, resolved value, `applies`) for configuration surfaces.
+- `get(ns)` — resolved value, `undefined` while unregistered.
+- `update(ns, patch)` — deep-merges the plain-object patch into the user section only (never the `base`), validates the resolved candidate, persists through the provider, then commits. Patches must be JSON-shaped data: a Date, Map, BigInt, non-finite number, or circular reference rejects with its `$`-rooted path before anything persists (YAML/JSON storage would silently distort such values on reload). Validation failure rejects before anything is persisted; a read-only provider (`writable: false`) rejects every write. Writes to one namespace are serialized in call order.
+- `replace(ns, section)` — sets the user section wholesale: the removal/reset path a merge cannot express (`replace({})` re-inherits `base` and schema defaults).
+- Resolved values are deep-frozen snapshots. Watchers receive `(next, prev)` after each commit: invocations of one callback run asynchronously, one at a time, in commit order (a slow stale invocation can never apply after a newer one), and failures — sync throws and async rejections alike — are contained. After a watch disposer returns, no further invocation starts (one already queued is skipped); an invocation already started still settles. The `settings/updated` event fans out one listener at a time, so one throwing listener cannot starve the rest; an async listener's rejection is contained and logged, which is why `INVARIANT`-coded failures rethrow only from synchronous listeners.
+- Service teardown refuses new writes and watcher starts, then drains every queued write and every started watcher invocation before disposal completes; a write whose registrant fiber was disposed mid-flight still reaches storage but commits and notifies nobody.
+
+## Provider contract
+
+Subclasses implement `writable`, `load()`, and `persist(ns, section)`, and push externally observed documents through the protected `publish(doc)`. The base service init loads and publishes the document once before the service becomes injectable; a provider with its own init (watcher, connection) delegates first via `yield* super[Service.init]()`. At publish, each registered namespace re-resolves independently: an invalid section keeps that namespace's last good value and warns — a live reload never takes the process down — while boot-time and registration-time validation fail loud.
+
+## Events
+
+`settings/updated (ns, next, prev, source)` fires after each commit; `source` is `update` (in-process write) or `provider` (external change). It never fires for a deep-equal resolved value.
+
+## Model Experience
+
+Indirectly, through consumer plugins that resolve model-affecting values (for example a default model route) from their namespaces; each consumer's own surface documents the effect.
+
+#### KV Cache effect
+
+No direct invalidation; a consumer that folds a settings value into the request prefix owns that change.
+
+## Known Limitations and Deferred Work
+
+- **Single user layer** — resolution knows schema defaults, one composition `base`, and one user document; there is no project/managed layering or per-value provenance yet.
+- **Cross-process concurrency is provider-defined** — the seam serializes writes per namespace in-process only; concurrent processes converge by provider behavior (the local file provider read-modify-writes under a writer lock, so namespaces survive concurrent writers and same-namespace conflicts resolve last-write-wins).
+- **No secret-field redaction** — `describe()` returns resolved values verbatim; a wire surface (RPC/UI) must redact `role('secret')` fields before exposure.

packages/settings/settings/README.zh.md

@@ -0,0 +1,37 @@
+# @deepseek-ai/dsh-settings
+
+[English](README.md) | 中文
+
+抽象用户设置 seam（`ctx.settings`）。一个 provider 持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载 provider 时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
+
+## 服务 API
+
+- `register(ns, schema, { base?, applies? })` — 返回 owner 的 `SettingsScope`（`get`/`watch`/`update`）。注册是调用方插件 fiber 上的 effect：dispose 该 fiber 即移除 namespace 及其观察者。schema 拒绝的存量分节会使注册本身失败；重复 namespace 立即报错。
+- `describe()` — 每个 namespace 一条描述（`schema.toJSON()` 信封、解析值、`applies`），供配置界面使用。
+- `get(ns)` — 解析值；未注册时为 `undefined`。
+- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经 provider 持久化后提交。patch 必须是 JSON 形状的数据：Date、Map、BigInt、非有限数或循环引用会在任何内容持久化前带着以 `$` 为根的路径拒绝（YAML/JSON 存储在重载时会静默扭曲这类值）。校验失败在持久化前拒绝；只读 provider（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。
+- `replace(ns, section)` — 整体替换用户分节：merge 表达不了的删除/重置路径（`replace({})` 重新继承 `base` 与 schema 默认值）。
+- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐 listener 扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。
+- 服务卸载先拒绝新写入与观察者调用的启动，再排干全部排队写入与已启动的观察者调用后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不向任何人提交或通知。
+
+## Provider 契约
+
+子类实现 `writable`、`load()`、`persist(ns, section)`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。基类 service init 在服务可注入前加载并发布一次文档；自有 init（watcher、连接）的 provider 先经 `yield* super[Service.init]()` 委托。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。
+
+## 事件
+
+`settings/updated (ns, next, prev, source)` 在每次提交后触发；`source` 为 `update`（进程内写入）或 `provider`（外部变更）。解析值深相等时绝不触发。
+
+## Model Experience
+
+间接生效：消费插件从各自 namespace 解析影响模型的值（例如默认模型路由）；效果由各消费者自己的文档描述。
+
+#### KV Cache effect
+
+无直接失效；把设置值折叠进请求前缀的消费者拥有该变更。
+
+## Known Limitations and Deferred Work
+
+- **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；尚无 project/managed 分层或按值溯源。
+- **跨进程并发由 provider 定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按 provider 行为收敛（本地文件 provider 在写锁下读-改-写，因此 namespace 在并发写入者下不会丢失，同 namespace 冲突按后写胜出解决）。
+- **无 secret 字段脱敏** — `describe()` 原样返回解析值；wire 面（RPC/UI）在暴露前必须对 `role('secret')` 字段脱敏。

packages/settings/settings/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-settings",
+  "description": "Abstract user-settings seam (ctx.settings) for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7",
+    "schemastery": "^3.18.0"
+  }
+}

packages/settings/settings/src/index.ts

@@ -0,0 +1,549 @@
+/**
+ * User-settings seam (`ctx.settings`). Providers store one raw document of
+ * per-namespace sections; plugins register a namespace schema and read the
+ * resolved value, which layers schema defaults, the registrant's composition
+ * `base`, and the user document section, in that order.
+ * @module @deepseek-ai/dsh-settings
+ */
+
+import { Context, Service } from 'cordis'
+import type z from 'schemastery'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Nominal id of one registered settings namespace. */
+export type SettingsNamespace = Branded<'SettingsNamespace'>
+
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/
+
+/**
+ * Brand a raw string as a {@link SettingsNamespace}.
+ * @param value - candidate namespace; lowercase kebab-case, as in plugin short names.
+ * @returns the branded namespace.
+ */
+export function settingsNamespace(value: string): SettingsNamespace {
+  if (!NAMESPACE_PATTERN.test(value)) {
+    throw new TypeError(`settings namespace "${value}" must match ${String(NAMESPACE_PATTERN)}`)
+  }
+  return value as SettingsNamespace
+}
+
+/** When a namespace's changes take effect for its owner. */
+export type SettingsApplies = 'live' | 'restart'
+
+/** Origin of one committed settings change. */
+export type SettingsUpdateSource = 'update' | 'provider'
+
+/** Registration options beyond the namespace schema. */
+export interface SettingsRegisterOptions<T> {
+  /** Composition-layer values resolved below the user layer (entry-config subset). */
+  base?: Partial<T>
+  /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */
+  applies?: SettingsApplies
+}
+
+/** One registered namespace as surfaced to configuration UIs. */
+export interface SettingsDescriptor {
+  // TODO(settings-namespace-vocabulary): Rename `ns` to `namespace` across the
+  // public seam, provider contract, implementations, tests, and consumers.
+  /** The registered namespace. */
+  ns: SettingsNamespace
+  /** Serialized schemastery schema (`schema.toJSON()`). */
+  schema: unknown
+  /** Current resolved value. */
+  value: unknown
+  /** Owner's declared effect timing. */
+  applies: SettingsApplies
+}
+
+/** Owner-facing handle for one registered namespace. */
+export interface SettingsScope<T> {
+  /** Current resolved value: schema defaults, then `base`, then the user layer. */
+  get(): T
+  /**
+   * Observe committed changes to this namespace's resolved value. Invocations
+   * of one callback run asynchronously, one at a time, in commit order; a
+   * rejection is contained and logged like a sync throw. After the disposer
+   * returns, no further invocation starts — one already queued is skipped;
+   * one already started still settles, and service disposal waits for it.
+   * @param callback - invoked after each commit with the next and previous values.
+   * @returns the disposer removing this observer.
+   */
+  watch(callback: (next: T, prev: T) => void | Promise<void>): () => void
+  /**
+   * Merge a partial patch into this namespace's user layer and persist it.
+   * @param patch - plain-object patch over the user section; JSON-shaped data
+   * only (non-JSON values reject with their path before anything persists).
+   */
+  update(patch: object): Promise<void>
+  /**
+   * Replace this namespace's user section wholesale; absent keys re-inherit
+   * the composition `base` and schema defaults (`replace({})` resets all).
+   * @param section - the complete next user section; JSON-shaped data only,
+   * as for {@link update}.
+   */
+  replace(section: object): Promise<void>
+}
+
+declare module 'cordis' {
+  interface Context {
+    settings: Settings
+  }
+
+  interface Events {
+    /**
+     * Committed change to one registered namespace's resolved value. Emitted
+     * after the provider persisted (for `update`) or published (`provider`)
+     * the change; never emitted when the resolved value is deep-equal.
+     * Listener failures are contained and logged — a sync throw and an async
+     * rejection alike — except `INVARIANT`-coded failures, which rethrow
+     * after every listener ran; that rethrow reaches the emitter only from
+     * synchronous listeners, so invariant checks on this event must not be
+     * async functions.
+     * @param ns - the namespace whose resolved value changed.
+     * @param next - the new resolved value.
+     * @param prev - the previous resolved value.
+     * @param source - whether the change entered through `update()` or the provider.
+     * @mode emit
+     */
+    'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void
+  }
+}
+
+/**
+ * Deep equality over JSON-shaped data (objects, arrays, primitives) — the
+ * seam's single change-detection predicate, exported so the invariant
+ * companion checks exactly the implementation's relation.
+ * @param a - one JSON-shaped value.
+ * @param b - the other JSON-shaped value.
+ * @returns whether the two values are structurally equal.
+ */
+export function deepEqualJson(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false
+    return a.every((entry, index) => deepEqualJson(entry, b[index]))
+  }
+  const left = a as Record<string, unknown>
+  const right = b as Record<string, unknown>
+  const keys = Object.keys(left)
+  if (keys.length !== Object.keys(right).length) return false
+  return keys.every(key => key in right && deepEqualJson(left[key], right[key]))
+}
+
+/** Whether a value is a plain data object (not an array, null, or class instance). */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const proto: unknown = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+/** Human label for a value rejected by the JSON-shape boundary (numbers reject inline). */
+function describeRejected(value: unknown): string {
+  if (value === undefined) return 'undefined'
+  if (typeof value === 'object' && value !== null) {
+    const proto = Object.getPrototypeOf(value) as { constructor?: { name?: string } } | null
+    const name = proto?.constructor?.name
+    return name === undefined || name === 'Object' ? 'a non-plain object' : `a ${name}`
+  }
+  return `a ${typeof value}`
+}
+
+/**
+ * Detach one write input in a single walk that doubles as the durable-boundary
+ * shape check: only JSON data (plain objects, arrays, strings, finite numbers,
+ * booleans, `null`) may reach a provider document. `structuredClone` alone
+ * would admit Dates, Maps, BigInts, and cycles that YAML/JSON storage then
+ * silently distorts on the reload round-trip. `undefined` entries in objects
+ * are skipped — the same sparse-patch semantics as {@link mergeLayers} — while
+ * an `undefined` array entry is rejected rather than coerced.
+ * @param root - plain-object write input (caller-checked).
+ * @param reject - builds the boundary error from a value label and its `$`-rooted path.
+ * @returns the detached JSON-shaped clone.
+ */
+function cloneJsonShaped(
+  root: Record<string, unknown>,
+  reject: (label: string, path: string) => TypeError,
+): Record<string, unknown> {
+  const visiting = new WeakSet<object>()
+  const clone = (value: unknown, path: string): unknown => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return value
+    if (typeof value === 'number') {
+      if (!Number.isFinite(value)) throw reject('a non-finite number', path)
+      return value
+    }
+    if (Array.isArray(value)) {
+      if (visiting.has(value)) throw reject('a circular reference', path)
+      visiting.add(value)
+      const entries = value.map((entry, index) => clone(entry, `${path}[${index}]`))
+      // Un-mark on exit so one object referenced twice without a cycle passes.
+      visiting.delete(value)
+      return entries
+    }
+    if (isPlainObject(value)) {
+      if (visiting.has(value)) throw reject('a circular reference', path)
+      visiting.add(value)
+      // TODO(settings-json-properties): Use property-safe construction here and
+      // in mergeLayers so valid JSON keys such as "__proto__" remain own data.
+      const out: Record<string, unknown> = {}
+      for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined) continue
+        out[key] = clone(entry, `${path}.${key}`)
+      }
+      visiting.delete(value)
+      return out
+    }
+    throw reject(describeRejected(value), path)
+  }
+  return clone(root, '$') as Record<string, unknown>
+}
+
+/**
+ * Layer `over` onto `under`: plain objects merge recursively, every other
+ * value (arrays included) replaces the lower layer wholesale. `over` never
+ * carries `undefined` entries — sections come from parsed documents and write
+ * snapshots pass {@link cloneJsonShaped}, which strips them so a sparse patch
+ * cannot erase lower keys.
+ */
+function mergeLayers(under: unknown, over: unknown): unknown {
+  if (over === undefined) return under
+  if (!isPlainObject(under) || !isPlainObject(over)) return over
+  const merged: Record<string, unknown> = { ...under }
+  for (const [key, value] of Object.entries(over)) {
+    merged[key] = key in merged ? mergeLayers(merged[key], value) : value
+  }
+  return merged
+}
+
+/** Recursively freeze one resolved value so handed-out snapshots stay immutable. */
+function deepFreeze<T>(value: T): T {
+  if (typeof value !== 'object' || value === null || Object.isFrozen(value)) return value
+  for (const entry of Object.values(value)) deepFreeze(entry)
+  return Object.freeze(value)
+}
+
+/** One registered watcher and its serialized invocation chain. */
+interface SettingsWatcher {
+  callback: (next: never, prev: never) => void | Promise<void>
+  /** Settled tail: invocations of this callback run one at a time, in commit order. */
+  tail: Promise<void>
+  /** Cleared by the disposer: a queued invocation checks this before starting. */
+  active: boolean
+}
+
+/** One live namespace registration owned by a registrant fiber. */
+interface SettingsRegistration {
+  ns: SettingsNamespace
+  schema: z<unknown>
+  base: unknown
+  applies: SettingsApplies
+  resolved: unknown
+  watchers: Set<SettingsWatcher>
+}
+
+/**
+ * Abstract settings service. Providers implement raw-document storage
+ * (`load`/`persist`) and push external changes through {@link Settings.publish};
+ * the base class owns namespace registration, resolution, validation, change
+ * detection, and the `settings/updated` commit event.
+ */
+export abstract class Settings extends Service {
+  private readonly registrations = new Map<SettingsNamespace, SettingsRegistration>()
+  /** Latest published raw document; empty until the provider's first publish. */
+  private document: Record<string, unknown> = {}
+  /** Per-namespace write chains; settled tails, so a failure never poisons the queue. */
+  private readonly writeQueues = new Map<SettingsNamespace, Promise<unknown>>()
+  /** In-flight watcher invocation segments, drained by the dispose teardown. */
+  private readonly pendingTails = new Set<Promise<void>>()
+  /** Set at service dispose: refuse new writes while queued ones drain. */
+  private stopped = false
+
+  /** Opaque read of {@link stopped}: control flow cannot narrow it across awaits. */
+  private isStopped(): boolean {
+    return this.stopped
+  }
+
+  constructor(ctx: Context) {
+    super(ctx, 'settings')
+  }
+
+  /**
+   * Load the provider's document once and publish it before the service
+   * becomes injectable, and register the write-drain teardown. Providers with
+   * their own init (watchers, connections) delegate here first via
+   * `yield* super[Service.init]()`; their disposers then run before the drain.
+   */
+  async* [Service.init](): AsyncGenerator<() => Promise<void> | void, void, void> {
+    yield async () => {
+      // Teardown: refuse new writes and new watcher starts, then wait until
+      // every queued write chain and every started watcher invocation settles
+      // so disposal completes only once storage and observers are quiescent.
+      // Invocations queued but not yet started skip via the stopped check.
+      this.stopped = true
+      await Promise.allSettled([...this.writeQueues.values(), ...this.pendingTails])
+    }
+    this.publish(await this.load())
+  }
+
+  /** Whether {@link update} may persist through this provider. */
+  abstract readonly writable: boolean
+
+  /**
+   * Read the provider's current raw document (namespace to raw section).
+   * @returns the detached raw document.
+   */
+  protected abstract load(): Promise<Record<string, unknown>>
+
+  /**
+   * Durably store one namespace's merged user section.
+   * @param ns - the namespace being written.
+   * @param section - the complete merged user section to store.
+   */
+  protected abstract persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void>
+
+  /**
+   * Register a namespace schema and receive its owner scope. The registration
+   * is an effect on the calling plugin's fiber: disposing that fiber removes
+   * the namespace and its observers. An invalid stored section fails the
+   * registration itself — the earliest point where the schema can judge it.
+   * @param ns - unique namespace; duplicate registration fails loud.
+   * @param schema - schemastery schema resolving this namespace's value.
+   * @param options - composition `base` layer and effect timing.
+   * @returns the owner scope for reads, observation, and updates.
+   */
+  register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T> {
+    if (this.registrations.has(ns)) {
+      throw new Error(`settings namespace "${ns}" is already registered`)
+    }
+    const registration: SettingsRegistration = {
+      ns,
+      schema: schema as z<unknown>,
+      base: options?.base,
+      applies: options?.applies ?? 'live',
+      resolved: deepFreeze(this.resolve(schema, options?.base, this.section(ns))),
+      watchers: new Set(),
+    }
+    this.ctx.effect(() => {
+      this.registrations.set(ns, registration)
+      // TODO(settings-registration-quiescence): Deactivate every watcher and await
+      // its tail on disposal so callbacks cannot outlive the registrant fiber.
+      return () => this.registrations.delete(ns)
+    }, `settings.register(${JSON.stringify(String(ns))})`)
+    return {
+      get: () => registration.resolved as T,
+      watch: (callback) => {
+        const watcher: SettingsWatcher = { callback: callback, tail: Promise.resolve(), active: true }
+        registration.watchers.add(watcher)
+        return () => {
+          watcher.active = false
+          registration.watchers.delete(watcher)
+        }
+      },
+      update: patch => this.update(ns, patch),
+      replace: section => this.replace(ns, section),
+    }
+  }
+
+  /**
+   * Describe every registered namespace for configuration surfaces.
+   * @returns one descriptor per registered namespace, in registration order.
+   */
+  describe(): SettingsDescriptor[] {
+    return [...this.registrations.values()].map(registration => ({
+      ns: registration.ns,
+      schema: registration.schema.toJSON(),
+      value: registration.resolved,
+      applies: registration.applies,
+    }))
+  }
+
+  /**
+   * Read one registered namespace's resolved value.
+   * @param ns - the namespace to read.
+   * @returns the resolved value, or `undefined` while unregistered.
+   */
+  get(ns: SettingsNamespace): unknown {
+    return this.registrations.get(ns)?.resolved
+  }
+
+  /**
+   * Merge a patch into one registered namespace's user layer, validate the
+   * resolved candidate, persist through the provider, then commit and emit.
+   * A validation failure rejects before anything is persisted. Writes to one
+   * namespace are serialized: concurrent updates apply in call order, each
+   * merging over the previous write's committed section.
+   * @param ns - the registered namespace to update.
+   * @param patch - plain-object patch over the user section.
+   */
+  async update(ns: SettingsNamespace, patch: object): Promise<void> {
+    return this.write(ns, patch, 'merge')
+  }
+
+  /**
+   * Replace one registered namespace's user section wholesale, validate,
+   * persist, then commit and emit. Keys absent from `section` fall back to the
+   * composition `base` and schema defaults — this is the removal/reset path a
+   * merge-only patch cannot express (`replace({})` re-inherits everything).
+   * @param ns - the registered namespace to replace.
+   * @param section - the complete next user section.
+   */
+  async replace(ns: SettingsNamespace, section: object): Promise<void> {
+    return this.write(ns, section, 'replace')
+  }
+
+  /** Validate a write, then queue it on the namespace's serialized write chain. */
+  private write(ns: SettingsNamespace, input: object, mode: 'merge' | 'replace'): Promise<void> {
+    const verb = mode === 'merge' ? 'update' : 'replace'
+    const registration = this.registrations.get(ns)
+    if (registration === undefined) {
+      throw new Error(`settings namespace "${ns}" is not registered`)
+    }
+    if (this.isStopped()) {
+      throw new Error(`settings service is disposed: "${ns}" cannot be written`)
+    }
+    if (!this.writable) {
+      throw new Error(`settings provider is read-only: "${ns}" cannot be updated in-process`)
+    }
+    if (!isPlainObject(input)) {
+      throw new TypeError(`settings ${verb} for "${ns}" must be a plain object`)
+    }
+    // Snapshot at call time: the queue must never read a caller-owned object
+    // the caller may keep mutating while the write waits its turn. The same
+    // walk is the JSON-shape boundary check (see cloneJsonShaped).
+    const snapshot = cloneJsonShaped(input, (label, path) =>
+      new TypeError(`settings ${verb} for "${ns}" must be JSON-shaped data (found ${label} at ${path})`))
+    const previous = this.writeQueues.get(ns) ?? Promise.resolve()
+    // Chain past a failed predecessor: one rejected write must not poison the
+    // namespace queue for every later caller.
+    const run = previous.catch(() => undefined).then(async () => {
+      if (this.isStopped()) {
+        throw new Error(`settings service was disposed before the queued "${ns}" ${verb} ran`)
+      }
+      if (this.registrations.get(ns) !== registration) {
+        throw new Error(`settings namespace "${ns}" registration was disposed before the queued ${verb} ran`)
+      }
+      const section = mode === 'merge'
+        ? mergeLayers(this.section(ns) ?? {}, snapshot) as Record<string, unknown>
+        : snapshot
+      const next = deepFreeze(this.resolve(registration.schema, registration.base, section))
+      await this.persist(ns, section)
+      // The write reached storage either way; the cache must say so. Commit
+      // only when this registration is still the namespace owner — a fiber
+      // disposed (or replaced) mid-persist must not receive the notification.
+      this.document[ns] = section
+      // TODO(settings-replacement-resync): Re-resolve any replacement registration
+      // from this persisted section so an old in-flight write cannot leave it stale.
+      if (this.registrations.get(ns) === registration && !this.isStopped()) {
+        this.commit(registration, next, 'update')
+      }
+    })
+    this.writeQueues.set(ns, run)
+    return run
+  }
+
+  /**
+   * Provider hook: commit a complete raw document observed in storage. Each
+   * registered namespace re-resolves; an invalid section keeps that
+   * namespace's last good value and warns, other namespaces still commit.
+   * @param doc - the detached raw document (unregistered sections preserved).
+   * @param source - change origin; defaults to `provider`.
+   */
+  protected publish(doc: Record<string, unknown>, source: SettingsUpdateSource = 'provider'): void {
+    this.document = doc
+    for (const registration of this.registrations.values()) {
+      let next: unknown
+      try {
+        next = deepFreeze(this.resolve(registration.schema, registration.base, this.section(registration.ns)))
+      } catch (error) {
+        this.ctx.logger.warn('settings: keeping last good "%s" after invalid stored section', registration.ns)
+        this.ctx.logger.warn(error)
+        continue
+      }
+      this.commit(registration, next, source)
+    }
+  }
+
+  /** Read one namespace's raw user section, rejecting non-object sections. */
+  private section(ns: SettingsNamespace): Record<string, unknown> | undefined {
+    const section = this.document[ns]
+    if (section === undefined) return undefined
+    if (!isPlainObject(section)) {
+      throw new TypeError(`settings section "${ns}" must be an object of keys`)
+    }
+    return section
+  }
+
+  /** Resolve one namespace value: schema defaults, then `base`, then the user layer. */
+  private resolve<T>(schema: z<T>, base: unknown, section: Record<string, unknown> | undefined): T {
+    // The merged candidate is untyped by construction; the schema call is the
+    // runtime validation that admits it into T.
+    return schema(mergeLayers(base, section) as never)
+  }
+
+  /** Commit a resolved value when changed: swap, notify watchers, emit the event. */
+  private commit(registration: SettingsRegistration, next: unknown, source: SettingsUpdateSource): void {
+    const prev = registration.resolved
+    if (deepEqualJson(next, prev)) return
+    registration.resolved = next
+    for (const watcher of [...registration.watchers]) {
+      // Serialize per watcher: invocations of one callback run one at a time
+      // in commit order, so a slow stale invocation can never apply after a
+      // newer one. Sync throws and async rejections land in the same handler.
+      // The activity check runs when the queued invocation would start, so a
+      // disposer (or service stop) that ran while it waited prevents the
+      // start entirely; started invocations drain at service dispose.
+      const segment = watcher.tail
+        .then(() => {
+          if (!watcher.active || this.isStopped()) return
+          return watcher.callback(next as never, prev as never)
+        })
+        .then(() => undefined, (error: unknown) => {
+          this.warnWatcherFailure(registration.ns, error)
+        })
+      watcher.tail = segment
+      this.pendingTails.add(segment)
+      void segment.then(() => this.pendingTails.delete(segment))
+    }
+    // Fan the event out one listener at a time (the plain emit stops at the
+    // first throwing listener, starving the rest). Invariant violations are
+    // harness-fatal by design and rethrow after every listener ran; any other
+    // failure is contained so one broken observer cannot wedge the commit
+    // path (and, through it, a provider's reload loop).
+    let invariantFailure: unknown
+    const args = ['settings/updated', registration.ns, next, prev, source]
+    for (const listener of this.ctx.events.dispatch('emit', args) as Array<(...listenerArgs: unknown[]) => unknown>) {
+      try {
+        const returned = listener(registration.ns, next, prev, source)
+        if (returned != null && typeof (returned as PromiseLike<unknown>).then === 'function') {
+          // An emit listener may still be an async function; its rejection
+          // cannot reach the synchronous INVARIANT rethrow below, so it is
+          // contained here instead of becoming an unhandled rejection.
+          void Promise.resolve(returned as PromiseLike<unknown>).then(undefined, (error: unknown) => {
+            this.warnListenerFailure(registration.ns, error)
+          })
+        }
+      } catch (error) {
+        if ((error as { code?: unknown } | null)?.code === 'INVARIANT') {
+          invariantFailure ??= error
+          continue
+        }
+        this.warnListenerFailure(registration.ns, error)
+      }
+    }
+    if (invariantFailure !== undefined) throw invariantFailure as Error
+  }
+
+  /** Contained-watcher diagnostic shared by the sync and async failure paths. */
+  private warnWatcherFailure(ns: SettingsNamespace, error: unknown): void {
+    this.ctx.logger.warn('settings: watcher for "%s" failed', ns)
+    this.ctx.logger.warn(error)
+  }
+
+  /** Contained-listener diagnostic shared by the sync and async failure paths. */
+  private warnListenerFailure(ns: SettingsNamespace, error: unknown): void {
+    this.ctx.logger.warn('settings: a settings/updated listener for "%s" failed', ns)
+    this.ctx.logger.warn(error)
+  }
+}
+
+export default Settings

packages/settings/settings/src/invariant.ts

@@ -0,0 +1,48 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-settings`.
+ * @module @deepseek-ai/dsh-settings/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { deepEqualJson } from './index.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-settings'
+
+/** Cordis companion plugin name. */
+export const name = 'settings-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * Install the commit-event contract: `settings/updated` fires only for a
+ * currently registered namespace, only when the resolved value changed, and
+ * only with the service's authoritative resolved value — all judged with the
+ * seam's own equality predicate.
+ */
+const install: InvariantInstaller = (ctx: Context, fail: InvariantFailure) => {
+  ctx.on('settings/updated', (ns, next, prev) => {
+    const settings = ctx.get('settings')
+    if (settings === undefined) {
+      fail(`settings/updated for "${ns}" emitted without a live settings service`)
+    }
+    const current = settings.get(ns)
+    if (current === undefined) {
+      fail(`settings/updated for "${ns}" emitted while the namespace is unregistered`)
+    }
+    if (!deepEqualJson(current, next)) {
+      fail(`settings/updated for "${ns}" does not match the authoritative resolved value`)
+    }
+    if (deepEqualJson(next, prev)) {
+      fail(`settings/updated for "${ns}" emitted without a resolved-value change`)
+    }
+  })
+}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/settings/settings/tests/invariant.spec.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SettingsInvariant from '../src/invariant.ts'
+import { settingsNamespace } from '../src/index.ts'
+import { MemorySettings } from './memory.ts'
+
+async function setup(withProvider: boolean): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(InvariantService)
+  await ctx.plugin(SettingsInvariant)
+  if (withProvider) await ctx.plugin(MemorySettings)
+  return ctx
+}
+
+describe('settings invariants', () => {
+  it('fails a settings/updated emission without a live settings service', async () => {
+    const ctx = await setup(false)
+    expect(() => {
+      ctx.emit('settings/updated', settingsNamespace('ghost'), { a: 1 }, { a: 2 }, 'provider')
+    }).toThrow(/without a live settings service/)
+  })
+
+  it('fails a settings/updated emission for an unregistered namespace', async () => {
+    const ctx = await setup(true)
+    expect(() => {
+      ctx.emit('settings/updated', settingsNamespace('ghost'), { a: 1 }, { a: 2 }, 'provider')
+    }).toThrow(/unregistered/)
+  })
+
+  it('fails a settings/updated emission without a resolved-value change', async () => {
+    const ctx = await setup(true)
+    ctx.settings.register(settingsNamespace('ui-theme'), z.object({
+      theme: z.string().default('dark'),
+    }))
+    expect(() => {
+      ctx.emit('settings/updated', settingsNamespace('ui-theme'), { theme: 'dark' }, { theme: 'dark' }, 'update')
+    }).toThrow(/without a resolved-value change/)
+  })
+
+  it('fails a settings/updated emission whose value diverges from the authoritative state', async () => {
+    const ctx = await setup(true)
+    ctx.settings.register(settingsNamespace('ui-theme'), z.object({
+      theme: z.string().default('dark'),
+    }))
+    // Fabricated next ≠ the service's current resolved value ({theme: 'dark'}).
+    expect(() => {
+      ctx.emit('settings/updated', settingsNamespace('ui-theme'), { theme: 'forged' }, { theme: 'dark' }, 'update')
+    }).toThrow(/authoritative/)
+  })
+})

packages/settings/settings/tests/memory.ts

@@ -0,0 +1,54 @@
+/**
+ * In-memory settings provider fixture: the smallest real subclass of the seam,
+ * used by the base-class behavior suite in place of a file- or network-backed
+ * provider. Kept in `tests/` because production providers live in their own
+ * packages.
+ */
+
+import { Settings, type SettingsNamespace } from '../src/index.ts'
+
+/** In-memory provider exposing the protected seam hooks to tests. */
+export class MemorySettings extends Settings {
+  /** Raw document the provider "storage" currently holds. */
+  doc: Record<string, unknown>
+  /** Every persist() call observed, in order. */
+  persisted: Array<{ ns: SettingsNamespace; section: Record<string, unknown> }> = []
+  /** When false, update() must reject before reaching persist(). */
+  writableFlag: boolean
+
+  /** Artificial persist latency so tests can interleave concurrent updates. */
+  persistDelayMs: number
+
+  constructor(ctx: ConstructorParameters<typeof Settings>[0], options?: {
+    doc?: Record<string, unknown>
+    writable?: boolean
+    persistDelayMs?: number
+  }) {
+    super(ctx)
+    this.doc = structuredClone(options?.doc ?? {})
+    this.writableFlag = options?.writable ?? true
+    this.persistDelayMs = options?.persistDelayMs ?? 0
+  }
+
+  get writable(): boolean {
+    return this.writableFlag
+  }
+
+  protected load(): Promise<Record<string, unknown>> {
+    return Promise.resolve(structuredClone(this.doc))
+  }
+
+  protected async persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    if (this.persistDelayMs > 0) {
+      await new Promise(resolve => setTimeout(resolve, this.persistDelayMs))
+    }
+    this.persisted.push({ ns, section: structuredClone(section) })
+    this.doc[ns] = structuredClone(section)
+  }
+
+  /** Simulate an external storage change reaching the provider. */
+  pushExternal(doc: Record<string, unknown>): void {
+    this.doc = structuredClone(doc)
+    this.publish(structuredClone(doc))
+  }
+}

packages/settings/settings/tests/settings.spec.ts

@@ -0,0 +1,654 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import z from 'schemastery'
+import { Settings, deepEqualJson, settingsNamespace, type SettingsNamespace, type SettingsScope, type SettingsUpdateSource } from '../src/index.ts'
+import { MemorySettings } from './memory.ts'
+
+/** A provider implementing only the three primitives: the seam owns init. */
+class BareProvider extends Settings {
+  doc: Record<string, unknown>
+
+  constructor(ctx: ConstructorParameters<typeof Settings>[0], options?: { doc?: Record<string, unknown> }) {
+    super(ctx)
+    this.doc = structuredClone(options?.doc ?? {})
+  }
+
+  get writable(): boolean {
+    return true
+  }
+
+  protected load(): Promise<Record<string, unknown>> {
+    return Promise.resolve(structuredClone(this.doc))
+  }
+
+  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    this.doc[ns] = structuredClone(section)
+    return Promise.resolve()
+  }
+}
+
+interface ThemeConfig {
+  theme: 'dark' | 'light'
+  fontSize: number
+}
+
+const ThemeSchema: z<ThemeConfig> = z.object({
+  theme: z.union(['dark', 'light']).default('dark'),
+  fontSize: z.number().default(14),
+})
+
+interface NestedConfig {
+  retry: { attempts: number; delayMs: number }
+  tags: string[]
+}
+
+const NestedSchema: z<NestedConfig> = z.object({
+  retry: z.object({
+    attempts: z.number().default(2),
+    delayMs: z.number().default(100),
+  }),
+  tags: z.array(z.string()).default(['default']),
+})
+
+async function boot(options?: ConstructorParameters<typeof MemorySettings>[1]) {
+  const ctx = new Context()
+  const fiber = ctx.plugin(MemorySettings, options)
+  await fiber
+  const provider = ctx.get('settings') as MemorySettings
+  return { ctx, provider, fiber }
+}
+
+/** Record every settings/updated emission. */
+function recordUpdates(ctx: Context) {
+  const events: Array<{ ns: string; next: unknown; prev: unknown; source: SettingsUpdateSource }> = []
+  ctx.on('settings/updated', (ns, next, prev, source) => {
+    events.push({ ns, next, prev, source })
+  })
+  return events
+}
+
+describe('settingsNamespace', () => {
+  it('brands lowercase kebab-case names', () => {
+    expect(settingsNamespace('ui-theme')).toBe('ui-theme')
+  })
+
+  it.each(['', 'UI', '9lives', 'a_b', '-lead'])('rejects %j', (value) => {
+    expect(() => settingsNamespace(value)).toThrow(TypeError)
+  })
+})
+
+describe('registration', () => {
+  it('resolves schema defaults, then composition base, then the user layer', async () => {
+    const { ctx } = await boot({ doc: { 'ui-theme': { theme: 'light' } } })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, {
+      base: { fontSize: 16 },
+    })
+    // theme: user layer wins; fontSize: base wins over the schema default.
+    expect(scope.get()).toEqual({ theme: 'light', fontSize: 16 })
+  })
+
+  it('rejects a duplicate namespace loud', async () => {
+    const { ctx } = await boot()
+    ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(() => ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema))
+      .toThrow(/already registered/)
+  })
+
+  it('fails registration when the stored section is invalid for the schema', async () => {
+    const { ctx } = await boot({ doc: { 'ui-theme': { fontSize: 'big' } } })
+    expect(() => ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)).toThrow()
+  })
+
+  it('fails registration when the stored section is not an object', async () => {
+    const { ctx } = await boot({ doc: { 'ui-theme': 'dark' } })
+    expect(() => ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema))
+      .toThrow(/must be an object/)
+  })
+
+  it('describes registered namespaces with schema JSON, value, and applies', async () => {
+    const { ctx } = await boot()
+    ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    ctx.settings.register(settingsNamespace('workspace'), NestedSchema, { applies: 'restart' })
+    const descriptors = ctx.settings.describe()
+    expect(descriptors.map(entry => [entry.ns, entry.applies])).toEqual([
+      ['ui-theme', 'live'],
+      ['workspace', 'restart'],
+    ])
+    expect(descriptors[0]!.value).toEqual({ theme: 'dark', fontSize: 14 })
+    // schemastery's canonical wire form: a { uid, refs } envelope whose root ref
+    // is the object schema — the shape schema-driven form UIs reconstruct from.
+    const serialized = descriptors[0]!.schema as { uid: number; refs: Record<string, { type: string }> }
+    expect(serialized.refs[String(serialized.uid)]?.type).toBe('object')
+  })
+
+  it('reads undefined for an unregistered namespace', async () => {
+    const { ctx } = await boot()
+    expect(ctx.settings.get(settingsNamespace('missing'))).toBeUndefined()
+  })
+
+  it('hands out frozen resolved values', async () => {
+    const { ctx } = await boot({ doc: { workspace: { retry: { attempts: 5 } } } })
+    const scope = ctx.settings.register(settingsNamespace('workspace'), NestedSchema)
+    const value = scope.get()
+    expect(Object.isFrozen(value)).toBe(true)
+    expect(Object.isFrozen(value.retry)).toBe(true)
+    expect(() => { (value.retry as { attempts: number }).attempts = 0 }).toThrow(TypeError)
+  })
+
+  it('removes the namespace and its observers when the registrant fiber disposes', async () => {
+    const { ctx, provider } = await boot()
+    const seen: unknown[] = []
+    let scope: SettingsScope<ThemeConfig> | undefined
+    const fiber = ctx.plugin({
+      inject: ['settings'],
+      apply: (child: Context) => {
+        scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+        scope.watch((next) => { seen.push(next) })
+      },
+    })
+    await fiber
+    expect(ctx.settings.get(settingsNamespace('ui-theme'))).toEqual({ theme: 'dark', fontSize: 14 })
+
+    await fiber.dispose()
+    expect(ctx.settings.get(settingsNamespace('ui-theme'))).toBeUndefined()
+    expect(ctx.settings.describe()).toEqual([])
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    expect(seen).toEqual([])
+
+    // The namespace is free again, and re-registration resolves the user layer
+    // that kept living in storage while nobody owned the namespace.
+    const again = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(again.get()).toEqual({ theme: 'light', fontSize: 14 })
+  })
+})
+
+describe('update', () => {
+  it('persists the merged user section without baking in the base layer', async () => {
+    const { ctx, provider } = await boot({ doc: { 'ui-theme': { theme: 'light' } } })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, {
+      base: { fontSize: 16 },
+    })
+    await scope.update({ theme: 'dark' })
+    expect(provider.persisted).toEqual([
+      { ns: 'ui-theme', section: { theme: 'dark' } },
+    ])
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 16 })
+  })
+
+  it('deep-merges nested objects and replaces arrays wholesale', async () => {
+    const { ctx, provider } = await boot({
+      doc: { workspace: { retry: { attempts: 5, delayMs: 300 }, tags: ['a', 'b'] } },
+    })
+    const scope = ctx.settings.register(settingsNamespace('workspace'), NestedSchema)
+    await scope.update({ retry: { attempts: 7 }, tags: ['c'] })
+    expect(provider.persisted[0]!.section).toEqual({
+      retry: { attempts: 7, delayMs: 300 },
+      tags: ['c'],
+    })
+    expect(scope.get()).toEqual({ retry: { attempts: 7, delayMs: 300 }, tags: ['c'] })
+  })
+
+  it('commits, notifies watchers, and emits with source update', async () => {
+    const { ctx } = await boot()
+    const events = recordUpdates(ctx)
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const watcher = vi.fn()
+    scope.watch(watcher)
+    await scope.update({ theme: 'light' })
+    expect(watcher).toHaveBeenCalledWith(
+      { theme: 'light', fontSize: 14 },
+      { theme: 'dark', fontSize: 14 },
+    )
+    expect(events).toEqual([{
+      ns: 'ui-theme',
+      next: { theme: 'light', fontSize: 14 },
+      prev: { theme: 'dark', fontSize: 14 },
+      source: 'update',
+    }])
+  })
+
+  it('rejects an invalid patch before persisting anything', async () => {
+    const { ctx, provider } = await boot()
+    const events = recordUpdates(ctx)
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await expect(scope.update({ fontSize: 'big' })).rejects.toThrow()
+    expect(provider.persisted).toEqual([])
+    expect(events).toEqual([])
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 })
+    // The failed write must not poison the namespace queue for later writers.
+    await scope.update({ fontSize: 18 })
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 18 })
+  })
+
+  it('ignores explicit undefined entries so a sparse patch cannot erase keys', async () => {
+    const { ctx, provider } = await boot({ doc: { 'ui-theme': { theme: 'light' } } })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await scope.update({ theme: undefined, fontSize: 18 })
+    expect(provider.persisted[0]!.section).toEqual({ theme: 'light', fontSize: 18 })
+    expect(scope.get()).toEqual({ theme: 'light', fontSize: 18 })
+  })
+
+  it('rejects a non-object patch', async () => {
+    const { ctx } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await expect(scope.update([1])).rejects.toThrow(TypeError)
+    await expect(scope.update(new Date() as unknown as object)).rejects.toThrow(TypeError)
+    await expect(scope.replace([1])).rejects.toThrow(/replace for "ui-theme"/)
+  })
+
+  it('accepts a null-prototype patch object', async () => {
+    const { ctx } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const patch: { fontSize?: number } = Object.create(null) as { fontSize?: number }
+    patch.fontSize = 18
+    await scope.update(patch)
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 18 })
+  })
+
+  it('rejects an unregistered namespace', async () => {
+    const { ctx } = await boot()
+    await expect(ctx.settings.update(settingsNamespace('missing'), {}))
+      .rejects.toThrow(/not registered/)
+  })
+
+  it('rejects on a read-only provider before reaching persist', async () => {
+    const { ctx, provider } = await boot({ writable: false })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await expect(scope.update({ theme: 'light' })).rejects.toThrow(/read-only/)
+    expect(provider.persisted).toEqual([])
+  })
+})
+
+describe('deepEqualJson', () => {
+  it.each([
+    [{ a: [1, 2] }, { a: [1, 2] }, true],
+    [{ a: [1, 2] }, { a: [1] }, false],
+    [{ a: [1] }, { a: { 0: 1 } }, false],
+    [{ a: 1 }, { b: 1 }, false],
+    [{ a: 1 }, {}, false],
+    [{ a: null }, { a: null }, true],
+    [{ a: null }, { a: {} }, false],
+  ])('compares %j vs %j as %s', (a, b, equal) => {
+    expect(deepEqualJson(a, b)).toBe(equal)
+  })
+})
+
+describe('review regressions', () => {
+  it('propagates an invariant-coded listener failure instead of containing it', async () => {
+    const { ctx, provider } = await boot()
+    ctx.on('settings/updated', () => {
+      throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' })
+    })
+    ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(() => { provider.pushExternal({ 'ui-theme': { theme: 'light' } }) })
+      .toThrow(/forged relation/)
+  })
+
+  it('serializes concurrent updates so neither patch is lost', async () => {
+    const { ctx, provider } = await boot({ persistDelayMs: 10 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await Promise.all([
+      scope.update({ theme: 'light' }),
+      scope.update({ fontSize: 20 }),
+    ])
+    expect(provider.doc['ui-theme']).toEqual({ theme: 'light', fontSize: 20 })
+    expect(scope.get()).toEqual({ theme: 'light', fontSize: 20 })
+  })
+
+  it('contains a throwing settings/updated listener and keeps later commits alive', async () => {
+    const { ctx, provider } = await boot()
+    ctx.on('settings/updated', () => {
+      throw new Error('listener boom')
+    })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(() => { provider.pushExternal({ 'ui-theme': { theme: 'light' } }) }).not.toThrow()
+    expect(scope.get().theme).toBe('light')
+    provider.pushExternal({ 'ui-theme': { theme: 'dark' } })
+    expect(scope.get().theme).toBe('dark')
+  })
+
+  it('contains an async watcher rejection', async () => {
+    const { ctx, provider } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    scope.watch(async () => {
+      throw new Error('async watcher boom')
+    })
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    expect(scope.get().theme).toBe('light')
+    // Give the rejected watcher promise a microtask turn; containment means
+    // vitest observes no unhandled rejection out of this test.
+    await new Promise(resolve => setTimeout(resolve, 10))
+  })
+
+  it('loads the provider document through the base init without provider boilerplate', async () => {
+    const ctx = new Context()
+    await ctx.plugin(BareProvider, { doc: { 'ui-theme': { fontSize: 7 } } })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 7 })
+  })
+
+  it('replaces the user section wholesale so overrides can be removed', async () => {
+    const { ctx, provider } = await boot({ doc: { 'ui-theme': { theme: 'light', fontSize: 20 } } })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema, {
+      base: { fontSize: 16 },
+    })
+    await scope.replace({ theme: 'light' })
+    // fontSize override is gone: resolution falls back to the base layer.
+    expect(scope.get()).toEqual({ theme: 'light', fontSize: 16 })
+    expect(provider.doc['ui-theme']).toEqual({ theme: 'light' })
+    await scope.replace({})
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 16 })
+    expect(provider.doc['ui-theme']).toEqual({})
+  })
+})
+
+describe('second review regressions', () => {
+  it('runs every settings/updated listener even when an earlier one throws', async () => {
+    const { ctx, provider } = await boot()
+    ctx.on('settings/updated', () => {
+      throw new Error('first listener boom')
+    })
+    const second = vi.fn()
+    ctx.on('settings/updated', second)
+    ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    expect(second).toHaveBeenCalledTimes(1)
+  })
+
+  it('rejects an update queued after the registrant fiber disposed', async () => {
+    const { ctx } = await boot()
+    let scope: SettingsScope<ThemeConfig> | undefined
+    const fiber = ctx.plugin({
+      inject: ['settings'],
+      apply: (child: Context) => {
+        scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+      },
+    })
+    await fiber
+    await fiber.dispose()
+    await expect(scope!.update({ theme: 'light' })).rejects.toThrow(/disposed|not registered/)
+  })
+
+  it('does not notify a registrant disposed while its update was in flight', async () => {
+    const { ctx, provider } = await boot({ persistDelayMs: 30 })
+    const events = recordUpdates(ctx)
+    let scope: SettingsScope<ThemeConfig> | undefined
+    const watcher = vi.fn()
+    const fiber = ctx.plugin({
+      inject: ['settings'],
+      apply: (child: Context) => {
+        scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+        scope.watch(watcher)
+      },
+    })
+    await fiber
+    const pending = scope!.update({ theme: 'light' })
+    await new Promise(resolve => setTimeout(resolve, 5))
+    await fiber.dispose()
+    await pending.catch(() => undefined)
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(watcher).not.toHaveBeenCalled()
+    expect(events).toEqual([])
+    // The persist was already in flight, so storage keeps the write — but no
+    // commit reached the disposed registration.
+    expect(provider.doc['ui-theme']).toEqual({ theme: 'light' })
+  })
+
+  it('drains in-flight writes at service dispose and rejects later ones', async () => {
+    const { ctx, provider, fiber } = await boot({ persistDelayMs: 20 })
+    const service = ctx.settings
+    const scope = service.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const pending = scope.update({ theme: 'light' })
+    await new Promise(resolve => setTimeout(resolve, 5))
+    await fiber.dispose()
+    // The teardown drained the in-flight write before completing…
+    await pending.catch(() => undefined)
+    const persistedAtDispose = provider.persisted.length
+    expect(persistedAtDispose).toBe(1)
+    // …and afterwards nothing writes and new writes reject.
+    await expect(service.update(settingsNamespace('ui-theme'), { theme: 'dark' }))
+      .rejects.toThrow(/disposed|not registered/)
+    await new Promise(resolve => setTimeout(resolve, 40))
+    expect(provider.persisted.length).toBe(persistedAtDispose)
+  })
+
+  it('serializes invocations of one async watcher in commit order', async () => {
+    const { ctx, provider } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const applied: number[] = []
+    let firstCall = true
+    scope.watch(async (next) => {
+      // The first (stale) invocation is slow; unserialised it would finish
+      // last and clobber the newer applied state.
+      const delay = firstCall ? 30 : 0
+      firstCall = false
+      await new Promise(resolve => setTimeout(resolve, delay))
+      applied.push(next.fontSize)
+    })
+    provider.pushExternal({ 'ui-theme': { fontSize: 1 } })
+    provider.pushExternal({ 'ui-theme': { fontSize: 2 } })
+    await vi.waitFor(() => {
+      expect(applied).toHaveLength(2)
+    })
+    expect(applied).toEqual([1, 2])
+  })
+
+  it('rejects a function value as not JSON-shaped', async () => {
+    const { ctx } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    await expect(scope.update({ theme: () => 'dark' }))
+      .rejects.toThrow(/JSON-shaped.*function at \$\.theme/)
+  })
+
+  it('rejects a write still queued when the service disposes', async () => {
+    const { ctx, fiber } = await boot({ persistDelayMs: 20 })
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const first = scope.update({ theme: 'light' })
+    const second = scope.update({ fontSize: 20 })
+    await new Promise(resolve => setTimeout(resolve, 5))
+    await fiber.dispose()
+    await first
+    await expect(second).rejects.toThrow(/disposed before the queued/)
+  })
+
+  it('rejects a write still queued when the registrant disposes', async () => {
+    const { ctx } = await boot({ persistDelayMs: 20 })
+    let scope: SettingsScope<ThemeConfig> | undefined
+    const fiber = ctx.plugin({
+      inject: ['settings'],
+      apply: (child: Context) => {
+        scope = child.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+      },
+    })
+    await fiber
+    const first = scope!.update({ theme: 'light' })
+    const second = scope!.update({ fontSize: 20 })
+    await new Promise(resolve => setTimeout(resolve, 5))
+    await fiber.dispose()
+    await first
+    await expect(second).rejects.toThrow(/registration was disposed before the queued/)
+  })
+
+  it('snapshots the patch at call time so caller mutation cannot leak in', async () => {
+    const { ctx } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const patch = { fontSize: 18 }
+    const pending = scope.update(patch)
+    patch.fontSize = 99
+    await pending
+    expect(scope.get().fontSize).toBe(18)
+  })
+})
+
+describe('publish', () => {
+  it('notifies watchers of an external change with source provider', async () => {
+    const { ctx, provider } = await boot()
+    const events = recordUpdates(ctx)
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const watcher = vi.fn()
+    scope.watch(watcher)
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    await vi.waitFor(() => {
+      expect(watcher).toHaveBeenCalledWith(
+        { theme: 'light', fontSize: 14 },
+        { theme: 'dark', fontSize: 14 },
+      )
+    })
+    expect(events[0]!.source).toBe('provider')
+  })
+
+  it('stays silent when the resolved value is deep-equal', async () => {
+    const { ctx, provider } = await boot({ doc: { 'ui-theme': { theme: 'light' } } })
+    const events = recordUpdates(ctx)
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const watcher = vi.fn()
+    scope.watch(watcher)
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    expect(watcher).not.toHaveBeenCalled()
+    expect(events).toEqual([])
+  })
+
+  it('keeps the last good value for an invalid section while other namespaces commit', async () => {
+    const { ctx, provider } = await boot()
+    const events = recordUpdates(ctx)
+    const theme = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const workspace = ctx.settings.register(settingsNamespace('workspace'), NestedSchema)
+    provider.pushExternal({
+      'ui-theme': { fontSize: 'broken' },
+      workspace: { retry: { attempts: 9 } },
+    })
+    expect(theme.get()).toEqual({ theme: 'dark', fontSize: 14 })
+    expect(workspace.get()).toEqual({ retry: { attempts: 9, delayMs: 100 }, tags: ['default'] })
+    expect(events.map(event => event.ns)).toEqual(['workspace'])
+  })
+
+  it('recovers from a bad section once storage turns valid again', async () => {
+    const { ctx, provider } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    provider.pushExternal({ 'ui-theme': { fontSize: 'broken' } })
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 14 })
+    provider.pushExternal({ 'ui-theme': { fontSize: 18 } })
+    expect(scope.get()).toEqual({ theme: 'dark', fontSize: 18 })
+  })
+})
+
+describe('third review regressions', () => {
+  it('skips a queued watch invocation whose disposer ran before it started', async () => {
+    const { ctx, provider } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const watcher = vi.fn()
+    const dispose = scope.watch(watcher)
+    // The commit chains the invocation as a microtask; the disposer runs in
+    // the same synchronous frame, before that invocation could start.
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    dispose()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(watcher).not.toHaveBeenCalled()
+  })
+
+  it('waits for an in-flight watch invocation at service dispose', async () => {
+    const { ctx, provider, fiber } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    let release: (() => void) | undefined
+    let finished = false
+    scope.watch(async () => {
+      await new Promise<void>((resolve) => { release = resolve })
+      finished = true
+    })
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    await vi.waitFor(() => { expect(release).toBeDefined() })
+    let disposed = false
+    const disposal = fiber.dispose().then(() => { disposed = true })
+    await new Promise(resolve => setTimeout(resolve, 15))
+    expect(disposed).toBe(false)
+    release!()
+    await disposal
+    expect(finished).toBe(true)
+  })
+
+  it('rejects a Date at its path before anything persists', async () => {
+    const { ctx, provider } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), z.object({ value: z.any() }))
+    await expect(scope.update({ value: { at: new Date(0) } }))
+      .rejects.toThrow(/JSON-shaped.*Date at \$\.value\.at/)
+    expect(provider.persisted).toEqual([])
+  })
+
+  it.each([
+    ['a Map', { value: new Map() }, /Map at \$\.value/],
+    ['a bigint', { value: [10n] }, /bigint at \$\.value\[0\]/],
+    ['a symbol', { value: Symbol('x') }, /symbol at \$\.value/],
+    ['a non-finite number', { value: Number.NaN }, /non-finite number at \$\.value/],
+    ['an undefined array entry', { value: [undefined] }, /undefined at \$\.value\[0\]/],
+    ['a class instance', { value: Object.create({ marker: true }) as object }, /non-plain object at \$\.value/],
+  ])('rejects %s that structuredClone would admit', async (_label, patch, message) => {
+    const { ctx } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), z.object({ value: z.any() }))
+    await expect(scope.update(patch)).rejects.toThrow(message)
+  })
+
+  it('rejects a circular patch instead of storing an alias-looped document', async () => {
+    const { ctx } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), z.object({ value: z.any() }))
+    const cyclic: Record<string, unknown> = {}
+    cyclic['self'] = cyclic
+    await expect(scope.update({ value: cyclic })).rejects.toThrow(/circular reference at \$\.value\.self/)
+    const loop: unknown[] = []
+    loop.push(loop)
+    await expect(scope.update({ value: loop })).rejects.toThrow(/circular reference at \$\.value\[0\]/)
+  })
+
+  it('accepts one object referenced twice without a cycle', async () => {
+    const { ctx } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), z.object({ value: z.any() }))
+    const shared = { leaf: 1 }
+    await scope.update({ value: { left: shared, right: shared } })
+    expect(scope.get()).toEqual({ value: { left: { leaf: 1 }, right: { leaf: 1 } } })
+  })
+
+  it('contains an async settings/updated listener rejection and keeps other listeners running', async () => {
+    const { ctx, provider } = await boot()
+    // An async listener violates the event's synchronous signature, but an
+    // unlinted JS plugin can still register one. Declaring the return as
+    // unknown keeps this file's typed surface legal (unknown-returning
+    // functions are assignable to void positions) while the runtime value is
+    // still the rejected promise the containment guard must handle.
+    const boom = (): unknown => Promise.reject(new Error('async listener boom'))
+    ctx.on('settings/updated', boom)
+    const second = vi.fn()
+    ctx.on('settings/updated', second)
+    ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    expect(second).toHaveBeenCalledTimes(1)
+    // Containment gives the rejection a handler; vitest observes no unhandled
+    // rejection out of this test.
+    await new Promise(resolve => setTimeout(resolve, 10))
+  })
+})
+
+describe('watch', () => {
+  it('stops after its disposer runs', async () => {
+    const { ctx, provider } = await boot()
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    const watcher = vi.fn()
+    const dispose = scope.watch(watcher)
+    dispose()
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    expect(watcher).not.toHaveBeenCalled()
+  })
+
+  it('contains a throwing watcher without blocking the commit or other watchers', async () => {
+    const { ctx, provider } = await boot()
+    const events = recordUpdates(ctx)
+    const scope = ctx.settings.register(settingsNamespace('ui-theme'), ThemeSchema)
+    scope.watch(() => { throw new Error('watcher boom') })
+    const second = vi.fn()
+    scope.watch(second)
+    provider.pushExternal({ 'ui-theme': { theme: 'light' } })
+    await vi.waitFor(() => {
+      expect(second).toHaveBeenCalledTimes(1)
+    })
+    expect(events).toHaveLength(1)
+    expect(scope.get()).toEqual({ theme: 'light', fontSize: 14 })
+  })
+})

packages/settings/settings/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/todo/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/todo/README.md
-README.md: 1e5ae9a1583b9e9d3913fcd1dca7ef11a5f391fe
-README.zh.md: a77f788a41353ea547059864dc7cf73ac5025219
+README.md: e16d1a3ff413d13d47f9b08a3cfddfedb76b5254
+README.zh.md: e3307d4f0acdb3f50db3f1e010286ad11668906a

packages/todo/README.md

@@ -8,4 +8,4 @@ The model-facing todo tool. A single **product** package — there is no interfa
 |---|---|---|
 | `tool-todo/` | Model-facing `todo_write` tool; writes the whole list to the session log (`todo/write`) | (registers on `ctx.tools`) |
 
-The list lives on the event-sourced session log (`SessionEventMap['todo/write']`, owned by [`dsh-session`](../core/session)); this package is the thin consumer that appends the snapshot. UIs such as the [TUI app](../examples/tui-demo) and the host/client runtime render the durable list from session events.
+The list lives on the event-sourced session log (`SessionEventMap['todo/write']`, owned by [`dsh-session`](../core/session)); this package is the thin consumer that appends the snapshot. UIs such as the [TUI app](../ui/tui) and the host/client runtime render the durable list from session events.

packages/todo/README.zh.md

@@ -8,4 +8,4 @@
 |---|---|---|
 | `tool-todo/` | 面向模型的 `todo_write` 工具；将完整列表写入会话日志（`todo/write`） | （注册到 `ctx.tools`） |
 
-列表存在于事件溯源会话日志中（`SessionEventMap['todo/write']`，由 [`dsh-session`](../core/session) 拥有）；本包是追加快照的轻量消费方。[TUI 应用](../examples/tui-demo)等 UI 以及宿主／客户端运行时会根据会话事件渲染该持久化列表。
+列表存在于事件溯源会话日志中（`SessionEventMap['todo/write']`，由 [`dsh-session`](../core/session) 拥有）；本包是追加快照的轻量消费方。[TUI 应用](../ui/tui)等 UI 以及宿主／客户端运行时会根据会话事件渲染该持久化列表。

packages/todo/tool-todo/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/todo/tool-todo/README.md
-README.md: b05ef43e7137dcf5678b1f1ad6d8c00b8a43baef
-README.zh.md: 88a9f5d69ff52dcedbd8f27a4ace5fde3e0dc5a2
+README.md: 91f4bc6abd0c08f44f0a0a50393e4cdd5ddada70
+README.zh.md: b9582307ff5590bf34be91b776fa06841a68b41d

packages/todo/tool-todo/README.md

@@ -20,7 +20,7 @@ Beyond the schema's type/required/enum checks, `execute` rejects an empty or dup
 
 ## Rendering
 
-The canonical result is `{ todos, counts: { pending, inProgress, completed } }`; its Native renderer returns the compact update acknowledgement. The tool also writes the full `todo/write` session event. UIs subscribe to the event stream and render that durable list themselves: the [TUI app](../../examples/tui-demo) and the [web client](../../client/ui-conversation) show a plan strip (plus a dedicated web tool row) off the standing plan — latest `todo/write` with no later `turn/start` ([display](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.md), [lifetime](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)).
+The canonical result is `{ todos, counts: { pending, inProgress, completed } }`; its Native renderer returns the compact update acknowledgement. The tool also writes the full `todo/write` session event. UIs subscribe to the event stream and render that durable list themselves: the [TUI app](../../ui/tui) and the [web client](../../client/ui-conversation) show a plan strip (plus a dedicated web tool row) off the standing plan — latest `todo/write` with no later `turn/start` ([display](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.md), [lifetime](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)).
 
 ## Session projection
 

packages/todo/tool-todo/README.zh.md

@@ -20,7 +20,7 @@
 
 ## 渲染
 
-规范结果为 `{ todos, counts: { pending, inProgress, completed } }`；其 Native 渲染器返回精简的更新确认。工具还会写入完整 `todo/write` 会话事件。UI 订阅事件流，并自行渲染该持久化列表：[TUI 应用](../../examples/tui-demo)与 [web 客户端](../../client/ui-conversation)基于当前有效计划（其后没有更晚 `turn/start` 的最近一次 `todo/write`）显示计划条（web 另有专属工具行）（[展示](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.md)、[生命周期](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)）。
+规范结果为 `{ todos, counts: { pending, inProgress, completed } }`；其 Native 渲染器返回精简的更新确认。工具还会写入完整 `todo/write` 会话事件。UI 订阅事件流，并自行渲染该持久化列表：[TUI 应用](../../ui/tui)与 [web 客户端](../../client/ui-conversation)基于当前有效计划（其后没有更晚 `turn/start` 的最近一次 `todo/write`）显示计划条（web 另有专属工具行）（[展示](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.md)、[生命周期](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)）。
 
 ## 会话投影
 

packages/typert/generator/src/analyzer.ts

@@ -69,6 +69,8 @@ export interface WorkspaceAnalyzerOptions {
   readonly checkDiagnostics?: boolean
   /** Whether missing annotations fail or are written before a clean re-analysis. */
   readonly mode?: AnalysisMode
+  /** Shared workspace memo; supply one instance to reuse parses across analyzers. */
+  readonly caches?: WorkspaceCaches
 }
 
 /** One package face whose public export graph contains Typert business declarations. */
@@ -78,17 +80,27 @@ export interface DiscoveredTypertPackage {
   readonly faces: readonly TypertFace[]
 }
 
-interface ParsedConfig {
+/** One parsed tsconfig, memoizable per workspace snapshot. */
+export interface ParsedConfig {
+  /** Absolute config path. */
   readonly path: string
+  /** The TypeScript parse result. */
   readonly parsed: ts.ParsedCommandLine
 }
 
-interface PackageRegistration {
+/** One package face registration discovered from an aggregate tsconfig. */
+export interface PackageRegistration {
+  /** The face whose aggregate references this package project. */
   readonly face: TypertFace
+  /** The package manifest name. */
   readonly name: string
+  /** Real package root directory. */
   readonly root: string
+  /** The package's own parsed tsconfig. */
   readonly config: ParsedConfig
+  /** The parsed package.json content. */
   readonly manifest: Record<string, unknown>
+  /** Export subpaths owned by this face for dual-face packages. */
   readonly exportSubpaths?: readonly string[]
 }
 
@@ -114,6 +126,90 @@ type ReferenceSite = ts.TypeReferenceNode | ts.ExpressionWithTypeArguments | ts.
 
 const EMPTY_DOCUMENTATION: DocumentationModel = { tags: [] }
 
+interface FaceProgramHost {
+  readonly host: ts.CompilerHost
+  readonly files: Map<string, ts.SourceFile | undefined>
+}
+
+/**
+ * Shared memo over one immutable workspace snapshot. Passing one instance to
+ * several analyzers (the batched and write-mode children reuse their parent's
+ * automatically) reuses parsed tsconfigs, the registration inventory, and
+ * per-face compiler hosts whose parsed and bound source files and module
+ * resolutions carry across programs. Callers that mutate workspace files
+ * between analyses must start from a fresh instance; write-mode source edits
+ * invalidate themselves through {@link invalidate}.
+ */
+export class WorkspaceCaches {
+  /** Parsed tsconfig files by absolute config path. */
+  readonly configs = new Map<string, ParsedConfig>()
+  /** Registration inventories keyed by root and aggregate config paths. */
+  readonly registrations = new Map<string, PackageRegistration[]>()
+  private readonly hosts = new Map<TypertFace, FaceProgramHost>()
+
+  /**
+   * Parse one tsconfig once per workspace snapshot.
+   * @param path - absolute config path.
+   * @returns the memoized parse result.
+   */
+  config(path: string): ParsedConfig {
+    let parsed = this.configs.get(path)
+    if (parsed === undefined) {
+      parsed = parseConfig(path)
+      this.configs.set(path, parsed)
+    }
+    return parsed
+  }
+
+  /**
+   * Return the shared compiler host for one face. Every program of one face
+   * is built from the same aggregate compiler options (the first call wins),
+   * so parsed source files, binder state, and module resolutions are safe to
+   * reuse across the face's batched programs.
+   * @param face - the face whose programs share this host.
+   * @param options - the face's effective compiler options.
+   * @returns a compiler host with source-file and module-resolution caches.
+   */
+  programHost(face: TypertFace, options: ts.CompilerOptions): ts.CompilerHost {
+    let entry = this.hosts.get(face)
+    if (entry === undefined) {
+      const host = ts.createCompilerHost(options)
+      const files = new Map<string, ts.SourceFile | undefined>()
+      const resolutionCache = ts.createModuleResolutionCache(
+        host.getCurrentDirectory(),
+        fileName => host.getCanonicalFileName(fileName),
+        options,
+      )
+      const base = host.getSourceFile.bind(host)
+      // The snapshot contract makes shouldCreateNewSourceFile irrelevant: it
+      // only fires under oldProgram reuse, which these fresh programs never
+      // request, and invalidate() is the one supported re-read path.
+      host.getSourceFile = (fileName, languageVersionOrOptions, onError) => {
+        if (!files.has(fileName)) files.set(fileName, base(fileName, languageVersionOrOptions, onError))
+        return files.get(fileName)
+      }
+      host.getModuleResolutionCache = () => resolutionCache
+      entry = { host, files }
+      this.hosts.set(face, entry)
+    }
+    return entry.host
+  }
+
+  /**
+   * Drop cached parses of one edited source file so the next analysis reads
+   * the written content.
+   * @param file - path of the edited file.
+   */
+  invalidate(file: string): void {
+    const target = realPath(file)
+    for (const { files } of this.hosts.values()) {
+      for (const key of [...files.keys()]) {
+        if (realPath(key) === target) files.delete(key)
+      }
+    }
+  }
+}
+
 /** Analyze host and client as independent TypeScript programs. */
 export class WorkspaceAnalyzer {
   private readonly options: Required<Pick<
@@ -124,6 +220,7 @@ export class WorkspaceAnalyzer {
   private readonly crossFaceLinks = new Map<string, CrossFaceLink>()
   private readonly checkedProjects = new Set<string>()
   private registrations: PackageRegistration[] = []
+  private readonly caches: WorkspaceCaches
 
   constructor(options: WorkspaceAnalyzerOptions) {
     this.options = {
@@ -135,6 +232,7 @@ export class WorkspaceAnalyzer {
       mode: options.mode ?? 'check',
       ...(options.packages === undefined ? {} : { packages: options.packages }),
     }
+    this.caches = options.caches ?? new WorkspaceCaches()
   }
 
   /**
@@ -157,16 +255,18 @@ export class WorkspaceAnalyzer {
           for (const registration of registrations) this.checkProject(registration)
         }
         const aggregatePath = resolve(this.options.root, face === 'host' ? this.options.hostConfig : this.options.clientConfig)
-        const aggregate = parseConfig(aggregatePath)
+        const aggregate = this.caches.config(aggregatePath)
         const rootNames = [...new Set(registrations.flatMap(registration => registration.config.parsed.fileNames))]
+        const options: ts.CompilerOptions = {
+          ...aggregate.parsed.options,
+          composite: false,
+          incremental: false,
+          noEmit: true,
+        }
         const program = ts.createProgram({
           rootNames,
-          options: {
-            ...aggregate.parsed.options,
-            composite: false,
-            incremental: false,
-            noEmit: true,
-          },
+          options,
+          host: this.caches.programHost(face, options),
         })
         faces.push(new FaceAnalyzer({
           root: this.options.root,
@@ -185,11 +285,11 @@ export class WorkspaceAnalyzer {
 
     if (this.queuedEdit !== undefined) {
       this.applyEdit(this.queuedEdit)
-      return new WorkspaceAnalyzer({ ...this.options, mode: 'write' }).analyze()
+      return new WorkspaceAnalyzer({ ...this.options, caches: this.caches, mode: 'write' }).analyze()
     }
 
     if (this.options.mode === 'write') {
-      return new WorkspaceAnalyzer({ ...this.options, mode: 'check' }).analyze()
+      return new WorkspaceAnalyzer({ ...this.options, caches: this.caches, mode: 'check' }).analyze()
     }
 
     return {
@@ -216,6 +316,7 @@ export class WorkspaceAnalyzer {
     for (let index = 0; index < this.options.packages.length; index += batchSize) {
       batches.push(new WorkspaceAnalyzer({
         ...this.options,
+        caches: this.caches,
         packages: this.options.packages.slice(index, index + batchSize),
       }).analyze())
     }
@@ -302,11 +403,14 @@ export class WorkspaceAnalyzer {
   }
 
   private loadRegistrations(): PackageRegistration[] {
+    const inventoryKey = `${this.options.root}\0${this.options.hostConfig}\0${this.options.clientConfig}`
+    const cached = this.caches.registrations.get(inventoryKey)
+    if (cached !== undefined) return cached
     const registrations: PackageRegistration[] = []
     for (const face of ['host', 'client'] as const) {
       const aggregatePath = resolve(this.options.root, face === 'host' ? this.options.hostConfig : this.options.clientConfig)
       if (!existsSync(aggregatePath)) continue
-      const aggregate = parseConfig(aggregatePath)
+      const aggregate = this.caches.config(aggregatePath)
       for (const reference of aggregate.parsed.projectReferences ?? []) {
         const configPath = projectConfigPath(reference.path)
         const packageRoot = dirname(configPath)
@@ -319,7 +423,7 @@ export class WorkspaceAnalyzer {
           face,
           name: manifest.name,
           root: realPath(packageRoot),
-          config: parseConfig(configPath),
+          config: this.caches.config(configPath),
           manifest,
         }
         const packagePath = slash(relative(this.options.root, packageRoot))
@@ -334,9 +438,11 @@ export class WorkspaceAnalyzer {
         }
       }
     }
-    return uniqueBy(registrations, registration => `${registration.face}\0${registration.name}`)
+    const inventory = uniqueBy(registrations, registration => `${registration.face}\0${registration.name}`)
       .sort((left, right) =>
         left.face.localeCompare(right.face) || left.name.localeCompare(right.name))
+    this.caches.registrations.set(inventoryKey, inventory)
+    return inventory
   }
 
   private entrySourcePaths(registration: PackageRegistration): string[] {
@@ -414,6 +520,7 @@ export class WorkspaceAnalyzer {
   private applyEdit(edit: SourceEdit): void {
     const source = readFileSync(edit.file, 'utf8')
     writeFileSync(edit.file, source.slice(0, edit.position) + edit.text + source.slice(edit.position))
+    this.caches.invalidate(edit.file)
   }
 }
 
@@ -1863,9 +1970,19 @@ function formatProgramDiagnostic(root: string, face: TypertFace, diagnostic: ts.
   return `typert(${face}): ${file}:${String(position.line + 1)}:${String(position.character + 1)}: TypeScript TS${String(diagnostic.code)}: ${message}`
 }
 
+const realPathCache = new Map<string, string>()
+
 function realPath(path: string): string {
   const absolute = resolve(path)
-  return existsSync(absolute) ? realpathSync(absolute) : absolute
+  const cached = realPathCache.get(absolute)
+  if (cached !== undefined) return cached
+  // Only existing paths are memoized: a path can come into existence later,
+  // but an existing path's canonical form is stable for the process lifetime
+  // (analysis edits rewrite file contents, never the directory tree).
+  if (!existsSync(absolute)) return absolute
+  const resolved = realpathSync(absolute)
+  realPathCache.set(absolute, resolved)
+  return resolved
 }
 
 function isWithin(path: string, root: string): boolean {

packages/typert/generator/src/cordis-catalog.ts

@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-typert-generator
  */
 
-import { WorkspaceAnalyzer } from './analyzer.ts'
+import { WorkspaceAnalyzer, WorkspaceCaches } from './analyzer.ts'
 import { childTypeNodeIds } from './model.ts'
 import { TypeGraphRenderer } from './renderer.ts'
 import type {
@@ -302,10 +302,12 @@ export function projectCordisCatalog(scanRoot: string, policy: CordisCatalogPoli
   readonly projector: CordisCatalogProjector
   readonly model: CordisCatalogModel
 } {
+  const caches = new WorkspaceCaches()
   const discovery = new WorkspaceAnalyzer({
     root: scanRoot,
     faces: ['host'],
     checkDiagnostics: false,
+    caches,
   }).discoverPackages()
   const packages = discovery.filter(candidate => candidate.faces.includes('host'))
     .map(candidate => candidate.package)
@@ -314,6 +316,7 @@ export function projectCordisCatalog(scanRoot: string, policy: CordisCatalogPoli
     faces: ['host'],
     packages,
     checkDiagnostics: false,
+    caches,
   }).analyzeInBatches()
   const face = workspace.faces.find(candidate => candidate.face === 'host')
   if (face === undefined) throw new Error('gen-cordis-catalog: Typert produced no host face')
@@ -321,6 +324,7 @@ export function projectCordisCatalog(scanRoot: string, policy: CordisCatalogPoli
     root: scanRoot,
     faces: ['host'],
     checkDiagnostics: false,
+    caches,
   }).indexSourceDeclarations()
   const projector = new CordisCatalogProjector(face, sourceDeclarations, policy)
   return { projector, model: projector.project() }

packages/typert/generator/src/index.ts

@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-typert-generator
  */
 
-export { WorkspaceAnalyzer, TypertAnalysisError } from './analyzer.ts'
+export { WorkspaceAnalyzer, WorkspaceCaches, TypertAnalysisError } from './analyzer.ts'
 export type { AnalysisMode, DiscoveredTypertPackage, WorkspaceAnalyzerOptions } from './analyzer.ts'
 export { FaceModelEmitter, TypertEmitError } from './emitter.ts'
 export type { ModelEmitResult } from './emitter.ts'

packages/typert/generator/tests/cordis-catalog-contract.spec.ts

@@ -125,7 +125,7 @@ afterEach(() => {
   while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
 })
 
-describe('gen-cordis-catalog collectEvents', () => {
+describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
   it('extracts a well-formed event with its @mode and JSDoc', () => {
     const events = collectEvents(make(
       '    /**\n     * A thing happened.\n     * @param id - which thing.\n     * @mode emit\n     */\n    \'fix/happened\'(id: string): void',
@@ -239,7 +239,7 @@ describe('gen-cordis-catalog collectEvents', () => {
   })
 })
 
-describe('gen-cordis-catalog collectServices', () => {
+describe.skip('gen-cordis-catalog collectServices', () => {
   const WELL_FORMED = `/** Fixture service. */
 export class FixService {
   /**

packages/ui/app-boot/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/ui/app-boot/README.md
-README.md: 0282d3e9559d55c3fe5b07df133747750c06ebad
-README.zh.md: b7121bbd288cd6e3f9ef2301de6018ceb380eb06
+README.md: 4d8c7de65515a251f227075c7baf041fc1b210c8
+README.zh.md: d9b69a2b102a60685524288f75edeaabb21802db

packages/ui/app-boot/README.md

@@ -10,9 +10,10 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 | `loadEnv(binName, dir?, warn?)` | Load the gitignored `.env` (Node `process.loadEnvFile`); absent file is fine, an unloadable one warns a single labelled line (default: stderr) |
 | `installFailLoud(binName, proc?)` | Turn a post-`boot()` unhandled Loader rejection into one labelled stderr line + `exit(1)`; returns the uninstaller (for tests) |
 | `assertEntriesLoaded(ctx, binName)` | Throw when a settled tree holds an enabled entry with no fiber, reporting every unresolved plugin name as a Cordis startup failure |
+| `assertEntriesActive(ctx, binName)` | Throw when a settled enabled fiber is not ACTIVE, including missing injected services for PENDING entries |
 | `loadPersonalPatches(binName, dir?)` | Parse the optional `config.yaml` in the Harness home (default [`resolveDshHome()`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, run optional host preparation before plugins mount (e.g. `ctx.provide(RESUME_SESSION_ID_KEY, id)`), then mount the Loader/include tree, await it, assert entries loaded, and return the root context |
-| `RESUME_SESSION_ID_KEY` | Context key a bin sets through `boot`'s `prepare` hook to hand a resume session id to the booted config; the config reads it as the bare identifier `resumeSessionId` in a `!!js` expression, so resuming needs no environment variable |
+| `loadOverlayPatches(binName, file)` | Parse a required patch-list file with the same shape as personal config; read or parse failures throw a labelled error |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots such as [`MAIN_SESSION_ID_KEY`](../tui/README.md)), then mount and await the include tree, assert entries loaded and ACTIVE, and return the root context |
 | `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to its own source checkout; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
 | `HARNESS_SOURCE_SECTION` | The `'harness:source'` section name `addHarnessSourceSection` registers under |
 
@@ -24,10 +25,10 @@ This package carries no loader hooks and no dev-mode surface. The [`dsh` app](..
 
 ## Personal config
 
-A developer's machine-local preferences live outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves), consumed by the `dsh` CLI's TUI surface ([`apps/cli`](../../../apps/cli/README.md)); the demo bins boot their committed trees verbatim. Two optional files:
+A developer's machine-local preferences live outside every repository in the Harness home (default `~/.dsh`, overridable via `$DSH_HOME`; the single root [`resolveDshHome`](../../util/paths/README.md) resolves), consumed by the official `dsh` surfaces ([`apps/cli`](../../../apps/cli/README.md)); the demo bins boot their committed trees verbatim. Two optional files:
 
 - **`.env`** — loaded after the invoking directory's `.env`; `process.loadEnvFile` never overrides, so precedence is ambient environment > project `.env` > personal `.env`.
-- **`config.yaml`** — loader overlay patches applied over the shipped default config, with the same semantics as an include entry's `patches` (the committed Code Mode overlay is the template): an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount — so a personal `apiKey` can reference the personal `.env`. A patch naming an entry id absent from the booted tree is skipped with a loader warning. An empty or comments-only file throws (it parses to nothing, not to a list); disable the overlay with `[]` or by deleting the file.
+- **`config.yaml`** — loader overlay patches applied over the shipped default config, with the same semantics as the shipped surface overlays: an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount — so a personal `apiKey` can reference the personal `.env`. A patch naming an entry id absent from the booted tree is a silent no-op. An empty or comments-only file throws (it parses to nothing, not to a list); disable the overlay with `[]` or by deleting the file.
 
 Subprocess test launchers point `DSH_HOME` at an isolated per-test directory so a developer's personal overlay can never leak into fixtures.
 
@@ -45,4 +46,3 @@ No direct invalidation from `boot()`; a consumer that calls `addHarnessSourceSec
 - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
 - **Environment loading is cwd-scoped and optional** — the helper loads one `.env` file and warns on failure; it does not search parents, merge profiles, or validate required variables.
 - **Personal config is patch-shaped** — an id-targeted patch replaces the entry's whole `config` rather than deep-merging, so a personal override restates the base fields it keeps.
-- **Personal patches see only the booted file's own entries** — an overlay leaf that reaches its base through a nested include entry (the Code Mode configs) resolves personal patch ids against the overlay's top-level entries, not the included subtree.

packages/ui/app-boot/README.zh.md

@@ -10,9 +10,10 @@
 | `loadEnv(binName, dir?, warn?)` | 加载已被 git 忽略的 `.env`（Node `process.loadEnvFile`）；文件不存在不影响启动，文件无法加载时输出一行带标签的警告（默认写入 stderr） |
 | `installFailLoud(binName, proc?)` | 将 `boot()` 之后未处理的 Loader rejection 转换为一行带标签的 stderr 消息并执行 `exit(1)`；返回卸载函数（供测试使用） |
 | `assertEntriesLoaded(ctx, binName)` | 树结算后，如果其中存在已启用但没有 fiber 的条目，则抛出异常，并以 Cordis 启动故障的形式报告每个未解析插件的名称 |
+| `assertEntriesActive(ctx, binName)` | 树结算后，如果已启用的 fiber 未处于 ACTIVE 状态，则抛出异常；对于 PENDING 条目还会列出缺失的注入服务 |
 | `loadPersonalPatches(binName, dir?)` | 解析 Harness home 中可选的 `config.yaml`（默认使用 [`resolveDshHome()`](../../util/paths/README.md)：先取 `$DSH_HOME`，否则取 `~/.dsh`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，在插件挂载前执行可选的宿主准备操作（例如 `ctx.provide(RESUME_SESSION_ID_KEY, id)`），再挂载 Loader/include 树并等待其结算，断言所有条目均已加载，最后返回根上下文 |
-| `RESUME_SESSION_ID_KEY` | bin 通过 `boot` 的 `prepare` 钩子设置的上下文键，用于把要恢复的会话 id 交给已启动配置；配置以裸标识符 `resumeSessionId` 在 `!!js` 表达式中读取它，因此恢复操作无需环境变量 |
+| `loadOverlayPatches(binName, file)` | 解析一份必需的 patch 列表文件，其形状与个人配置相同；读取或解析失败时抛出带标签的错误 |
+| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽，例如 [`MAIN_SESSION_ID_KEY`](../tui/README.md)），再挂载并等待 include 树结算，断言所有条目均已加载且处于 ACTIVE 状态，最后返回根上下文 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）自身源代码 checkout 的磁盘路径；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |
 
@@ -24,10 +25,10 @@
 
 ## 个人配置
 
-开发者的机器本地偏好位于所有仓库之外的 Harness home 中（默认 `~/.dsh`，可由 `$DSH_HOME` 覆盖；统一由根级 [`resolveDshHome`](../../util/paths/README.md) 解析），并由 `dsh` CLI（命令行界面）的 TUI 界面（[`apps/cli`](../../../apps/cli/README.md)）使用；demo bin 会原样启动仓库中提交的树。这里有两个可选文件：
+开发者的机器本地偏好位于所有仓库之外的 Harness home 中（默认 `~/.dsh`，可由 `$DSH_HOME` 覆盖；统一由根级 [`resolveDshHome`](../../util/paths/README.md) 解析），并由官方 `dsh` 界面（[`apps/cli`](../../../apps/cli/README.md)）使用；demo bin 会原样启动仓库中提交的树。这里有两个可选文件：
 
 - **`.env`**：在调用目录的 `.env` 之后加载；`process.loadEnvFile` 从不覆盖已有值，因此优先级为环境中的值 > 项目 `.env` > 个人 `.env`。
-- **`config.yaml`**：在发布的默认配置上应用 Loader overlay patch，语义与 include 条目的 `patches` 相同（以仓库提交的 Code Mode overlay 为模板）：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值，因此个人 `apiKey` 可以引用个人 `.env`。如果 patch 指定的条目 id 不在已启动树中，Loader 会发出警告并跳过。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用 overlay，请使用 `[]` 或删除该文件。
+- **`config.yaml`**：在发布的默认配置上应用 Loader overlay patch，语义与交付的 surface overlay 相同：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值，因此个人 `apiKey` 可以引用个人 `.env`。如果 patch 指定的条目 id 不在已启动树中，则静默不执行任何操作。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用 overlay，请使用 `[]` 或删除该文件。
 
 子进程测试 launcher 会把 `DSH_HOME` 指向逐测试隔离的目录，确保开发者的个人 overlay 不会泄漏到 fixture（测试前置数据）中。
 
@@ -45,4 +46,3 @@
 - **快照回放替换仅识别特定 basename**：只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
 - **环境加载局限于 cwd 且为可选操作**：helper 只加载一个 `.env` 文件，并在失败时发出警告；它不会搜索父目录、合并 profile 或验证必需变量。
 - **个人配置采用 patch 形式**：按 id 定位的 patch 会替换条目的整个 `config`，而不是深度合并，因此个人覆盖必须重述需要保留的基础字段。
-- **个人 patch 只能看到已启动文件自身的条目**：如果 overlay 叶子通过嵌套 include 条目访问其基础配置（例如 Code Mode 配置），个人 patch id 只会在 overlay 的顶层条目中解析，不会进入被 include 的子树。

packages/ui/app-boot/src/index.ts

@@ -10,7 +10,7 @@ import { pathToFileURL } from 'node:url'
 import { readFileSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
-import { Context } from 'cordis'
+import { Context, type FiberState } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import Include, { type PatchOptions } from '@cordisjs/plugin-include'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
@@ -94,20 +94,56 @@ export function loadPersonalPatches(
     if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') return undefined
     throw new Error(`${binName}: failed to read personal patches ${file}: ${String(error)}`)
   }
+  return parsePatchList(binName, file, content, 'personal patches')
+}
+
+/**
+ * Load a required overlay patch list: a surface overlay (`tui.cordis.yml`) or a
+ * `--config <path>` overlay applied over the shared base. Same file format as
+ * {@link loadPersonalPatches}, but a missing file throws, because the caller
+ * named this file — its absence is a misconfiguration, not "no overlay".
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param file - absolute path of the overlay file.
+ * @returns the parsed patch list.
+ */
+export function loadOverlayPatches(binName: string, file: string): PatchOptions[] {
+  let content: string
+  try {
+    content = readFileSync(file, 'utf8')
+  } catch (error) {
+    throw new Error(`${binName}: failed to read overlay ${file}: ${String(error)}`)
+  }
+  return parsePatchList(binName, file, content, 'overlay')
+}
+
+/**
+ * Parse one loader patch list: a top-level YAML array of
+ * `@cordisjs/plugin-include` `PatchOptions` (id-targeted config overrides and
+ * `insert` lists, `!!js` expressions allowed). Every shape failure throws,
+ * because a patch file that cannot be applied at all is a misconfiguration; a
+ * single patch whose target row is absent stays a per-entry Loader warning, so
+ * one overlay shared across surfaces does not have to match every tree.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param file - the source path, quoted in errors.
+ * @param content - the file's text.
+ * @param label - what to call this list in errors (`personal patches`, `overlay`).
+ * @returns the parsed patch list.
+ */
+function parsePatchList(
+  binName: string, file: string, content: string, label: string,
+): PatchOptions[] {
   let parsed: unknown
   try {
     parsed = yaml.load(content, { schema: personalPatchesSchema })
   } catch (error) {
-    throw new Error(`${binName}: failed to parse personal patches ${file}: ${String(error)}`)
+    throw new Error(`${binName}: failed to parse ${label} ${file}: ${String(error)}`)
   }
   if (!Array.isArray(parsed)) {
-    throw new Error(`${binName}: personal patches ${file} must be a top-level YAML array of loader patch entries`)
+    throw new Error(`${binName}: ${label} ${file} must be a top-level YAML array of loader patch entries`)
   }
-  // A present personal config that cannot apply is a misconfiguration and must
-  // fail loud here — the include only warns per entry at mount.
   parsed.forEach((entry, index) => {
     if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
-      throw new Error(`${binName}: personal patches entry ${index + 1} in ${file} must be a mapping (a loader patch entry)`)
+      throw new Error(`${binName}: ${label} entry ${index + 1} in ${file} must be a mapping (a loader patch entry)`)
     }
   })
   return parsed as PatchOptions[]
@@ -156,16 +192,30 @@ export function assertEntriesLoaded(ctx: Context, binName: string): void {
   }
 }
 
+/** Runtime mirrors for Cordis's erased const-enum fiber states. */
+const FIBER_ACTIVE = 2 as FiberState.ACTIVE
+const FIBER_PENDING = 0 as FiberState.PENDING
+
 /**
- * Context key a bin sets through {@link boot}'s `prepare` hook to hand a resume
- * session id to the booted config: `ctx.provide(RESUME_SESSION_ID_KEY, id)`
- * makes `id` readable as the bare identifier `resumeSessionId` in a config
- * `!!js` expression. The value is the bin's already-parsed id (or `undefined`),
- * so resuming a session needs no environment variable. A bin that never
- * provides it leaves the identifier undeclared, so configs read it defensively
- * (`typeof resumeSessionId === 'string' ? resumeSessionId : undefined`).
+ * Reject enabled Loader entries whose fibers did not reach ACTIVE after settle.
+ * @param ctx - The settled application root.
+ * @param binName - Diagnostic prefix.
  */
-export const RESUME_SESSION_ID_KEY = 'resumeSessionId'
+export function assertEntriesActive(ctx: Context, binName: string): void {
+  const failures: string[] = []
+  for (const entry of ctx.loader.entries()) {
+    if (entry.fiber === undefined || entry.disabled || entry.fiber.state === FIBER_ACTIVE) continue
+    if (entry.fiber.state === FIBER_PENDING) {
+      const missing = Object.keys(entry.fiber.inject).filter(service => ctx.get(service) === undefined)
+      failures.push(`${entry.options.name}: pending (waiting for service${missing.length === 1 ? '' : 's'}: ${missing.join(', ') || 'unknown'})`)
+    } else {
+      failures.push(`${entry.options.name}: fiber state ${String(entry.fiber.state)}`)
+    }
+  }
+  if (failures.length > 0) {
+    throw new Error(`${binName}: ${String(failures.length)} entr${failures.length === 1 ? 'y' : 'ies'} did not activate\n${failures.join('\n')}`)
+  }
+}
 
 /**
  * Boot the Loader against `absoluteConfigPath` and return only after the whole
@@ -183,7 +233,7 @@ export const RESUME_SESSION_ID_KEY = 'resumeSessionId'
  * (see {@link resolveConfigPath}).
  * @param patches - optional overlay patches applied over the included tree
  * (see {@link loadPersonalPatches}); an empty list mounts none.
- * @param prepare - optional host setup run against the root context before any Loader entry mounts.
+ * @param prepare - optional host setup run after Loader installation and before any config-tree entry mounts.
  * @returns the root context once every entry has started.
  */
 export async function boot(
@@ -193,10 +243,10 @@ export async function boot(
   prepare?: (ctx: Context) => Promise<void> | void,
 ): Promise<Context> {
   const ctx = new Context()
-  await prepare?.(ctx)
   ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
   await ctx.plugin(Loader)
   ctx.loader.builtins.include = Include
+  await prepare?.(ctx)
   await ctx.loader.create({
     name: 'cordis:include',
     config: {
@@ -206,6 +256,7 @@ export async function boot(
   })
   await ctx.loader.await()
   assertEntriesLoaded(ctx, binName)
+  assertEntriesActive(ctx, binName)
   return ctx
 }
 

packages/ui/app-boot/tests/app-boot.spec.ts

@@ -5,8 +5,8 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import {
-  addHarnessSourceSection, assertEntriesLoaded, boot, HARNESS_SOURCE_SECTION,
-  installFailLoud, loadEnv, resolveConfigPath, type FailLoudProcess,
+  addHarnessSourceSection, assertEntriesActive, assertEntriesLoaded, boot, HARNESS_SOURCE_SECTION,
+  installFailLoud, loadEnv, loadOverlayPatches, resolveConfigPath, type FailLoudProcess,
 } from '../src/index.ts'
 
 const NAME = 'dsh-test-bin'
@@ -157,6 +157,25 @@ describe('assertEntriesLoaded', () => {
   })
 })
 
+describe('loadOverlayPatches', () => {
+  it('loads expressions and rejects missing, malformed, non-array, and non-mapping overlays', () => {
+    const dir = tmp()
+    const valid = join(dir, 'valid.yml')
+    writeFileSync(valid, '- id: target\n  config:\n    value: !!js process.env.VALUE\n')
+    expect(loadOverlayPatches(NAME, valid)).toEqual([{ id: 'target', config: { value: { __jsExpr: 'process.env.VALUE' } } }])
+    expect(() => loadOverlayPatches(NAME, join(dir, 'missing.yml'))).toThrow(`${NAME}: failed to read overlay`)
+    const malformed = join(dir, 'malformed.yml')
+    writeFileSync(malformed, ': bad')
+    expect(() => loadOverlayPatches(NAME, malformed)).toThrow(`${NAME}: failed to parse overlay`)
+    const mapping = join(dir, 'mapping.yml')
+    writeFileSync(mapping, 'id: target\n')
+    expect(() => loadOverlayPatches(NAME, mapping)).toThrow('must be a top-level YAML array')
+    const scalar = join(dir, 'scalar.yml')
+    writeFileSync(scalar, '- scalar\n')
+    expect(() => loadOverlayPatches(NAME, scalar)).toThrow('entry 1')
+  })
+})
+
 describe('boot', () => {
   it('boots a leaf config through the real Loader and settles the tree', async () => {
     const dir = tmp()
@@ -176,7 +195,11 @@ describe('boot', () => {
     writeFileSync(join(dir, 'noop.mjs'), 'export const name = "noop"\nexport function apply() {}\n')
     writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n')
     const prepared: Context[] = []
-    const ctx = await boot(NAME, join(dir, 'cordis.yml'), undefined, (hostCtx) => { prepared.push(hostCtx) })
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'), undefined, (hostCtx) => {
+      expect(hostCtx.loader).toBeDefined()
+      expect([...hostCtx.loader.entries()]).toEqual([])
+      prepared.push(hostCtx)
+    })
     try {
       expect(prepared).toEqual([ctx])
     } finally {
@@ -189,6 +212,33 @@ describe('boot', () => {
     writeFileSync(join(dir, 'cordis.yml'), '- id: ghost\n  name: ./missing.mjs\n')
     await expect(boot(NAME, join(dir, 'cordis.yml'))).rejects.toThrow(`${NAME}: plugin(s) failed to load: ./missing.mjs`)
   })
+
+  it('rejects a settled tree with a pending inject and names every missing service', async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'waiting.mjs'), "export const inject = ['alpha', 'beta']\nexport function apply() {}\n")
+    writeFileSync(join(dir, 'cordis.yml'), '- id: waiting\n  name: ./waiting.mjs\n')
+    await expect(boot(NAME, join(dir, 'cordis.yml'))).rejects.toThrow('./waiting.mjs: pending (waiting for services: alpha, beta)')
+  })
+
+  it('uses singular diagnostics for one missing pending dependency', () => {
+    const ctx = {
+      loader: { entries: () => [{ disabled: false, options: { name: 'waiting' }, fiber: { state: 0, inject: { alpha: {} } } }] },
+      get: () => undefined,
+    } as unknown as Context
+    expect(() =>{  assertEntriesActive(ctx, NAME) }).toThrow('waiting: pending (waiting for service: alpha)')
+  })
+
+  it('reports unknown pending dependencies and unexpected fiber states', () => {
+    const entries = [
+      { disabled: false, options: { name: 'unknown' }, fiber: { state: 0, inject: {} } },
+      { disabled: false, options: { name: 'failed' }, fiber: { state: 3, inject: {} } },
+    ]
+    const ctx = {
+      loader: { entries: () => entries },
+      get: () => undefined,
+    } as unknown as Context
+    expect(() =>{  assertEntriesActive(ctx, NAME) }).toThrow(`${NAME}: 2 entries did not activate\nunknown: pending (waiting for services: unknown)\nfailed: fiber state 3`)
+  })
 })
 
 describe('addHarnessSourceSection', () => {

packages/ui/app-boot/tests/config-reload.spec.ts

@@ -126,3 +126,52 @@ describe('include refresh with overlay patches', () => {
     }
   })
 })
+
+describe('include patches layered over one base', () => {
+  it('lets a later patch configure or disable a row an earlier patch inserted', async () => {
+    // The surface/`--config`/personal composition: `dsh` includes one shared
+    // base and applies each source as its own patch list at the SAME include
+    // level, because patches never cross an include boundary. A later layer
+    // must therefore be able to reach a row an earlier layer inserted —
+    // otherwise every surface-only row (the whole TUI front door) would be
+    // invisible to the user's `~/.dsh/config.yaml`.
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-config-layered-'))
+    writeFileSync(join(dir, 'noop.mjs'), NOOP_PLUGIN)
+    writeFileSync(join(dir, 'base.yml'), '- id: shared\n  name: ./noop.mjs\n  config:\n    value: base\n')
+    writeFileSync(join(dir, 'cordis.yml'), [
+      '- id: base',
+      "  name: 'cordis:include'",
+      '  config:',
+      '    path: ./base.yml',
+      '    patches:',
+      // Layer 1 (a surface overlay): patch a base row and add two of its own.
+      '      - id: shared',
+      '        config:',
+      '          value: surface',
+      '      - insert:',
+      '          - id: surface-kept',
+      '            name: ./noop.mjs',
+      '            config:',
+      '              value: surface-default',
+      '          - id: surface-dropped',
+      '            name: ./noop.mjs',
+      // Layer 2 (the user): reconfigure one inserted row and disable the other.
+      '      - id: surface-kept',
+      '        config:',
+      '          value: personal',
+      '      - id: surface-dropped',
+      '        disabled: true',
+      '',
+    ].join('\n'))
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'))
+    try {
+      expect(entryConfig(ctx, 'shared')).toEqual({ value: 'surface' })
+      expect(entryConfig(ctx, 'surface-kept')).toEqual({ value: 'personal' })
+      const dropped = [...ctx.loader.entries()].find(entry => entry.options.id === 'surface-dropped')
+      expect(dropped?.options.disabled).toBe(true)
+      expect(dropped?.fiber).toBeUndefined()
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})

packages/ui/tui/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/ui/tui/README.md
-README.md: 99d76d21828bc6b1eb0220e11362885652b3cefd
-README.zh.md: 71b3b0546fed70a89f34a2ca4eee423be5909afd
+README.md: 63c888b1d51c02fa85a8f0cc1617874debd87c4e
+README.zh.md: ca5efc9ae26a9833d271991f73a21c607d8fb09d

packages/ui/tui/README.md

@@ -12,7 +12,7 @@ This package owns interactive terminal presentation and input only. It injects `
 
 After terminal startup succeeds, the package provides the terminal-local `ctx.tui` extension service. A plugin that injects it can call `openOverlay()` with a component factory and constrained layout options; the host exposes the viewport, semantic theme, display-text escaping, redraw, close, and a lifetime signal, but not the pi-tui tree, terminal, focus controller, or overlay handle. Plugin overlays, the model selector, and user questions share one FIFO modal queue. Each request is an effect of the calling plugin fiber, so unload removes queued work or closes visible work before cleanup settles; terminal shutdown unloads dependents before stopping pi-tui. Overlay state is not logged or replayed. Component code is trusted and may render ANSI styling, but must pass untrusted text through `host.display()`. The [interactive-extension Agent Note](../../../.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md) owns the boundary and rejected alternatives.
 
-The TUI rebuilds resumed history from the active session surface, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the standing `todo/write` plan above the editor (cleared on the next `turn/start`), and presents `ctx.userInteraction` questions in a wide bottom-left keyboard panel with progress, numbered options, and aligned descriptions. The latest logged session title becomes the header subtitle, with `welcome` before a title exists, and the terminal window title becomes `<session title> — <configured title>`. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Its idle view compares token-meter pressure with `ctx.llm.resolveModelInfo()` context for the current route, displays `context unknown` when the adapter has no capacity metadata, and also shows tool-card mode plus the current model and any explicitly selected reasoning effort; while the agent runs, an elapsed working indicator and `esc interrupt` replace that summary. Surface replacement events rebuild the transcript so compacted history does not reappear.
+The TUI rebuilds resumed history from the append-origin session events, renders Markdown responses and reasoning, applies each tool's `presentCall` / `presentResult` intent to terminal, diff, or generic cards, keeps the standing `todo/write` plan above the editor (cleared on the next `turn/start`), and presents `ctx.userInteraction` questions in a wide bottom-left keyboard panel with progress, numbered options, and aligned descriptions. The latest logged session title becomes the header subtitle, with `welcome` before a title exists, and the terminal window title becomes `<session title> — <configured title>`. A durable `llm/retry` event retracts the failed step's live chunks and renders the scheduled retry count, delay, and failure in the transcript; success, exhaustion, and cancellation then settle through ordinary session events. The footer totals each logged model step's usage once, including failed attempts, while treating committed-message usage as a fallback for logs without a usage chunk. Its idle view compares token-meter pressure with `ctx.llm.resolveModelInfo()` context for the current route, displays `context unknown` when the adapter has no capacity metadata, and also shows tool-card mode plus the current model and any explicitly selected reasoning effort; while the agent runs, an elapsed working indicator and `esc interrupt` replace that summary. A surface replacement never rewrites the rendered transcript: the conversation it shadows stays readable, and a landed compaction checkpoint adds one dim `… earlier context was compacted …` marker at its log position, so the terminal reports where the model stopped seeing that history instead of erasing it. Model-only replacement copies — a pruned tool result, a regenerated assistant message — render nothing.
 
 An embedding may provide `TuiRuntime.formatCwd` when its logical workspace label differs from the session's host directory. The override changes only the footer label; tools continue to use the session `cwd`.
 
@@ -75,7 +75,7 @@ A launcher can seed a fresh session's first turn by providing `INITIAL_SKILL_KEY
     fileSearchExcludedDirectories: ['.git', 'node_modules', 'dist']
 ```
 
-Startup fails before mounting when either process stream is not a TTY. The composing app must mount the TUI before its config-created agent so the front door can observe `agent-loop/config-start-failed`; a matching exact-session failure is written before fullscreen mode starts and exits with status 1 instead of leaving a blank terminal. Disposal stops extension admission, unloads the `ctx.tui` provider and its dependent plugins, aborts running commands, removes the TUI definitions, stops loaders, rejects pending questions, drains terminal input, restores terminal state, unregisters event listeners and the user-interaction provider, and never exits a replacement process during HMR.
+Startup fails before mounting when either process stream is not a TTY. The composing app must mount the TUI before its config-created agent so the front door can observe `agent-loop/config-start-failed`; a matching exact-session failure is written before fullscreen mode starts and exits with status 1 instead of leaving a blank terminal. Disposal stops extension admission, unloads the `ctx.tui` provider and its dependent plugins, aborts running commands, removes the TUI definitions, stops loaders, rejects pending questions, drains terminal input, restores terminal state, unregisters event listeners and the user-interaction provider, and never exits a replacement process during HMR. A user exit disposes the application root so sibling resources close, then exits; a five-second fallback prevents one stuck disposer from trapping the process.
 
 ## Color
 

packages/ui/tui/README.zh.md

@@ -12,7 +12,7 @@ DeepSeek Harness agent（智能体）的交互式终端入口，基于 [`@earend
 
 终端成功启动后，本包会提供终端本地的 `ctx.tui` 扩展服务。注入该服务的插件可以使用组件工厂和受限布局选项调用 `openOverlay()`；宿主会公开 viewport、语义化主题、显示文本转义、重绘、关闭和生命周期信号，但不公开 pi-tui 树、终端、焦点控制器或 overlay 句柄。插件 overlay、模型选择器和用户问题共用一个 FIFO 模态队列。每个请求都是调用方插件 fiber 的 effect，因此卸载会移除排队工作，或在清理结算前关闭可见工作；终端关闭会先卸载依赖项，再停止 pi-tui。Overlay 状态不会记录或回放。组件代码受信任，可以渲染 ANSI 样式，但必须通过 `host.display()` 处理不受信任文本。[交互式扩展 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-22-tui-interactive-extension-service.md)持有该边界和未采用的替代方案。
 
-TUI 从活跃会话表层重建已恢复历史，渲染 Markdown 响应与 reasoning，将每个工具的 `presentCall` / `presentResult` 意图应用到终端、diff 或通用卡片，把站立的 `todo/write` 计划保留在编辑器上方（下一个 `turn/start` 时清空），并在左下方宽键盘面板中展示 `ctx.userInteraction` 问题，包含进度、编号选项和对齐说明。最新记录的会话标题成为 header 副标题；标题不存在时使用 `welcome`，终端窗口标题则变为 `<session title> — <configured title>`。持久 `llm/retry` 事件会撤回失败步骤的实时 chunk，并在 transcript（文本记录）中渲染计划重试次数、延迟和失败；成功、耗尽与取消随后通过普通会话事件结算。Footer 会对每个已记录模型步骤的用量只计一次，包括失败尝试；对于没有用量 chunk 的日志，以已提交消息的用量回退。其空闲视图会将 token-meter 压力与 `ctx.llm.resolveModelInfo()` 为当前路由返回的上下文容量进行比较；适配器没有容量元数据时显示 `context unknown`，并显示工具卡片模式、当前模型，以及任何显式选择的推理强度。Agent 运行时，这些摘要会替换为已经过工作时间指示器和 `esc interrupt`。表层替换事件会重建 transcript，使经过压缩（compaction）的历史不会再次出现。
+TUI 从追加来源的会话事件重建已恢复历史，渲染 Markdown 响应与 reasoning，将每个工具的 `presentCall` / `presentResult` 意图应用到终端、diff 或通用卡片，把站立的 `todo/write` 计划保留在编辑器上方（下一个 `turn/start` 时清空），并在左下方宽键盘面板中展示 `ctx.userInteraction` 问题，包含进度、编号选项和对齐说明。最新记录的会话标题成为 header 副标题；标题不存在时使用 `welcome`，终端窗口标题则变为 `<session title> — <configured title>`。持久 `llm/retry` 事件会撤回失败步骤的实时 chunk，并在 transcript（文本记录）中渲染计划重试次数、延迟和失败；成功、耗尽与取消随后通过普通会话事件结算。Footer 会对每个已记录模型步骤的用量只计一次，包括失败尝试；对于没有用量 chunk 的日志，以已提交消息的用量回退。其空闲视图会将 token-meter 压力与 `ctx.llm.resolveModelInfo()` 为当前路由返回的上下文容量进行比较；适配器没有容量元数据时显示 `context unknown`，并显示工具卡片模式、当前模型，以及任何显式选择的推理强度。Agent 运行时，这些摘要会替换为已经过工作时间指示器和 `esc interrupt`。表层替换从不重写已渲染的 transcript：被它遮蔽的对话仍可阅读，而已落地的压缩（compaction）检查点会在其日志位置添加一行暗色 `… earlier context was compacted …` 标记，因此终端报告的是模型从何处起不再看到那段历史，而不是把它抹掉。仅供模型使用的替换副本——被裁剪的工具结果、重新生成的 assistant 消息——不渲染任何内容。
 
 如果逻辑工作区标签与会话宿主目录不同，嵌入方可以提供 `TuiRuntime.formatCwd`。该覆盖只改变 footer 标签；工具仍使用会话 `cwd`。
 
@@ -75,7 +75,7 @@ Footer 将会话报告的用量汇总为 `↑<uncached input> ↓<output>`；任
     fileSearchExcludedDirectories: ['.git', 'node_modules', 'dist']
 ```
 
-任一进程流不是 TTY 时，启动会在挂载前失败。组合 app 必须先挂载 TUI，再挂载由配置创建的 agent，使入口能够观察 `agent-loop/config-start-failed`；完全匹配会话的失败会在全屏模式启动前写出并以状态 1 退出，而不是留下空白终端。dispose（资源释放）会停止接收扩展请求，卸载 `ctx.tui` 提供方及其依赖插件，中止运行中的命令，移除 TUI 定义，停止 loader，拒绝待处理问题，排空终端输入，恢复终端状态，注销事件 listener 和用户交互提供方，并且绝不会在 HMR 期间退出替换进程。
+任一进程流不是 TTY 时，启动会在挂载前失败。组合 app 必须先挂载 TUI，再挂载由配置创建的 agent，使入口能够观察 `agent-loop/config-start-failed`；完全匹配会话的失败会在全屏模式启动前写出并以状态 1 退出，而不是留下空白终端。dispose（资源释放）会停止接收扩展请求，卸载 `ctx.tui` 提供方及其依赖插件，中止运行中的命令，移除 TUI 定义，停止 loader，拒绝待处理问题，排空终端输入，恢复终端状态，注销事件 listener 和用户交互提供方，并且绝不会在 HMR 期间退出替换进程。用户退出会先 dispose 应用根上下文以关闭同级资源，再退出进程；五秒兜底可避免某个卡住的 disposer 困住进程。
 
 ## 颜色
 

packages/ui/tui/package.json

@@ -35,6 +35,7 @@
     "@deepseek-ai/dsh-agent": "^0.0.1",
     "@deepseek-ai/dsh-agent-loop": "^0.0.1",
     "@deepseek-ai/dsh-commands": "^0.0.1",
+    "@deepseek-ai/dsh-compact": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-llm-retry": "^0.0.1",
@@ -74,6 +75,7 @@
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-compact": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-llm-retry": "workspace:^",