Merge branch 'master' into worktree/provider-credential-lifecycle

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/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/*/*`.
+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 `packages/bundle/web-app/cordis.patch.yml`; a `packages/bundle/web-app/package.json` dependency (profile boots resolve bare row names through the healed `$DSH_HOME/profiles/node_modules` fallback, which mirrors the app's and each bundle's declared dependencies — a row whose package no manifest declares 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**: apply order is unconstrained, and a business service is not a declaration barrier. Use `ctx.slots.inject(name, () => ctx.slots.register(...))`; it waits on the actual declaration, removes the contribution when that declaration collapses, reruns after redeclaration, and leaves with the caller's plugin fiber. Return a generator yielding each registration when several contributions must install and roll back atomically. A bare `slots.register` into an undeclared slot remains an error; keep service edges only for services the contribution actually reads.
 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/runtime/src/client/sessions/lineage.ts

@@ -29,6 +29,8 @@ export interface SessionListEntry {
   projectionValues?: Readonly<Partial<SessionProjectionMap>>
   /** User interaction currently blocking this session, derived from live mux frames. */
   pendingInteraction?: PendingInteractionStatus
+  /** Finished running while not selected and not yet opened — the sidebar's green "done" reminder (clears on select or the next run). */
+  completed: boolean
   /** Lineage indent depth: root = 0; the UI just multiplies by the indent width. */
   depth: number
 }
