Merge remote-tracking branch 'origin/master' into worktree/persist-web-theme-settings

packages/client/connection/src/client/fixture.ts

@@ -474,11 +474,14 @@ function buildAlphaLog(): SessionEvent[] {
     push({ type: 'step/end', data: { turn, step: 0 } })
     push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
   }
-  // Turn 67: todo_write sample — the TodoRow toolview in the flow plus the
-  // todo/write snapshot event feeding the TodoPanel plan strip.
+  // Turn 71: todo_write sample — the TodoRow toolview in the flow plus the
+  // todo/write snapshot event feeding the TodoPanel plan strip. Two items are
+  // in_progress: this fixture chooses the parallel policy, so both surfaces
+  // must render a parallel plan rather than the first active item alone.
   const fixtureTodos = [
     { content: '梳理需求', status: 'completed' },
     { content: '实现 fixture 样本', status: 'in_progress' },
+    { content: '跑后台构建', status: 'in_progress' },
     { content: '浏览器验收', status: 'pending' },
   ]
   // Turn 65: the terminal sample turn 60's two clean prompt rows cannot cover —
@@ -531,7 +534,7 @@ function buildAlphaLog(): SessionEvent[] {
   toolTurn(70, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')
 
   const todoArgs = JSON.stringify({ todos: fixtureTodos })
-  toolTurn(71, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
+  toolTurn(71, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 2 in progress, 1 completed.')
   // The real tool appends the snapshot mid-execution — between tool/call and
   // tool/result — so the fixture reproduces that exact ordering (the last
   // toolTurn events run ... tool/call, tool/result, step/end, turn/end).

packages/client/connection/tests/fixture.spec.ts

@@ -242,6 +242,10 @@ describe('createFixtureApi', () => {
     const times = events.slice(todoAt - 1, todoAt + 2).map(e => e.time)
     expect(times[0]).toBeLessThanOrEqual(times[1] ?? 0)
     expect(times[1]).toBeLessThanOrEqual(times[2] ?? 0)
+    // The sample is a parallel plan: this fixture chooses the parallel policy,
+    // so the surfaces fed from here face more than one active item.
+    const snapshot = events[todoAt] as { data: { todos: { status: string }[] } }
+    expect(snapshot.data.todos.filter(t => t.status === 'in_progress')).toHaveLength(2)
   })
 
   it('create adds a session and pushes host/session-added to open host streams', async () => {

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: bbd115eac0eb914914dc11e504639633c801abdd
-README.zh.md: 843b49e311fbf1a9157413c42a0ef3e9828284bc
+README.md: 8d6c26f67916f043251c58a3283542bd58a08666
+README.zh.md: 8dd43cca59f8dfda18ce036b5d8c6f948306c947

packages/client/ui-conversation/README.md

@@ -34,7 +34,7 @@ A `grep`/`glob` call declaring the `search` render intent renders its result inl
 
 Tool rows use the keyed, session-scoped `'conversation.chat.toolview'` slot; its render site dispatches via `entryKey: toolName` with `GenericToolCard` as the call-site fallback. The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openFile`), and `ToolRowProps` composes it with the session standard kit. A registrant is a plain plugin with only the slot service edge: `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row))`. The declaration is the activation and reload dependency; `ConversationService` is required only by registrations that call its actions. Trajectory and waterfall toolview slots share this shape and use their own render sites; RendersCheck rejects a declaration nobody renders.
 
-The todo surfaces are two registrations over that shape, both using slot declaration injection without a `ConversationService` edge. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> 已完成 · <active item>` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: 0` — before Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"<done>/<total> tasks · <n> in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
+The todo surfaces are two registrations over that shape, both using slot declaration injection without a `ConversationService` edge. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> completed · <active item>` plus a `+<n>` count of the other active ones, parsed from its args through `toolviews/plan-summary.ts` `planSummary`, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). When the deployment permits parallel work, several items may be `in_progress` at once, so `planSummary` names the first and counts the rest, and deliberately returns the two unjoined: the row ellipsizes its summary text, so a count concatenated onto the end of the task name would be the first thing a narrow row clips. The row hands the count to `ToolRow`'s `summarySuffix`, the shared row's non-shrinking slot beside that ellipsized text (an error row drops it, since its collapsed summary is the failure line). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: 0` — before Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus its own `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted; status glyphs are the figma check / progress / dashed-pending set), so it reports the parallel count without needing a name to truncate. The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
 
 `QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `"<n> 条排队消息"` header whose button expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Each visible ordinary-session row remains a single-line preview with its exact-occurrence edit, delete, and strict-steer actions; addressed subagents retain the rows as a read-only projection because their continuation transport does not expose queue mutation. If strict steer loses to a closed window, the original occurrence remains queued for normal delivery; if the driver already claimed it, normal delivery is already underway. Neither converged race displays a failure, while transport and unknown failures do.
 

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

@@ -34,7 +34,7 @@ Think 行默认保持折叠，并在不展开思维链的情况下暴露实时
 
 审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。运行时 manager 会将所有审批或问题等待通过 `SessionSummary.pendingInteraction` 投影出来，未实例化的 Session 也不例外；`ui-workspace` 负责其侧边栏呈现。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，其中 kebab-case 预设名渲染为 Title Case 标签；普通安全预设会立即经输入栏注入的 `command` 回调提交 `/permission <preset>`，而 `danger-full-access` 在界面中显示为 `Full access`，选择后先打开页面内的 Modal 风险确认。用户勾选确认项前启用按钮始终不可用；取消、Escape、关闭按钮与点击遮罩都不会提交命令。
 
-todo 两个面就是在该形状上的两个注册项，都使用 slot 声明注入，不依赖 `ConversationService`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加 `"<已完成>/<总数> tasks · <n> in progress"`（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
+todo 两个面就是在该形状上的两个注册项，都使用 slot 声明注入，不依赖 `ConversationService`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 经 `toolviews/plan-summary.ts` 的 `planSummary` 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`，以及「其余活跃项的数量」`+<n>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。部署允许并行工作时，可以有多个条目同时处于 `in_progress`，因此 `planSummary` 给出第一个活跃条目并计数其余，且刻意不把两者拼成一个字符串：行会对摘要文本做省略号截断，把数量接在任务名末尾时，窄行最先裁掉的正是这个数量。该行把数量交给 `ToolRow` 的 `summarySuffix`——共享行在被截断文本旁的不收缩位（出错的行会丢弃它，因为其折叠摘要是失败首行）。`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加它自行计算的、以 `·` 连接的各状态计数（本地化，形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略；状态图标为 figma 的勾选／进行中／虚线未开始一组），因此它无需一个可被截断的任务名即可报告并行数量。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
 
 `QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `"<n> 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。普通会话中的每条可见行仍是单行预览，并提供针对精确单次入队项的编辑、删除和严格 steering 操作；已寻址 subagent 则保留只读行，因为其继续执行传输不提供 Queue 变更。如果严格 steering 输给已关闭的窗口，原单次入队项会留在 Queue 中正常投递；如果驱动器已经认领该项，正常投递就已开始。这两种已收敛的竞态都不显示失败，传输和未知错误仍会显示。
 

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

@@ -89,6 +89,20 @@
   text-overflow: clip;
 }
 
+/* Trailing summary fragment kept out of .summary's ellipsis, for a count whose
+   whole value is that it survives a narrow row (the todo row's parallel-active
+   `+n`). Repeats .summary's type because it sits beside that text, and its
+   `nowrap` too: `flex: none` stops the box shrinking but not the text wrapping,
+   which would break the one-line row in the narrow case the slot exists for. */
+.summarySuffix {
+  flex: none;
+  margin-left: 4px;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
 /* File-tool path: same geometry as .summary; hover underline + pointer. */
 .fileLink {
   flex: 1 1 auto;

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

@@ -46,6 +46,14 @@ export interface ToolRowProps {
   icon: ReactNode
   title: string
   summary: string
+  /**
+   * Trailing summary fragment rendered outside the ellipsized summary text, so
+   * a narrow row clips the summary before this. For a fragment whose whole
+   * value is surviving that clip — the todo row's parallel-active count.
+   * null/absent = the summary is the whole collapsed content. Dropped on an
+   * error row, whose collapsed summary is the failure line instead.
+   */
+  summarySuffix?: string | null | undefined
   /** Expanded-body input text; null = no input section. */
   body: string | null
   /** Flattened result text for the expanded Output section; null/absent = no output section. */
@@ -139,6 +147,7 @@ export function ToolRow({
   icon,
   title,
   summary,
+  summarySuffix,
   body,
   output,
   errorSummary,
@@ -173,6 +182,9 @@ export function ToolRow({
   // the error color outranks both the args summary and a terminal description.
   const failureLine = state === 'error' ? errorSummary ?? null : null
   const summaryText = failureLine ?? summary
+  // The failure line replaces the summary wholesale, so a suffix derived from
+  // the call args has nothing left to sit beside.
+  const suffix = failureLine === null ? summarySuffix ?? null : null
   // The failure line is error prose, not the path: no open-file affordance.
   const fileLink = filePath !== undefined && onOpenFile !== undefined && failureLine === null
   const isThink = variant === 'think'
@@ -249,6 +261,7 @@ export function ToolRow({
                 {summaryText}
               </span>
             )}
+            {suffix !== null && <span className={css.summarySuffix}>{suffix}</span>}
           </>
         )}
       >

packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css

@@ -191,6 +191,14 @@
   flex-direction: column;
   min-height: 0;
   overflow-y: auto;
+  /* The column scrolls on ONE axis. Stating `hidden` rather than leaving the
+     initial `visible` is what removes the horizontal bar: a box that scrolls in
+     one axis computes `visible` to `auto` in the other, so any bleed becomes
+     user-scrollable. `.heroGlow` bleeds by construction (1051/776 of the hero
+     box), which put a horizontal scrollbar under every center column narrower
+     than the glow. Clipping is unchanged — `overflow-y: auto` already made this
+     a scroll container that clips both axes, so this only takes away the bar. */
+  overflow-x: hidden;
   /* Reserved unconditionally: the composer seat rides this box's content box in
      Chat and its padding box under a view's composer overlay, so an `auto`
      gutter moves the input card sideways by the bar's width whenever the two

packages/client/ui-conversation/src/client/toolviews/plan-summary.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure plan derivation for the todo_write row's one-line summary. Several items
+ * may be `in_progress` at once — parallel work runs concurrent tasks, so a
+ * summary built from one active item would silently drop the rest. The plan
+ * strip header derives its own counts inline and shares nothing with this, so
+ * this stays inside the toolviews domain rather than in `contract/` (the
+ * inter-domain face).
+ * @module
+ */
+
+/**
+ * One list item as the row sees it: unvalidated model JSON parsed from a call's
+ * args, so any field may be missing or mistyped.
+ */
+export interface PlanItemLike {
+  content?: unknown
+  status?: unknown
+}
+
+/**
+ * Counts plus the two halves of the summary, deliberately NOT pre-joined: the
+ * row ellipsizes its summary text, and a count concatenated onto the end of the
+ * task name is the first thing a narrow row clips — exactly when it carries
+ * information. The row renders `activeExtra` in its own non-shrinking span
+ * beside the truncatable text.
+ */
+export interface PlanSummary {
+  done: number
+  total: number
+  /** First `in_progress` content, or null when that first item is unusable. */
+  activeContent: string | null
+  /** Active items beyond the first; 0 whenever there is no `activeContent` to sit beside. */
+  activeExtra: number
+}
+
+/**
+ * Derive the counts and the active summary from a whole-list snapshot. It names
+ * the first `in_progress` item and counts the remaining active ones, so a
+ * parallel plan reports how many tasks are running rather than naming one and
+ * hiding the others. `activeContent` is null when nothing is in progress, or
+ * when the first active item's content is missing, mistyped, or blank once
+ * trimmed — the tool's own rule for usable content, applied here because a
+ * rejected call keeps its args verbatim. The row then renders the counts alone
+ * rather than falling back to the generic tool summary: the counts are already
+ * known to be good, and the active-item clause is the only part an unusable
+ * name costs.
+ * @param todos - the whole list, in model order.
+ * @returns the done/total counts and the two summary halves.
+ */
+export function planSummary(todos: readonly PlanItemLike[]): PlanSummary {
+  const active = todos.filter(t => t.status === 'in_progress')
+  const first = active[0]?.content
+  const named = typeof first === 'string' && first.trim() !== ''
+  return {
+    done: todos.filter(t => t.status === 'completed').length,
+    total: todos.length,
+    activeContent: named ? first : null,
+    activeExtra: named ? active.length - 1 : 0,
+  }
+}

packages/client/ui-conversation/src/client/toolviews/todo-row.tsx

@@ -2,9 +2,10 @@
 // "Tool call" card, registered into the keyed 'conversation.chat.toolview'
 // hole like the bash sample (a product registration, not a sample). The row
 // composes ToolRow (chrome, running sweep, whole-row expand) and swaps in a
-// summary of the written list (counts + active item) from the call args; the
-// durable list itself renders in the TodoPanel above the composer, so the
-// row stays one line until expanded.
+// summary of the written list (counts + active items) from the call args, with
+// the parallel-active count riding ToolRow's non-shrinking summary suffix so a
+// narrow row never clips it; the durable list itself renders in the TodoPanel
+// above the composer, so the row stays one line until expanded.
 
 import { IconChecklistOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { Context } from 'cordis'
@@ -13,18 +14,26 @@ import type { ToolRowProps } from '../contract/slots.ts'
 import { toolRowModel } from '../contract/tool-call-model.ts'
 import { ToolRow } from '../chat/ToolRow.tsx'
 import { NS } from '../locales.ts'
+import { planSummary, type PlanItemLike } from './plan-summary.ts'
 
 /** Todo row props: the toolview runtime share plus the standard locale seat. */
 type TodoRowProps = ToolRowProps & PropsLocale<'conversation'>
 
-/** One parsed args item, shape-checked (model JSON: any field may be missing or mistyped). */
-interface TodoWriteItem { content?: unknown; status?: unknown }
-
-function isItem(value: unknown): value is TodoWriteItem {
+function isItem(value: unknown): value is PlanItemLike {
   return typeof value === 'object' && value !== null
 }
 
-function summarize(argsRaw: string, t: TodoRowProps['t']): string | null {
+/**
+ * The row's summary split at the ellipsis boundary: `text` truncates, `extra`
+ * is the parallel-active count that must not, so a narrow row never clips the
+ * one part that says several tasks are running.
+ */
+interface RowSummary {
+  text: string
+  extra: number
+}
+
+function summarize(argsRaw: string, t: TodoRowProps['t']): RowSummary | null {
   let parsed: unknown
   try {
     parsed = JSON.parse(argsRaw)
@@ -37,12 +46,12 @@ function summarize(argsRaw: string, t: TodoRowProps['t']): string | null {
   if (typeof parsed !== 'object' || parsed === null) return null
   const todos = (parsed as { todos?: unknown }).todos
   if (!Array.isArray(todos) || !todos.every(isItem)) return null
-  const done = todos.filter(item => item.status === 'completed').length
-  const active = todos.find(item => item.status === 'in_progress')
-  const head = t('todo.completed', { done, total: todos.length })
-  return typeof active?.content === 'string' && active.content !== ''
-    ? `${head} · ${active.content}`
-    : head
+  const { done, total, activeContent, activeExtra } = planSummary(todos)
+  const head = t('todo.completed', { done, total })
+  return {
+    text: activeContent === null ? head : `${head} · ${activeContent}`,
+    extra: activeExtra,
+  }
 }
 
 /** One-line plan update row (the whole row toggles the call's Input/Output
@@ -52,7 +61,7 @@ function summarize(argsRaw: string, t: TodoRowProps['t']): string | null {
 export function TodoRow({ toolName, block, inspect, t }: TodoRowProps) {
   const model = toolRowModel(toolName, block)
   const argsRaw = ('kind' in block ? block.call?.argsRaw : block.argsRaw) ?? ''
-  const summary = summarize(argsRaw, t) ?? model.summary
+  const summary = summarize(argsRaw, t) ?? { text: model.summary, extra: 0 }
   return (
     <ToolRow
       t={t}
@@ -60,7 +69,8 @@ export function TodoRow({ toolName, block, inspect, t }: TodoRowProps) {
       toolName={toolName}
       icon={<IconChecklistOutline14 />}
       title={t('todo.rowTitle')}
-      summary={summary}
+      summary={summary.text}
+      summarySuffix={summary.extra > 0 ? `+${summary.extra}` : null}
       body={model.body}
       output={model.output}
       errorSummary={model.errorSummary}

packages/client/ui-conversation/tests/chat-tool-row.spec.tsx

@@ -301,6 +301,20 @@ describe('ToolRow', () => {
     expect(view.getByText('List files')).toBeTruthy()
   })
 
+  it('renders summarySuffix outside the ellipsized summary span, and drops it on a failure line', () => {
+    const view = render(<ToolRow {...rowProps} summarySuffix="+2" />)
+    const summary = view.getByText('List files')
+    const suffix = view.getByText('+2')
+    // Separate spans: .summary truncates, the suffix must not travel inside it.
+    expect(summary.contains(suffix)).toBe(false)
+    view.unmount()
+    // The failure line replaces the summary wholesale, so the suffix goes with it.
+    const failed = render(
+      <ToolRow {...rowProps} state="error" errorSummary="boom" summarySuffix="+2" />,
+    )
+    expect(failed.queryByText('+2')).toBeNull()
+  })
+
   it('an error file row drops the open-file link (the summary is failure prose, not the path)', () => {
     const open = vi.fn()
     const view = render(

packages/client/ui-conversation/tests/todo-panel.spec.tsx

@@ -1,10 +1,13 @@
 // @vitest-environment jsdom
 /**
- * Todo display acceptance: the TodoPanel plan strip (empty-hidden, status
- * rows, collapse), its TodoDock adapter (selects the plan off the session
- * snapshot and follows changes), and the todo_write toolview row (progress
- * summary from args, generic fallback on malformed JSON, shared ToolRow
- * state dots and leading expansion).
+ * Todo display acceptance: the TodoPanel plan strip (empty-hidden, status rows
+ * including several `in_progress` at once, collapse), its TodoDock adapter
+ * (selects the plan off the session snapshot and follows changes), the row's
+ * plan summary (counts plus the two halves of the active summary — the named
+ * task and the `+N` count that parallel work adds, kept apart so the row never
+ * ellipsizes the count away), and the todo_write toolview row (progress summary
+ * from args, generic fallback on malformed JSON, shared ToolRow state dots and
+ * leading expansion).
  */
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -17,6 +20,7 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import { TodoRow, todoToolview } from '../src/client/toolviews/todo-row.tsx'
 import type { TodoDockProps } from '../src/client/skeleton/TodoPanel.tsx'
 import { TodoDock, TodoPanel, todoDockEntry } from '../src/client/skeleton/TodoPanel.tsx'
+import { planSummary } from '../src/client/toolviews/plan-summary.ts'
 import { NS, zh } from '../src/client/locales.ts'
 
 type TodoRowProps = Parameters<typeof TodoRow>[0]
@@ -32,6 +36,49 @@ const LIST: TodoItem[] = [
   { content: '补测试', status: 'pending' },
 ]
 
+/** A parallel plan: three tasks running at once (concurrent subagents). */
+const PARALLEL: TodoItem[] = [
+  { content: '搭骨架', status: 'completed' },
+  { content: '写组件', status: 'in_progress' },
+  { content: '跑后台构建', status: 'in_progress' },
+  { content: '读源码', status: 'in_progress' },
+  { content: '补测试', status: 'pending' },
+]
+
+describe('planSummary', () => {
+  it('counts done/total and names the single active item with no extra count', () => {
+    expect(planSummary(LIST)).toEqual({ done: 1, total: 3, activeContent: '写组件', activeExtra: 0 })
+  })
+
+  it('reports the extra active count separately when several items are in progress', () => {
+    // Parallel work marks several: naming one and hiding the rest would lose
+    // them, and the count stays unjoined so the row cannot ellipsize it.
+    expect(planSummary(PARALLEL)).toEqual({ done: 1, total: 5, activeContent: '写组件', activeExtra: 2 })
+  })
+
+  it('has no hint when nothing is in progress', () => {
+    expect(planSummary([{ content: '都完了', status: 'completed' }]))
+      .toEqual({ done: 1, total: 1, activeContent: null, activeExtra: 0 })
+  })
+
+  it('has no hint when the first active item carries no usable content (model JSON)', () => {
+    // Unvalidated args: a missing, mistyped, empty, or whitespace-only content
+    // yields no hint — and no orphan count, even with a second active item to
+    // count. Whitespace-only is the tool's own rejection rule (trimmed
+    // non-empty), and a rejected call keeps its args verbatim.
+    expect(planSummary([{ status: 'in_progress' }, { content: 'x', status: 'in_progress' }]))
+      .toMatchObject({ activeContent: null, activeExtra: 0 })
+    expect(planSummary([{ content: 42, status: 'in_progress' }]).activeContent).toBeNull()
+    expect(planSummary([{ content: '', status: 'in_progress' }]).activeContent).toBeNull()
+    expect(planSummary([{ content: '   ', status: 'in_progress' }, { content: 'x', status: 'in_progress' }]))
+      .toMatchObject({ activeContent: null, activeExtra: 0 })
+  })
+
+  it('is empty-safe', () => {
+    expect(planSummary([])).toEqual({ done: 0, total: 0, activeContent: null, activeExtra: 0 })
+  })
+})
+
 describe('TodoPanel', () => {
   it('renders nothing while the list is empty', () => {
     const { container } = render(<TodoPanel todos={[]} t={t} />)
@@ -80,6 +127,18 @@ describe('TodoPanel', () => {
     expect(screen.getAllByRole('listitem')).toHaveLength(3)
   })
 
+  it('marks every parallel active item, and counts them all in the header', () => {
+    render(<TodoPanel todos={PARALLEL} t={t} />)
+    fireEvent.click(screen.getByRole('button', { expanded: false }))
+    // The old unconditional cap made this list unreachable: three items carry
+    // the in-progress glyph at once, and the header counts all three.
+    const statuses = screen.getAllByRole('listitem').map(li => li.getAttribute('data-status'))
+    expect(statuses.filter(s => s === 'in_progress')).toHaveLength(3)
+    expect(screen.getByText('跑后台构建')).toBeTruthy()
+    expect(screen.getByText('读源码')).toBeTruthy()
+    expect(screen.getByText('1 已完成 · 3 进行中 · 1 待处理')).toBeTruthy()
+  })
+
   it('an all-completed list collapses the summary to the done count alone', () => {
     render(<TodoPanel todos={[{ content: '都完了', status: 'completed' }]} t={t} />)
     expect(screen.getByRole('button', { expanded: false })).toBeTruthy()
@@ -145,12 +204,30 @@ describe('TodoRow', () => {
     expect(screen.getByText('1/3 已完成 · 写组件')).toBeTruthy()
   })
 
+  it('reports the extra active count outside the ellipsized summary text', () => {
+    const { container } = render(<TodoRow {...rowProps(resultNode(JSON.stringify({ todos: PARALLEL })))} />)
+    const text = screen.getByText('1/5 已完成 · 写组件')
+    const extra = screen.getByText('+2')
+    // Separate spans: .summary truncates, the count must not travel inside it.
+    expect(text.contains(extra)).toBe(false)
+    expect(container.textContent).toContain('1/5 已完成 · 写组件+2')
+  })
+
   it('omits the active clause when no item is in progress and reads running-call args', () => {
     const args = JSON.stringify({ todos: [{ content: 'x', status: 'completed' }] })
     render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null })} />)
     expect(screen.getByText('1/1 已完成')).toBeTruthy()
   })
 
+  it('keeps the counts when an active item has unusable content, instead of the generic summary', () => {
+    // planSummary yields activeContent null here, but the counts are known good,
+    // so the row drops only the active clause — `?? model.summary` never runs.
+    const args = JSON.stringify({ todos: [{ content: 'done', status: 'completed' }, { content: 42, status: 'in_progress' }] })
+    const { container } = render(<TodoRow {...rowProps(resultNode(args))} />)
+    expect(screen.getByText('1/2 已完成')).toBeTruthy()
+    expect(container.textContent).not.toContain('+')
+  })
+
   it('keeps the non-ok execution states visible through the shared row states', () => {
     // A running call (no result yet) carries the running state (row sweep).
     const args = JSON.stringify({ todos: LIST })

packages/client/ui-conversation/tests/tool-row-styles.spec.ts

@@ -0,0 +1,45 @@
+/**
+ * The one-line contract of the ToolRow summary line as CSS text. jsdom has no
+ * layout, so the rendering specs (chat-tool-row.spec.tsx) can pin which spans
+ * exist but not whether a narrow row still fits on one line; these read the
+ * declarations the layout depends on.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const css = readFileSync(fileURLToPath(new URL('../src/client/chat/ToolRow.module.css', import.meta.url)), 'utf8')
+/** Declarations only: the sheet's prose names the properties it explains. */
+const declarationText = css.replace(/\/\*[\s\S]*?\*\//g, ' ')
+
+function declarations(selector: string): string[] {
+  // Anchored at a rule boundary: an unanchored match would silently read a
+  // compound rule that merely contains the selector (`.root:hover .summarySuffix`)
+  // if one ever lands above the base rule.
+  const rule = new RegExp(`(?:^|\\})\\s*\\${selector}\\s*\\{([^{}]*)\\}`).exec(declarationText)
+  if (rule === null) throw new Error(`ToolRow.module.css has no \`${selector}\` rule`)
+  return (rule[1] ?? '').split(';').map(part => part.trim()).filter(Boolean)
+}
+
+describe('ToolRow.module.css summary line', () => {
+  it('keeps the summary suffix on one line and unshrunk', () => {
+    // `flex: none` stops the box shrinking, not the text wrapping: without
+    // `nowrap`, a row too narrow for title + separator + suffix wraps the `+n`
+    // onto a second line — the exact case the slot exists to survive.
+    expect(declarations('.summarySuffix')).toEqual(expect.arrayContaining([
+      'flex: none',
+      'white-space: nowrap',
+    ]))
+  })
+
+  it('leaves the truncation to the summary text alone', () => {
+    // The suffix must never ellipsize: a clipped count reads as a smaller
+    // number rather than as missing information.
+    expect(declarations('.summary')).toEqual(expect.arrayContaining([
+      'overflow: hidden',
+      'text-overflow: ellipsis',
+      'white-space: nowrap',
+    ]))
+    expect(declarations('.summarySuffix')).not.toEqual(expect.arrayContaining(['text-overflow: ellipsis']))
+  })
+})

packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx

@@ -7,7 +7,7 @@
 import { useEffect, useRef } from 'react'
 import type { ReactNode } from 'react'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import { BrandWordmark, Button } from '@deepseek-ai/dsh-client-ui-primitives'
+import { BrandWordmark, Button, OnboardingSurface } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
 import type { ModelsSettingsState, ModelsSettingsStore } from './store.ts'
 import { deepSeekReadiness } from './store.ts'
@@ -66,6 +66,9 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
     openSection('models')
   }
 
+  // Null covers the still-deciding and nothing-to-do states alike: the
+  // takeover chrome below is part of THIS render, so declining paints and
+  // blocks nothing while the shared join is in flight.
   switch (readiness.kind) {
     case 'loading':
     case 'adapter-absent':
@@ -80,25 +83,27 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
   }
 
   return (
-    <section className={styles['page']} role="region" aria-labelledby="deepseek-onboarding-title">
-      <div className={styles['brand']} aria-hidden="true"><BrandWordmark size={24} /></div>
-      <h2
-        ref={titleRef}
-        id="deepseek-onboarding-title"
-        className={styles['title']}
-        tabIndex={-1}
-      >
-        {t('onboardingTitle')}
-      </h2>
-      <p className={styles['description']}>{t('onboardingDescription')}</p>
-      <div className={styles['actions']}>
-        <Button variant="ghost" className={styles['later']} onClick={complete}>
-          {t('onboardingLater')}
-        </Button>
-        <Button variant="primary" className={styles['primary']} onClick={openModels}>
-          {t('onboardingGoToSettings')}
-        </Button>
-      </div>
-    </section>
+    <OnboardingSurface>
+      <section className={styles['page']} role="region" aria-labelledby="deepseek-onboarding-title">
+        <div className={styles['brand']} aria-hidden="true"><BrandWordmark size={24} /></div>
+        <h2
+          ref={titleRef}
+          id="deepseek-onboarding-title"
+          className={styles['title']}
+          tabIndex={-1}
+        >
+          {t('onboardingTitle')}
+        </h2>
+        <p className={styles['description']}>{t('onboardingDescription')}</p>
+        <div className={styles['actions']}>
+          <Button variant="ghost" className={styles['later']} onClick={complete}>
+            {t('onboardingLater')}
+          </Button>
+          <Button variant="primary" className={styles['primary']} onClick={openModels}>
+            {t('onboardingGoToSettings')}
+          </Button>
+        </div>
+      </section>
+    </OnboardingSurface>
   )
 }

packages/client/ui-primitives/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-primitives/README.md
-README.md: 385730c94831d2fd4af83f9eca0f55941551c796
-README.zh.md: b8a75dbffc6549f6294dfda5988c67d6569386c9
+README.md: 7571cb48424b650a1aaa5222b33a3ee14faa69b4
+README.zh.md: fa0c3f24023ec8c1eb77553bfe191801b6698687

packages/client/ui-primitives/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock. Contract: api-contracts v3 §8.
+Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock. Contract: api-contracts v3 §8.
 
 ## Hover cards
 

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

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。契约：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。契约：api-contracts v3 §8。
 
 ## 悬浮卡片
 

packages/client/ui-primitives/src/OnboardingSurface.module.css

@@ -0,0 +1,29 @@
+/* First-run stage: keep the product top bar visible, then let onboarding own
+   the complete workspace instead of presenting another settings modal. */
+.onboardingOverlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1100;
+}
+
+/* Mask */
+.onboardingMask {
+  position: absolute;
+  left: 0px;
+  right: 0px;
+  top: 80px;
+  bottom: 0px;
+  background: rgba(0, 0, 0, 0.24);
+  /* Mask-blur */
+  backdrop-filter: blur(2px);
+}
+
+.onboardingStage {
+  position: absolute;
+  z-index: 1;
+  inset: 0;
+  display: flex;
+  justify-content: center;
+  overflow: hidden;
+  background: var(--dsw-alias-bg-layer-1);
+}

packages/client/ui-primitives/src/OnboardingSurface.tsx

@@ -0,0 +1,34 @@
+// OnboardingSurface: the full-viewport first-run takeover an onboarding step
+// wraps its visible content in. The overlay portals to this document's body
+// (the Modal precedent: ancestor stacking contexts cannot leave sticky page
+// controls above the mask), and the surface holds `#root` inert for exactly
+// its own lifetime — a step that renders null paints nothing and blocks
+// nothing, so "should onboarding show right now" stays a plain render
+// decision inside the step component.
+
+import { useEffect } from 'react'
+import type { ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import css from './OnboardingSurface.module.css'
+
+/**
+ * Render the onboarding takeover chrome (mask + opaque stage) around one
+ * step's content and keep the application root inert while mounted.
+ * @param props.children - the step's page content, centered on the stage.
+ * @returns the body-portaled overlay tree.
+ */
+export function OnboardingSurface({ children }: { children: ReactNode }) {
+  useEffect(() => {
+    const appRoot = document.getElementById('root')
+    if (appRoot === null) return
+    appRoot.inert = true
+    return () => { appRoot.inert = false }
+  }, [])
+
+  return createPortal((
+    <div className={css.onboardingOverlay} role="presentation">
+      <div className={css.onboardingMask} aria-hidden="true" />
+      <div className={css.onboardingStage}>{children}</div>
+    </div>
+  ), document.body)
+}

packages/client/ui-primitives/src/index.ts

@@ -13,6 +13,7 @@ export type { MenuEntry, MenuItem, MenuSeparator, MenuLabel } from './Menu.tsx'
 export { useAnchoredMaxHeight } from './useAnchoredMaxHeight.ts'
 export { HoverCard } from './HoverCard.tsx'
 export { Modal } from './Modal.tsx'
+export { OnboardingSurface } from './OnboardingSurface.tsx'
 export { RiskConfirmation } from './RiskConfirmation.tsx'
 export type { RiskConfirmationProps } from './RiskConfirmation.tsx'
 export { ConnectionBanner } from './ConnectionBanner.tsx'

packages/client/ui-primitives/tests/onboarding-surface.spec.tsx

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { OnboardingSurface } from '@deepseek-ai/dsh-client-ui-primitives'
+
+let appRoot: HTMLDivElement
+
+beforeEach(() => {
+  appRoot = document.createElement('div')
+  appRoot.id = 'root'
+  document.body.appendChild(appRoot)
+})
+
+afterEach(() => {
+  cleanup()
+  appRoot.remove()
+})
+
+describe('OnboardingSurface', () => {
+  it('portals the overlay chrome to document.body around its content', () => {
+    const view = render(<OnboardingSurface><p>step content</p></OnboardingSurface>)
+    // Portaled: the overlay is a body child, not inside the render container.
+    expect(view.container.querySelector('[class*="onboardingOverlay"]')).toBeNull()
+    const overlay = document.body.querySelector('[class*="onboardingOverlay"]')
+    expect(overlay).not.toBeNull()
+    // The onboarding e2e pins the mask by class substring; the stage carries
+    // the content.
+    expect(overlay!.querySelector('[class*="onboardingMask"]')).not.toBeNull()
+    const stage = overlay!.querySelector('[class*="onboardingStage"]')
+    expect(stage).not.toBeNull()
+    expect(stage!.textContent).toBe('step content')
+  })
+
+  it('holds #root inert for exactly its own lifetime', () => {
+    const view = render(<OnboardingSurface>x</OnboardingSurface>)
+    expect(appRoot.inert).toBe(true)
+    view.unmount()
+    expect(appRoot.inert).toBe(false)
+  })
+
+  it('renders without an #root element (compositions that mount elsewhere)', () => {
+    appRoot.remove()
+    const view = render(<OnboardingSurface>x</OnboardingSurface>)
+    expect(document.body.querySelector('[class*="onboardingStage"]')!.textContent).toBe('x')
+    view.unmount()
+  })
+})

packages/client/ui-settings-general/src/client/WelcomeNotice.tsx

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useRef } from 'react'
 import type { ReactNode } from 'react'
 import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import { BrandWordmark, Button } from '@deepseek-ai/dsh-client-ui-primitives'
+import { BrandWordmark, Button, OnboardingSurface } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
 import type { WelcomeNoticeState, WelcomeNoticeStore } from './welcome-store.ts'
 import css from './WelcomeNotice.module.css'
@@ -55,6 +55,9 @@ export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode {
     if (state.status === 'ready' && !state.acknowledged) titleRef.current?.focus()
   }, [state.acknowledged, state.status])
 
+  // Null while the acknowledgement fact is still loading (or already given):
+  // the takeover chrome below is part of THIS render, so deciding not to
+  // show paints and blocks nothing.
   if (state.status === 'idle' || state.status === 'loading' || state.acknowledged) return null
 
   const acknowledge = async (): Promise<void> => {
@@ -62,25 +65,27 @@ export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode {
   }
 
   return (
-    <section className={css.page} role="region" aria-labelledby="welcome-notice-title">
-      <div className={css.brand} aria-hidden="true"><BrandWordmark size={24} /></div>
-      <h2 ref={titleRef} id="welcome-notice-title" className={css.title} tabIndex={-1}>{t('welcome.title')}</h2>
-      <p className={css.opening}>{t('welcome.paragraph.0')}</p>
-      <blockquote className={css.reflection}>{t('welcome.paragraph.1')}</blockquote>
-      <p className={css.feedback}>
-        {emphasizedFeedback(t('welcome.paragraph.2'), t('welcome.feedbackEmphasis'))}
-      </p>
-      {state.error === null ? null : <p className={css.error} role="alert">{t('welcome.error')}</p>}
-      <div className={css.footer}>
-        <Button
-          variant="primary"
-          className={css.primary}
-          disabled={state.status === 'saving'}
-          onClick={() => { void acknowledge() }}
-        >
-          {t('welcome.continue')}
-        </Button>
-      </div>
-    </section>
+    <OnboardingSurface>
+      <section className={css.page} role="region" aria-labelledby="welcome-notice-title">
+        <div className={css.brand} aria-hidden="true"><BrandWordmark size={24} /></div>
+        <h2 ref={titleRef} id="welcome-notice-title" className={css.title} tabIndex={-1}>{t('welcome.title')}</h2>
+        <p className={css.opening}>{t('welcome.paragraph.0')}</p>
+        <blockquote className={css.reflection}>{t('welcome.paragraph.1')}</blockquote>
+        <p className={css.feedback}>
+          {emphasizedFeedback(t('welcome.paragraph.2'), t('welcome.feedbackEmphasis'))}
+        </p>
+        {state.error === null ? null : <p className={css.error} role="alert">{t('welcome.error')}</p>}
+        <div className={css.footer}>
+          <Button
+            variant="primary"
+            className={css.primary}
+            disabled={state.status === 'saving'}
+            onClick={() => { void acknowledge() }}
+          >
+            {t('welcome.continue')}
+          </Button>
+        </div>
+      </section>
+    </OnboardingSurface>
   )
 }

packages/client/ui-settings/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-settings/README.md
-README.md: de78d599b7833179339ceeb680fbd665b056bd83
-README.zh.md: 8ae3bdf34f59ca03e4796c354df739aa9fe29bd9
+README.md: 785f0417f00ec8eb1f8c9273b4d81f8ca5ca1810
+README.zh.md: 8e7bd7325b78416345985ee25a56a5eb8b382478

packages/client/ui-settings/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.action` (ordered content-header actions), `settings.section` (one page per feature), and `settings.onboarding` (ordered feature-owned pages in a full-viewport stage). The shell ships no copy of its own — all text arrives from registrants (ui-settings-general owns chrome, General, and the product notice; features own their actions, sections, rows, and conditional onboarding pages). Nav labels may be locale-following thunks, so the nav projection resolves them through `resolveSlotLabel` and re-renders on the section ledger bump or the locale revision (an optional `ctx.get('locale')` read; no hard locale dependency).
 
-The shell projects the onboarding ledger into ascending order and mounts exactly one page at a time in a body-level stage while marking the underlying app root inert. The active registrant receives its id, `complete()`, and an `openSection(id)` callback; completing or skipping transfers ownership to the next entry. Registrants own durable completion, capability readiness, copy, and mutations, so independently registered flows cannot stack and the shell does not become a second configuration fact source.
+The shell projects the onboarding ledger into ascending order and mounts exactly one page at a time; the takeover chrome (body-level stage, mask, app-root `inert`) belongs to the step itself through ui-primitives' `OnboardingSurface`, so a mounted step still resolving its private facts renders null and neither paints nor blocks anything — the shell shows no empty stage while a step decides. The active registrant receives its id, `complete()`, and an `openSection(id)` callback; completing or skipping transfers ownership to the next entry. Registrants own durable completion, capability readiness, copy, mutations, and the surface wrap, so independently registered flows cannot stack and the shell does not become a second configuration fact source.
 
 ## Model Experience
 

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

@@ -4,7 +4,7 @@
 
 设置外壳插件：一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`，并声明由注册方填充的 slot：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）、`settings.action`（内容标题栏中的有序操作）、`settings.section`（每项功能一页）和 `settings.onboarding`（由各功能持有、显示在全视口展示层中的有序页面）。外壳不自带文案：所有文本都来自注册方（ui-settings-general 拥有界面框架、「通用」分区和产品声明；各功能拥有各自的操作、分区、行和条件式首次使用引导页面）。导航 label 可以是跟随语言的 thunk，因此导航投影经 `resolveSlotLabel` 解析，并在分区账本更新或 locale revision 变化时重新渲染（`ctx.get('locale')` 可选读取，无硬 locale 依赖）。
 
-外壳将首次使用引导记录按升序投影，在 body 层级的展示层中每次只挂载一个页面，同时将下层应用根节点标记为 `inert`。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前页面后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案和变更操作均由注册方持有，因此独立注册的流程无法堆叠，外壳也不会成为第二个配置事实来源。
+外壳将首次使用引导记录按升序投影，每次只挂载一个页面；接管界面框架（body 层级的展示层、遮罩、应用根节点 `inert`）经 ui-primitives 的 `OnboardingSurface` 由步骤自身持有，因此已挂载但仍在判定私有事实的步骤渲染 null 时不绘制也不阻塞任何内容——步骤判定期间外壳不会露出空白展示层。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前页面后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案、变更操作以及页面的外层包裹均由注册方持有，因此独立注册的流程无法堆叠，外壳也不会成为第二个配置事实来源。
 
 ## 模型体验
 

packages/client/ui-settings/src/client/SettingsRoot.module.css

@@ -219,33 +219,3 @@
   clip: rect(0 0 0 0);
   white-space: nowrap;
 }
-
-/* First-run stage: keep the product top bar visible, then let onboarding own
-   the complete workspace instead of presenting another settings modal. */
-.onboardingOverlay {
-  position: fixed;
-  inset: 0;
-  z-index: 1100;
-}
-
-/* Mask */
-.onboardingMask {
-  position: absolute;
-  left: 0px;
-  right: 0px;
-  top: 80px;
-  bottom: 0px;
-  background: rgba(0, 0, 0, 0.24);
-  /* Mask-blur */
-  backdrop-filter: blur(2px);
-}
-
-.onboardingStage {
-  position: absolute;
-  z-index: 1;
-  inset: 0;
-  display: flex;
-  justify-content: center;
-  overflow: hidden;
-  background: var(--dsw-alias-bg-layer-1);
-}

packages/client/ui-settings/src/client/SettingsRoot.tsx

@@ -7,10 +7,11 @@
  * aria-labelledby the title node; close: visually-hidden slot text). Modal
  * open state and the active section id are component-local viewing state;
  * the onboarding coordinator mounts exactly one ordered registrant while the
- * sessions-derived empty-Hero fact is active.
+ * sessions-derived empty-Hero fact is active — the takeover chrome
+ * (OnboardingSurface) belongs to the step, so a mounted-but-deciding step
+ * paints nothing here.
  */
 import { useCallback, useEffect, useId, useRef, useState } from 'react'
-import { createPortal } from 'react-dom'
 import clsx from 'clsx'
 import { IconCloseOutline16, IconDataOutline16, IconSettingsOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SettingsRootComponentProps, SettingsSectionRow } from './contract/slots.ts'
@@ -134,14 +135,6 @@ export function SettingsRoot(props: SettingsRootComponentProps) {
     })
   }, [])
 
-  useEffect(() => {
-    if (onboardingStep === undefined) return
-    const appRoot = document.getElementById('root')
-    if (appRoot === null) return
-    appRoot.inert = true
-    return () => { appRoot.inert = false }
-  }, [onboardingStep])
-
   return (
     <>
       <button
@@ -162,18 +155,15 @@ export function SettingsRoot(props: SettingsRootComponentProps) {
           onClose={close}
         />
       )}
-      {onboardingStep !== undefined && createPortal((
-        <div className={css.onboardingOverlay} role="presentation">
-          <div className={css.onboardingMask} aria-hidden="true" />
-          <div className={css.onboardingStage}>
-            {renderSlot('settings.onboarding', {
-              stepId: onboardingStep.id,
-              complete: () => { completeOnboardingStep(onboardingStep.id) },
-              openSection,
-            }, { only: onboardingStep.id })}
-          </div>
-        </div>
-      ), document.body)}
+      {/* The takeover chrome (OnboardingSurface: mask, opaque stage, `#root`
+          inert) lives inside the step component, wrapped around its visible
+          content — a step still deciding (private facts loading) renders
+          null, so nothing paints or blocks while it decides. */}
+      {onboardingStep !== undefined && renderSlot('settings.onboarding', {
+        stepId: onboardingStep.id,
+        complete: () => { completeOnboardingStep(onboardingStep.id) },
+        openSection,
+      }, { only: onboardingStep.id })}
     </>
   )
 }

packages/client/ui-settings/src/client/contract/slots.ts

@@ -57,7 +57,13 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * Root-scoped onboarding steps contributed by settings features. The
      * shell mounts one ordered step at a time; the active registrant either
      * completes itself or keeps ownership until the user completes its sole
-     * path. Registrants own readiness, copy, and dialog behavior.
+     * path. Registrants own readiness, copy, dialog behavior, AND the
+     * takeover chrome: a step wraps its visible content in the
+     * OnboardingSurface primitive (mask, opaque stage, `#root` inert) and
+     * renders null while its private facts are still loading — the shell
+     * paints no chrome of its own, so a mounted-but-deciding step shows and
+     * blocks nothing (the reload white-flash fix; a bare unwrapped step
+     * would render without mask or stage).
      */
     'settings.onboarding': { kind: 'list'; scope: 'root'; owner: SettingsOnboardingOwnerProps }
   }

packages/client/ui-settings/tests/settings-root.spec.tsx

@@ -204,14 +204,19 @@ describe('SettingsPanel navigation', () => {
     expect(inactive).toHaveLength(0)
   })
 
-  it('makes the underlying application inert while onboarding owns the viewport', () => {
+  it('paints no takeover chrome of its own around the mounted step', () => {
+    // The chrome (mask, opaque stage, #root inert) belongs to the step via
+    // the OnboardingSurface primitive — a mounted-but-deciding step that
+    // renders null must show and block nothing (the reload white-flash fix;
+    // onboarding-surface.spec.tsx pins the primitive's half).
     const appRoot = document.createElement('div')
     appRoot.id = 'root'
     document.body.append(appRoot)
     const { view } = mount()
-    expect(appRoot.inert).toBe(true)
+    expect(view.container.querySelector('[class*="onboarding"]')).toBeNull()
+    expect(document.body.querySelector('[class*="onboarding"]')).toBeNull()
+    expect(appRoot.inert).not.toBe(true)
     view.unmount()
-    expect(appRoot.inert).toBe(false)
     appRoot.remove()
   })