@@ -39,11 +41,13 @@ export interface SessionListEntry {
  * hydrated list from mutable timestamps.
  * @param summaries - the host's session.list items.
  * @param pendingInteractions - current manager-owned interaction status by session.
+ * @param completed - sessions with a pending completion reminder (manager-owned live fact; absent = false).
  * @returns display rows in render order.
  */
 export function flattenLineage(
   summaries: readonly TitledSessionSummary[],
   pendingInteractions?: ReadonlyMap<SessionId, PendingInteractionStatus>,
+  completed?: ReadonlySet<SessionId>,
 ): SessionListEntry[] {
   const byId = new Map<SessionId, TitledSessionSummary>()
   for (const s of summaries) byId.set(s.sessionId, s)
@@ -72,6 +76,7 @@ export function flattenLineage(
     out.push({
       ...s,
       ...(pendingInteraction === undefined ? {} : { pendingInteraction }),
+      completed: completed?.has(s.sessionId) ?? false,
       depth,
     })
     const kids = children.get(s.sessionId)

packages/client/runtime/src/client/sessions/manager.ts

@@ -109,6 +109,14 @@ export class SessionManager {
    *  sessions never instantiated. Cleared per connection generation — the reopen replay re-adds
    *  still-pending requests — and on session-removed. */
   private readonly pendingInteractions = new Map<SessionId, Map<string, PendingInteractionStatus>>()
+  /**
+   * Sessions that finished running while not selected — the sidebar's green
+   * "done" reminder (manager-owned, survives connection generations; cleared
+   * on select and session-removed, re-armed by the next completion).
+   */
+  private readonly completedNotifications = new Set<SessionId>()
+  /** Last-observed running bits per session; the true→false edge here arms {@link completedNotifications}. */
+  private readonly prevRunning = new Map<SessionId, boolean>()
   /** Per-session projection value stores, retained independently of instance arrival (the
    *  title-snapshot precedent, generalized): push frames land here whether or not the Session
    *  is instantiated (list rows read the 'title' key), and an instantiated Session adopts the
@@ -175,6 +183,8 @@ export class SessionManager {
         : this.catalogs.get(address.parentSessionId)?.parentAvailable ?? false,
     )
     this.selected = sessionId
+    // Looking at the session consumes its completion reminder (dot clears).
+    this.completedNotifications.delete(sessionId)
     void this.refreshSubagents(sessionId)
     this.notifier.notifyNow()
   }
@@ -192,6 +202,7 @@ export class SessionManager {
     this.addresses.set(address.childSessionId, address)
     this.sessions.get(address.childSessionId)?.configureSubagent(address, catalog?.parentAvailable ?? false)
     this.selected = address.childSessionId
+    this.completedNotifications.delete(address.childSessionId)
     void this.refreshSubagents(address.childSessionId)
     this.notifier.notifyNow()
   }
@@ -414,13 +425,28 @@ export class SessionManager {
       try {
         const { result } = await this.api.sessions.list({})
         if (result.ok) {
-          let summaries = this.listPhase === 'pending'
+          const baseline = this.listPhase === 'pending'
             ? result.value.items
             : mergeOrderedBaseline(established, result.value.items, summary => summary.sessionId)
-          for (const mutation of mutations) summaries = applyMutation(summaries, mutation)
+          // Seed first observations from the pull-time baseline BEFORE replaying
+          // in-flight mutations, then reconcile the reminders after EVERY
+          // replayed mutation: an edge that happens entirely between mutations
+          // (baseline idle → running → idle) must still arm, which a single
+          // sync on the folded result would collapse away.
+          for (const s of baseline) {
+            if (!this.prevRunning.has(s.sessionId)) this.prevRunning.set(s.sessionId, s.running)
+          }
+          let summaries = baseline
+          for (const mutation of mutations) {
+            summaries = applyMutation(summaries, mutation)
+            this.summaries = summaries
+            this.syncCompletedNotifications()
+          }
           this.summaries = summaries
           this.listState = 'idle'
           this.listPhase = 'ready'
+          // Covers the empty-mutations pull (a plain baseline carries no edge).
+          this.syncCompletedNotifications()
           // Push running/blank bits down to instantiated Sessions (the list is the authoritative summary source).
           for (const s of this.summaries) {
             const session = this.sessions.get(s.sessionId)
@@ -566,6 +592,8 @@ export class SessionManager {
   private recordMutation(mutation: SessionListMutation): void {
     this.listMutations?.push(mutation)
     this.summaries = applyMutation(this.summaries, mutation)
+    // Eager edge reconciliation — a snapshot-build-time pass would miss consecutive status frames.
+    this.syncCompletedNotifications()
     this.notifier.markDirty()
   }
 
@@ -893,6 +921,38 @@ export class SessionManager {
     })
   }
 
+  /**
+   * Reconcile completion reminders against the latest summaries, eagerly after
+   * every mutation and pull (a snapshot-build-time pass would collapse
+   * consecutive status frames into one observation). A running→idle edge of a
+   * non-selected session arms its reminder; running disarms it; removal drops
+   * it. First observation only records the running bit — sessions already
+   * idle at load get no reminder.
+   */
+  private syncCompletedNotifications(): void {
+    const seen = new Set<SessionId>()
+    for (const s of this.summaries) {
+      seen.add(s.sessionId)
+      const prev = this.prevRunning.get(s.sessionId)
+      if (prev === undefined) {
+        this.prevRunning.set(s.sessionId, s.running)
+        continue
+      }
+      if (prev && !s.running) {
+        if (s.sessionId !== this.selected) this.completedNotifications.add(s.sessionId)
+      } else if (s.running) {
+        this.completedNotifications.delete(s.sessionId)
+      }
+      this.prevRunning.set(s.sessionId, s.running)
+    }
+    for (const id of this.prevRunning.keys()) {
+      if (!seen.has(id)) this.prevRunning.delete(id)
+    }
+    for (const id of this.completedNotifications) {
+      if (!seen.has(id)) this.completedNotifications.delete(id)
+    }
+  }
+
   private buildListSnapshot(): SessionListSnapshot {
     const merged: TitledSessionSummary[] = this.summaries.map((summary) => {
       // List rows read the generic 'title' projection key (host-computed unit
@@ -914,7 +974,7 @@ export class SessionManager {
       const status = statuses.find(candidate => candidate !== 'approval') ?? statuses[0]
       if (status !== undefined) pendingInteractions.set(sessionId, status)
     }
-    const fresh = flattenLineage(merged, pendingInteractions)
+    const fresh = flattenLineage(merged, pendingInteractions, this.completedNotifications)
     const items = fresh.map((entry) => {
       const prev = this.entryCache.get(entry.sessionId)
       if (
@@ -924,6 +984,7 @@ export class SessionManager {
         && prev.origin === entry.origin && prev.title === entry.title && prev.depth === entry.depth
         && prev.pendingInteraction === entry.pendingInteraction
         && prev.projectionValues === entry.projectionValues
+        && prev.completed === entry.completed
       ) return prev
       this.entryCache.set(entry.sessionId, entry)
       return entry

packages/client/runtime/src/client/sessions/service.ts

@@ -51,6 +51,8 @@ export interface SessionSummary {
   running: boolean
   /** User interaction currently blocking this session (sidebar amber-dot state). */
   pendingInteraction?: PendingInteractionStatus
+  /** Finished while not selected and not yet opened — the sidebar's green "done" reminder. Absent = false. */
+  completed?: boolean
   /**
    * Empty-log bit (host summary derivation mirror). New Session reuses a blank
    * one targeting the same workspace. Filtering stays with the consumer: the
@@ -614,6 +616,7 @@ export class SessionsService implements ISessions {
         id: entry.sessionId,
         displayTitle: displayTitleOf(entry.title, entry.cwd, entry.sessionId),
         running: entry.running,
+        ...(entry.completed ? { completed: true } : {}),
         blank: entry.blank,
         updatedAt: entry.updatedAt,
         ...(entry.pendingInteraction === undefined

packages/client/runtime/tests/lineage.spec.ts

@@ -52,4 +52,11 @@ describe('flattenLineage', () => {
       warnSpy.mockRestore()
     }
   })
+
+  it('projects the completion-reminder set into rows (absent = false)', () => {
+    const out = flattenLineage([s('a', 10), s('b', 20)], undefined, new Set(['b' as SessionId]))
+    expect(out.find(e => e.sessionId === 'a')?.completed).toBe(false)
+    expect(out.find(e => e.sessionId === 'b')?.completed).toBe(true)
+    expect(flattenLineage([s('a', 10)])[0]?.completed).toBe(false)
+  })
 })

packages/client/runtime/tests/manager.spec.ts

@@ -985,3 +985,128 @@ describe('pending-interaction list status', () => {
     expect(session.getSnapshot().pending).toEqual([])
   })
 })
+
+describe('completed reminder', () => {
+  const status = (rpcId: string, sessionId: SessionId, running: boolean) => ({
+    rpcId: rpcId as never,
+    payload: { type: 'host/session-status' as const, sessionId, running },
+  })
+  const added = (rpcId: string, sessionId: SessionId) => ({
+    rpcId: rpcId as never,
+    payload: { type: 'host/session-added' as const, sessionId, blank: false },
+  })
+  const entry = (manager: SessionManager, sessionId: SessionId) =>
+    manager.getListSnapshot().items.find(item => item.sessionId === sessionId)
+
+  it('arms on a running→idle flip of a non-selected session and clears on select', () => {
+    const manager = new SessionManager(new FakeApiClient())
+    manager.handleHostEnvelope(added('h1', S1))
+    manager.handleHostEnvelope(added('h2', S2))
+    manager.select(S1)
+    expect(entry(manager, S2)?.completed).toBe(false)
+    manager.handleHostEnvelope(status('s1', S2, true))
+    manager.handleHostEnvelope(status('s2', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+    // Opening the session consumes the reminder.
+    manager.select(S2)
+    expect(entry(manager, S2)?.completed).toBe(false)
+  })
+
+  it('never arms for the session being watched and re-arms after a switch-away re-run', () => {
+    const manager = new SessionManager(new FakeApiClient())
+    manager.handleHostEnvelope(added('h1', S1))
+    manager.handleHostEnvelope(added('h2', S2))
+    manager.select(S2)
+    manager.handleHostEnvelope(status('s1', S2, true))
+    manager.handleHostEnvelope(status('s2', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(false) // watched to completion: no reminder
+    // Switch away; a fresh run completing again arms the reminder.
+    manager.select(S1)
+    manager.handleHostEnvelope(status('s3', S2, true))
+    manager.handleHostEnvelope(status('s4', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+
+  it('a re-run disarms the reminder while running and re-arms on its completion', () => {
+    const manager = new SessionManager(new FakeApiClient())
+    manager.handleHostEnvelope(added('h1', S1))
+    manager.handleHostEnvelope(added('h2', S2))
+    manager.select(S1)
+    manager.handleHostEnvelope(status('s1', S2, true))
+    manager.handleHostEnvelope(status('s2', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+    // The user starts a new run without opening the session: running wins.
+    manager.handleHostEnvelope(status('s3', S2, true))
+    expect(entry(manager, S2)?.completed).toBe(false)
+    manager.handleHostEnvelope(status('s4', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+
+  it('session-removed drops the reminder and a re-add starts clean', () => {
+    const manager = new SessionManager(new FakeApiClient())
+    manager.handleHostEnvelope(added('h1', S1))
+    manager.handleHostEnvelope(added('h2', S2))
+    manager.select(S1)
+    manager.handleHostEnvelope(status('s1', S2, true))
+    manager.handleHostEnvelope(status('s2', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+    manager.handleHostEnvelope({ rpcId: 'rm' as never, payload: { type: 'host/session-removed', sessionId: S2 } })
+    expect(manager.getListSnapshot().items.find(item => item.sessionId === S2)).toBeUndefined()
+    manager.handleHostEnvelope(added('h3', S2))
+    expect(entry(manager, S2)?.completed).toBe(false)
+  })
+
+  it('a list refresh carrying the running→idle transition arms the reminder', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200, running: true })] as never[] }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    manager.select(S1)
+    expect(entry(manager, S2)?.completed).toBe(false)
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200, running: false })] as never[] }))
+    await manager.refreshList()
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+
+  it('never arms for sessions already idle at first observation', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[] }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    manager.select(S1)
+    expect(entry(manager, S2)?.completed).toBe(false)
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 201 })] as never[] }))
+    await manager.refreshList()
+    expect(entry(manager, S2)?.completed).toBe(false)
+  })
+
+  it('arms a completion that happened during an in-flight first pull (baseline running, replayed idle)', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onList']>>>()
+    api.onList = () => gate.promise
+    const manager = new SessionManager(api)
+    const refresh = manager.refreshList()
+    // The session finishes while the first pull is still in flight; the pull
+    // response recorded it as running at pull time.
+    manager.handleHostEnvelope(status('s-mid', S2, false))
+    gate.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200, running: true })] as never[] }))
+    await refresh
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+
+  it('arms when a session ran and completed entirely between in-flight mutations (baseline idle)', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onList']>>>()
+    api.onList = () => gate.promise
+    const manager = new SessionManager(api)
+    const refresh = manager.refreshList()
+    // The unknown session starts and finishes while the first pull is in
+    // flight; the pull-time baseline recorded it idle, so the running→idle
+    // edge lives entirely inside the replayed mutations.
+    manager.handleHostEnvelope(status('s-start', S2, true))
+    manager.handleHostEnvelope(status('s-finish', S2, false))
+    gate.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[] }))
+    await refresh
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+})

packages/client/ui-command/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-command/README.md
-README.md: a19bfe7135acc5408448dc73d04813ed4104dd48
-README.zh.md: 79d903b916728c1200ab1311055f2be190008787
+README.md: bc7386c8fca3b5c623473328bee6322fa7295277
+README.zh.md: 478ee4ccee4558c70075baa45ab34ac6e3d71617

packages/client/ui-command/README.md

@@ -8,6 +8,8 @@ Client command surface (`ctx.command`): the session-keyed command-directory cach
 
 `CommandDirectory` (`src/client/directory.ts`) is the one wire-derived cache, keyed by session. Ordinary sessions fetch through `command.list({sessionId})`, and the source's scope-birth `warm` hook prewarms the session's entry. Catalog-addressed continuable children resolve an empty command directory locally: `command.list` is Agent-bound, so prewarming it would activate a child merely to view persisted history. Entries are soft-invalidated by the `commands/changed` typed event (old snapshot serves while the repull flies), hard-invalidated by `connection/reset`, epoch-guarded so a superseded pull can never overwrite a newer one. `matchSpace` answers synchronously from this cache only; `matchEnter` strong-waits it on the SubmitAttempt signal and rejects on warmup failure — a `/` line is never silently downgraded to a plain prompt.
 
+Menu queries fuzzy-match ordered, case-insensitive subsequences of command names. Prefixes rank first; separator boundaries, adjacent characters, and shorter gaps rank the remaining matches, with directory and contribution order breaking ties. This affects discovery only: space and Enter still require an exact command name. Rationale: [Web slash-command fuzzy discovery](../../../.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.md).
+
 `PopupSelectController` (`src/client/popup.ts`) is the headless shell state: `PopupSelectView` self-registers into `conversation.input.overlay` (the SlotMap key is ui-conversation's; this package pulls the declaration in with a type-only import — no runtime edge). The shell is a transient layer holding focus while open; token-segment consumption after onSelect runs both branches through `consumeTokenSegment` (menu-path span CAS, enter-path bare-token equality) against the draft face the wiring layer binds via `bindDraft`.
 
 The `/client` export surface is the plugin body (`apply`/`inject`), `CommandService`, the directory and popup classes with their state types, and the frozen contract types; the shell component itself is internal to the overlay registration.

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

@@ -8,6 +8,8 @@
 
 `CommandDirectory`（`src/client/directory.ts`）是唯一的 wire 派生缓存，以会话为 key。普通会话通过 `command.list({sessionId})` 拉取，source 的 scope 出生 `warm` 钩子会预热该会话的缓存项。由目录寻址的可继续子代理会在客户端解析为空命令目录：`command.list` 绑定 Agent，若预热它，就会仅因查看持久化历史而激活子代理。缓存项由 `commands/changed` 类型化事件软失效（重拉在途期间旧快照继续服务），由 `connection/reset` 硬失效，并以 epoch 把关，被取代的旧拉取永远无法覆盖更新的结果。`matchSpace` 只凭该缓存同步应答；`matchEnter` 在 SubmitAttempt 信号上强等缓存，预热失败即拒绝——`/` 开头的一行绝不会被静默降级为普通提示词。
 
+菜单查询会按顺序且不区分大小写地模糊匹配命令名的子序列。前缀排名最高；其余匹配项按分隔符边界优先、相邻字符优先、间隔越短越优先的规则排序，若仍同分，则以目录顺序和 contribution 顺序打破平局。此行为只影响命令发现：space 和 Enter 仍要求命令名精确匹配。原理：[Web 斜杠命令模糊发现](../../../.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.md)。
+
 `PopupSelectController`（`src/client/popup.ts`）是无头的壳状态：`PopupSelectView` 自行注册进 `conversation.input.overlay`（SlotMap key 归 ui-conversation 所有；本包只以 type-only 导入引入该声明——没有运行时依赖边）。壳是打开期间持有焦点的瞬态层；onSelect 之后的 token 片段消费在两条分支上都经 `consumeTokenSegment` 执行（菜单路径做 span CAS，回车路径做裸 token 相等比较），作用于接线层经 `bindDraft` 绑定的草稿表层。
 
 `/client` 导出表层是插件主体（`apply`／`inject`）、`CommandService`、目录类和 popup 类及其状态类型，以及冻结的契约类型；壳组件本身是 overlay 注册的内部实现。

packages/client/ui-command/src/client/service.ts

@@ -2,9 +2,10 @@
  * CommandService (`ctx.command`): the '/' command source over the
  * session-keyed directory, the client-contribution registry, and the
  * per-session popupSelect controllers. Candidate synthesis merges the host
- * catalog with contributions by availability, then query/position filtering;
- * a host/contribution name collision fails loud. Every execute addresses the
- * session's agent by sessionId — sessions are always agent-backed.
+ * catalog with contributions by availability, then fuzzy query/position
+ * filtering; a host/contribution name collision fails loud. Every execute
+ * addresses the session's agent by sessionId — sessions are always
+ * agent-backed.
  */
 import { Service } from 'cordis'
 import type { Context } from 'cordis'
@@ -27,6 +28,69 @@ interface LiveState {
   readonly popups: Map<SessionId, PopupSelectController<ClientSessionContext>>
 }
 
+/** One fuzzy match with its stable source position. */
+interface RankedCandidate {
+  readonly candidate: SlashCandidate
+  readonly index: number
+  readonly prefix: boolean
+  readonly score: number
+}
+
+/** Extra weight for command-name starts and separator boundaries. */
+function boundaryBonus(name: string, index: number): number {
+  return index === 0 || name.charAt(index - 1) === '-' || name.charAt(index - 1) === '_' ? 8 : 0
+}
+
+/**
+ * Score the strongest ordered-subsequence alignment in O(name × query).
+ * Boundary and adjacent matches earn weight; skipped and leading characters
+ * cost weight.
+ */
+function fuzzyScore(name: string, query: string): number | undefined {
+  if (query === '') return 0
+  if (query.length > name.length) return undefined
+  const noMatch = Number.NEGATIVE_INFINITY
+  let previous = Array<number>(name.length).fill(noMatch)
+  for (let index = 0; index < name.length; index++) {
+    if (name.charAt(index) === query.charAt(0)) previous[index] = 1 + boundaryBonus(name, index) - index
+  }
+  for (let queryIndex = 1; queryIndex < query.length; queryIndex++) {
+    const current = Array<number>(name.length).fill(noMatch)
+    let bestGapped = noMatch
+    for (let index = 0; index < name.length; index++) {
+      const gappedIndex = index - 2
+      if (gappedIndex >= 0) {
+        const prior = previous[gappedIndex] ?? noMatch
+        if (prior !== noMatch) bestGapped = Math.max(bestGapped, prior + gappedIndex)
+      }
+      if (name.charAt(index) !== query.charAt(queryIndex)) continue
+      const bonus = 1 + boundaryBonus(name, index)
+      const adjacent = index > 0 ? previous[index - 1] ?? noMatch : noMatch
+      if (adjacent !== noMatch) current[index] = adjacent + bonus + 4
+      if (bestGapped !== noMatch) current[index] = Math.max(current[index] ?? noMatch, bestGapped + bonus + 1 - index)
+    }
+    previous = current
+  }
+  let best = noMatch
+  for (const score of previous) best = Math.max(best, score)
+  return best === noMatch ? undefined : best
+}
+
+/** Case-insensitive fuzzy filtering with stable ordering for equal matches. */
+function fuzzyCandidates(candidates: readonly SlashCandidate[], rawQuery: string): readonly SlashCandidate[] {
+  const query = rawQuery.toLowerCase()
+  if (query === '') return candidates
+  const ranked: RankedCandidate[] = []
+  candidates.forEach((candidate, index) => {
+    const name = candidate.name.toLowerCase()
+    const score = fuzzyScore(name, query)
+    if (score !== undefined) ranked.push({ candidate, index, prefix: name.startsWith(query), score })
+  })
+  ranked.sort((left, right) =>
+    Number(right.prefix) - Number(left.prefix) || right.score - left.score || left.index - right.index)
+  return ranked.map(match => match.candidate)
+}
+
 /** Command surface: session-keyed directory + '/' source + contribution registry + per-session popups. */
 export class CommandService extends Service implements CommandServiceContract {
   static inject = ['slash', 'sessions', 'connection']
@@ -147,7 +211,7 @@ export class CommandService extends Service implements CommandServiceContract {
     }
   }
 
-  /** Menu candidates: host catalog + contribution availability, then query/position filtering. */
+  /** Menu candidates: host catalog + contribution availability, then position filtering and fuzzy name ranking. */
   private async candidates(session: ClientSessionContext, req: CandidateRequest): Promise<readonly SlashCandidate[]> {
     const list = await this.directory.ensureReady(session.sessionId, req.signal)
     const rows: SlashCandidate[] = []
@@ -163,9 +227,10 @@ export class CommandService extends Service implements CommandServiceContract {
       }
       rows.push({ name: contribution.name, description: contribution.description })
     }
-    return rows
-      .filter(c => c.name.startsWith(req.query))
-      .filter(c => req.position === 'leading' || c.hint === undefined)
+    return fuzzyCandidates(
+      rows.filter(c => req.position === 'leading' || c.hint === undefined),
+      req.query,
+    )
   }
 
   /** Decision table, menu column: contribution/decorated-host → popup; host input → claim; host bare → detached execute. */

packages/client/ui-command/tests/service.spec.ts

@@ -164,13 +164,33 @@ describe('candidates', () => {
     expect(b.listCalls).toEqual([])
   })
 
-  it('pulls the session catalog; prefix filter and hint mapping apply', async () => {
+  it('pulls the session catalog; fuzzy filter and hint mapping apply', async () => {
     const { source, listCalls } = await bench()
     const list = await source.candidates(proj('s1'), req('g'))
     expect(listCalls).toEqual([{ sessionId: sid('s1') }])
     expect(list).toEqual([{ name: 'goal', description: 'leadingInput kind', hint: 'goal text' }])
   })
 
+  it('matches case-insensitive subsequences and ranks prefixes, boundaries, adjacency, gaps, then source order', async () => {
+    const commands: CommandDescriptor[] = [
+      { name: 'q-xylophone', description: '' },
+      { name: 'qx-long', description: '' },
+      { name: 'fabulous', description: '' },
+      { name: 'foo-bar', description: '' },
+      { name: 'zuv', description: '' },
+      { name: 'zu1v', description: '' },
+      { name: 'yu1v', description: '' },
+      { name: 'zu12v', description: '' },
+    ]
+    const { source } = await bench({ commands: () => Promise.resolve({ commands }) })
+    const names = async (query: string) => (await source.candidates(proj('s1'), req(query))).map(c => c.name)
+    await expect(names('QX')).resolves.toEqual(['qx-long', 'q-xylophone'])
+    await expect(names('fb')).resolves.toEqual(['foo-bar', 'fabulous'])
+    await expect(names('uv')).resolves.toEqual(['zuv', 'zu1v', 'yu1v', 'zu12v'])
+    await expect(names('zzz')).resolves.toEqual([])
+    await expect(names('query-longer-than-every-name')).resolves.toEqual([])
+  })
+
   it('catalogs are per session: another session pulls its own key', async () => {
     const { source, listCalls } = await bench()
     const names = (await source.candidates(proj('s2'), req(''))).map(c => c.name)
@@ -195,10 +215,10 @@ describe('candidates', () => {
     expect(s2Names).not.toContain('theme')
   })
 
-  it('contribution rows ride the same query prefix filter', async () => {
+  it('contribution rows ride the same fuzzy query filter', async () => {
     const { command, source } = await bench()
     command.register(themeContribution())
-    const names = (await source.candidates(proj('s1'), req('th'))).map(c => c.name)
+    const names = (await source.candidates(proj('s1'), req('tm'))).map(c => c.name)
     expect(names).toEqual(['theme'])
   })
 

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: 7bd0d551fc41967326dd9860f5c31a99ea3c254a
-README.zh.md: d339f6423d9a9f77c02d86ad0b8e57bd0baba52b
+README.md: bbd115eac0eb914914dc11e504639633c801abdd
+README.zh.md: 843b49e311fbf1a9157413c42a0ef3e9828284bc

packages/client/ui-conversation/README.md

@@ -6,9 +6,9 @@ Conversation domain: skeleton (header/tabs/composer/empty state), chat view (gro
 
 Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. The disclosure renders the checkpoint's `compact/summary` provenance; when that event is outside the loaded window, the row remains visible but non-expandable. The framed checkpoint payload is model-facing and never renders.
 
-The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it a scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
+The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
-The view ring is a slot: the conversation registration declares the session-scoped `'conversation.view'` list in its `children` table, ConversationRoot renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from registration options (`id`/`order`/`label`). The chat view is this package's own entry; plugins such as ui-trajectory contribute tabs through `ctx.slots.register`, and each view owns its chrome.
+The view ring is a slot: the strict session-body registration declares the session-scoped `'conversation.view'` list in its `children` table, that body renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from registration options (`id`/`order`/`label`). The chat view is this package's own entry; plugins such as ui-trajectory contribute tabs through `ctx.slots.register`, and each view owns its chrome.
 
 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 runtime manager projects every approval or question wait through `SessionSummary.pendingInteraction`, including sessions never instantiated; `ui-workspace` owns its sidebar presentation. 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. Safe preset picks submit `/permission <preset>` immediately through the bar's injected `command` callback, while `danger-full-access` is presented as `Full access` and first opens an in-page Modal risk confirmation. The enabling action stays disabled until the user checks the acknowledgement; cancel, Escape, close, and mask click submit nothing.
 

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

@@ -6,9 +6,9 @@
 
 压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。展开内容来自检查点溯源的 `compact/summary`；该事件位于已加载窗口之外时，标记仍然可见但不可展开。面向模型的带框检查点载荷绝不渲染。
 
-常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
+常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
-视图环是一个 slot：会话注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: <active id>`），视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
+视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 

packages/client/ui-conversation/src/client/apply.ts

@@ -8,7 +8,7 @@ import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type { ViewTab } from './contract/views.ts'
 import type {
   ApprovalWait, ChatScrollPosition, ChatViewInjected, ComposerBarInjected, ComposerChainProps, ConversationInjected,
-  ConversationSessionInjected, DetailsInjected,
+  ConversationSessionHeaderInjected, ConversationSessionInjected, DetailsInjected,
 } from './contract/slots.ts'
 import type { InputNotice } from './input/contract.ts'
 import { resolveToolPath } from './contract/tool-call-model.ts'
@@ -33,7 +33,7 @@ import { askQuestionToolview } from './toolviews/ask-question-row.tsx'
 import { todoDockEntry } from './skeleton/TodoPanel.tsx'
 import { queueDockEntry } from './queue/QueueDock.tsx'
 import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
-import { ConversationSession } from './skeleton/ConversationSession.tsx'
+import { ConversationSession, ConversationSessionHeader } from './skeleton/ConversationSession.tsx'
 import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 import { en, NS, zh, type ConversationKey } from './locales.ts'
 
@@ -123,6 +123,11 @@ export function apply(ctx: Context): void {
     }
     return tabs
   }
+  const views = {
+    list: viewTabs,
+    subscribe: (fn: () => void) => slots.subscribe('conversation.view', fn),
+    version: () => slots.getVersion('conversation.view'),
+  }
 
   // The per-session input machine registry (InputService face; published as
   // ctx.conversation.input by the service below sharing this one instance).
@@ -151,6 +156,7 @@ export function apply(ctx: Context): void {
     locale: NS,
     children: {
       'conversation.session': { kind: 'single', scope: 'session' },
+      'conversation.session.header': { kind: 'single', scope: 'session' },
       'conversation.composer': { kind: 'chain', scope: 'session' },
       'conversation.composer.bar': { kind: 'single', scope: 'session-maybe' },
       'conversation.input.overlay': { kind: 'list', scope: 'session' },
@@ -176,27 +182,36 @@ export function apply(ctx: Context): void {
     }),
   }, ConversationRoot)
 
-  // The strict session subtree owns only per-session store and view content;
-  // the resident parent keeps Hero and composer layout identity stable.
+  // The strict session body fills the resident scrollport without owning it;
+  // the Hero/composer path therefore stays fixed while the first blank
+  // session appears after a Workspace pick.
   slots.register({
     name: 'conversation.session',
-    locale: NS,
     children: {
       'conversation.view': { kind: 'list', scope: 'session' },
-      'conversation.session.header.actions': { kind: 'list', scope: 'session' },
     },
     store: chatStore,
     inject: (sessionId: SessionId, _actions: BoundActions<typeof chatStore>): ConversationSessionInjected => ({
-      views: {
-        list: viewTabs,
-        subscribe: fn => slots.subscribe('conversation.view', fn),
-        version: () => slots.getVersion('conversation.view'),
-      },
+      views,
       bindDraftMirror: write => inputHub.shell(sessionId).bindMirror(write),
-      open: (id) => { sessions.open(id) },
     }),
   }, ConversationSession)
 
+  // Header chrome sits above the resident scrollport but shares the same
+  // per-session chat store (active view) as its body and view entries.
+  slots.register({
+    name: 'conversation.session.header',
+    locale: NS,
+    children: {
+      'conversation.session.header.actions': { kind: 'list', scope: 'session' },
+    },
+    store: chatStore,
+    inject: (): ConversationSessionHeaderInjected => ({
+      views,
+      open: (id) => { sessions.open(id) },
+    }),
+  }, ConversationSessionHeader)
+
   // The default composer body: its own single slot inside the composer
   // chain's fallback (decision 20). Public machine surface arrives via the
   // provide channel above; the keyboard command face and the stop/retry

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

@@ -13,19 +13,20 @@ import type { CallId, SelectionTarget, ViewTab } from './views.ts'
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SlotMap {
     /**
-     * Strict-session content inside the resident conversation shell. This
-     * subtree owns the per-session chat store, header, and view ring and is
-     * remounted when the current session id changes.
+     * Strict-session body inside the resident conversation scrollport. It
+     * owns the per-session draft mirror and active view ring.
      */
-    'conversation.session': { kind: 'single'; scope: 'session'; owner: ConversationSessionOwnerProps }
+    'conversation.session': { kind: 'single'; scope: 'session' }
+    /** Strict-session header above the resident conversation scrollport. */
+    'conversation.session.header': { kind: 'single'; scope: 'session' }
     /** Session-header actions contributed by feature plugins. */
     'conversation.session.header.actions': { kind: 'list'; scope: 'session'; owner: ConversationHeaderActionOwnerProps }
     /**
      * The conversation view ring: one list entry per view tab (chat here;
      * trajectory/waterfall from ui-trajectory), rendered one-at-a-time by
-     * ConversationRoot via `only: <active id>`. Declared by this package's
-     * 'conversation' entry (declaring is claiming). Session scope: views read
-     * the conversation snapshot through the standard kit.
+     * the session body via `only: <active id>`. Declared by this package's
+     * body entry (declaring is claiming). Session scope: views read the
+     * conversation snapshot through the standard kit.
      */
     'conversation.view': { kind: 'list'; scope: 'session'; owner: ConvViewOwnerProps }
     /**
@@ -122,22 +123,6 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
   }
 }
 
-/** Owner share of the strict session content seat. */
-export interface ConversationSessionOwnerProps {
-  /**
-   * Wrap the view ring in the transcript scrollport that also hosts the
-   * sticky composer seat (whole `'conversation.composer'` chain output).
-   * Supplied for every real session (hero/settling/active) so the composer
-   * keeps one tree seat across the blank → active flip; the header stays
-   * outside that wrapper as ordinary column chrome (`flex: none`), while
-   * active CSS sticks the seat to the bottom of the same scrollport so wheel
-   * over the footer scrolls the flow.
-   * @param view - the session view-ring content (null while blank chrome is hidden).
-   * @returns the scrollport containing `view` and the sticky composer seat.
-   */
-  wrapActiveBody?: (view: ReactNode) => ReactNode
-}
-
 /** Header actions derive their state from the standard session/global kit. */
 export interface ConversationHeaderActionOwnerProps {}
 
@@ -228,7 +213,7 @@ export type CommandRowProps = PropsRuntime<'conversation.chat.commandview'>
  */
 export type ConvViewProps = PropsRuntime<'conversation.view'>
 
-/** The shared chat store handle type (apply constructs one; the conversation, details, and chat-view registrations all declare it). */
+/** The shared chat store handle type declared by the Session header/body, details, and chat-view registrations. */
 export type ChatStore = ReturnType<typeof createChatStore>
 
 /** Business callbacks injected into the conversation slot. */
@@ -240,7 +225,7 @@ export interface ConversationInjected {
   selectWorkspace: (workspaceId: WorkspaceId) => Promise<void>
 }
 
-/** Business callbacks injected into the strict session content seat. */
+/** Business callbacks injected into the strict Session body seat. */
 export interface ConversationSessionInjected {
   /** Views projected from the `conversation.view` slot ledger. */
   views: {
@@ -250,6 +235,16 @@ export interface ConversationSessionInjected {
   }
   /** Bind the input machine's draft persistence mirror to the session store. */
   bindDraftMirror: (write: (text: string) => void) => () => void
+}
+
+/** Business callbacks injected into the strict session header seat. */
+export interface ConversationSessionHeaderInjected {
+  /** Views projected from the `conversation.view` slot ledger. */
+  views: {
+    list: () => readonly ViewTab[]
+    subscribe: (fn: () => void) => () => void
+    version: () => number
+  }
   /** Select a real Session through the runtime navigation owner. */
   open: (sessionId: SessionId) => void
 }
@@ -354,7 +349,8 @@ export interface ComposerChainProps {
  */
 export type ConversationSlotProps =
   PropsRuntime<'conversation'> & PropsRenderSlots<
-    | 'conversation.session' | 'conversation.composer' | 'conversation.composer.bar'
+    | 'conversation.session' | 'conversation.session.header'
+    | 'conversation.composer' | 'conversation.composer.bar'
     | 'conversation.input.overlay'
     | 'conversation.input.dock' | 'conversation.composer.dock'
     | 'conversation.input.left' | 'conversation.input.right'
@@ -363,12 +359,19 @@ export type ConversationSlotProps =
   & ConversationInjected
   & PropsLocale<'conversation'>
 
-/** Full strict-session content props: per-session store, view ring, callbacks, and the locale seat. */
+/** Full strict-session body props: per-session store, view ring, and draft mirror. */
 export type ConversationSessionSlotProps =
   PropsRuntime<'conversation.session'>
-  & PropsRenderSlots<'conversation.view' | 'conversation.session.header.actions'>
+  & PropsRenderSlots<'conversation.view'>
   & PropsStore<ChatStore>
   & ConversationSessionInjected
+
+/** Full strict-session header props: shared store, tabs/actions render shares, navigation, and locale. */
+export type ConversationSessionHeaderSlotProps =
+  PropsRuntime<'conversation.session.header'>
+  & PropsRenderSlots<'conversation.session.header.actions'>
+  & PropsStore<ChatStore>
+  & ConversationSessionHeaderInjected
   & PropsLocale<'conversation'>
 
 /** The pending approval carrier the owner dispatches into the composer chain. */

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

@@ -15,7 +15,8 @@ export type { ConversationKey } from './locales.ts'
 export type {
   ChatStore, ChatViewInjected, ChatViewSlotProps, CommandRowOwnerProps, CommandRowProps, ComposerBarInjected,
   ComposerChainProps, ConversationInjected,
-  ConversationSessionInjected, ConversationSlotProps, ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
+  ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps,
+  ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
   EmptyWorkspaceOwnerProps, ToolRowOwnerProps, ToolRowProps,
 } from './contract/slots.ts'
 // Export discipline: packages/client/AGENTS.md.

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

@@ -31,8 +31,8 @@
   border-bottom: 1px solid var(--dsw-alias-border-l2);
 }
 
-/* Blank hero/settling: keep the header node mounted (stable Session tree for
-   the wrapActiveBody composer) without taking column space. */
+/* Blank hero/settling: keep the strict Session header mounted without taking
+   column space; the root-owned scrollport and composer remain below it. */
 .headerHidden {
   display: none;
 }
@@ -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/skeleton/ConversationRoot.tsx

@@ -2,7 +2,7 @@
 // chain, AND the composer bar (session-maybe slot) stay mounted across
 // no-session/session transitions — the bar renders inert via owner props.
 
-import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import clsx from 'clsx'
 import type { WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationSlotProps, InputZone } from '../contract/slots.ts'
@@ -31,9 +31,8 @@ export function ConversationRoot({
 
   // Publishes the seat's live height as --dsh-composer-height on the scroll
   // body so floating controls (ChatView back-to-bottom) clear the composer as
-  // it grows. Callback ref, not an effect: the seat remounts when the tree
-  // moves between the no-session and session paths. Stable identity so React
-  // reattaches only on those remounts, not on every render.
+  // it grows. Callback ref, not an effect; stable identity prevents observer
+  // churn while the first blank session fills the resident body outlet.
   const seatObserver = useRef<ResizeObserver | null>(null)
   const seatResizeRef = useCallback((seat: HTMLDivElement | null): void => {
     seatObserver.current?.disconnect()
@@ -167,28 +166,13 @@ export function ConversationRoot({
     </div>
   )
 
-  // Header stays column chrome above this scrollport; the sticky composer
-  // seat lives inside it with the transcript. Always wrap while a session
-  // exists (hero/settling/active) so the composer keeps one tree seat across
-  // the blank → active flip — relocating it only in active remounted the textarea.
-  const wrapActiveBody = (view: ReactNode): ReactNode => (
-    <div className={css.scrollBody} data-conversation-scroll="">
-      {view}
-      {composerSeat}
-    </div>
-  )
-
   return (
     <div className={css.root} data-phase={phase}>
-      {/* Mounted for every real session, hero included: ConversationSession
-          keeps a chrome-hidden shell while blank and owns the draft-
-          persistence mirror bind — unmounting it in the hero would lose
-          pre-first-send text on a refresh or scope rebuild. */}
-      {sessionId !== undefined && renderSlot(
-        'conversation.session',
-        { wrapActiveBody },
-      )}
-      {sessionId === undefined ? wrapActiveBody(null) : null}
+      {renderSlot('conversation.session.header', {})}
+      <div className={css.scrollBody} data-conversation-scroll="">
+        {renderSlot('conversation.session', {})}
+        {composerSeat}
+      </div>
     </div>
   )
 }

packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx

@@ -1,14 +1,19 @@
-/** Strict per-session conversation content: header, view ring, and chat store bindings. */
+/** Strict per-session header/body content inserted into the resident conversation layout. */
 
-import { useEffect, useSyncExternalStore, type ReactNode } from 'react'
+import { useEffect, useSyncExternalStore } from 'react'
 import clsx from 'clsx'
 import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ConversationSessionSlotProps } from '../contract/slots.ts'
+import type {
+  ConversationSessionHeaderSlotProps, ConversationSessionSlotProps,
+} from '../contract/slots.ts'
 import css from './ConversationRoot.module.css'
 
-/** Full props composed from the strict session slot contract. */
+/** Full props composed from the strict session body contract. */
 export type ConversationSessionProps = ConversationSessionSlotProps
 
+/** Full props composed from the strict session header contract. */
+export type ConversationSessionHeaderProps = ConversationSessionHeaderSlotProps
+
 interface Breadcrumb {
   readonly id: SessionId
   readonly displayTitle: string
@@ -38,10 +43,15 @@ function equalBreadcrumbs(left: readonly Breadcrumb[], right: readonly Breadcrum
     })
 }
 
-export function ConversationSession({
-  sessionId, useSession, useSessions, useInput, inputActions, useStore, actions,
-  renderSlot, views, bindDraftMirror, open, wrapActiveBody, t,
-}: ConversationSessionProps) {
+/**
+ * Renders Session header chrome above the resident conversation scrollport.
+ * @param props - Strict Session store, view ledger, navigation, render, and locale shares.
+ * @returns the hidden blank-session header or visible title and tabs.
+ */
+export function ConversationSessionHeader({
+  sessionId, useSession, useSessions, useStore, actions,
+  renderSlot, views, open, t,
+}: ConversationSessionHeaderProps) {
   useSyncExternalStore(views.subscribe, views.version)
   const tabs = views.list()
   const activeId = useStore(s => s.view) ?? 'chat'
@@ -49,6 +59,77 @@ export function ConversationSession({
   const ancestry = useSessions(s => deriveAncestry(s, sessionId), equalBreadcrumbs)
   const composerPhase = useSession(s => s.composerPhase)
   const blank = useSession(s => s.blank)
+  const hideChrome = blank && composerPhase === 'blank'
+
+  return (
+    <header
+      className={clsx(css.header, hideChrome && css.headerHidden)}
+      aria-hidden={hideChrome || undefined}
+    >
+      {!hideChrome && (
+        <>
+          <div className={css.titleRow}>
+            <nav className={css.crumbs} aria-label={t('session.hierarchy')}>
+              {ancestry.map((summary, index) => {
+                const last = index === ancestry.length - 1
+                return (
+                  <span key={summary.id} className={css.crumbSeg}>
+                    {index > 0 && <span className={css.crumbSep}>/</span>}
+                    <button
+                      type="button"
+                      className={clsx(css.crumb, last && css.crumbCurrent)}
+                      disabled={last}
+                      onClick={() => { open(summary.id) }}
+                    >
+                      {summary.displayTitle}
+                    </button>
+                  </span>
+                )
+              })}
+              {ancestry.length === 0 && <span className={css.crumbCurrent}>{sessionId}</span>}
+            </nav>
+            <div className={css.headerActions}>
+              {renderSlot('conversation.session.header.actions', {})}
+            </div>
+          </div>
+          {tabs.length > 1 && (
+            <div className={css.tabs} role="tablist">
+              {tabs.map(viewTab => (
+                <button
+                  key={viewTab.id}
+                  type="button"
+                  role="tab"
+                  aria-selected={viewTab.id === active?.id}
+                  className={clsx(css.tab, viewTab.id === active?.id && css.tabActive)}
+                  onClick={() => { actions.setView(viewTab.id) }}
+                >
+                  {viewTab.label}
+                </button>
+              ))}
+            </div>
+          )}
+        </>
+      )}
+    </header>
+  )
+}
+
+/**
+ * Renders the active Session view inside the resident scrollport and keeps
+ * the input draft mirrored while blank Hero chrome is visible.
+ * @param props - Strict Session input/store, view ledger, and render shares.
+ * @returns the active view area, or null while the Session remains blank.
+ */
+export function ConversationSession({
+  useSession, useInput, inputActions, useStore, actions,
+  renderSlot, views, bindDraftMirror,
+}: ConversationSessionProps) {
+  useSyncExternalStore(views.subscribe, views.version)
+  const tabs = views.list()
+  const activeId = useStore(s => s.view) ?? 'chat'
+  const active = tabs.find(view => view.id === activeId) ?? tabs[0]
+  const composerPhase = useSession(s => s.composerPhase)
+  const blank = useSession(s => s.blank)
   const inputState = useInput(s => s)
   const storedDraft = useStore(s => s.draft)
   // `?? null`: persisted snapshots from before the inspect field rehydrate without it.
@@ -62,13 +143,8 @@ export function ConversationSession({
     // the machine mirror, not this seed effect.
   }, [inputActions])
 
-  // Blank hero/settling: keep the same header + body tree shape so a
-  // wrapActiveBody-hosted composer keeps its DOM identity across the first
-  // send (hero → active). Chrome is hidden; the draft-persistence mirror
-  // still runs because this component stays mounted.
-  const hideChrome = blank && composerPhase === 'blank'
-
-  const view: ReactNode = hideChrome ? null : (
+  if (blank && composerPhase === 'blank') return null
+  return (
     <div className={css.viewArea}>
       {active !== undefined && renderSlot('conversation.view', {
         inspect,
@@ -76,59 +152,4 @@ export function ConversationSession({
       }, { only: active.id })}
     </div>
   )
-
-  return (
-    <>
-      <header
-        className={clsx(css.header, hideChrome && css.headerHidden)}
-        aria-hidden={hideChrome || undefined}
-      >
-        {!hideChrome && (
-          <>
-            <div className={css.titleRow}>
-              <nav className={css.crumbs} aria-label={t('session.hierarchy')}>
-                {ancestry.map((summary, index) => {
-                  const last = index === ancestry.length - 1
-                  return (
-                    <span key={summary.id} className={css.crumbSeg}>
-                      {index > 0 && <span className={css.crumbSep}>/</span>}
-                      <button
-                        type="button"
-                        className={clsx(css.crumb, last && css.crumbCurrent)}
-                        disabled={last}
-                        onClick={() => { open(summary.id) }}
-                      >
-                        {summary.displayTitle}
-                      </button>
-                    </span>
-                  )
-                })}
-                {ancestry.length === 0 && <span className={css.crumbCurrent}>{sessionId}</span>}
-              </nav>
-              <div className={css.headerActions}>
-                {renderSlot('conversation.session.header.actions', {})}
-              </div>
-            </div>
-            {tabs.length > 1 && (
-              <div className={css.tabs} role="tablist">
-                {tabs.map(viewTab => (
-                  <button
-                    key={viewTab.id}
-                    type="button"
-                    role="tab"
-                    aria-selected={viewTab.id === active?.id}
-                    className={clsx(css.tab, viewTab.id === active?.id && css.tabActive)}
-                    onClick={() => { actions.setView(viewTab.id) }}
-                  >
-                    {viewTab.label}
-                  </button>
-                ))}
-              </div>
-            )}
-          </>
-        )}
-      </header>
-      {wrapActiveBody !== undefined ? wrapActiveBody(view) : view}
-    </>
-  )
 }

packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx

@@ -123,9 +123,9 @@ export function HeroShell({ t, children }: HeroShellProps) {
           <span className={css.previewBadge}>{t('hero.preview')}</span>
         </div>
         <div className={css.body}>
-          {/* The resident composer (ConversationRoot wrapActiveBody seat; the
-              workspace row rides the stack above the card) is CSS-centered in
-              the session scroll body during hero — see
+          {/* The resident composer (ConversationRoot's root-owned scrollport;
+              the workspace row rides the stack above the card) is CSS-centered
+              in that scroll body during hero — see
               ConversationRoot.module.css [data-phase='hero']. */}
         </div>
       </div>

packages/client/ui-conversation/tests/apply-inject.spec.tsx

@@ -21,7 +21,8 @@ import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { ISession, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
-  ChatViewInjected, ComposerBarInjected, ConversationInjected, ConversationSessionInjected, DetailsInjected,
+  ChatViewInjected, ComposerBarInjected, ConversationInjected, ConversationSessionHeaderInjected,
+  ConversationSessionInjected, DetailsInjected,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { createChatStore } from '../src/client/stores.ts'
 
@@ -70,7 +71,7 @@ async function bench() {
   // The host face (store resolution) exists only inside the installed
   // renderer, so materialize it the way the shell does.
   runtime.renderRoot()
-  const entryOf = (key: 'conversation' | 'conversation.session' | 'conversation.composer.bar' | 'conversation.view' | 'details') =>
+  const entryOf = (key: 'conversation' | 'conversation.session' | 'conversation.session.header' | 'conversation.composer.bar' | 'conversation.view' | 'details') =>
     runtime.slots.entries(key)[0]!
   /** Resolve store instance + call the inject the way the outlet would. */
   const conversationSurface = (id: SessionId) => {
@@ -80,6 +81,13 @@ async function bench() {
       id, instance.actions)
     return { instance, injected }
   }
+  const conversationHeaderSurface = (id: SessionId) => {
+    const entry = entryOf('conversation.session.header')
+    const instance = runtime.storeOf('conversation.session.header', id) as ChatInstance
+    const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ConversationSessionHeaderInjected)(
+      id, instance.actions)
+    return { instance, injected }
+  }
   const residentSurface = (id: SessionId | undefined) => {
     const entry = entryOf('conversation')
     return (entry.inject as unknown as (sessionId: SessionId | undefined) => ConversationInjected)(id)
@@ -111,7 +119,7 @@ async function bench() {
   }
   return {
     runtime, feature, slots: runtime.slots, entryOf,
-    conversationSurface, residentSurface, composerSurface, chatViewSurface, inputSurface,
+    conversationSurface, conversationHeaderSurface, residentSurface, composerSurface, chatViewSurface, inputSurface,
     sessionFake, layoutFake,
   }
 }

packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx

@@ -21,11 +21,12 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, waitFor, within } from '@testing-library/react'
+import { useState } from 'react'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { ISession, SessionId, TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
-import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { apply, inject, type EmptyWorkspaceOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
@@ -83,6 +84,16 @@ const LAYOUT_CHILDREN = {
   'details': { kind: 'single', scope: 'session' },
 } as const
 
+/** Stateful occupant proving the root-scoped Hero workspace outlet is not rebuilt. */
+function WorkspaceProbe({ open }: EmptyWorkspaceOwnerProps) {
+  const [count, setCount] = useState(0)
+  return (
+    <button data-testid="workspace-probe" onClick={() => { setCount(value => value + 1) }}>
+      {String(open)}:{count}
+    </button>
+  )
+}
+
 async function bench(nodes: ToolResultNode[], opts?: { blank?: boolean }) {
   const runtime = await SlotTestRuntime.create()
   runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
@@ -188,6 +199,49 @@ describe('resident composer', () => {
     await runtime.dispose()
   })
 
+  it('keeps the complete Hero tree mounted when the first Workspace session appears', async () => {
+    const runtime = await SlotTestRuntime.create()
+    runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+    const locale = new LocaleService(runtime.ctx)
+    runtime.provide('locale', locale)
+    runtime.slots.installLocale(locale)
+    await runtime.workspaces.update((draft) => {
+      draft.items = [{ workspaceId: 'w1', title: 'Proj', path: '/proj', sessionIds: [SID] }] as never
+    })
+    await runtime.root.declare(LAYOUT_CHILDREN, AppRoot)
+    await runtime.mount({ inject: [...inject], apply })
+    runtime.slots.register({ name: 'conversation.hero.workspace' }, WorkspaceProbe)
+    const view = runtime.renderRoot()
+
+    const root = view.container.querySelector('[data-phase="hero"]')!
+    const scrollBody = view.container.querySelector('[data-conversation-scroll]')!
+    const composerSeat = view.container.querySelector('[data-composer-seat]')!
+    const textarea = view.container.querySelector('textarea')!
+    const workspaceChip = view.getByRole('button', { name: '选择工作区' })
+    const workspaceProbe = view.getByTestId('workspace-probe')
+    expect(textarea.disabled).toBe(true)
+
+    fireEvent.click(workspaceChip)
+    fireEvent.click(workspaceProbe)
+    expect(workspaceProbe.textContent).toBe('true:1')
+
+    await runtime.sessions.add({
+      id: SID,
+      summary: { title: 'S', displayTitle: 'S', cwd: '/proj', blank: true },
+      snapshot: { blank: true, composerPhase: 'blank' },
+    })
+
+    expect(view.container.querySelector('[data-phase="hero"]')).toBe(root)
+    expect(view.container.querySelector('[data-conversation-scroll]')).toBe(scrollBody)
+    expect(view.container.querySelector('[data-composer-seat]')).toBe(composerSeat)
+    expect(view.container.querySelector('textarea')).toBe(textarea)
+    expect(view.getByRole('button', { name: '选择工作区' })).toBe(workspaceChip)
+    expect(view.getByTestId('workspace-probe')).toBe(workspaceProbe)
+    expect(workspaceProbe.textContent).toBe('true:1')
+    expect(textarea.disabled).toBe(false)
+    await runtime.dispose()
+  })
+
 
   it('the textarea survives the blank→active conversion as the same DOM node', async () => {
     const runtime = await bench([], { blank: true })

packages/client/ui-conversation/tests/chat-apply.spec.tsx

@@ -45,7 +45,7 @@ async function bench() {
 }
 
 /** First stored entry for a key (inject/store live directly on StoredEntry). */
-function renderEntryOf(slots: Awaited<ReturnType<typeof bench>>['slots'], key: 'conversation' | 'conversation.session' | 'conversation.view' | 'details') {
+function renderEntryOf(slots: Awaited<ReturnType<typeof bench>>['slots'], key: 'conversation' | 'conversation.session' | 'conversation.session.header' | 'conversation.view' | 'details') {
   return slots.entries(key)[0] as undefined | { inject?: unknown; store?: unknown }
 }
 
@@ -73,6 +73,7 @@ describe('apply wiring', () => {
     const b = await bench()
     const conversation = renderEntryOf(b.slots, 'conversation')
     const conversationSession = renderEntryOf(b.slots, 'conversation.session')
+    const conversationHeader = renderEntryOf(b.slots, 'conversation.session.header')
     const chatView = renderEntryOf(b.slots, 'conversation.view')
     const details = renderEntryOf(b.slots, 'details')
     expect(conversation?.inject).toBeTypeOf('function')
@@ -81,6 +82,7 @@ describe('apply wiring', () => {
     // The shared handle: one apply-built store value on ALL session entries
     // (the session-maybe 'conversation' shell carries no store by design).
     expect(conversationSession?.store).toBeDefined()
+    expect(conversationHeader?.store).toBe(conversationSession?.store)
     expect(details?.store).toBe(conversationSession?.store)
     expect(chatView?.store).toBe(conversationSession?.store)
     // The hero workspace picker hole rides the conversation entry's children

packages/client/ui-conversation/tests/selection-survival.spec.tsx

@@ -15,16 +15,17 @@ type ChatInstance = ReturnType<ReturnType<typeof createChatStore>['create']>
 async function bench() {
   const runtime = await SlotTestRuntime.create()
   const chat = createChatStore()
-  // The apply.ts shape: one shared handle across both strict-session slot
-  // registrations ('conversation.session'/'details'); the session-maybe
-  // 'conversation' shell carries no store by design. The slots must first
-  // exist in the ledger — the test root declares them (the AppFrame role).
+  // The apply.ts shape: one shared handle across the strict Session header,
+  // body, and details registrations; the session-maybe 'conversation' shell
+  // carries no store by design. The slots must first exist in the ledger.
   await runtime.root.declare({
     'conversation': { kind: 'single', scope: 'session-maybe' },
     'conversation.session': { kind: 'single', scope: 'session' },
+    'conversation.session.header': { kind: 'single', scope: 'session' },
     'details': { kind: 'single', scope: 'session' },
   }, (_p: { renderSlot?: unknown }) => null)
   runtime.slots.register({ name: 'conversation.session', store: chat }, () => null)
+  runtime.slots.register({ name: 'conversation.session.header', store: chat }, () => null)
   runtime.slots.register({ name: 'details', store: chat }, () => null)
   runtime.renderRoot() // materializes the host face storeOf resolves through
   return { runtime, chat }

packages/client/ui-conversation/tests/skeleton.spec.tsx

@@ -18,7 +18,7 @@ import { createChatStore } from '../src/client/stores.ts'
 import { SessionInputShell } from '../src/client/input/facade.ts'
 import { en, zh } from '../src/client/locales.ts'
 import { ConversationRoot } from '../src/client/skeleton/ConversationRoot.tsx'
-import { ConversationSession } from '../src/client/skeleton/ConversationSession.tsx'
+import { ConversationSession, ConversationSessionHeader } from '../src/client/skeleton/ConversationSession.tsx'
 import { HeroShell } from '../src/client/skeleton/EmptyHero.tsx'
 import { InputBar } from '../src/client/skeleton/InputBar.tsx'
 import type { InputBarProps } from '../src/client/skeleton/InputBar.tsx'
@@ -122,6 +122,33 @@ function mount(
   const renderSlot = ((key: string, owner: object, opts?: { only?: string }) => {
     slotCalls.push(key)
     if (key === 'conversation.hero.workspace') { pickerOwner = owner; return null }
+    if (key === 'conversation.session.header') {
+      return (
+        <ConversationSessionHeader
+          sessionId={SID}
+          SessionProvider={({ children }) => children(SID)}
+          useSession={useSession}
+          useSessions={props.useSessions}
+          useWorkspaces={props.useWorkspaces}
+          useProjection={(() => undefined)}
+          useInput={useInput}
+          inputActions={inputActions}
+          useStore={bindSnapshotSelector(chat)}
+          actions={chat.actions}
+          renderSlot={renderSlot as never}
+          views={{
+            list: () => [
+              { id: 'chat', label: 'Chat' },
+              { id: 'trajectory', label: 'Trajectory' },
+            ],
+            subscribe: () => () => {},
+            version: () => 1,
+          }}
+          open={open}
+          t={t}
+        />
+      )
+    }
     if (key === 'conversation.session') {
       return (
         <ConversationSession
@@ -145,9 +172,6 @@ function mount(
             version: () => 1,
           }}
           bindDraftMirror={write => wiring.bindMirror(write)}
-          open={open}
-          t={t}
-          {...owner}
         />
       )
     }
@@ -340,7 +364,7 @@ describe('ConversationRoot resident composer', () => {
     const before = b.view.getByRole('textbox')
     fireEvent.change(before, { target: { value: 'kept across flip' } })
     // First message landed: content exists, phase leaves blank. Composer
-    // already sat in the Session scrollport during hero, so the textarea
+    // already sat in the resident scrollport during hero, so the textarea
     // node and InputHub draft both survive.
     b.session.set(conversationSnapshot({ composerPhase: 'active', blank: false }))
     b.rerender()

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()
   })
 

packages/client/ui-trajectory/tests/views.spec.tsx

@@ -21,7 +21,10 @@ import type {
   SessionHistorySnapshot, SessionId, SessionListState, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConvViewProps, ViewTab } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { ConversationSession, type ConversationSessionProps } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/ConversationSession.tsx'
+import {
+  ConversationSession, ConversationSessionHeader,
+  type ConversationSessionHeaderProps, type ConversationSessionProps,
+} from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/ConversationSession.tsx'
 import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { zh as conversationZh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-trajectory/client'
@@ -35,12 +38,9 @@ import { createTrajectoryDurationStore } from '../src/client/duration-store.ts'
 import { deriveTrajectoryTimeline } from '../src/client/timeline.ts'
 
 const SID = 's1' as SessionId
-
-// Stub of the conversation package's standard locale seat (this spec mounts
-// its ConversationSession chrome); answers from the zh dictionary and falls
-// back to the key like the real chain.
-const tConversation: ConversationSessionProps['t'] =
+const tConversation: ConversationSessionHeaderProps['t'] =
   key => (conversationZh as Record<string, string>)[key] ?? key
+
 afterEach(cleanup)
 // The chat store persists under its declared key; clear so one case's active
 // view cannot rehydrate into the next.
@@ -180,7 +180,7 @@ function tabsOf(slots: SlotsService): ViewTab[] {
     .map(e => ({ id: e.options.id!, label: resolveSlotLabel(e.options.label) ?? e.options.id! }))
 }
 
-/** Mount the strict session content over the ring ledger with an outlet-faithful renderSlot. */
+/** Mount the strict Session header/body over the ring ledger with outlet-faithful render shares. */
 function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES) {
   const sessionSnapshot = createSnapshotStore({
     running: false, removed: false, promptError: null, nodes,
@@ -190,6 +190,13 @@ function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES
   })
   const useSession = bindSnapshotSelector(sessionSnapshot) as unknown as UseSession<ConversationSnapshot>
   const chat = createChatStore().create()
+  const views = {
+    list: () => tabsOf(slots),
+    subscribe: (fn: () => void) => slots.subscribe('conversation.view', fn),
+    version: () => slots.getVersion('conversation.view'),
+  }
+  const useInput = bindSnapshotSelector(createSnapshotStore({ draft: '', draftRev: 0, phase: 'plain', queue: [] })) as never
+  const inputActions = { setDraft: vi.fn(), submit: vi.fn() }
   // Minimal outlet twin: resolve the ring entry by the `only` filter and
   // render it with the session standard kit (what SlotOutlet does for a
   // list-kind session slot, minus machinery).
@@ -222,27 +229,39 @@ function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES
     )
   }) as unknown as ConversationSessionProps['renderSlot']
   return render(
-    <ConversationSession
-      sessionId={SID}
-      t={tConversation}
-      SessionProvider={({ children }) => children(SID)}
-      useSession={useSession}
-      useSessions={emptySessions()}
-      useWorkspaces={emptyWorkspaces()}
-      useProjection={(() => undefined)}
-      useStore={bindSnapshotSelector(chat)}
-      actions={chat.actions}
-      renderSlot={renderSlot}
-      views={{
-        list: () => tabsOf(slots),
-        subscribe: (fn: () => void) => slots.subscribe('conversation.view', fn),
-        version: () => slots.getVersion('conversation.view'),
-      }}
-      useInput={bindSnapshotSelector(createSnapshotStore({ draft: '', draftRev: 0, phase: 'plain', queue: [] })) as never}
-      inputActions={{ setDraft: vi.fn(), submit: vi.fn() }}
-      bindDraftMirror={() => () => {}}
-      open={vi.fn()}
-    />,
+    <>
+      <ConversationSessionHeader
+        sessionId={SID}
+        SessionProvider={({ children }) => children(SID)}
+        useSession={useSession}
+        useSessions={emptySessions()}
+        useWorkspaces={emptyWorkspaces()}
+        useProjection={(() => undefined)}
+        useStore={bindSnapshotSelector(chat)}
+        actions={chat.actions}
+        renderSlot={() => null}
+        views={views}
+        useInput={useInput}
+        inputActions={inputActions}
+        open={vi.fn()}
+        t={tConversation}
+      />
+      <ConversationSession
+        sessionId={SID}
+        SessionProvider={({ children }) => children(SID)}
+        useSession={useSession}
+        useSessions={emptySessions()}
+        useWorkspaces={emptyWorkspaces()}
+        useProjection={(() => undefined)}
+        useStore={bindSnapshotSelector(chat)}
+        actions={chat.actions}
+        renderSlot={renderSlot}
+        views={views}
+        useInput={useInput}
+        inputActions={inputActions}
+        bindDraftMirror={() => () => {}}
+      />
+    </>,
   )
 }
 

packages/client/ui-workspace/src/client/locales.ts

@@ -49,6 +49,7 @@ export const zh = {
   'status.waitingApproval': '等待审批',
   'status.planReview': '计划待审',
   'status.waitingAnswer': '等待回答',
+  'status.completed': '已完成',
   'hover.created': '创建于 {time}',
   'hover.copied': '已复制',
   'date.ymd': '{y}年{m}月{d}日',
@@ -109,6 +110,7 @@ export const en = {
   'status.waitingApproval': 'Waiting for approval',
   'status.planReview': 'Plan awaiting review',
   'status.waitingAnswer': 'Waiting for answer',
+  'status.completed': 'Completed',
   'hover.created': 'Created {time}',
   'hover.copied': 'Copied',
   'date.ymd': '{y}-{m}-{d}',

packages/client/ui-workspace/src/client/rows/Rows.tsx

@@ -173,7 +173,7 @@ function assertNever(value: never): never {
 
 /** Session status presentation; pending user interaction outranks the running state. */
 function sessionStatus(
-  node: Pick<SessionNode, 'pendingInteraction' | 'running'>,
+  node: Pick<SessionNode, 'pendingInteraction' | 'running' | 'completed'>,
   t: RowTranslate,
 ): { state: StateDotState; label: string } {
   switch (node.pendingInteraction) {
@@ -185,10 +185,11 @@ function sessionStatus(
     default: return assertNever(node.pendingInteraction)
   }
   if (node.running) return { state: 'ongoing', label: t('status.running') }
+  if (node.completed) return { state: 'done', label: t('status.completed') }
   return { state: 'done', label: t('status.idle') }
 }
 
-/** Hover-card body: full title, relative time, and interaction/running/idle status. */
+/** Hover-card body: full title, relative time, and interaction/running/completed/idle status. */
 function SessionHoverContent({ node, now, t }: { node: SessionNode; now: number; t: RowTranslate }) {
   const status = sessionStatus(node, t)
   return (
@@ -251,7 +252,7 @@ export function SearchResultItem({ result, currentId, onOpen, t }: {
     >
       <span className={css.searchResultHeading}>
         <span className={css.slot}>
-          {status.state !== 'done' && (
+          {(status.state !== 'done' || result.completed) && (
             <>
               <StateDot state={status.state} />
               <span className={css.visuallyHidden}>{status.label}</span>
@@ -351,8 +352,11 @@ export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork
           drag.drop(rowHalf(e))
         }}
     >
+      {/* Pending interactions and running outrank the idle state; a
+          finished-but-unviewed session shows the green done reminder dot
+          (cleared by opening the session). */}
       <span className={css.slot}>
-        {status.state !== 'done' && (
+        {(status.state !== 'done' || row.completed) && (
           <>
             <StateDot state={status.state} />
             <span className={css.visuallyHidden}>{status.label}</span>

packages/client/ui-workspace/src/client/tree.ts

@@ -24,6 +24,8 @@ export interface SessionNode {
   /** The runtime Session list reports an interaction awaiting this user. */
   pendingInteraction?: PendingInteractionStatus
   running: boolean
+  /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
+  completed: boolean
   updatedAt: number
 }
 
@@ -54,6 +56,8 @@ export interface SearchResultNode {
   /** The runtime Session list reports an interaction awaiting this user. */
   pendingInteraction?: PendingInteractionStatus
   running: boolean
+  /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
+  completed: boolean
   snippet?: string
 }
 
@@ -175,6 +179,7 @@ function sessionNode(s: SessionSummary): SessionNode {
     title: sessionTitle(s),
     blank: s.blank,
     running: s.running,
+    completed: s.completed === true,
     updatedAt: s.updatedAt,
     ...(s.pendingInteraction === undefined ? {} : { pendingInteraction: s.pendingInteraction }),
   }
@@ -330,6 +335,7 @@ export function deriveSearchResults(
         ...(summary.pendingInteraction === undefined
           ? {}
           : { pendingInteraction: summary.pendingInteraction }),
+        completed: summary.completed === true,
         ...match === undefined ? {} : { snippet: match.snippet },
       }
     }),

packages/client/ui-workspace/tests/rows.spec.tsx

@@ -64,6 +64,7 @@ describe('workspace browser rows', () => {
       title: 'Result title',
       workspace: 'Workspace context',
       running: true,
+      completed: false,
       snippet: 'matching message excerpt',
     }
     render(<SearchResultItem result={result} currentId={result.id} onOpen={onOpen} t={t} />)
@@ -85,7 +86,7 @@ describe('workspace browser rows', () => {
   ] as const)('shows %s ahead of running in search results', (pendingInteraction, label) => {
     const result: SearchResultNode = {
       id: sid(pendingInteraction), title: 'Needs input', workspace: 'Project',
-      pendingInteraction, running: true,
+      pendingInteraction, running: true, completed: false,
     }
     render(<SearchResultItem result={result} currentId={undefined} onOpen={vi.fn()} t={t} />)
     const row = screen.getByRole('treeitem')
@@ -114,7 +115,7 @@ describe('workspace browser rows', () => {
 
   it('renders and opens a selected running Session row', () => {
     const node: SessionNode = {
-      id: sid('session'), title: 'Session', blank: false, running: true, updatedAt: 0,
+      id: sid('session'), title: 'Session', blank: false, running: true, completed: false, updatedAt: 0,
     }
     const onOpen = vi.fn()
     render(
@@ -130,6 +131,38 @@ describe('workspace browser rows', () => {
     expect(onOpen).toHaveBeenCalledWith(node.id)
   })
 
+  it('shows the green done dot only on a finished, unviewed session (running wins the slot)', () => {
+    const renderRow = (over: Partial<SessionNode>) => render(
+      <SessionNodeItem
+        node={{ id: sid('s1'), title: 'One', blank: false, running: false, completed: false, updatedAt: 0, ...over }}
+        currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t}
+      />,
+    )
+    const stateDot = (view: ReturnType<typeof renderRow>) =>
+      view.container.querySelector('[data-state]')
+    // No completion reminder, not running: no state dot at all.
+    const plain = renderRow({})
+    expect(stateDot(plain)).toBeNull()
+    plain.unmount()
+    // Completed while unviewed: the green done dot.
+    const done = renderRow({ completed: true })
+    expect(done.container.querySelector('[data-state="done"]')).not.toBeNull()
+    done.unmount()
+    // Running wins the slot: the animated ongoing dot, no done dot.
+    const running = renderRow({ completed: true, running: true })
+    expect(running.container.querySelector('[data-state="ongoing"]')).not.toBeNull()
+    expect(running.container.querySelector('[data-state="done"]')).toBeNull()
+  })
+
+  it('shows the green done dot on a finished search result row', () => {
+    render(<SearchResultItem
+      result={{ id: sid('result'), title: 'Done', workspace: 'Workspace', running: false, completed: true }}
+      currentId={undefined} onOpen={vi.fn()} t={t}
+    />)
+    expect(screen.getByRole('treeitem').querySelector('[data-state="done"]')).not.toBeNull()
+  })
+
   it('workspace row menu opens on the ellipsis, renames, and shows the danger delete row', () => {
     const onRename = vi.fn()
     const onDelete = vi.fn()
@@ -198,7 +231,7 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s-blank'), title: 'ignored', blank: true, running: false, updatedAt: 0,
+        id: sid('s-blank'), title: 'ignored', blank: true, running: false, completed: false, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={node.id} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -224,7 +257,7 @@ describe('workspace browser rows', () => {
     const onFork = vi.fn()
     const onArchive = vi.fn()
     const node: SessionNode = {
-      id: sid('s1'), title: 'One', blank: false, running: false, updatedAt: 0,
+      id: sid('s1'), title: 'One', blank: false, running: false, completed: false, updatedAt: 0,
     }
     render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={onOpen}
       onRename={onRename} onFork={onFork} onArchive={onArchive} t={t} />)
@@ -257,7 +290,7 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s1'), title: 'Hovered', blank: false, running: true, updatedAt: 0,
+        id: sid('s1'), title: 'Hovered', blank: false, running: true, completed: false, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={undefined} now={60_000} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -288,7 +321,7 @@ describe('workspace browser rows', () => {
     try {
       const node: SessionNode = {
         id: sid(pendingInteraction), title: 'Needs input', blank: false,
-        pendingInteraction, running: true, updatedAt: 0,
+        pendingInteraction, running: true, completed: false, updatedAt: 0,
       }
       const view = render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -314,7 +347,7 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s1'), title: 'Quiet', blank: false, running: false, updatedAt: 0,
+        id: sid('s1'), title: 'Quiet', blank: false, running: false, completed: false, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -327,9 +360,26 @@ describe('workspace browser rows', () => {
     }
   })
 
+  it('completed hover card shows the Completed status line', () => {
+    vi.useFakeTimers()
+    try {
+      const node: SessionNode = {
+        id: sid('s1'), title: 'Done', blank: false, running: false, completed: true, updatedAt: 0,
+      }
+      render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
+      fireEvent.pointerEnter(screen.getByRole('treeitem').parentElement as HTMLElement)
+      act(() => { vi.advanceTimersByTime(500) })
+      // Row's visually-hidden reminder label plus the hover card's status line.
+      expect(screen.getAllByText('已完成')).toHaveLength(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('draggable row wires start/end and gates hover/drop on an active same-group drag', () => {
     const node: SessionNode = {
-      id: sid('s1'), title: 'Drag me', blank: false, running: false, updatedAt: 0,
+      id: sid('s1'), title: 'Drag me', blank: false, running: false, completed: false, updatedAt: 0,
     }
     const inactive = dragProps()
     const { rerender } = render(

packages/client/ui-workspace/tests/tree.spec.ts

@@ -77,6 +77,22 @@ describe('deriveGroups', () => {
     expect(strayGroups.map(group => group.key)).toEqual(['first'])
   })
 
+  it('projects the completion reminder into session and search rows (absent = false)', () => {
+    const done = { ...summary('done', 3), completed: true }
+    const plain = summary('plain', 2)
+    const sessions = list(done, plain)
+    const groups = deriveGroups(
+      sessions, [workspace('first', ['done', 'plain'])], noArchive, view(['first']),
+    )
+    const doneNode = groups[0]!.sessions.find(session => session.id === done.id)!
+    const plainNode = groups[0]!.sessions.find(session => session.id === plain.id)!
+    expect(doneNode.completed).toBe(true)
+    expect(plainNode.completed).toBe(false)
+    expect(deriveFlat(sessions, noArchive).find(node => node.id === done.id)!.completed).toBe(true)
+    const search = deriveSearchResults(sessions, [workspace('first', ['done', 'plain'])], 'done', noArchive, { items: [], hasMore: false }, 10)
+    expect(search.items[0]?.completed).toBe(true)
+  })
+
   it('hides subagent-origin sessions without hiding ordinary forks', () => {
     const parent = summary('parent', 1)
     const fork = { ...summary('fork', 2), parentId: parent.id }
@@ -259,6 +275,7 @@ describe('deriveSearchResults', () => {
           workspace: 'Alpha',
           running: false,
           pendingInteraction: 'plan-review',
+          completed: false,
           snippet: 'title session body excerpt',
         },
         {
@@ -266,12 +283,14 @@ describe('deriveSearchResults', () => {
           title: 'Ordinary title',
           workspace: 'Needle Workspace',
           running: false,
+          completed: false,
         },
         {
           id: contentHit.id,
           title: 'content-hit',
           workspace: 'c',
           running: false,
+          completed: false,
           snippet: 'body needle excerpt',
         },
       ],