Merge master into fix/turn-actions

packages/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/README.md
-README.md: 3f467641bbc9eae14a94aa2d3bff0402116a9d3f
-README.zh.md: c9d11bbf6239b4239a4e037dac63b05d3a9a58f7
+README.md: 0c729f781151fcc0bda81899e51227e71c7b8d2b
+README.zh.md: 660a24eeea5f1a36841654626d94412371a2f462

packages/README.md

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

packages/README.zh.md

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

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

@@ -1042,6 +1042,56 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
         const appended = logOf(sessionId).at(-1) as SessionEvent
         return ok(request, { title: normalized, seq: appended.seq })
       },
+      fork: (request) => {
+        const { sessionId, atSeq } = request.payload
+        const source = summaryOf(sessionId)
+        if (source === undefined) {
+          return err(request, {
+            code: 'session-not-found',
+            message: `no session ${sessionId}`,
+            details: { sessionId },
+          })
+        }
+        const log = logs.get(sessionId) ?? []
+        const lastSeq = log.at(-1)?.seq ?? -1
+        const anchoredBoundary = atSeq === undefined
+          ? undefined
+          : log.find(e => e.type === 'turn/end' && e.seq >= atSeq)
+        const boundary = anchoredBoundary
+          ?? (atSeq === undefined || atSeq > lastSeq
+            ? log.findLast(e => e.type === 'turn/end')
+            : undefined)
+        if (boundary === undefined) {
+          return err(request, {
+            code: 'fork-unavailable',
+            message: atSeq !== undefined && atSeq <= lastSeq
+              ? `session ${sessionId} has not completed the turn containing event ${String(atSeq)}`
+              : `session ${sessionId} has no completed turn`,
+            details: { sessionId },
+          })
+        }
+        let cut = boundary.seq + 1
+        while (cut < log.length && log[cut]?.type !== 'turn/start') cut++
+        const child: SessionSummary = {
+          sessionId: sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, blank: false,
+          parentSessionId: sessionId,
+          ...source.cwd === undefined ? {} : { cwd: source.cwd },
+        }
+        logs.set(child.sessionId, log.slice(0, cut))
+        sessions.push(child)
+        emitHost({
+          type: 'host/session-added', sessionId: child.sessionId, blank: false,
+          parentSessionId: sessionId,
+          ...source.cwd === undefined ? {} : { cwd: source.cwd },
+        })
+        const workspace = workspaces.find(w => w.sessionIds.includes(sessionId))
+        if (workspace !== undefined) {
+          workspace.sessionIds = [child.sessionId, ...workspace.sessionIds]
+          workspace.updatedAt = new Date().toISOString()
+          emitHost({ type: 'host/workspace-changed', workspace: { ...workspace } })
+        }
+        return ok(request, { sessionId: child.sessionId })
+      },
       history: async (request) => {
         const log = logs.get(request.payload.sessionId) ?? []
         // Snapshot at request time, deliver after the transit delay (mirrors a real host under latency).
@@ -1591,6 +1641,7 @@ export class FixtureApiClient extends AbstractApiClient {
       case 'session.models': return this.api.sessions.models(request)
       case 'session.selectModel': return this.api.sessions.selectModel(request)
       case 'session.rename': return this.api.sessions.rename(request)
+      case 'session.fork': return this.api.sessions.fork(request)
       case 'session.prompt': return this.api.sessions.prompt(request)
       case 'session.updateQueue': return this.api.sessions.updateQueue(request)
       case 'session.cancel': return this.api.sessions.cancel(request)

packages/client/connection/tests/fake-api.ts

@@ -46,6 +46,7 @@ export class FakeApiClient implements IApiClient {
   onList: (payload: unknown) => Promise<RpcResponse<{ items: never[] }>> = () => Promise.resolve(ok({ items: [] }))
   onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
   onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
+  onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
   => Promise<RpcResponse<{ events: never[]; hasMore: boolean; modelTarget: ModelTarget }>> =
     () => Promise.resolve(ok({
@@ -99,6 +100,7 @@ export class FakeApiClient implements IApiClient {
     selectModel: (payload: ModelTarget & { sessionId: SessionId }) =>
       this.record('session.selectModel', payload, this.onSelectModel(payload)),
     rename: (payload: unknown) => this.record('session.rename', payload, this.onRename(payload)),
+    fork: (payload: unknown) => this.record('session.fork', payload, this.onFork(payload)),
     prompt: (payload: unknown) => this.record('session.prompt', payload, this.onPrompt(payload)),
     updateQueue: (payload: unknown) => this.record('session.updateQueue', payload, this.onUpdateQueue(payload)),
     cancel: (payload: unknown) => this.record('session.cancel', payload, this.onCancel(payload)),

packages/client/runtime/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/runtime/README.md
-README.md: 766d8516225cd46cb1a3a80c832d1cf55e816140
-README.zh.md: 9b514afca91f604b3e895187de3b5532bf22a692
+README.md: b85deeec92fd4da1f342b5536757692f594853a5
+README.zh.md: 2dbb66c56ad5687fb299fe030d0abfe451004a62

packages/client/runtime/README.md

@@ -28,6 +28,10 @@ SlotsService gives the renderer separate bare observables for `useSessions` and
 
 `SessionManager` retains the latest validated `session/title` control snapshot independently of list and session-instance arrival. Newer event seqs replace older snapshots, title timestamps contribute to list recency, and a subscription baseline discards any retained title beyond its `lastSeq` before the optional folded title arrives. Explicit session removal also clears the retained title. The client-facing `SessionSummary.title` is therefore only the actual durable title; `displayTitle` is always present and falls back through the cwd basename and session id. A cold persisted session keeps that fallback until opening or resuming it causes the host to fold and project its log-backed title. `ISession.rename` settles the `title` projection cell directly from the unary response's `{title, seq}` under the same higher-seq-wins rule — the list row and every `useProjection('title')` reader update ahead of the push frame, whose later replay of the same seq is a no-op.
 
+## Session forking
+
+`ISessions.fork({sessionId, atSeq?, increaseTitle?})` resolves only after the child summary is locally addressable, carrying source lineage and cwd with `blank: false`; callers choose whether to open it. With `increaseTitle: true`, the client renames the child from the source session's persisted title: a trailing `(N)` or `（N）` is incremented without changing bracket style, while any other title gets ` (1)` appended; the rename is skipped when the source has no persisted title, and a rename failure rejects the promise but leaves the created child in place. This option is not sent in the Host fork request. A `workspace-attach-failed` response still identifies a child already published by the Host, so `SessionManager` reconciles that partial success before `SessionForkError` reaches the caller instead of making a retry create a duplicate child.
+
 ## Session model selection
 
 Each resident `Session` owns a `modelSelection` snapshot containing the current provider/model target, provider-grouped directory, provider-local failures, and the `idle`/`loading`/`ready`/`selecting`/`error` state. History establishes or refreshes the current target, opening a selector refreshes the directory, and selection failures preserve the last target and usable groups. Directory and selection operations share a monotonically increasing generation so an older response cannot overwrite a newer selection. A reconnect rebuild restores the target reported by the Host without replacing unchanged selection substructure.

packages/client/runtime/README.zh.md

@@ -28,6 +28,10 @@ SlotsService 分别为 renderer 提供 `useSessions` 与 `useWorkspaces` 的裸
 
 `SessionManager` 独立于列表和 Session 实例到达情况，保留最近一次通过验证的 `session/title` 控制快照。seq 更高的事件会替换旧快照，标题时间戳计入列表新近程度；订阅基线会先丢弃 seq 超过其 `lastSeq` 的任何已保留标题，再接收可选的折叠标题。显式移除 Session 也会清除已保留标题。因此，面向客户端的 `SessionSummary.title` 只包含实际的持久化标题；`displayTitle` 始终存在，并依次回退到 cwd basename 和 Session id。冷态持久化会话会保持该回退值，直到打开或恢复会话，促使主机折叠并投影由日志支撑的标题。`ISession.rename` 用 unary 响应中的 `{title, seq}` 直接结算 `title` 投影格，遵循同一 seq 高者胜规则——列表行和所有 `useProjection('title')` 读者在推送帧到达前即更新；推送帧随后重放同一 seq 时为无操作。
 
+## 会话 fork
+
+`ISessions.fork({sessionId, atSeq?, increaseTitle?})` 只在子会话摘要已能在本地寻址后才完成；该摘要携带源会话的谱系和 cwd，且 `blank: false`，由调用方决定是否打开。`increaseTitle: true` 会在 client 端把源会话的持久化标题改名到子会话：尾部 `(N)` 或 `（N）` 递增并保留括号样式，其余标题追加 ` (1)`；源会话没有持久化标题时跳过改名，改名失败时拒绝 promise 但保留已创建的子会话。该选项不会进入 Host fork 请求。即使响应为 `workspace-attach-failed`，其中仍会标识 Host 已发布的子会话，因此 `SessionManager` 会先将这一部分成功对账，再让 `SessionForkError` 到达调用方，避免重试创建重复的子会话。
+
 ## 会话模型选择
 
 每个常驻 `Session` 都拥有一个 `modelSelection` 快照，其中包含当前提供方/模型目标、按提供方分组的目录、逐提供方失败记录，以及 `idle`／`loading`／`ready`／`selecting`／`error` 状态。历史记录会建立或刷新当前目标，打开选择器会刷新目录；选择失败会保留上一个目标和可用分组。目录与选择操作共用单调递增的代次，因此较旧响应无法覆盖较新的选择。重连重建会恢复 Host 报告的目标，同时不替换未变化的选择子结构。

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

@@ -29,6 +29,17 @@ export interface ISessions {
   open(id: SessionId): void
   /** Clear the current selection into the no-session view state. */
   clear(): void
+  /**
+   * Fork a session from a completed-turn prefix of the source; on resolution
+   * the child is in the list store and `open()` can target it.
+   * @param opts - source session id, the optional event seq anchoring the
+   *   cut (the boundary is the first turn/end at or after it; an in-log
+   *   anchor in an open turn is unavailable rather than clipped backward),
+   *   and whether to increment an inherited durable title before resolving.
+   * @returns the child session id.
+   * @throws when the fork fails, or when a requested child-title rename fails after creation.
+   */
+  fork(opts: { sessionId: SessionId; atSeq?: number; increaseTitle?: boolean }): Promise<SessionId>
   /**
    * Register a per-session standard-props provider (hooks become `use<Name>`
    * selector hooks on the render side; props spread verbatim).

packages/client/runtime/src/client/session-history/source.ts

@@ -1,12 +1,14 @@
 import type {
   HistoryEntry, IApiClient, MuxFrame, RpcError, SessionId,
 } from '@deepseek-ai/dsh-client-connection/client'
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { transportError } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type {
   SessionHistoryFace, SessionHistorySnapshot,
 } from '../contract/session-history.ts'
 import { createHistoryInspection } from '../sessions/history.ts'
 import { Notifier } from '../sessions/notifier.ts'
+import { PartialAccumulator } from '../sessions/partial.ts'
 
 const HISTORY_PAGE_MESSAGES = 50
 
@@ -33,6 +35,9 @@ export class SessionHistorySource implements SessionHistoryFace {
     entries: readonly HistoryEntry[]
     value: SessionHistorySnapshot['inspection']
   } | null = null
+  private streamPublishToken: object | null = null
+  private streamBaseInspection: SessionHistorySnapshot['inspection'] | null = null
+  private streamPartial: PartialAccumulator | null = null
   private snapshotCache: SessionHistorySnapshot
   private readonly notifier = new Notifier(() => {
     this.snapshotCache = this.buildSnapshot()
@@ -125,7 +130,7 @@ export class SessionHistorySource implements SessionHistoryFace {
     if (this.state !== 'cold') {
       this.state = 'cold'
       this.error = null
-      this.notifier.markDirty()
+      this.publishDirtyNow()
     }
   }
 
@@ -143,7 +148,7 @@ export class SessionHistorySource implements SessionHistoryFace {
     this.hasMore = false
     this.state = 'cold'
     this.error = null
-    this.notifier.markDirty()
+    this.publishDirtyNow()
     void this.loadForConsumers()
   }
 
@@ -155,6 +160,9 @@ export class SessionHistorySource implements SessionHistoryFace {
     this.openPromise = null
     this.olderPromise = null
     this.liveBuffer = []
+    this.streamPublishToken = null
+    this.streamBaseInspection = null
+    this.streamPartial = null
   }
 
   private open(): Promise<void> {
@@ -188,7 +196,7 @@ export class SessionHistorySource implements SessionHistoryFace {
   private async doOpen(generation: number): Promise<void> {
     this.state = 'loading'
     this.error = null
-    this.notifier.markDirty()
+    this.publishDirtyNow()
     try {
       let { result } = await this.api.sessions.history({
         sessionId: this.sessionId,
@@ -222,7 +230,7 @@ export class SessionHistorySource implements SessionHistoryFace {
       /* v8 ignore next -- transportError always returns the error branch. */
       this.error = folded.ok ? null : folded.error
     } finally {
-      if (generation === this.generation) this.notifier.markDirty()
+      if (generation === this.generation) this.publishDirtyNow()
     }
   }
 
@@ -261,7 +269,7 @@ export class SessionHistorySource implements SessionHistoryFace {
     const settled = operation.finally(() => {
       if (this.olderPromise !== settled) return
       this.olderPromise = null
-      this.notifier.markDirty()
+      this.publishDirtyNow()
     })
     this.olderPromise = settled
     return settled
@@ -286,7 +294,7 @@ export class SessionHistorySource implements SessionHistoryFace {
     const buffered = this.liveBuffer
     this.liveBuffer = []
     for (const entry of buffered) this.appendLive(entry)
-    this.notifier.markDirty()
+    this.publishDirtyNow()
   }
 
   private acceptLive(entry: HistoryEntry): void {
@@ -301,8 +309,16 @@ export class SessionHistorySource implements SessionHistoryFace {
       void this.repairGap()
       return
     }
+    if (
+      entry.event.type === 'assistant/chunk'
+      && entry.event.data.chunk.type !== 'usage'
+    ) {
+      if (!this.appendIncrementalChunk(entry, entry.event)) return
+      this.publishStreamDirty()
+      return
+    }
     this.appendLive(entry)
-    this.notifier.markDirty()
+    this.publishDirtyNow()
   }
 
   private appendLive(entry: HistoryEntry): void {
@@ -311,6 +327,66 @@ export class SessionHistorySource implements SessionHistoryFace {
     this.entries = [...this.entries, entry]
   }
 
+  /** Append a chunk against the cached finalized projection; false means no visible publish. */
+  private appendIncrementalChunk(
+    entry: HistoryEntry,
+    event: SessionEvent<'assistant/chunk'>,
+  ): boolean {
+    const { turn, step, chunk } = event.data
+    if (!isVisibleAssistantChunk(chunk.type)) {
+      const inspection = this.currentInspection()
+      this.appendLive(entry)
+      this.inspectionCache = { entries: this.entries, value: inspection }
+      return false
+    }
+    const base = this.streamBaseInspection ?? this.currentInspection()
+    this.streamBaseInspection = base
+    if (
+      this.streamPartial === null
+      || this.streamPartial.turn !== turn
+      || this.streamPartial.step !== step
+    ) {
+      const current = base.partial
+      this.streamPartial = new PartialAccumulator(
+        turn,
+        step,
+        current?.turn === turn && current.step === step ? current.blocks : [],
+      )
+    }
+    this.streamPartial.push(chunk)
+    this.appendLive(entry)
+    this.inspectionCache = {
+      entries: this.entries,
+      value: { ...base, partial: this.streamPartial.toPartial() },
+    }
+    return true
+  }
+
+  /** Coalesce token-stream projection and rendering work to one publish per browser frame. */
+  private publishStreamDirty(): void {
+    if (this.streamPublishToken !== null) return
+    const token = {}
+    this.streamPublishToken = token
+    const publish = () => {
+      if (this.streamPublishToken !== token) return
+      this.streamPublishToken = null
+      this.notifier.markDirty()
+    }
+    if (typeof globalThis.requestAnimationFrame === 'function') {
+      globalThis.requestAnimationFrame(publish)
+    } else {
+      queueMicrotask(publish)
+    }
+  }
+
+  /** Publish structural changes immediately and invalidate an older scheduled stream publish. */
+  private publishDirtyNow(): void {
+    this.streamPublishToken = null
+    this.streamBaseInspection = null
+    this.streamPartial = null
+    this.notifier.markDirty()
+  }
+
   private async repairGap(): Promise<void> {
     if (this.stitching) return
     this.stitching = true
@@ -335,6 +411,16 @@ export class SessionHistorySource implements SessionHistoryFace {
   }
 
   private buildSnapshot(): SessionHistorySnapshot {
+    return {
+      state: this.state,
+      error: this.error,
+      hasMore: this.hasMore,
+      inspection: this.currentInspection(),
+    }
+  }
+
+  /** Inspection pinned to the source's current immutable entry array. */
+  private currentInspection(): SessionHistorySnapshot['inspection'] {
     if (this.inspectionCache?.entries !== this.entries) {
       const entries = this.entries
       this.inspectionCache = {
@@ -342,11 +428,14 @@ export class SessionHistorySource implements SessionHistoryFace {
         value: createHistoryInspection(() => entries),
       }
     }
-    return {
-      state: this.state,
-      error: this.error,
-      hasMore: this.hasMore,
-      inspection: this.inspectionCache.value,
-    }
+    return this.inspectionCache.value
   }
 }
+
+function isVisibleAssistantChunk(type: string): boolean {
+  return type === 'block-start'
+    || type === 'text-delta'
+    || type === 'reasoning-delta'
+    || type === 'tool-call-delta'
+    || type === 'block-end'
+}

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

@@ -289,6 +289,40 @@ export class SessionManager {
     }
   }
 
+  /**
+   * Contract session.fork; on success merge the child into summaries
+   * immediately (same synchronous-addressability guarantee as create). The
+   * child carries the source's history, so it is never blank; lineage rides
+   * parentSessionId so the list nests it under its source. A child published
+   * before Workspace attachment fails is also reconciled into the list.
+   * @param opts - source session and the optional seq anchoring the cut.
+   * @returns the fork result (the child session id).
+   */
+  async fork(
+    opts: { sessionId: SessionId; atSeq?: number },
+  ): Promise<RpcResult<{ sessionId: SessionId }>> {
+    try {
+      const source = this.summaries.find(s => s.sessionId === opts.sessionId)
+      const { result } = await this.api.sessions.fork({
+        sessionId: opts.sessionId,
+        ...opts.atSeq === undefined ? {} : { atSeq: opts.atSeq },
+      })
+      const childId = result.ok
+        ? result.value.sessionId
+        : workspaceAttachSessionId(result.error)
+      if (childId !== undefined) {
+        this.recordMutation({ kind: 'upsert', summary: {
+          sessionId: childId, updatedAt: Date.now(), running: false, blank: false,
+          parentSessionId: opts.sessionId,
+          ...(source?.cwd !== undefined ? { cwd: source.cwd } : {}),
+        } })
+      }
+      return result
+    } catch (error) {
+      return transportError(error)
+    }
+  }
+
   /**
    * Insert-or-enrich a locally synthesized summary: a new id prepends; an
    * existing entry only gains fields it lacks (the session-added frame and the

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

@@ -13,8 +13,18 @@ export class PartialAccumulator {
   private changed = true
   private snapshot: PartialAssistant
 
-  constructor(readonly turn: number, readonly step: number) {
-    this.snapshot = { turn, step, blocks: [] }
+  /**
+   * @param turn - Owning agent turn.
+   * @param step - Owning model step.
+   * @param initialBlocks - Materialized prefix when accumulation begins after history replay.
+   */
+  constructor(
+    readonly turn: number,
+    readonly step: number,
+    initialBlocks: readonly AssistantBlock[] = [],
+  ) {
+    this.blocks = [...initialBlocks]
+    this.snapshot = { turn, step, blocks: initialBlocks }
   }
 
   /**

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

@@ -81,6 +81,22 @@ export class SessionCreateError extends Error {
   }
 }
 
+/** Structured session-fork failure. */
+export class SessionForkError extends Error {
+  override readonly name = 'SessionForkError'
+
+  /**
+   * @param rpcError - Host business or folded transport error.
+   * @param sourceSessionId - the session the fork was cut from.
+   */
+  constructor(
+    readonly rpcError: RpcError,
+    readonly sourceSessionId: SessionId,
+  ) {
+    super(`session fork failed: ${rpcError.code}: ${rpcError.message}`)
+  }
+}
+
 /** Session assembly handle for SessionProvider/inject factories (identity-stable per session). */
 export interface SessionBinding {
   readonly sessionId: SessionId
@@ -121,6 +137,24 @@ function displayTitleOf(title: string | undefined, cwd: string | undefined, id:
   return id
 }
 
+/**
+ * Increment a trailing fork number while preserving its half-width or
+ * full-width parentheses; an unnumbered title starts with ` (1)`.
+ * @param title - source session's durable title.
+ * @returns the title assigned to the fork child.
+ */
+function increasedForkTitle(title: string): string {
+  const ascii = /^(.*?)\((\d+)\)$/u.exec(title)
+  if (ascii?.[1] !== undefined && ascii[2] !== undefined) {
+    return `${ascii[1]}(${BigInt(ascii[2]) + 1n})`
+  }
+  const fullWidth = /^(.*?)（(\d+)）$/u.exec(title)
+  if (fullWidth?.[1] !== undefined && fullWidth[2] !== undefined) {
+    return `${fullWidth[1]}（${BigInt(fullWidth[2]) + 1n}）`
+  }
+  return `${title} (1)`
+}
+
 interface ScopeRecord {
   fiber: Fiber
   ctx: Context
@@ -317,6 +351,42 @@ export class SessionsService implements ISessions {
     return result.value.sessionId
   }
 
+  /**
+   * Fork a session from a completed-turn prefix of the source (same
+   * synchronous-addressability guarantee as {@link SessionsService.create}:
+   * on resolution the child is in the list store and open() can target it).
+   * @param opts - source session id, the optional event seq anchoring the
+   *   cut (the boundary is the first turn/end at or after it; an in-log
+   *   anchor in an open turn is unavailable rather than clipped backward),
+   *   and whether to increment an inherited durable title before resolving.
+   * @returns the child session id.
+   * @throws {SessionForkError} with the source id.
+   * @throws {Error} when a requested child-title rename fails after creation.
+   */
+  async fork(opts: {
+    sessionId: SessionId
+    atSeq?: number
+    increaseTitle?: boolean
+  }): Promise<SessionId> {
+    const sourceTitle = opts.increaseTitle
+      ? this.list.getSnapshot().byId[opts.sessionId]?.title
+      : undefined
+    const result = await this.manager.fork({
+      sessionId: opts.sessionId,
+      ...(opts.atSeq === undefined ? {} : { atSeq: opts.atSeq }),
+    })
+    if (!result.ok) throw new SessionForkError(result.error, opts.sessionId)
+    this.projectList()
+    const childId = result.value.sessionId
+    if (sourceTitle !== undefined) {
+      const child = this.binding(childId)?.session
+      if (child === undefined) throw new Error(`fork child "${childId}" is not locally addressable`)
+      const renamed = await child.rename(increasedForkTitle(sourceTitle))
+      if (!renamed.ok) throw new Error(`fork child rename failed: ${renamed.error.code}: ${renamed.error.message}`)
+    }
+    return childId
+  }
+
   /**
    * Resolve an Agent-scoped context view (use-and-discard).
    * @param id - session id (the agent identity — 1:1 same axis).

packages/client/runtime/tests/fake-api.ts

@@ -64,6 +64,7 @@ export class FakeApiClient implements IApiClient {
   onCreate: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-new' as SessionId }))
   readonly defaultModel: ModelTarget = { provider: 'deepseek', model: 'deepseek-v4-flash' }
   onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
+  onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
   => Promise<RpcResponse<{ events: never[]; hasMore: boolean }>> =
     () => Promise.resolve(ok({ events: [], hasMore: false }))
@@ -118,6 +119,7 @@ export class FakeApiClient implements IApiClient {
     selectModel: (payload: { provider: string; model: string }) =>
       this.record('session.selectModel', payload, this.onSelectModel(payload)),
     rename: (payload: unknown) => this.record('session.rename', payload, this.onRename(payload)),
+    fork: (payload: unknown) => this.record('session.fork', payload, this.onFork(payload)),
     prompt: (payload: unknown) => this.record('session.prompt', payload, this.onPrompt(payload)),
     updateQueue: (payload: unknown) => this.record('session.updateQueue', payload, this.onUpdateQueue(payload)),
     cancel: (payload: unknown) => this.record('session.cancel', payload, this.onCancel(payload)),

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

@@ -277,6 +277,23 @@ describe('remaining branches', () => {
     expect(manager.getListSnapshot().items[0]).not.toHaveProperty('cwd')
   })
 
+  it('reconciles a fork child published before workspace attachment fails', async () => {
+    const api = new FakeApiClient()
+    api.onFork = () => Promise.resolve(err({
+      code: 'workspace-attach-failed',
+      message: 'forked but unattached',
+      details: { sessionId: S2, workspaceId: 'w1' },
+    } as never))
+    const manager = new SessionManager(api)
+    const result = await manager.fork({ sessionId: S1 })
+    expect(result).toMatchObject({ ok: false, error: { code: 'workspace-attach-failed' } })
+    expect(manager.getListSnapshot().items).toEqual([expect.objectContaining({
+      sessionId: S2,
+      parentSessionId: S1,
+      blank: false,
+    })])
+  })
+
   it('reconciles a preallocated id after an ordinary transport failure', async () => {
     const api = new FakeApiClient()
     api.onCreate = () => Promise.reject(new Error('response lost'))

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

@@ -41,6 +41,12 @@ describe('PartialAccumulator', () => {
     expect(acc.toPartial().blocks).toEqual([{ kind: 'reasoning', text: '思考' }])
   })
 
+  it('continues from a materialized history prefix', () => {
+    const acc = new PartialAccumulator(1, 0, [{ kind: 'text', text: '已有' }])
+    acc.push(chunk({ type: 'text-delta', index: 0, text: '增量' }))
+    expect(acc.toPartial().blocks).toEqual([{ kind: 'text', text: '已有增量' }])
+  })
+
   it('folds tool-call deltas: first id pins callId, late name overrides, argsRaw concatenates', () => {
     const acc = new PartialAccumulator(1, 0)
     acc.push(chunk({ type: 'tool-call-delta', index: 0, id: 'c1', argumentsDelta: '{"a"' }))

packages/client/runtime/tests/session-history-source.spec.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import { SessionHistorySource } from '../src/client/session-history/source.ts'
@@ -7,6 +7,10 @@ import { entries, ev, plainTurn } from './event-script.ts'
 
 const SID = 'history-s1' as SessionId
 
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
 function histResponse(events: SessionEvent[], hasMore = false) {
   return Promise.resolve(ok({ events: entries(events) as never[], hasMore }))
 }
@@ -52,6 +56,71 @@ describe('SessionHistorySource', () => {
       .toEqual([1, 3, 6])
   })
 
+  it('publishes multiple assistant chunks once per browser frame', async () => {
+    const api = new FakeApiClient()
+    api.onHistory = () => histResponse(plainTurn(0, 0, '问', '答'))
+    const source = new SessionHistorySource(SID, api)
+    await source.loadAll()
+    const frames: FrameRequestCallback[] = []
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+      frames.push(callback)
+      return frames.length
+    })
+    let notifications = 0
+    const unsubscribe = source.subscribe(() => { notifications++ })
+    const before = source.getSnapshot().inspection
+    const finalizedNodes = before.eventNodes
+    const requests = before.requests
+    const contexts = before.contexts
+
+    for (const event of [
+      ev.chunkStart(6, 1),
+      ev.chunkText(7, 1, 'stream '),
+      ev.chunkText(8, 1, 'content'),
+    ]) {
+      source.handleMuxFrame({
+        type: 'session/event',
+        sessionId: SID,
+        event,
+      })
+    }
+
+    expect(frames).toHaveLength(1)
+    expect(notifications).toBe(0)
+    frames[0]?.(0)
+    await Promise.resolve()
+
+    expect(notifications).toBe(1)
+    const streamed = source.getSnapshot().inspection
+    expect(streamed.eventNodes).toBe(finalizedNodes)
+    expect(streamed.requests).toBe(requests)
+    expect(streamed.contexts).toBe(contexts)
+    expect(streamed.partial?.blocks).toEqual([
+      { kind: 'text', text: 'stream content' },
+    ])
+
+    source.handleMuxFrame({
+      type: 'session/event',
+      sessionId: SID,
+      event: ev.chunkText(9, 1, ' then final'),
+    })
+    source.handleMuxFrame({
+      type: 'session/event',
+      sessionId: SID,
+      event: ev.assistant(10, 1, 'stream content then final'),
+    })
+    await Promise.resolve()
+
+    expect(notifications).toBe(2)
+    const finalized = source.getSnapshot().inspection
+    expect(finalized.eventNodes).not.toBe(finalizedNodes)
+    expect(finalized.partial).toBeNull()
+    frames[1]?.(0)
+    await Promise.resolve()
+    expect(notifications).toBe(2)
+    unsubscribe()
+  })
+
   it('stops loading when an older page fails to advance', async () => {
     const api = new FakeApiClient()
     api.onHistory = payload => payload.beforeSeq === undefined

packages/client/runtime/tests/sessions-service.spec.ts

@@ -10,7 +10,7 @@ import { Context } from 'cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 import { SessionCreateError, SessionsService, scopeOf } from '../src/client/sessions/service.ts'
-import { FakeApiClient, deferred, ok } from './fake-api.ts'
+import { FakeApiClient, deferred, err, ok } from './fake-api.ts'
 
 const sid = (s: string): SessionId => s as SessionId
 
@@ -399,6 +399,69 @@ describe('create', () => {
   })
 })
 
+describe('fork', () => {
+  it.each([
+    ['Roadmap', 'Roadmap (1)'],
+    ['Roadmap (1)', 'Roadmap (2)'],
+    ['计划（1）', '计划（2）'],
+    ['计划 （9）', '计划 （10）'],
+  ])('increments the durable title %j after the child is published', async (sourceTitle, childTitle) => {
+    const b = bench()
+    b.svc.handleMuxEnvelope({
+      rpcId: 'source-title' as never,
+      payload: { type: 'session/projection', sessionId: sid('source'), key: 'title', value: sourceTitle, seq: 2 } as never,
+    })
+    await feedList(b, [{ id: 'source', cwd: '/work' }])
+    b.api.onFork = () => Promise.resolve(ok({ sessionId: sid('child') }))
+    b.api.onRename = (payload) => {
+      const { title } = payload as { title: string }
+      return Promise.resolve(ok({ title, seq: 3 }))
+    }
+
+    await expect(b.svc.fork({
+      sessionId: sid('source'), atSeq: 7, increaseTitle: true,
+    })).resolves.toBe('child')
+
+    expect(b.api.callsOf('session.fork')).toEqual([{ sessionId: 'source', atSeq: 7 }])
+    expect(b.api.callsOf('session.rename')).toEqual([{ sessionId: 'child', title: childTitle }])
+    await Promise.resolve()
+    expect(b.svc.list.getSnapshot().byId[sid('child')]).toMatchObject({
+      title: childTitle,
+      displayTitle: childTitle,
+      parentId: 'source',
+    })
+  })
+
+  it('does not rename without the title policy or a durable source title', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 'source', cwd: '/work' }])
+    b.api.onFork = () => Promise.resolve(ok({ sessionId: sid('child') }))
+    await expect(b.svc.fork({ sessionId: sid('source'), increaseTitle: true })).resolves.toBe('child')
+    expect(b.api.callsOf('session.rename')).toEqual([])
+
+    b.api.onFork = () => Promise.resolve(ok({ sessionId: sid('child-2') }))
+    await expect(b.svc.fork({ sessionId: sid('source') })).resolves.toBe('child-2')
+    expect(b.api.callsOf('session.rename')).toEqual([])
+  })
+
+  it('rejects when child rename fails while keeping the published child addressable', async () => {
+    const b = bench()
+    b.svc.handleMuxEnvelope({
+      rpcId: 'source-title' as never,
+      payload: { type: 'session/projection', sessionId: sid('source'), key: 'title', value: 'Roadmap', seq: 2 } as never,
+    })
+    await feedList(b, [{ id: 'source' }])
+    b.api.onFork = () => Promise.resolve(ok({ sessionId: sid('child') }))
+    b.api.onRename = () => Promise.resolve(err({
+      code: 'title-invalid', message: 'rejected', details: { sessionId: sid('child') },
+    }))
+
+    await expect(b.svc.fork({ sessionId: sid('source'), increaseTitle: true }))
+      .rejects.toThrow('fork child rename failed: title-invalid: rejected')
+    expect(b.svc.binding(sid('child'))).toBeDefined()
+  })
+})
+
 describe('scope lifecycle rides the list mirror (entity parity: no client-side pre-birth)', () => {
   it('a session-added frame births the row (blank) and makes the scope resolvable; removal prunes it', async () => {
     const b = bench()

packages/client/test-runtime/src/sessions.ts

@@ -169,7 +169,7 @@ export class TestSessions implements ISessions {
   private readonly channel: SessionProvideChannel
 
   /** Calls observed on the service-level face (open/clear), newest last. */
-  readonly calls: { method: 'open' | 'clear'; args: unknown[] }[] = []
+  readonly calls: { method: 'open' | 'clear' | 'fork'; args: unknown[] }[] = []
 
   /**
    * @param stabilize - the owning runtime's act wrapper.
@@ -392,6 +392,17 @@ export class TestSessions implements ISessions {
     this.list.update((draft) => { draft.current = undefined })
   }
 
+  /**
+   * Recorded fork stub: no child materializes (benches asserting the full
+   * fork flow drive the production service; this face only proves the call).
+   * @param opts - source session id, optional cut anchor, and client title policy.
+   * @returns the source id (no child record is created).
+   */
+  fork(opts: { sessionId: SessionId; atSeq?: number; increaseTitle?: boolean }): Promise<SessionId> {
+    this.calls.push({ method: 'fork', args: [opts] })
+    return Promise.resolve(opts.sessionId)
+  }
+
   /**
    * The session face of a fixture (typed view for assertions; fixture
    * behavior methods are grafted onto it).

packages/client/test-runtime/tests/runtime.spec.tsx

@@ -201,7 +201,7 @@ describe('sessions', () => {
     await runtime.dispose()
   })
 
-  it('records service-face calls; open() moves the selection and clear() empties it', async () => {
+  it('records service-face calls; open() moves selection, clear() empties it, and fork() echoes the source', async () => {
     const runtime = await runtimeWithFrame()
     await runtime.sessions.add({ id: 's1' })
     await runtime.sessions.add({ id: 's2' })
@@ -211,9 +211,13 @@ describe('sessions', () => {
     runtime.sessions.clear()
     await runtime.flush()
     expect(runtime.sessions.list.getSnapshot().current).toBeUndefined()
+    await expect(runtime.sessions.fork({
+      sessionId: 's1' as SessionId, atSeq: 7, increaseTitle: true,
+    })).resolves.toBe('s1')
     expect(runtime.sessions.calls).toEqual([
       { method: 'open', args: ['s1'] },
       { method: 'clear', args: [] },
+      { method: 'fork', args: [{ sessionId: 's1', atSeq: 7, increaseTitle: true }] },
     ])
     await runtime.dispose()
   })

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: 77f73408953003899b0b90661b01a2d0411f01cb
-README.zh.md: 1ce9787df01719b81115448f914a74aad9a99b16
+README.md: bfb56dc52406e1377cd84c87866a644ade10293a
+README.zh.md: e09bdcc4bebd8176a3061b221e07ae73a7a8941c

packages/client/ui-conversation/README.md

@@ -20,6 +20,8 @@ Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.to
 
 The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> 已完成 · <active item>` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: -1` — above the queue rows — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"<done>/<total> tasks · <n> in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
 
+`QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `"<n> 条排队消息"` header whose button expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Each visible row remains a single-line preview with its exact-occurrence edit and delete actions.
+
 Per-session UI state for selection and the active view lives in the declared chat store (`stores.ts` `createChatStore`); the InputHub owns the composer state machine and mirrors its draft into that store for persistence. Apply passes one store handle to the strict session subtree, chat view, and details registrations, so each session shares one instance and the framework owns its lifecycle. Components are pure: the framework standard kit supplies `useSession`/`sessionId`, global `useSessions`/`useWorkspaces`, and the input machine's `useInput`/`inputActions`; store faces and inject factories supply the remaining state and callbacks.
 
 The composer bar declares session-scoped single seats for `'conversation.input.plan'` (right of the local access-mode control) and `'conversation.input.model'` (immediately before the pending indicator and send/stop button), plus list slots for overlay, dock, left, and right input extensions. Feature packages own each control and its state; ui-conversation supplies placement, the `locked` owner prop, and the standard slot shares. While the `plan` projection's effective target is plan mode, InputBar swaps its textarea placeholder to the plan-task wording, localized through the `command.hint` locale namespace this package registers and shared verbatim with the claimed `/plan` command hint (a host-folded value read through the standard-kit `useProjection`; owner-supplied placeholders win). A pending composer takeover remains mounted when another conversation view is active so the blocked agent can still receive its answer; without a pending interaction, the active-session composer belongs to Chat. The composer-bar slot itself is `session-maybe`: with no current session the same bar renders inert (machine faces absent, `disabled` owner prop) instead of swapping in a parallel disabled tree, so the textarea DOM survives the workspace pick; the strict-session control seats simply stay empty until a session exists.
@@ -38,7 +40,7 @@ None; this package neither assembles nor sends a provider request.
 
 - **Stats-line durations cover the in-window flow only** — LLM and tool wall times fold the snapshot's assistant `timing` and tool call/result pairs, so nodes outside the loaded event window (older history) are not counted.
 - **Details panel is the minimal form and currently has no entry point** — selected call args/result raw display; the Input/Output/Metadata switch, Prev/Next stepping, and See-in-trajectory deep link are deferred. Tool rows stopped being details-panel click targets and nothing replaced that gesture, so `ChatViewInjected.openDetails` is implemented but uncalled and the panel (including its terminal card) is unreachable in the assembled application; its rendering stays covered by mounting it with a selection directly.
-- **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under the last content-text assistant of each turn only; mid-turn narration and Think-only nodes stay chrome-free; branch remains a chrome stub.
+- **Assistant per-message paging is a reserved slot** — drawn in the design, not implemented. The finalized content IconActions row (copy / branch / clock) ships under the last content-text assistant of each turn only; mid-turn narration and Think-only nodes stay chrome-free. Branch forks through the turn containing that message, increments the inherited title on the client, and then opens the child, while a fork or rename failure leaves the source selected.
 - **The sparkle icon for the others tool row is a hand-drawn approximation** — the design glyph's vector geometry is not exportable locally; promotion into ui-primitives waits on an exact export.
 - **The approval panel's "Always allow this type" is deferred** — durable grants need a grant-storage design; only allow-once/reject answer today.
 - **TodoPanel truncates long item text to one ellipsized line** — the figma strip has no wrap or expand affordance; full text is not readable inline.

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

@@ -20,6 +20,8 @@
 
 todo 两个面就是在该形状上的两个注册项，都是普通注册方插件，`inject: ['slots', 'conversation']`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: -1` 占用 `'conversation.input.dock'` 列表 slot（位于队列行之上），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加 `"<已完成>/<总数> tasks · <n> in progress"`（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
 
+`QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `"<n> 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。每条可见行仍是单行预览，并提供针对精确单次入队项的编辑和删除操作。
+
 逐 Session UI 状态中的选择与活跃视图位于已声明的聊天 store（`stores.ts` `createChatStore`）中；InputHub 拥有输入区状态机，并将草稿镜像到该 store 以便持久化。apply 将同一个 store handle 传给严格限定于会话的子树、聊天视图和详情注册，因此每个会话内共享一个实例，框架拥有其生命周期。组件保持纯粹：框架标准工具包提供 `useSession`／`sessionId`、全局 `useSessions`／`useWorkspaces`，以及输入状态机的 `useInput`／`inputActions`；store 表层与 inject factory 提供其余状态和回调。
 
 输入栏为 `'conversation.input.plan'`（位于本地 access 模式控件右侧）和 `'conversation.input.model'`（渲染在 pending 指示器与发送／停止按钮之前）声明会话作用域的单实例 seat，并为 overlay、dock、left 和 right 输入扩展声明列表 slot。各功能包拥有相应控件及其状态；ui-conversation 提供放置位置、`locked` owner prop 和标准 slot share。当 `plan` 投影的有效目标为 plan mode 时，InputBar 将文本框 placeholder 切换为 plan 任务措辞，经本包注册的 `command.hint` locale 命名空间本地化，并与已认领 `/plan` 命令的提示逐字共用同一份文案（经标准套件 `useProjection` 读取的 host 折叠值；owner 提供的 placeholder 优先）。另一个会话视图活跃时，待处理的 composer 接管仍保持挂载，使被阻塞的 agent（智能体）仍能收到回答；没有待处理交互时，活跃会话的 composer 归 Chat 所有。composer bar slot 本身为 `session-maybe`：没有当前会话时，同一个 bar 以不可交互状态渲染（machine face 均缺席、`disabled` owner prop），而不是换入一棵平行的 disabled 树，因此选择 workspace 时 textarea DOM 不会被销毁；严格会话作用域的控件 seat 在会话存在之前保持为空。
@@ -36,9 +38,9 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插
 
 ## 已知限制与暂缓事项
 
-- **统计行的耗时只覆盖窗口内消息流**：LLM 与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。
+- **统计行的耗时只覆盖窗口内消息流**：LLM（大语言模型）与工具墙钟时间由快照的 assistant `timing` 与工具 call/result 配对折算，落在已加载事件窗口之外的节点（更早的历史）不计入。
 - **详情面板是最小形态，且当前没有入口**：以原始形式显示已选择调用的参数／结果；Input/Output/Metadata 切换、Prev/Next 步进与 See-in-trajectory 深链接暂缓实现。工具行已不再是详情面板的点击目标，且没有任何手势接替它，因此 `ChatViewInjected.openDetails` 虽已实现却无人调用，该面板（含其终端卡片）在组装后的应用中不可达；其渲染仍由直接以选中态挂载它来覆盖。
-- **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在每个 turn 最后一条带 text 的 assistant 消息下；turn 中间叙述与纯 Think 节点不带 chrome；分支仍是 chrome stub。
+- **assistant 逐消息分页是预留 slot**：设计中已有图稿，尚未实现。已定稿的内容 IconActions 行（复制／分支／时钟）只挂在每个轮次中最后一条带 text 内容的 assistant 下；轮次中间的叙述与纯 Think 节点不带 chrome。分支会 fork 到包含该消息的轮次末尾，在 client 端递增继承标题后打开子会话，而 fork 或改名失败时源会话保持选中。
 - **others 工具行的闪光图标是手绘近似版本**：无法在本地导出设计字形的矢量几何；等到存在精确导出后再将其提升到 ui-primitives。
 - **审批面板的「始终允许此类」暂缓**：持久授权需要授权存储设计；今天只能回答允许一次／拒绝。
 - **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。

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

@@ -262,6 +262,13 @@ export function apply(ctx: Context): void {
           })
         },
         loadOlder: () => { void scoped.loadOlder() },
+        forkAt: (seq) => {
+          sessions.fork({ sessionId, atSeq: seq, increaseTitle: true })
+            .then((childId) => { sessions.open(childId) })
+            .catch(() => {
+              // Fork or child-rename failure keeps the source view untouched.
+            })
+        },
       }
     },
   }, ChatView)

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

@@ -25,6 +25,10 @@ export interface AssistantMarkdownProps {
   /** Unix epoch ms for the IconActions clock; omitted while streaming or when
    *  the parent withholds chrome (mid-turn content assistants). */
   time?: number | undefined
+  /** Event sequence used as the fork boundary; omitted while streaming. */
+  seq?: number | undefined
+  /** Fork the session through the turn containing this finalized message. */
+  onFork?: ((seq: number) => void) | undefined
 }
 
 function firstLine(text: string): string {
@@ -62,7 +66,7 @@ function ThinkRow({ text, running }: { text: string; running: boolean }) {
 }
 
 export const AssistantMarkdown = memo(function AssistantMarkdown({
-  blocks, streaming, interrupted, time,
+  blocks, streaming, interrupted, time, seq, onFork,
 }: AssistantMarkdownProps) {
   const last = blocks.length - 1
   // Tool-call heads render as tool rows in the chat view's grouping pass, so
@@ -93,6 +97,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
           text={copyText(blocks)}
           time={time}
           clock="end"
+          onBranch={onFork === undefined || seq === undefined ? undefined : () => { onFork(seq) }}
           className={css.actions}
         />
       )}

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

@@ -230,7 +230,7 @@ function StreamingTail({ useSession, onGrow }: {
  * The chat view slot entry: pure component over the composed props (tool rows
  * render through the declared keyed hole's renderSlot share).
  */
-export function ChatView({ useSession, useSessions, useStore, renderSlot, sessionId, openFile, loadOlder }: ChatViewSlotProps) {
+export function ChatView({ useSession, useSessions, useStore, renderSlot, sessionId, openFile, loadOlder, forkAt }: ChatViewSlotProps) {
   const nodes = useSession(s => s.nodes)
   // Workspace root off the session list row: path summaries display relative to it.
   const cwd = useSessions(s => s.byId[sessionId]?.cwd)
@@ -380,6 +380,8 @@ export function ChatView({ useSession, useSessions, useStore, renderSlot, sessio
           streaming={false}
           interrupted={node.interrupted}
           time={actionSeqs.has(node.seq) ? node.time : undefined}
+          seq={node.seq}
+          onFork={forkAt}
         />
       )
     }
@@ -388,7 +390,7 @@ export function ChatView({ useSession, useSessions, useStore, renderSlot, sessio
     }
     /* v8 ignore next -- tool-result never reaches here: deriveChatFlow folds them into groups. */
     if (node.kind === 'tool-result') return null
-    return <MessageItem key={item.key} node={node} />
+    return <MessageItem key={item.key} node={node} onFork={forkAt} />
   }
 
   return (

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

@@ -1,5 +1,6 @@
-// Shared IconActions chrome for user and assistant messages: copy / branch
-// live (branch still a stub), date-aware clock, optional edit stub.
+// Shared IconActions chrome for user and assistant messages: copy live,
+// branch wired through onBranch, date-aware clock,
+// optional edit stub.
 
 import { useCallback } from 'react'
 import {
@@ -18,17 +19,19 @@ export interface MessageIconActionsProps {
   clock: 'start' | 'end'
   /** When true, append the stub edit control (user bubble). */
   edit?: boolean | undefined
+  /** Fork the session at this message. */
+  onBranch?: (() => void) | undefined
   /** Parent layout class composed onto the actions row. */
   className?: string | undefined
 }
 
 /**
  * Copy / branch (/ clock) IconActions row shared by user and assistant chrome.
- * @param props - Copy text, event time, clock side, optional edit, className.
+ * @param props - Copy text, event time, clock side, optional edit, branch callback, className.
  * @returns The actions row element.
  */
 export function MessageIconActions({
-  text, time, clock, edit, className,
+  text, time, clock, edit, onBranch, className,
 }: MessageIconActionsProps) {
   const day = useCalendarDay()
   const onCopy = useCallback(() => {
@@ -48,7 +51,7 @@ export function MessageIconActions({
         </button>
       </Tooltip>
       <Tooltip label="在新对话中分支" side="bottom">
-        <button type="button" className={css.action} aria-label="在新对话中分支">
+        <button type="button" className={css.action} aria-label="在新对话中分支" onClick={onBranch}>
           <IconBranchOutline16 />
         </button>
       </Tooltip>

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

@@ -16,6 +16,8 @@ import css from './MessageItem.module.css'
 
 export interface MessageItemProps {
   node: UserMessageNode | SteeringMessageNode | ContextMessageNode | UnknownSurfaceNode
+  /** Fork the session through the turn containing this message (user-bubble branch action). */
+  onFork?: (seq: number) => void
 }
 
 function contentText(content: readonly unknown[]): { text: string; rest: unknown[] } {
@@ -61,7 +63,7 @@ function projectUserText(text: string): ReactNode {
   return <>{parts}</>
 }
 
-export const MessageItem = memo(function MessageItem({ node }: MessageItemProps) {
+export const MessageItem = memo(function MessageItem({ node, onFork }: MessageItemProps) {
   switch (node.kind) {
     case 'user': {
       const { text, rest } = contentText(node.content)
@@ -76,6 +78,7 @@ export const MessageItem = memo(function MessageItem({ node }: MessageItemProps)
             time={node.time}
             clock="start"
             edit
+            onBranch={onFork === undefined ? undefined : () => { onFork(node.seq) }}
             className={css.actions}
           />
         </div>

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

@@ -419,6 +419,8 @@ export interface ChatViewInjected {
    */
   openFile: (path: string) => void
   loadOlder: () => void
+  /** Fork the session through the turn containing the message at `seq`, then open the child. */
+  forkAt: (seq: number) => void
 }
 
 /** Full chat-view component props: runtime share & the declared toolview/commandview holes' render share & store share & injected share. */

packages/client/ui-conversation/src/client/queue/QueueDock.module.css

@@ -20,6 +20,8 @@
   padding-top: 2px;
   border-radius: 14px 14px 0 0;
   background: var(--dsw-specific-tip);
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
 }
 
 .panel::after {
@@ -32,7 +34,52 @@
   pointer-events: none;
 }
 
+.header {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  height: 36px;
+  padding: 4px 16px 4px 12px;
+  border: none;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+  text-align: left;
+  cursor: pointer;
+}
+
+.header:focus-visible {
+  outline: 2px solid var(--dsw-alias-label-tertiary);
+  outline-offset: -2px;
+}
+
+.header:disabled {
+  cursor: default;
+}
+
+.count {
+  flex: 1 1 auto;
+  min-width: 0;
+  font-family: Inter, var(--dsw-font-family);
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 24px;
+}
+
+.chevron {
+  display: grid;
+  flex: none;
+  place-items: center;
+  width: 14px;
+  height: 14px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
 .list {
+  max-height: 180px;
+  overflow-y: auto;
   margin: 0;
   padding: 0;
   list-style: none;

packages/client/ui-conversation/src/client/queue/QueueDock.tsx

@@ -4,11 +4,12 @@
 // The 'conversation.input.dock' SlotMap declaration lives in
 // ../contract/slots.ts beside the other input-region slots.
 import type { Context } from 'cordis'
-import { useEffect, useState } from 'react'
+import { useEffect, useId, useState } from 'react'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import {
-  IconCheckOutline16, IconCloseOutline16, IconEditOutline16, IconTrashOutline16,
+  IconCheckOutline16, IconChevronDownOutline14, IconChevronUpOutline14,
+  IconCloseOutline16, IconEditOutline16, IconTrashOutline16,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { QueueAction, QueueItemId } from '../contract/queue.ts'
 import css from './QueueDock.module.css'
@@ -22,18 +23,28 @@ export interface QueueDockInjected {
 /** Full props of a dock entry: InputZone owner share + session standard kit + global seat. */
 export type QueueDockProps = PropsRuntime<'conversation.input.dock'> & QueueDockInjected
 
-/** Queue strip: one preview line per queued message; renders null when the queue is empty. */
+/**
+ * Queue strip: one item renders directly; multiple items default to a
+ * collapsible count header; an empty queue renders nothing.
+ */
 export function QueueDock({ useSession, updateQueue, notify }: QueueDockProps) {
   const queue = useSession(s => s.queue)
   const [editing, setEditing] = useState<{ id: QueueItemId; text: string } | null>(null)
   const [busy, setBusy] = useState<QueueItemId | null>(null)
+  const [collapsed, setCollapsed] = useState(true)
+  const listId = useId()
 
   useEffect(() => {
+    if (queue.length === 0 && !collapsed) setCollapsed(true)
     if (editing !== null && !queue.some(row => row.id === editing.id)) setEditing(null)
-  }, [editing, queue])
+  }, [collapsed, editing, queue])
 
   if (queue.length === 0) return null
 
+  const interactionActive = editing !== null || busy !== null
+  const expanded = !collapsed || interactionActive
+  const listVisible = queue.length === 1 || expanded
+
   const applyAction = async (
     itemId: QueueItemId,
     action: QueueAction,
@@ -63,8 +74,23 @@ export function QueueDock({ useSession, updateQueue, notify }: QueueDockProps) {
   return (
     <div className={css.dock}>
       <div className={css.panel}>
-        <ul className={css.list}>
-          {queue.map(row => (
+        {queue.length > 1 && (
+          <button
+            type="button"
+            className={css.header}
+            aria-controls={listId}
+            aria-expanded={expanded}
+            disabled={interactionActive}
+            onClick={() => { setCollapsed(value => !value) }}
+          >
+            <span className={css.count}>{queue.length} 条排队消息</span>
+            <span className={css.chevron} aria-hidden>
+              {expanded ? <IconChevronDownOutline14 /> : <IconChevronUpOutline14 />}
+            </span>
+          </button>
+        )}
+        <ul id={listId} className={css.list} hidden={!listVisible}>
+          {listVisible && queue.map(row => (
             <li key={row.id} className={css.row}>
               {editing?.id === row.id
                 ? (

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

@@ -19,6 +19,13 @@
   border-radius: 20px;
   background: var(--dsw-specific-input-major);
   box-shadow: var(--dsw-shadow-lv2);
+  /* Elevated surface in dark, same as the menus: `.body` inside scrolls once
+     the justification or command passes the cap, so the thumb takes the l2
+     pair. Declared on the card because the elevation belongs to the surface,
+     and the custom properties inherit down to the region that actually
+     scrolls (see ui-theme styles/scrollbar.css for the rebinding contract). */
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
 }
 
 /* Tinted full-width header band. */
@@ -40,11 +47,22 @@
   background: var(--dsw-alias-state-warn-primary);
 }
 
+/* Scroll region: an agent's justification and its command are unbounded model
+   text (a one-line `cd` or a 40-line heredoc), and the seat sits in a
+   fixed-height column — uncapped, a long command pushed the action row past
+   the viewport and the approval could not be answered at all. The strip and
+   the action row stay outside, so the buttons are always on screen. */
 .body {
   display: flex;
   flex-direction: column;
   gap: 6px;
-  padding: 12px 16px 14px;
+  /* border-box so the cap is the region's OUTER height: the composer's draft
+     area counts its padding inside the same number, and the two seats are
+     only interchangeable if they occupy the same box. */
+  box-sizing: border-box;
+  max-height: var(--dsh-composer-text-max-height);
+  overflow-y: auto;
+  padding: 12px 16px 0;
 }
 
 /* The model's justification is the panel's message, not a footnote. */
@@ -63,11 +81,15 @@
   word-break: break-all;
 }
 
+/* Card-level row, not body content. Its padding reproduces the metrics the row
+   had inside the body: 14px above (the flex gap of 6 plus the row's 8px top
+   margin, neither of which reaches it out here) and the body's former 14px
+   bottom pad below, so the resting card is unchanged. */
 .actionRow {
   display: flex;
   justify-content: flex-end;
   gap: 8px;
-  margin-top: 8px;
+  padding: 14px 16px 14px;
 }
 
 .allow,

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

@@ -4,7 +4,11 @@
 // pending, this panel occupies the composer slot in place of the InputBar:
 // an amber "Waiting for approval" strip on the card top, the model's
 // justification as the headline, the paired command in muted code text, and
-// a right-aligned refuse/allow action row. One-shot: the buttons disable
+// a right-aligned refuse/allow action row. Justification and command are
+// unbounded model text, so they scroll inside the card at the shared composer
+// cap (`data-approval-scroll`) and the action row stays outside it — the
+// buttons must be reachable no matter how long the command is.
+// One-shot: the buttons disable
 // after a click and the panel leaves (the InputBar returns) on the broadcast
 // resolved frame. The draft's "Always allow this type" is deferred with
 // grant storage.
@@ -53,17 +57,20 @@ function ApprovalFlow({ pending, command }: { pending: PendingApproval; command?
     <div className={css.root} data-approval-key={pending.key}>
       <div className={css.card}>
         <div className={css.strip}><span className={css.dot} />等待审批</div>
-        <div className={css.body}>
+        {/* Tab stop: the region scrolls once the command passes the cap and
+            holds nothing focusable of its own, so without one a keyboard-only
+            user cannot reach the command's tail before answering. */}
+        <div className={css.body} data-approval-scroll="" tabIndex={0} role="group" aria-label="审批详情">
           <div className={css.headline}>{pending.reason ?? `工具 ${pending.toolName} 请求越权执行`}</div>
           {command !== undefined && <div className={css.command}>{command}</div>}
-          <div className={css.actionRow}>
-            <button type="button" className={css.reject} disabled={answered} onClick={() => { answer('rejected') }}>
-              拒绝
-            </button>
-            <button type="button" className={css.allow} disabled={answered} onClick={() => { answer('allowed-once') }}>
-              允许一次
-            </button>
-          </div>
+        </div>
+        <div className={css.actionRow}>
+          <button type="button" className={css.reject} disabled={answered} onClick={() => { answer('rejected') }}>
+            拒绝
+          </button>
+          <button type="button" className={css.allow} disabled={answered} onClick={() => { answer('allowed-once') }}>
+            允许一次
+          </button>
         </div>
       </div>
     </div>

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

@@ -143,6 +143,14 @@
   display: flex;
   flex: none;
   flex-direction: column;
+  /* One cap for every scrolling text region a composer seat can hold: the
+     InputBar draft (figma Input 75:8208 max 14 lines × 24px line) and the
+     takeover panels' bodies top out at the same height, so electing a
+     takeover never grows the footer past the card it replaces. Declared on
+     the seat because it is the chain's only shared ancestor — fallback and
+     elected overlay are siblings — and custom properties inherit down to
+     whichever entry is mounted. */
+  --dsh-composer-text-max-height: 336px;
 }
 
 /* Active phase: header is ordinary column chrome above the scrollport (not

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

@@ -209,7 +209,9 @@
 .mirror {
   visibility: hidden;
   pointer-events: none;
-  max-height: 336px;
+  /* 14-line cap, shared with the composer takeovers (declared on
+     ConversationRoot .composerSeat). */
+  max-height: var(--dsh-composer-text-max-height);
   overflow: hidden;
 }
 

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

@@ -122,6 +122,13 @@ describe('conversation slot inject surface', () => {
     const chatView = b.chatViewSurface(ROOT)
     chatView.injected.loadOlder()
     expect(b.sessionFake.loadOlder).toHaveBeenCalledTimes(1)
+    chatView.injected.forkAt(17)
+    await vi.waitFor(() => {
+      expect(b.runtime.sessions.calls).toContainEqual({ method: 'open', args: [ROOT] })
+    })
+    expect(b.runtime.sessions.calls).toContainEqual({
+      method: 'fork', args: [{ sessionId: ROOT, atSeq: 17, increaseTitle: true }],
+    })
     await b.runtime.dispose()
   })
 

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

@@ -94,6 +94,7 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
   const openDetails = vi.fn<(t: SelectionTarget) => void>()
   const openFile = vi.fn<(path: string) => void>()
   const loadOlder = vi.fn()
+  const forkAt = vi.fn()
   // Selection rides the REAL chat store (same construction path as
   // production; the view reads it through the PropsStore useStore share).
   // renderSlot stub renders the render-site fallback (an empty keyed ledger:
@@ -120,9 +121,10 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     openDetails,
     openFile,
     loadOlder,
+    forkAt,
   }
   const setSelection = (next: SelectionTarget | null): void => { chat.actions.select(next) }
-  return { set, ChatView, props, openDetails, openFile, loadOlder, setSelection }
+  return { set, ChatView, props, openDetails, openFile, loadOlder, forkAt, setSelection }
 }
 
 describe('chat-flow derivation', () => {
@@ -228,6 +230,16 @@ describe('ChatView', () => {
     expect(view.getAllByRole('button', { name: '在新对话中分支' })).toHaveLength(4)
   })
 
+  it('forks from both user and finalized assistant message actions at their event seq', () => {
+    const h = makeHarness({ nodes: [user(1, 'question'), assistant(2, 'answer')] })
+    const view = render(<h.ChatView {...h.props} />)
+    const buttons = view.getAllByRole('button', { name: '在新对话中分支' })
+    expect(buttons).toHaveLength(2)
+    fireEvent.click(buttons[0]!)
+    fireEvent.click(buttons[1]!)
+    expect(h.forkAt.mock.calls).toEqual([[1], [2]])
+  })
+
   it('renders assistant Markdown across history, streaming, final, and interrupted states while user text stays literal', () => {
     const markdown = '# Rendered\n\n- **one**\n- `two`'
     const h = makeHarness({ nodes: [user(1, markdown), assistant(2, markdown)] })

packages/client/ui-conversation/tests/queue-dock.spec.tsx

@@ -1,7 +1,7 @@
 // @vitest-environment jsdom
 /**
  * QueueDock rendering and operations: authoritative rows, inline editing,
- * removal, failure notices, and live retirement.
+ * collapse state, removal, failure notices, and live retirement.
  */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, waitFor } from '@testing-library/react'
@@ -78,16 +78,109 @@ describe('QueueDock', () => {
     expect(container.innerHTML).toBe('')
   })
 
+  it('renders one row directly and defaults multiple rows to a collapsible count header', () => {
+    const single = snapshotWith([row('i-1', 'one')])
+    const source = liveSession(single)
+    const view = render(<QueueDock {...kitFor(single)} useSession={source.useSession} />)
+    expect(view.queryByRole('button', { name: '1 条排队消息' })).toBeNull()
+    expect(view.getByText('one')).toBeTruthy()
+
+    act(() => { source.push(snapshotWith([row('i-1', 'one'), row('i-2', 'two')])) })
+    const header = view.getByRole('button', { name: '2 条排队消息' })
+    expect(header.getAttribute('aria-expanded')).toBe('false')
+    expect(document.getElementById(header.getAttribute('aria-controls')!)).toBeTruthy()
+    expect(view.queryByText('one')).toBeNull()
+    expect(view.queryByText('two')).toBeNull()
+
+    fireEvent.click(header)
+    expect(header.getAttribute('aria-expanded')).toBe('true')
+    expect(view.getByText('one')).toBeTruthy()
+    expect(view.getByText('two')).toBeTruthy()
+
+    fireEvent.click(header)
+    expect(header.getAttribute('aria-expanded')).toBe('false')
+    expect(view.queryByText('one')).toBeNull()
+  })
+
+  it('keeps an active single-row editor visible when another item arrives', () => {
+    const single = snapshotWith([row('i-edit', 'before')])
+    const source = liveSession(single)
+    const view = render(<QueueDock {...kitFor(single)} useSession={source.useSession} />)
+
+    fireEvent.click(view.getByLabelText('编辑排队消息'))
+    fireEvent.change(view.getByLabelText('编辑排队消息'), { target: { value: 'draft' } })
+    act(() => {
+      source.push(snapshotWith([row('i-edit', 'before'), row('i-2', 'second')]))
+    })
+
+    const header = view.getByRole('button', { name: '2 条排队消息' })
+    expect(header).toHaveProperty('disabled', true)
+    expect(header.getAttribute('aria-expanded')).toBe('true')
+    expect(view.getByRole('textbox', { name: '编辑排队消息' })).toHaveProperty('value', 'draft')
+    expect(view.getByText('second')).toBeTruthy()
+
+    fireEvent.click(view.getByLabelText('取消编辑'))
+    expect(header).toHaveProperty('disabled', false)
+    expect(header.getAttribute('aria-expanded')).toBe('false')
+    expect(view.queryByText('second')).toBeNull()
+  })
+
+  it('keeps an in-flight row action visible when another item arrives', async () => {
+    const single = snapshotWith([row('i-remove', 'remove me')])
+    const source = liveSession(single)
+    let finishUpdate: (() => void) | undefined
+    const updateQueue = vi.fn(() => new Promise<void>((resolve) => { finishUpdate = resolve }))
+    const view = render(
+      <QueueDock {...kitFor(single, { updateQueue })} useSession={source.useSession} />,
+    )
+
+    fireEvent.click(view.getByLabelText('删除排队消息'))
+    act(() => {
+      source.push(snapshotWith([row('i-remove', 'remove me'), row('i-2', 'second')]))
+    })
+
+    const header = view.getByRole('button', { name: '2 条排队消息' })
+    expect(header).toHaveProperty('disabled', true)
+    expect(header.getAttribute('aria-expanded')).toBe('true')
+    expect(view.getByText('remove me')).toBeTruthy()
+    expect(view.getByText('second')).toBeTruthy()
+
+    act(() => { finishUpdate?.() })
+    await waitFor(() => {
+      expect(header).toHaveProperty('disabled', false)
+      expect(header.getAttribute('aria-expanded')).toBe('false')
+    })
+  })
+
+  it('defaults a new multi-row queue to collapsed after the prior queue empties', () => {
+    const first = snapshotWith([row('i-1', 'one'), row('i-2', 'two')])
+    const source = liveSession(first)
+    const view = render(<QueueDock {...kitFor(first)} useSession={source.useSession} />)
+    fireEvent.click(view.getByRole('button', { name: '2 条排队消息' }))
+    expect(view.getByText('one')).toBeTruthy()
+
+    act(() => { source.push(snapshotWith([])) })
+    expect(view.container.innerHTML).toBe('')
+    act(() => {
+      source.push(snapshotWith([row('i-3', 'three'), row('i-4', 'four')]))
+    })
+
+    const header = view.getByRole('button', { name: '2 条排队消息' })
+    expect(header.getAttribute('aria-expanded')).toBe('false')
+    expect(view.queryByText('three')).toBeNull()
+  })
+
   it('renders active actions and disables editing for mixed-content rows', () => {
     const snap = snapshotWith([
       row('i-1', '第一条排队消息'),
       row('i-2', null, 'image [image]'),
     ])
     const source = liveSession(snap)
-    const { container } = render(<QueueDock {...kitFor(snap)} useSession={source.useSession} />)
+    const { container, getByRole } = render(<QueueDock {...kitFor(snap)} useSession={source.useSession} />)
+    fireEvent.click(getByRole('button', { name: '2 条排队消息' }))
     expect([...container.querySelectorAll('li')].map(item => item.textContent))
       .toEqual(['第一条排队消息', 'image [image]'])
-    expect(container.querySelectorAll('button')).toHaveLength(4)
+    expect(container.querySelectorAll('button')).toHaveLength(5)
     expect(container.querySelectorAll('[aria-label="编辑排队消息"]')).toHaveLength(2)
     expect(container.querySelectorAll('[aria-label="删除排队消息"]')).toHaveLength(2)
     expect(container.querySelectorAll('[aria-label="立即发送排队消息"]')).toHaveLength(0)
@@ -162,10 +255,11 @@ describe('QueueDock', () => {
     const snap = snapshotWith([row('i-1', 'one'), row('i-2', 'two')])
     const source = liveSession(snap)
     const updateQueue = vi.fn(() => Promise.resolve())
-    const { getAllByLabelText } = render(
+    const { getAllByLabelText, getByRole } = render(
       <QueueDock {...kitFor(snap, { updateQueue })} useSession={source.useSession} />,
     )
 
+    fireEvent.click(getByRole('button', { name: '2 条排队消息' }))
     fireEvent.click(getAllByLabelText('删除排队消息')[0]!)
     await waitFor(() => {
       expect(updateQueue).toHaveBeenCalledWith(iid('i-1'), { kind: 'remove' })

packages/client/ui-layout/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-layout/README.md
-README.md: 0e92958c9b088071ab58f7e87e8af68f6c2df68d
-README.zh.md: 0fb3b1cd85bbf6e070a2a1dd01b25981e5990df0
+README.md: cb99023e6a9e3364c6f48190cf4a0cd71da2cbba
+README.zh.md: 3681b4517670eb92d8f32be2ac62d5852ac745a3

packages/client/ui-layout/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Shell plugin: three-column AppFrame (drag handles and concession chain) plus the `ctx.layout` panel-geometry service; it registers into the runtime-owned `root` slot and declares `sidebar`, `conversation`, `details`, and `conversation.empty`. The sidebar is fixed-width (only details shrinks, then auto-closes); a closed sidebar retains a 56px control rail while details closes to zero width. The package also seats the theme presenter: it consumes resolved `ctx.theme` snapshots and projects them onto the document (`html { color-scheme }` for native UA chrome, `body[data-ds-dark-theme]` from the active color scheme, plus the theme's alias tokens as inline variables on body).
+Shell plugin: three-column AppFrame (drag handles and concession chain) plus the `ctx.layout` panel-geometry service; it registers into the runtime-owned `root` slot and declares `sidebar`, `conversation`, `details`, and `conversation.empty`. The sidebar resize boundary is an invisible hit strip, while the details boundary retains its floating pill; only details shrinks during concession and then auto-closes. A closed sidebar retains a 56px control rail while details closes to zero width. The package also seats the theme presenter: it consumes resolved `ctx.theme` snapshots and projects them onto the document (`html { color-scheme }` for native UA chrome, `body[data-ds-dark-theme]` from the active color scheme, plus the theme's alias tokens as inline variables on body).
 
 AppFrame always mounts the conversation and details columns; a connected Session renders through `SessionProvider`. The transient layout store starts the sidebar at its default width and details closed, and it never reads or writes `localStorage`. Hero and other unselected states also derive a zero rendered details width without changing that stored preference. AppFrame retains the last non-blank Session id across those states: the first Session remains closed, an explicit details action opens the contract default width, returning to the same Session restores its unchanged width, and selecting a different Session closes details before paint. The conversation owner share is empty, while the sidebar owner share contains only `collapsed` and `width`; registrants obtain business data from standard hooks and actions from their own inject faces.
 

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

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏宽度固定（只会收缩详情栏，然后将其自动关闭）；关闭的侧边栏仍保留 56px 控制轨道，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量）。
+外壳插件：三栏 AppFrame（拖动手柄与让步链）加 `ctx.layout` 面板几何服务；它注册到运行时拥有的 `root` slot，并声明 `sidebar`、`conversation`、`details` 和 `conversation.empty`。侧边栏的缩放边界是不可见命中条带，详情栏边界则保留其浮动胶囊；让步期间只有详情栏会收缩并随后自动关闭。关闭的侧边栏仍保留 56px 控制轨道，详情栏则关闭到零宽度。该包还提供主题呈现器：它消费解析后的 `ctx.theme` 快照，并将其投影到 document（用 `html { color-scheme }` 驱动原生 UA 控件，依据当前配色方案设置 `body[data-ds-dark-theme]`，并将主题的别名 token 设为 body 上的内联变量）。
 
 AppFrame 始终挂载会话栏和详情栏；已连接 Session 通过 `SessionProvider` 渲染。布局 store 是瞬时状态，侧边栏以默认宽度启动，详情栏则保持关闭，且该 store 从不读写 `localStorage`。hero 和其他未选中状态也会将详情栏的渲染宽度派生为零，但不会改变存储的首选宽度。AppFrame 会跨越这些状态保留最后一个非 blank 会话 id：首个会话保持关闭；显式打开详情栏的操作会使用契约默认宽度；返回同一会话时恢复其未改变的宽度；选择不同会话时，详情栏会在绘制前关闭。会话 owner share 为空，侧边栏 owner share 只包含 `collapsed` 和 `width`；注册方通过标准钩子获取业务数据，并从各自的 inject 表层获取操作。
 

packages/client/ui-layout/src/client/AppFrame.module.css

@@ -49,9 +49,8 @@
 }
 
 /* Drag handles are frame children (columns clip overflow): an 8px hit strip
-   centered on the column border via inline left, above column content. The
-   visible pill (12x32 r10, riding the border at vertical center) is the figma
-   Handle component; the hit strip stays wider than the pill. */
+   centered on the column border via inline left, above column content. Details
+   adds a visible 12x32 pill at vertical center; sidebar keeps only the hit strip. */
 .handle {
   position: absolute;
   top: 0;
@@ -76,7 +75,7 @@
   }
 }
 
-.handle::after {
+.handle[data-side='details']::after {
   content: '';
   position: absolute;
   top: 50%;
@@ -88,23 +87,22 @@
   box-sizing: border-box;
   background: var(--dsw-alias-button-floating-fill);
   border: 1px solid var(--dsw-alias-border-l2-darkmode-thin);
-  /* Hover affordance: the pill hides until the pointer is over the owning
-     column (data-side pairs handle and column), the strip itself, or a drag. */
+  /* Hover affordance: the details pill hides until the pointer is over its
+     column, the strip itself, or a drag. */
   opacity: 0;
   transition:
     opacity var(--ds-transition-duration-slow) var(--ds-ease-in-out),
     background var(--ds-transition-duration-slow) var(--ds-ease-in-out);
 }
 
-.sidebarCol:hover ~ .handle[data-side='sidebar']::after,
 .detailsCol:hover ~ .handle[data-side='details']::after,
-.handle:hover::after,
-.handle[data-dragging='true']::after {
+.handle[data-side='details']:hover::after,
+.handle[data-side='details'][data-dragging='true']::after {
   opacity: 1;
 }
 
-.handle:hover::after,
-.handle[data-dragging='true']::after {
+.handle[data-side='details']:hover::after,
+.handle[data-side='details'][data-dragging='true']::after {
   background: var(--dsw-alias-button-floating-hover);
   border-color: var(--dsw-alias-border-l3);
 }

packages/client/ui-question/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-question/README.md
-README.md: 0700375758774610fcd897b9a3e16484206a871d
-README.zh.md: d9e5eb22cef13e16ab1ce2cebba9e563bd9d08d9
+README.md: 5ebba2a1da6e6108b82e9deb235b84f987600345
+README.zh.md: 0aa6428a9b6472fc5b525c11b4716ebc50c378c3

packages/client/ui-question/README.md

@@ -6,6 +6,8 @@ Web `ask_user_question` feature plugin. Its host half mounts `dsh-tool-ask-user`
 
 The component renders one question at a time with progress navigation, single- and multi-select choices, recommendation badges derived from label suffixes, and custom answers. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. Single-select choices advance immediately, and Enter submits once every question is answered or skipped; Enter during IME composition confirms the input candidate without advancing. It submits one structured answer batch for the whole request: “Skip this question” retains other drafts and emits the existing blank `{ selected: [] }` shape for that item, while close rejects the whole wait as `ASK_CANCELLED`.
 
+A request whose single question declares a presentation intent renders as that intent's own surface instead. `plan-review` — set by `dsh-plan-mode` on the `exit_plan_mode` review — takes the waiting-approval card shape: a `Plan review` strip, the plan as the scrolling markdown body, the question text as the card's accessible name, and one decision row of `Chat about it` / `Refuse` / `Approve`. Approve and Refuse answer with the asker's own option labels (the intent names which label approves, so the verdict never rides option order) and keep the asker's descriptions as tooltips; `Chat about it` rejects the wait as `ASK_CANCELLED`, returning the composer so the user can say what they want instead. The card claims a request only when it can send every answer that request allows: one question, the intent declared, the plan present as `detail`, the named approve label offered, and a binary single choice (at most one option besides approve, not multi-select). Anything else — no intent, a batch of several questions, a missing plan, an approve label naming no option, a third option, a multi-select decision — stays on the generic flow, which can express it. An intent changes the layout, never which answers are reachable.
+
 Selection state is local to a component keyed by the request rpcId. A replay with the same id preserves a still-mounted draft, while `question/resolved` from the host removes the composer. The host remains authoritative: successful HTTP delivery does not remove pending state locally.
 
 Composer chrome copy (pager, buttons, placeholders, validation feedback) is bilingual: the plugin registers zh/en dictionaries under the `question` namespace of `dsh-client-locale` and hands the entry its bound translator plus the locale snapshot source through the inject face, so a locale switch re-renders a mounted composer. Question and option text arrives from the model and renders verbatim; carrier failure messages also display untranslated.

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

@@ -6,6 +6,8 @@ Web `ask_user_question` 功能插件。只有选择 Web 功能时，其主机侧
 
 组件每次渲染一个问题，提供进度导航、单选和多选选项、由标签后缀派生的推荐徽标，以及自定义答案。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信内容策略。封顶卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。单选选项会立即前进；所有问题均已回答或跳过后，Enter 会提交；IME 输入法组合期间按 Enter 只会确认输入候选，不会前进。组件为整个请求提交一批结构化答案：「跳过此问题」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 形状；关闭则以 `ASK_CANCELLED` 拒绝整个等待。
 
+若某个请求的唯一问题声明了呈现意图，则改为渲染该意图自己的界面。`plan-review` —— 由 `dsh-plan-mode` 在 `exit_plan_mode` 审阅上设置 —— 采用等待审批卡片的形状：一条 `Plan review` 条带、计划作为可滚动的 markdown 主体、问题文本作为卡片的无障碍名称，以及一行 `Chat about it` / `Refuse` / `Approve` 的决定操作。Approve 与 Refuse 用提问方自己的选项标签回答（意图指名哪个标签表示批准，因此裁决绝不依赖选项顺序），并把提问方的描述保留为 tooltip；`Chat about it` 以 `ASK_CANCELLED` 拒绝该等待，让编辑器归位，用户可以直接说出他想说的话。卡片只在能够发出该请求允许的每一个答案时才接管：只有一个问题、声明了意图、计划以 `detail` 存在、提供了被指名的批准标签，且是二元单选（除批准外最多一个选项，且非多选）。其他任何情形 —— 没有意图、一批含多个问题、缺少计划、批准标签未命中任何选项、出现第三个选项、多选决定 —— 都留在能够表达它的通用流程上。意图改变的只是布局，从不改变可达的答案。
+
 选择状态只存在于以请求 rpcId 为 key 的组件本地。使用相同 id 回放时，只要组件仍挂载，就会保留草稿；主机发出的 `question/resolved` 则会移除编辑器。主机仍具有最终决定权：HTTP 交付成功不会在本地移除待处理状态。
 
 编辑器外框文案（翻页器、按钮、占位符、校验提示）是双语的：插件在 `dsh-client-locale` 的 `question` 命名空间下注册 zh/en 词典，并通过 inject face 把绑定的翻译函数和 locale 快照源交给该配置项，因此切换语言会重新渲染已挂载的编辑器。问题与选项文本来自模型并原样渲染；载体失败消息也不经翻译直接显示。

packages/client/ui-question/src/client/PlanReviewPanel.module.css

@@ -0,0 +1,113 @@
+/* Plan-review takeover: the waiting-approval card language (amber strip on a
+   floating capsule, right-aligned actions) applied to a reviewed plan. Kept as
+   its own module rather than shared with ui-conversation's ApprovalPanel: the
+   two takeovers agree on tokens and geometry, not on content — this one's body
+   is scrollable markdown, that one's is a headline plus a command line. Warn
+   semantics ride the alias state tokens; no hardcoded colors. */
+
+/* Mirrors the question card's frame so the takeover is a content swap. */
+.frame {
+  display: flex;
+  justify-content: center;
+  padding: 6px 24px 10px;
+}
+
+.card {
+  display: flex;
+  overflow: hidden;
+  flex-direction: column;
+  width: 100%;
+  max-width: 776px;
+  /* Composer seat sits in a fixed-height conversation column (overflow
+     hidden): cap the card against the viewport and scroll the plan, so the
+     strip and the decision row stay reachable on a long plan. */
+  max-height: min(60vh, 520px);
+  border: 1px solid var(--dsw-alias-state-warn-secondary);
+  border-radius: 20px;
+  background: var(--dsw-specific-input-major);
+  box-shadow: var(--dsw-shadow-lv2);
+  color: var(--dsw-alias-label-primary);
+  /* Elevated surface in dark: the plan body inside scrolls once the card hits
+     the cap above, so the thumb takes the l2 pair (see ui-theme
+     styles/scrollbar.css for the rebinding contract). */
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
+}
+
+.card,
+.card * {
+  box-sizing: border-box;
+}
+
+/* Tinted full-width header band, as on the approval takeover. */
+.strip {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  gap: 8px;
+  padding: 10px 16px;
+  background: var(--dsw-alias-state-warn-tertiary);
+  color: var(--dsw-alias-state-warn-primary);
+  font-size: 13px;
+  line-height: 18px;
+}
+
+.dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--dsw-alias-state-warn-primary);
+}
+
+/* The plan is the panel's message: it takes the whole body and the scroll. */
+.body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding: 12px 16px 4px;
+  font-size: 14px;
+  line-height: 22px;
+}
+
+.footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-shrink: 0;
+  gap: 12px;
+  padding: 8px 16px 12px;
+}
+
+.feedback {
+  min-height: 16px;
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 11px;
+  line-height: 16px;
+}
+
+.actions {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  gap: 8px;
+}
+
+@media (max-width: 720px) {
+  .frame {
+    padding: 6px 10px 10px;
+  }
+
+  .card {
+    border-radius: 16px;
+  }
+
+  .body {
+    padding: 10px 12px 4px;
+  }
+
+  .footer {
+    align-items: flex-end;
+    padding: 8px 12px 10px;
+  }
+}

packages/client/ui-question/src/client/PlanReviewPanel.tsx

@@ -0,0 +1,100 @@
+// PlanReviewPanel: the composer takeover for a question carrying the
+// `plan-review` presentation intent. A plan under review is one decision over
+// one body of markdown, so it takes the waiting-approval card shape — tinted
+// strip, content, right-aligned action row — instead of the generic question
+// flow's pager, numbered options, skip and custom-answer affordances, which
+// read as a quiz the user is being graded on.
+//
+// The three actions are the whole decision surface: approve and decline answer
+// the question with the option labels the asker offered (localised copy on the
+// buttons, the asker's descriptions as their tooltips), while "discuss"
+// dismisses the request so the composer returns and the user can simply say
+// what they want. Dismissal is the generic flow's own cancel verb, promoted to
+// a labelled button because in a two-outcome decision it is the third real
+// answer, not an escape hatch.
+
+import { useState } from 'react'
+import { Button, IconEditOutline16, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { PendingQuestion, PlanReview, QuestionComposerProps } from './contract/slots.ts'
+import css from './PlanReviewPanel.module.css'
+
+/** The panel's own props: the question domain face, the narrowed review, and the locale seat. */
+export type PlanReviewPanelProps =
+  { pending: PendingQuestion; review: PlanReview } & Pick<QuestionComposerProps, 't'>
+
+/**
+ * Optional-prop spread for a decision button's tooltip: `title` is optional on
+ * the DOM props, and exactOptionalPropertyTypes rejects an explicit undefined.
+ *
+ * @param description - the asker's option description, when it carries one.
+ * @returns The `title` prop to spread, or nothing.
+ */
+function tooltip(description: string | undefined): { title?: string } {
+  return description === undefined ? {} : { title: description }
+}
+
+/**
+ * Render a plan review as a decision card.
+ *
+ * @param props - the question domain face, the narrowed plan review, and `t`.
+ * @returns The plan-review takeover for this request.
+ */
+export function PlanReviewPanel({ pending, review, t }: PlanReviewPanelProps) {
+  // One-shot latch shaped like the approval takeover's: the panel leaves only
+  // when the host's resolved frame lands, so until then a second click must
+  // not re-fire. A failed send (rejected receipt / transport) re-arms it and
+  // shows why, since nothing else would tell the user the click was lost.
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const settle = (send: () => Promise<void>): void => {
+    setBusy(true)
+    setError(null)
+    void send().catch((cause: unknown) => {
+      setBusy(false)
+      setError(cause instanceof Error ? cause.message : String(cause))
+    })
+  }
+  const decide = (label: string): void => {
+    settle(() => pending.answer({ answers: [{ id: review.id, selected: [label] }] }))
+  }
+  const decline = review.decline
+
+  return (
+    <div className={css.frame} data-plan-review-key={pending.key}>
+      <section className={css.card} aria-label={review.question}>
+        <div className={css.strip}>
+          <span className={css.dot} />
+          {t('plan.header')}
+        </div>
+        <div className={css.body} data-plan-review-scroll>
+          <MarkdownText text={review.plan} />
+        </div>
+        <div className={css.footer}>
+          <div className={css.feedback} role="status">{error}</div>
+          <div className={css.actions}>
+            <Button
+              size="sm" variant="ghost" icon={<IconEditOutline16 />}
+              disabled={busy} onClick={() => { settle(() => pending.cancel()) }}
+            >
+              {t('plan.discuss')}
+            </Button>
+            {decline !== undefined && (
+              <Button
+                size="sm" variant="outline" {...tooltip(decline.description)}
+                disabled={busy} onClick={() => { decide(decline.label) }}
+              >
+                {t('plan.decline')}
+              </Button>
+            )}
+            <Button
+              size="sm" variant="primary" {...tooltip(review.approve.description)}
+              disabled={busy} onClick={() => { decide(review.approve.label) }}
+            >
+              {t('plan.approve')}
+            </Button>
+          </div>
+        </div>
+      </section>
+    </div>
+  )
+}

packages/client/ui-question/src/client/QuestionComposer.tsx

@@ -5,9 +5,10 @@ import {
   IconCloseOutline16, IconEditOutline16, MarkdownText,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import {
-  PendingQuestion,
+  PendingQuestion, planReviewOf,
   type QuestionAnswer, type QuestionComposerProps,
 } from './contract/slots.ts'
+import { PlanReviewPanel } from './PlanReviewPanel.tsx'
 import css from './QuestionComposer.module.css'
 
 interface DraftAnswer {
@@ -46,14 +47,24 @@ function isComposing(event: KeyboardEvent<HTMLTextAreaElement | HTMLInputElement
 /**
  * Composer takeover boundary; the carrier key keys local drafts, so a
  * same-request replay (same key, new carrier object) preserves them.
+ *
+ * One takeover, two shapes: a request that declares a presentation intent this
+ * package renders takes that shape (a plan review is one decision over one
+ * plan, not a question set), and every other request takes the generic flow.
+ * The routing lives here, at the one entry that owns the composer seat, so
+ * neither shape can claim a request the other is already rendering.
+ *
  * @param props - the selector-matched pending question carrier plus the framework standard kit.
- * @returns The question flow for this request.
+ * @returns The question flow, or the intent's own surface, for this request.
  */
 export function QuestionComposer(props: QuestionComposerProps) {
   // Domain-face mint rides the carrier's stable identity (never minted in a
   // select/render dispatch — per-dispatch minting would churn memo identity).
   const question = useMemo(() => new PendingQuestion(props.matched), [props.matched])
-  return <QuestionFlow key={question.key} pending={question} t={props.t} />
+  const review = useMemo(() => planReviewOf(question.questions), [question])
+  return review === undefined
+    ? <QuestionFlow key={question.key} pending={question} t={props.t} />
+    : <PlanReviewPanel key={question.key} pending={question} review={review} t={props.t} />
 }
 
 function QuestionFlow({ pending, t }: { pending: PendingQuestion } & Pick<QuestionComposerProps, 't'>) {

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

@@ -19,6 +19,71 @@ export type QuestionWait = PendingWait<'question'>
 /** One structured answer batch covering every question of the request. */
 export type QuestionAnswer = QuestionResponsePayload['answer']
 
+/** One question of the request, as the carrier payload carries it. */
+type QuestionItem = QuestionWait['payload']['questions'][number]
+
+/** One option the asker offered on a question. */
+type QuestionOption = NonNullable<QuestionItem['options']>[number]
+
+/**
+ * A request narrowed to the `plan-review` presentation intent: everything the
+ * decision card renders and answers with, so the panel never re-reads the
+ * request shape. `approve` and `decline` are the asker's own options — an
+ * answer must carry one of those labels verbatim — and `plan` is the markdown
+ * body under review.
+ */
+export interface PlanReview {
+  /** The reviewed question's id, echoed in the answer. */
+  id: string
+  /** The question text, kept as the card's accessible name. */
+  question: string
+  /** The plan markdown under review. */
+  plan: string
+  /** The option that approves the plan. */
+  approve: QuestionOption
+  /** The option that declines it; absent when the asker offered no other option. */
+  decline?: QuestionOption
+}
+
+/**
+ * Narrow a request to a renderable plan review, or return undefined to leave it
+ * to the generic question flow.
+ *
+ * The card is one decision over one plan, and it claims a request only when it
+ * can send every answer that request allows — an intent changes the layout,
+ * never which answers are reachable. So the batch must be a single question
+ * that declares the intent, carries the plan as its detail, offers the approve
+ * label the intent names, and is a binary single choice: at most one option
+ * besides approve, and not multi-select. A third option or a multi-select batch
+ * has answers two buttons cannot express, so the generic flow keeps it — as it
+ * keeps any request whose intent the asker's own service would have rejected,
+ * because the client sits downstream of a wire boundary and every request must
+ * stay answerable.
+ *
+ * @param questions - the request's whole question batch.
+ * @returns The narrowed review, or undefined when the generic flow owns it.
+ */
+export function planReviewOf(questions: readonly QuestionItem[]): PlanReview | undefined {
+  if (questions.length !== 1) return undefined
+  // Length-checked above; the index read is the narrowing tax, not a guess.
+  const question = questions[0] as QuestionItem
+  const intent = question.intent
+  if (intent?.kind !== 'plan-review' || question.detail === undefined) return undefined
+  if (question.multiSelect === true) return undefined
+  const options = question.options ?? []
+  if (options.length > 2) return undefined
+  const approve = options.find(option => option.label === intent.approve)
+  if (approve === undefined) return undefined
+  const decline = options.find(option => option.label !== intent.approve)
+  return {
+    id: question.id,
+    question: question.question,
+    plan: question.detail,
+    approve,
+    ...(decline === undefined ? {} : { decline }),
+  }
+}
+
 /**
  * Question domain face over the carrier: render identity and questions
  * transparently forwarded; answer/cancel own the wire encoding (the ok value

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

@@ -5,6 +5,12 @@
  * question carrier (matched prop), and the whole behavior surface rides the
  * carrier (domain encoding in contract/slots.ts PendingQuestion); copy rides
  * the standard locale seat. Export discipline: packages/client/AGENTS.md.
+ *
+ * One entry, two shapes: the composer renders a request that declares a
+ * presentation intent as that intent's own surface (`plan-review` → the plan
+ * decision card) and every other request as the generic question flow. A
+ * separate chain entry per shape would race the same carrier, so the shape
+ * choice lives inside this entry — see QuestionComposer.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ComposerChainProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
@@ -15,7 +21,9 @@ import { QuestionComposer } from './QuestionComposer.tsx'
 import { en, zh, type QuestionKey } from './locales.ts'
 
 export { PendingQuestion } from './contract/slots.ts'
-export type { QuestionAnswer, QuestionComposerProps, QuestionWait } from './contract/slots.ts'
+export type {
+  PlanReview, QuestionAnswer, QuestionComposerProps, QuestionWait,
+} from './contract/slots.ts'
 export type { QuestionKey } from './locales.ts'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {

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

@@ -11,6 +11,10 @@ export const zh = {
   'custom.placeholder': '输入你的答案',
   'action.skip': '跳过本题',
   'action.next': '下一题',
+  'plan.header': '计划待审',
+  'plan.approve': '确认执行',
+  'plan.decline': '拒绝',
+  'plan.discuss': '去聊天里说',
 } satisfies Record<string, string>
 
 /** The question namespace key union. */
@@ -27,4 +31,8 @@ export const en = {
   'custom.placeholder': 'Type your answer',
   'action.skip': 'Skip this question',
   'action.next': 'Next',
+  'plan.header': 'Plan review',
+  'plan.approve': 'Approve',
+  'plan.decline': 'Refuse',
+  'plan.discuss': 'Chat about it',
 } satisfies Record<QuestionKey, string>

packages/client/ui-question/tests/plan-review-panel.spec.tsx

@@ -0,0 +1,228 @@
+// @vitest-environment jsdom
+// The plan-review takeover, driven through the composer entry that routes to
+// it: a request carrying the intent must reach the decision card and answer
+// with the asker's own option labels, and a request that does not (or cannot)
+// must keep the generic question flow.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import type {
+  ConversationSnapshot, SessionId, SessionListState, WorkspaceListState,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import { PendingWait } from '@deepseek-ai/dsh-client-runtime/client'
+import type { RpcReceipt } from '@deepseek-ai/dsh-client-connection/client'
+import { RpcId } from '@deepseek-ai/dsh-client-connection/client'
+import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-ui-slots'
+import { planReviewOf, type QuestionComposerProps, type QuestionWait } from '../src/client/contract/slots.ts'
+import { QuestionComposer } from '../src/client/QuestionComposer.tsx'
+import { en, zh } from '../src/client/locales.ts'
+import { en as commonEn } from '@deepseek-ai/dsh-client-locale/src/locales/en.ts'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+/** Seat stub over a dictionary pair mirroring the real lookup chain: package dictionary, then common vocabulary, then the key. */
+const seatOver = (dict: Record<string, string>, common: Record<string, string>): QuestionComposerProps['t'] =>
+  (key => dict[key] ?? common[key] ?? key)
+
+/** Framework standard-kit stubs: the panel consumes only the locale seat. */
+const kit = {
+  sessionId: SID,
+  useSession: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook<ConversationSnapshot>,
+  useSessions: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook<SessionListState>,
+  useWorkspaces: (() => { throw new Error('unused') }) as unknown as SnapshotSelectorHook<WorkspaceListState>,
+  useProjection: (() => undefined) as never,
+  useInput: (() => { throw new Error('unused') }) as never,
+  inputActions: { setDraft: () => { throw new Error('unused') }, submit: () => { throw new Error('unused') } } as never,
+  t: seatOver(zh, commonZh),
+}
+
+const PLAN = '# Ship the picker\n\n- read the store\n- render the rows\n'
+
+/** The plan-mode request shape: one question, the plan as detail, approve named. */
+const questions = (): QuestionWait['payload']['questions'] => [{
+  id: 'plan-review',
+  header: 'Plan review',
+  question: 'Approve this plan and leave plan mode?',
+  detail: PLAN,
+  options: [
+    { label: 'Approve', description: 'Leave plan mode; the plan is carried out from the next step.' },
+    { label: 'Keep planning', description: 'Stay in plan mode; feedback goes back to the model.' },
+  ],
+  intent: { kind: 'plan-review', approve: 'Approve' },
+}]
+
+/** Carrier fixture over a scripted respond carrier. */
+function wait(
+  payload: QuestionWait['payload'] = { questions: questions() },
+  respond = vi.fn(() => Promise.resolve<RpcReceipt>({ accepted: true })),
+) {
+  return { carrier: new PendingWait('question', RpcId('q-1'), SID, payload, respond), respond }
+}
+
+/** The client-response envelope respond must have received for a decision. */
+function decidedEnvelope(label: string) {
+  return {
+    type: 'client-response', rpcId: RpcId('q-1'),
+    result: { ok: true, value: { sessionId: SID, answer: { answers: [{ id: 'plan-review', selected: [label] }] } } },
+  }
+}
+
+describe('planReviewOf', () => {
+  it('narrows a plan-review request to its decision, options included', () => {
+    expect(planReviewOf(questions())).toEqual({
+      id: 'plan-review',
+      question: 'Approve this plan and leave plan mode?',
+      plan: PLAN,
+      approve: { label: 'Approve', description: 'Leave plan mode; the plan is carried out from the next step.' },
+      decline: { label: 'Keep planning', description: 'Stay in plan mode; feedback goes back to the model.' },
+    })
+  })
+
+  it('leaves the decline absent when the asker offered approve alone', () => {
+    const [question] = questions()
+    const review = planReviewOf([{ ...question as object, options: [{ label: 'Approve' }] } as never])
+    expect(review?.approve).toEqual({ label: 'Approve' })
+    expect(review === undefined ? true : 'decline' in review).toBe(false)
+  })
+
+  it.each([
+    ['a batch of more than one question', () => [...questions(), ...questions()]],
+    ['no intent at all', () => [{ ...questions()[0] as object, intent: undefined }]],
+    ['an intent without the plan as detail', () => [{ ...questions()[0] as object, detail: undefined }]],
+    ['an intent whose approve names no option', () => [{
+      ...questions()[0] as object, intent: { kind: 'plan-review', approve: 'Ship it' },
+    }]],
+    ['an intent with no options at all', () => [{ ...questions()[0] as object, options: undefined }]],
+    // Two buttons cannot send a third label or a combination, and the generic
+    // flow can: an intent never costs the user a reachable answer.
+    ['a third option the card could not offer', () => [{
+      ...questions()[0] as object,
+      options: [{ label: 'Approve' }, { label: 'Keep planning' }, { label: 'Start over' }],
+    }]],
+    ['a multi-select decision', () => [{ ...questions()[0] as object, multiSelect: true }]],
+  ])('declines %s, leaving the request to the generic flow', (_case, build) => {
+    expect(planReviewOf(build() as never)).toBeUndefined()
+  })
+
+  it('declines an empty batch, which the generic flow reports as such', () => {
+    expect(planReviewOf([])).toBeUndefined()
+  })
+})
+
+describe('PlanReviewPanel', () => {
+  it('renders the plan under a review strip, with none of the quiz affordances', () => {
+    const { carrier } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    expect(document.querySelector('[data-plan-review-key="q:q-1"]')).toBeTruthy()
+    expect(screen.getByText(zh['plan.header'])).toBeTruthy()
+    // The plan renders as markdown, so its heading is a heading.
+    expect(screen.getByRole('heading', { name: 'Ship the picker' })).toBeTruthy()
+    expect(screen.getByText('render the rows')).toBeTruthy()
+    // The question text stays as the card's accessible name rather than a title
+    // that reads like a test item.
+    expect(screen.getByLabelText('Approve this plan and leave plan mode?')).toBeTruthy()
+    // No pager, no numbered options, no skip, no custom answer.
+    expect(screen.queryByText('1 / 1')).toBeNull()
+    expect(screen.queryByRole('radio')).toBeNull()
+    expect(screen.queryByText(zh['action.skip'])).toBeNull()
+    expect(screen.queryByRole('textbox')).toBeNull()
+  })
+
+  it('answers with the asker\'s approve label and keeps its description as the tooltip', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    const approve = screen.getByRole('button', { name: zh['plan.approve'] })
+    expect(approve.getAttribute('title')).toBe('Leave plan mode; the plan is carried out from the next step.')
+    fireEvent.click(approve)
+    expect(respond).toHaveBeenCalledWith(decidedEnvelope('Approve'))
+    // One-shot: every action locks until the host's resolved frame lands.
+    expect(approve.hasAttribute('disabled')).toBe(true)
+    expect(screen.getByRole('button', { name: zh['plan.decline'] }).hasAttribute('disabled')).toBe(true)
+    fireEvent.click(approve)
+    expect(respond).toHaveBeenCalledTimes(1)
+  })
+
+  it('answers with the asker\'s decline label', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('button', { name: zh['plan.decline'] }))
+    expect(respond).toHaveBeenCalledWith(decidedEnvelope('Keep planning'))
+  })
+
+  it('dismisses the request so the composer returns for a plain message', () => {
+    const { carrier, respond } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('button', { name: zh['plan.discuss'] }))
+    expect(respond).toHaveBeenCalledWith({
+      type: 'client-response', rpcId: RpcId('q-1'),
+      result: {
+        ok: false,
+        error: { code: 'cancelled', message: 'the user closed this question request', details: {} },
+      },
+    })
+  })
+
+  it('omits the tooltip for an option carrying no description', () => {
+    const { carrier } = wait({ questions: [{
+      ...questions()[0] as object,
+      options: [{ label: 'Approve' }, { label: 'Keep planning' }],
+    }] as never })
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    expect(screen.getByRole('button', { name: zh['plan.approve'] }).hasAttribute('title')).toBe(false)
+    expect(screen.getByRole('button', { name: zh['plan.decline'] }).hasAttribute('title')).toBe(false)
+  })
+
+  it('hides the decline action when the asker offered approve alone', () => {
+    const { carrier } = wait({ questions: [{
+      ...questions()[0] as object, options: [{ label: 'Approve' }],
+    }] as never })
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    expect(screen.queryByRole('button', { name: zh['plan.decline'] })).toBeNull()
+    expect(screen.getByRole('button', { name: zh['plan.approve'] })).toBeTruthy()
+  })
+
+  it('re-arms the actions and says why when the decision does not land', async () => {
+    const { carrier, respond } = wait(
+      { questions: questions() },
+      vi.fn(() => Promise.resolve<RpcReceipt>({ accepted: false, reason: 'not-pending' })),
+    )
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('button', { name: zh['plan.approve'] }))
+    const failure = await screen.findByText('question response rejected: not-pending')
+    expect(failure.getAttribute('role')).toBe('status')
+    // Re-armed for the retry: a lost click must not leave a dead card.
+    expect(screen.getByRole('button', { name: zh['plan.approve'] }).hasAttribute('disabled')).toBe(false)
+    fireEvent.click(screen.getByRole('button', { name: zh['plan.approve'] }))
+    expect(respond).toHaveBeenCalledTimes(2)
+  })
+
+  it('reports a non-Error transport failure as its stringified value', async () => {
+    // A non-Error rejection is the case under test: a carrier can reject with
+    // anything, and the panel must still show the user something.
+    // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+    const { carrier } = wait({ questions: questions() }, vi.fn(() => Promise.reject('socket gone')))
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
+
+    fireEvent.click(screen.getByRole('button', { name: zh['plan.discuss'] }))
+    expect(await screen.findByText('socket gone')).toBeTruthy()
+  })
+
+  it('carries the same decision surface in English', () => {
+    const { carrier } = wait()
+    render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} t={seatOver(en, commonEn)} />)
+
+    expect(screen.getByText('Plan review')).toBeTruthy()
+    expect(screen.getByRole('button', { name: 'Approve' })).toBeTruthy()
+    expect(screen.getByRole('button', { name: 'Refuse' })).toBeTruthy()
+    expect(screen.getByRole('button', { name: 'Chat about it' })).toBeTruthy()
+  })
+})

packages/client/ui-trajectory/src/client/TrajectoryTable.module.css

@@ -16,6 +16,7 @@
   flex: 1;
   min-width: 0;
   overflow: auto;
+  container: trajectory-table / inline-size;
 }
 
 .table {
@@ -235,6 +236,18 @@
   width: 3px;
 }
 
+.table tbody tr[data-error='true'] .turnRail {
+  background: color-mix(
+    in srgb,
+    var(--dsw-alias-state-error-primary) 22%,
+    var(--dsw-alias-bg-layer-1)
+  );
+}
+
+.table tbody tr[data-error='true'] .selectionRail {
+  background: var(--dsw-alias-state-error-primary);
+}
+
 .table tbody tr[data-turn-start='true'] td {
   position: relative;
   overflow: visible;
@@ -279,6 +292,10 @@
   white-space: nowrap;
 }
 
+.turnLabelCompact {
+  display: none;
+}
+
 .turnLabelActive {
   color: color-mix(
     in srgb,
@@ -325,11 +342,66 @@
   user-select: none;
 }
 
+.kindTagIcon {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  width: 13px;
+  height: 13px;
+}
+
+.kindTagLabel {
+  display: inline;
+}
+
 .table .kindSlot .message {
   justify-content: center;
   width: 100%;
 }
 
+@container trajectory-table (max-width: 620px) {
+  .eventColumn {
+    width: 50px;
+  }
+
+  .event {
+    padding-right: 3px !important;
+    padding-left: 28px !important;
+  }
+
+  .requestBoundaryControl {
+    left: 6px;
+  }
+
+  .kindSlot {
+    width: 19px;
+  }
+
+  .kindTag,
+  .table .kindSlot .message {
+    justify-content: center;
+    width: 19px;
+    padding-right: 0;
+    padding-left: 0;
+  }
+
+  .kindTagIcon {
+    display: inline-flex;
+  }
+
+  .kindTagLabel {
+    display: none;
+  }
+
+  .turnLabelFull {
+    display: none;
+  }
+
+  .turnLabelCompact {
+    display: inline;
+  }
+}
+
 .user {
   color: var(--dsw-alias-state-business-primary);
   background: var(--dsw-alias-state-business-tertiary);
@@ -576,6 +648,28 @@
   color: var(--dsw-alias-state-error-primary);
 }
 
+.overview dd.error {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.details .errorPayload {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.details .errorPayload .resultBlockText {
+  color: inherit;
+}
+
+.details .jsonPayload.errorPayload,
+.details .jsonPreview.errorPayload {
+  --json-tree-property: var(--dsw-alias-state-error-primary);
+  --json-tree-string: var(--dsw-alias-state-error-primary);
+  --json-tree-number: var(--dsw-alias-state-error-primary);
+  --json-tree-keyword: var(--dsw-alias-state-error-primary);
+  --json-tree-punctuation: var(--dsw-alias-state-error-primary);
+  --json-tree-icon: var(--dsw-alias-state-error-primary);
+}
+
 .details {
   position: relative;
   display: flex;

packages/client/ui-trajectory/src/client/TrajectoryTable.tsx

@@ -1,9 +1,15 @@
 /** Turn-aware trajectory event ledger with a local record inspector. */
 
-import { useEffect, useRef, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
 import {
-  extractMarkdownPlainText, IconChevronRightOutline14, JsonTree, MarkdownText,
+  IconChevronRightOutline14,
+  IconSettingsOutline16,
+  IconSparkle16,
+  IconUserOutline16,
+  JsonTree,
+  MarkdownText,
+  Tooltip,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import { structuredPatch } from 'diff'
 import type {
@@ -13,7 +19,7 @@ import type {
   AssistantMetricDetail, TrajectoryCellKind, TrajectoryCellProps, TrajectorySourceBlock,
 } from './trajectory-record.ts'
 import { formatElapsedSeconds } from './trajectory-record.ts'
-import type { TrajectoryTurnModel } from './layout.ts'
+import { trajectoryPreviewText, type TrajectoryTurnModel } from './layout.ts'
 import css from './TrajectoryTable.module.css'
 
 const KIND_LABEL: Record<TrajectoryCellKind, string> = {
@@ -26,6 +32,77 @@ const KIND_LABEL: Record<TrajectoryCellKind, string> = {
   subtool: 'SUBTOOL',
 }
 
+function ToolWrenchIcon(): ReactNode {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      data-role-icon="wrench"
+      aria-hidden="true"
+    >
+      <path d="M14 3.3a3.8 3.8 0 0 1-4.8 4.8l-5.1 5.1a1.6 1.6 0 1 1-2.3-2.3l5.1-5.1A3.8 3.8 0 0 1 11.7 1l-2.3 2.3 2.3 2.3L14 3.3Z" />
+    </svg>
+  )
+}
+
+function InformationIcon(): ReactNode {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.4"
+      strokeLinecap="round"
+      data-role-icon="information"
+      aria-hidden="true"
+    >
+      <circle cx="8" cy="8" r="6.7" />
+      <circle cx="8" cy="5.5" r=".85" fill="currentColor" stroke="none" />
+      <path d="M8 7.75v3.4" strokeWidth="1.8" />
+    </svg>
+  )
+}
+
+function CompactedIcon(): ReactNode {
+  return (
+    <svg
+      width="13"
+      height="13"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      data-role-icon="compacted"
+      aria-hidden="true"
+    >
+      <path d="m2.5 2.5 3.75 3.75M3 6.25h3.25V3" />
+      <path d="m13.5 2.5-3.75 3.75M13 6.25H9.75V3" />
+      <path d="m2.5 13.5 3.75-3.75M3 9.75h3.25V13" />
+      <path d="m13.5 13.5-3.75-3.75M13 9.75H9.75V13" />
+    </svg>
+  )
+}
+
+const KIND_ICON: Record<TrajectoryCellKind, ReactNode> = {
+  system: <IconSettingsOutline16 size={13} />,
+  user: <IconUserOutline16 size={13} />,
+  context: <InformationIcon />,
+  compacted: <CompactedIcon />,
+  message: <IconSparkle16 size={13} />,
+  tool: <ToolWrenchIcon />,
+  subtool: <ToolWrenchIcon />,
+}
+
 interface TableRecord {
   turn: number
   group: string
@@ -225,6 +302,8 @@ export interface TrajectoryTableProps {
   onSelectedIndexChange?: (index: number | null) => void
   /** Report a direct user selection from a ledger row. */
   onRecordSelect?: (index: number) => void
+  /** One externally requested record selection; a new object repeats the request. */
+  recordSelection?: { readonly index: number } | null
   /** Clear selection state owned by the ledger host. */
   onClearSelection?: () => void
   /** Turn ids whose rows after the first are folded into a summary. */
@@ -721,13 +800,13 @@ function detailTabs(record: TableRecord): readonly DetailTabItem[] {
 
 function recordDisplayText(cell: TrajectoryCellProps): string {
   if (isToolCallOnly(cell)) return ''
+  if (cell.text !== '') return cell.text
   const markdown = cell.kind === 'user' || cell.kind === 'context'
     ? cell.inputDetail
     : cell.kind === 'message'
       ? cell.outputDetail ?? cell.thinkingDetail
       : undefined
-  if (!markdown) return cell.text
-  return extractMarkdownPlainText(markdown).replace(/\s+/g, ' ').trim()
+  return markdown === undefined ? '' : trajectoryPreviewText(markdown)
 }
 
 function toolCallTextParts(
@@ -1043,13 +1122,20 @@ function SystemPromptDiff({
 
 function ToolOutputBlocks({
   blocks,
+  error,
   preview,
 }: {
   blocks: readonly TrajectorySourceBlock[]
+  error: boolean
   preview: boolean
 }) {
   return (
-    <div className={preview ? `${css.resultBlocks} ${css.resultBlocksPreview}` : css.resultBlocks}>
+    <div className={[
+      css.resultBlocks,
+      preview ? css.resultBlocksPreview : undefined,
+      error ? css.errorPayload : undefined,
+    ].filter((value): value is string => value !== undefined).join(' ')}
+    >
       {blocks.map((block, index) => (
         block.imageSrc !== undefined
           ? <PanelImage block={block} preview={preview} key={index} />
@@ -1222,6 +1308,9 @@ function RecordPayload({
     ? 'No payload captured'
     : 'No result captured'
   if (!value) return <p className={css.noPayload}>{missing}</p>
+  const error = direction === 'output' && record.cell.isError === true
+  const payloadClass = preview ? css.jsonPreview : css.jsonPayload
+  const payloadClassName = error ? `${payloadClass} ${css.errorPayload}` : payloadClass
 
   const json = parseJsonContainer(value)
   const singleTextResult = direction === 'output'
@@ -1232,7 +1321,7 @@ function RecordPayload({
       <JsonTree
         data={json}
         label="Result JSON"
-        className={preview ? css.jsonPreview : css.jsonPayload}
+        className={payloadClassName}
       />
     )
   }
@@ -1245,6 +1334,7 @@ function RecordPayload({
     return (
       <ToolOutputBlocks
         blocks={record.cell.outputBlocks}
+        error={error}
         preview={preview}
       />
     )
@@ -1258,7 +1348,11 @@ function RecordPayload({
   )
   if (markdown) {
     return (
-      <div className={preview ? css.markdownPreview : css.markdownPayload}>
+      <div className={[
+        preview ? css.markdownPreview : css.markdownPayload,
+        error ? css.errorPayload : undefined,
+      ].filter((className): className is string => className !== undefined).join(' ')}
+      >
         <MarkdownText text={value} />
       </div>
     )
@@ -1268,7 +1362,7 @@ function RecordPayload({
       <JsonTree
         data={json}
         label={`${direction === 'input' ? 'Payload' : 'Result'} JSON`}
-        className={preview ? css.jsonPreview : css.jsonPayload}
+        className={payloadClassName}
       />
     )
   }
@@ -1276,7 +1370,7 @@ function RecordPayload({
     <pre className={[
       css.payload,
       preview ? css.payloadPreview : undefined,
-      record.cell.isError ? css.error : undefined,
+      error ? css.errorPayload : undefined,
       value === 'No output' ? css.noOutputText : undefined,
     ].filter((value): value is string => value !== undefined).join(' ')}
     >
@@ -1397,6 +1491,7 @@ export function TrajectoryTable({
   searchMatchIndexes = null,
   onSelectedIndexChange,
   onRecordSelect,
+  recordSelection = null,
   onClearSelection,
   collapsedTurns,
   onToggleTurn,
@@ -1406,15 +1501,16 @@ export function TrajectoryTable({
   const [selectedIndex, setSelectedIndex] = useState<number | null>(null)
   const [selectedRequest, setSelectedRequest] = useState<SelectedRequest | null>(null)
   const [activeTab, setActiveTab] = useState<DetailTab>('overview')
-  const [thinkingExpanded, setThinkingExpanded] = useState(true)
+  const [thinkingExpanded, setThinkingExpanded] = useState(false)
   const [detailsWidth, setDetailsWidth] = useState<number | null>(null)
   const [toolRequestOffset, setToolRequestOffset] = useState<number | null>(null)
   const detailsResizeDrag = useRef<DetailsResizeDrag | null>(null)
+  const appliedRecordSelection = useRef<TrajectoryTableProps['recordSelection']>(null)
   const tabHistory = useRef<Set<DetailTab>>(new Set(['overview']))
   useEffect(() => {
     onSelectedIndexChange?.(selectedIndex)
   }, [onSelectedIndexChange, selectedIndex])
-  const allRecords = flattenRecords(turns)
+  const allRecords = useMemo(() => flattenRecords(turns), [turns])
   const requestNumbers = indexRequestNumbers(allRecords, sessionRequestNumbers)
   const records = searchMatchIndexes === null
     ? collapseAssistantRecords(
@@ -1531,7 +1627,7 @@ export function TrajectoryTable({
     onClearSelection?.()
   }
 
-  const selectRecord = (index: number) => {
+  const selectRecord = useCallback((index: number) => {
     const record = allRecords.find(candidate => candidate.cell.index === index)
     onRecordSelect?.(index)
     setSelectedRequest(null)
@@ -1541,7 +1637,15 @@ export function TrajectoryTable({
     const available = new Set(tabs.map(tab => tab.id))
     const recent = [...tabHistory.current].reverse().find(tab => available.has(tab))
     setActiveTab(recent ?? tabs[0]?.id ?? 'overview')
-  }
+  }, [allRecords, onRecordSelect])
+  useEffect(() => {
+    if (
+      recordSelection === null
+      || appliedRecordSelection.current === recordSelection
+    ) return
+    appliedRecordSelection.current = recordSelection
+    selectRecord(recordSelection.index)
+  }, [recordSelection, selectRecord])
 
   const selectRequest = (
     request: SelectedRequest,
@@ -1714,8 +1818,14 @@ export function TrajectoryTable({
                         className={activeTurn === record.turn
                           ? `${css.turnLabel} ${css.turnLabelActive}`
                           : css.turnLabel}
+                        aria-label={`Turn ${record.turn}`}
                       >
-                        Turn {record.turn}
+                        <span className={css.turnLabelFull} aria-hidden="true">
+                          Turn {record.turn}
+                        </span>
+                        <span className={css.turnLabelCompact} aria-hidden="true">
+                          #{record.turn}
+                        </span>
                       </span>
                     )}
                     <div className={css.eventInner}>
@@ -1723,24 +1833,33 @@ export function TrajectoryTable({
                         <span
                           className={css.kindSlot}
                         >
-                          <span className={`${css.kindTag} ${
-                            record.cell.kind === 'system'
-                              ? css.systemNeutral
-                              : record.cell.kind === 'context'
-                                ? css.contextGreen
-                                : record.cell.kind === 'compacted'
-                                  ? css.compacted
-                                  : record.cell.kind === 'tool'
-                                    ? css.toolAmber
-                                    : record.cell.kind === 'message'
-                                      ? css.assistantVioletBright
-                                      : record.cell.kind === 'subtool'
-                                        ? css.subtoolAmber
-                                        : css[record.cell.kind]
-                          }`}
-                          >
-                            {KIND_LABEL[record.cell.kind]}
-                          </span>
+                          <Tooltip label={KIND_LABEL[record.cell.kind]} side="bottom">
+                            <span
+                              className={`${css.kindTag} ${
+                                record.cell.kind === 'system'
+                                  ? css.systemNeutral
+                                  : record.cell.kind === 'context'
+                                    ? css.contextGreen
+                                    : record.cell.kind === 'compacted'
+                                      ? css.compacted
+                                      : record.cell.kind === 'tool'
+                                        ? css.toolAmber
+                                        : record.cell.kind === 'message'
+                                          ? css.assistantVioletBright
+                                          : record.cell.kind === 'subtool'
+                                            ? css.subtoolAmber
+                                            : css[record.cell.kind]
+                              }`}
+                              data-role-kind={record.cell.kind}
+                            >
+                              <span className={css.kindTagIcon} aria-hidden="true">
+                                {KIND_ICON[record.cell.kind]}
+                              </span>
+                              <span className={css.kindTagLabel}>
+                                {KIND_LABEL[record.cell.kind]}
+                              </span>
+                            </span>
+                          </Tooltip>
                         </span>
                       )}
                     </div>
@@ -1973,7 +2092,9 @@ export function TrajectoryTable({
                 <dl className={css.overview}>
                   <div>
                     <dt>Status</dt>
-                    <dd>{statusLabel(selectedRequestState)}</dd>
+                    <dd className={selectedRequestState === 'error' ? css.error : undefined}>
+                      {statusLabel(selectedRequestState)}
+                    </dd>
                   </div>
                   {selectedRequestInfo?.purpose === 'compaction' && (
                     <div>
@@ -2014,7 +2135,7 @@ export function TrajectoryTable({
                   {selectedRequestInfo?.error !== undefined && (
                     <div>
                       <dt>Error</dt>
-                      <dd>{selectedRequestInfo.error}</dd>
+                      <dd className={css.error}>{selectedRequestInfo.error}</dd>
                     </div>
                   )}
                   {selectedRequestInfo?.retry !== undefined && (
@@ -2122,7 +2243,9 @@ export function TrajectoryTable({
                 <dl className={css.overview}>
                   <div>
                     <dt>Status</dt>
-                    <dd>{statusLabel(selectedState)}</dd>
+                    <dd className={selectedState === 'error' ? css.error : undefined}>
+                      {statusLabel(selectedState)}
+                    </dd>
                   </div>
                   <div>
                     <dt>Duration</dt>
@@ -2225,7 +2348,9 @@ export function TrajectoryTable({
                   )}
                   <div>
                     <dt>Status</dt>
-                    <dd>{statusLabel(selectedState)}</dd>
+                    <dd className={selectedState === 'error' ? css.error : undefined}>
+                      {statusLabel(selectedState)}
+                    </dd>
                   </div>
                   {selected.cell.kind === 'message' && (
                     <TokenRows cell={selected.cell} />

packages/client/ui-trajectory/src/client/TrajectoryTimeline.module.css

@@ -70,16 +70,29 @@
 .lanes {
   position: absolute;
   z-index: 2;
-  inset: 7px 0;
+  top: 7px;
+  bottom: 7px;
+  left: var(--trajectory-domain-left);
+  width: var(--trajectory-domain-width);
 }
 
 .turnBoundaries {
   position: absolute;
   z-index: 3;
-  inset: 0;
+  top: 0;
+  bottom: 0;
+  left: var(--trajectory-domain-left);
+  width: var(--trajectory-domain-width);
   pointer-events: none;
 }
 
+@media (prefers-reduced-motion: no-preference) {
+  .lanes[data-animate-viewport='true'],
+  .turnBoundaries[data-animate-viewport='true'] {
+    transition: left 180ms ease-out;
+  }
+}
+
 .turnBoundary {
   position: absolute;
   top: 0;
@@ -133,6 +146,10 @@
   );
 }
 
+.span[data-error='true'] {
+  background: var(--dsw-alias-state-error-primary);
+}
+
 .span[data-equal-duration='true'] {
   width: 8px;
   min-width: 8px;
@@ -142,6 +159,18 @@
   opacity: 0.2;
 }
 
+.span[data-hovered='true']:not([data-current='true']) {
+  z-index: 1;
+  opacity: 0.78;
+  box-shadow:
+    0 0 0 1px var(--dsw-alias-bg-layer-2),
+    0 0 0 2px color-mix(
+      in srgb,
+      var(--dsw-alias-state-business-primary) 80%,
+      transparent
+    );
+}
+
 .span[data-current='true'] {
   z-index: 1;
   opacity: 1;

packages/client/ui-trajectory/src/client/TrajectoryTimeline.tsx

@@ -15,12 +15,20 @@ import css from './TrajectoryTimeline.module.css'
 
 const MINIMUM_DRAG_PX = 3
 const MINIMUM_ZOOM_OPERATIONS = 4
+const EDGE_PAN_ZONE_FRACTION = 0.08
+const EDGE_PAN_STEP_FRACTION = 0.025
+const MAXIMUM_EDGE_PAN_PX = 32
 
 interface FractionRange {
   start: number
   end: number
 }
 
+interface HoverPoint {
+  fraction: number
+  recordIndex: number | null
+}
+
 /** Props for the fixed full-domain overview above the trajectory ledger. */
 export interface TrajectoryTimelineProps {
   turns: readonly TrajectoryTurnModel[]
@@ -30,6 +38,9 @@ export interface TrajectoryTimelineProps {
   /** Record indexes matching the active ledger search, or null without a query. */
   searchMatchIndexes?: ReadonlySet<number> | null
   onRangeChange: (range: TrajectoryTimeRange | null) => void
+  /** Select a directly clicked timeline block. */
+  onRecordSelect?: (index: number) => void
+  /** Bring the nearest record into view after clicking timeline whitespace. */
   onRecordFocus?: (index: number) => void
 }
 
@@ -41,11 +52,16 @@ function clampFraction(value: number): number {
   return Math.min(1, Math.max(0, value))
 }
 
-function centeredRange(center: number, width: number): FractionRange {
-  const clampedWidth = Math.min(1, Math.max(0, width))
+function centeredRange(
+  center: number,
+  width: number,
+  minimum: number,
+  maximum: number,
+): FractionRange {
+  const clampedWidth = Math.min(maximum - minimum, Math.max(0, width))
   const start = Math.min(
-    Math.max(center - clampedWidth / 2, 0),
-    1 - clampedWidth,
+    Math.max(center - clampedWidth / 2, minimum),
+    maximum - clampedWidth,
   )
   return { start, end: start + clampedWidth }
 }
@@ -79,6 +95,7 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
   selectedIndex = null,
   searchMatchIndexes = null,
   onRangeChange,
+  onRecordSelect,
   onRecordFocus,
 }: TrajectoryTimelineProps) {
   const model = useMemo(() => deriveTrajectoryTimeline(turns, mode), [mode, turns])
@@ -94,10 +111,16 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
     )),
     [turns],
   )
-  const dragRef = useRef<{ pointerId: number; anchor: number; width: number } | null>(null)
-  const [draft, setDraft] = useState<FractionRange | null>(null)
-  const [hover, setHover] = useState<number | null>(null)
+  const dragRef = useRef<{
+    pointerId: number
+    anchorTime: number
+    anchorClientX: number
+    recordIndex: number | null
+  } | null>(null)
+  const [draft, setDraft] = useState<TrajectoryTimeRange | null>(null)
+  const [hover, setHover] = useState<HoverPoint | null>(null)
   const [viewport, setViewport] = useState<TrajectoryTimeRange | null>(null)
+  const [animateViewport, setAnimateViewport] = useState(false)
   useEffect(() => {
     if (
       model !== null
@@ -109,11 +132,35 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
   }, [model, onRangeChange, range])
   useEffect(() => {
     if (model === null) return
+    setAnimateViewport(false)
     setViewport(current =>
       current !== null && (current.end < model.start || current.start > model.end)
         ? null
         : current)
   }, [model])
+  useEffect(() => {
+    if (model === null || selectedIndex === null) return
+    const selectedSpan = model.spans.find(span => span.index === selectedIndex)
+    if (selectedSpan === undefined) return
+    setAnimateViewport(true)
+    setViewport((current) => {
+      if (current === null) return current
+      if (
+        selectedSpan.end > current.start
+        && selectedSpan.start < current.end
+      ) return current
+      const duration = Math.max(1, current.end - current.start)
+      const desiredStart = selectedSpan.end <= current.start
+        ? selectedSpan.start
+        : selectedSpan.end - duration
+      const nextStart = Math.min(
+        Math.max(desiredStart, model.start),
+        Math.max(model.start, model.end - duration),
+      )
+      if (nextStart === current.start) return current
+      return { start: nextStart, end: nextStart + duration }
+    })
+  }, [model, selectedIndex])
   const fullDuration = Math.max(1, (model?.end ?? 0) - (model?.start ?? 0))
   const viewportDuration = Math.min(
     fullDuration,
@@ -127,16 +174,21 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
     )
   const domainDuration = viewport === null ? fullDuration : viewportDuration
   const domainStart = viewport === null ? model?.start ?? 0 : viewportStart
+  const projectedDomainStyle = model === null
+    ? undefined
+    : {
+      '--trajectory-domain-left':
+        `${-(domainStart - model.start) / domainDuration * 100}%`,
+      '--trajectory-domain-width': `${fullDuration / domainDuration * 100}%`,
+    } as CSSProperties
   const committed = model === null || range === null
     ? null
     : rangeFraction(range, domainStart, domainDuration)
-  const visibleRange = draft ?? committed
-  const activeRange = draft === null
-    ? range
-    : {
-      start: domainStart + draft.start * domainDuration,
-      end: domainStart + draft.end * domainDuration,
-    }
+  const draftFraction = model === null || draft === null
+    ? null
+    : rangeFraction(draft, domainStart, domainDuration)
+  const visibleRange = draftFraction ?? committed
+  const activeRange = draft ?? range
 
   if (model === null) {
     return (
@@ -151,9 +203,9 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
     )
   }
 
-  const minimumSelectionFraction = Math.min(
-    1,
-    fullDuration / domainDuration / model.spans.length,
+  const minimumSelectionDuration = Math.min(
+    domainDuration,
+    fullDuration / model.spans.length,
   )
 
   const fractionAt = (event: PointerEvent<HTMLDivElement>): number => {
@@ -161,51 +213,107 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
     return clampFraction((event.clientX - rect.left) / Math.max(1, rect.width))
   }
 
-  const commit = (fraction: FractionRange) => {
-    onRangeChange({
-      start: domainStart + fraction.start * domainDuration,
-      end: domainStart + fraction.end * domainDuration,
-    })
+  const recordIndexAt = (event: PointerEvent<HTMLDivElement>): number | null => {
+    const target = event.target instanceof HTMLElement ? event.target : null
+    const value = target?.closest<HTMLElement>('[data-timeline-record-index]')
+      ?.dataset.timelineRecordIndex
+    if (value === undefined) return null
+    const index = Number(value)
+    return Number.isFinite(index) ? index : null
+  }
+
+  const commit = (nextRange: TrajectoryTimeRange) => {
+    onRangeChange(nextRange)
   }
 
   const onPointerDown = (event: PointerEvent<HTMLDivElement>) => {
     if (event.button !== 0) return
-    const rect = event.currentTarget.getBoundingClientRect()
     const anchor = fractionAt(event)
-    setHover(anchor)
-    dragRef.current = { pointerId: event.pointerId, anchor, width: Math.max(1, rect.width) }
+    const anchorTime = domainStart + anchor * domainDuration
+    const recordIndex = recordIndexAt(event)
+    setHover({ fraction: anchor, recordIndex })
+    dragRef.current = {
+      pointerId: event.pointerId,
+      anchorTime,
+      anchorClientX: event.clientX,
+      recordIndex,
+    }
     if (typeof event.currentTarget.setPointerCapture === 'function') {
       event.currentTarget.setPointerCapture(event.pointerId)
     }
-    setDraft({ start: anchor, end: anchor })
+    setDraft({ start: anchorTime, end: anchorTime })
   }
 
   const onPointerMove = (event: PointerEvent<HTMLDivElement>) => {
     const drag = dragRef.current
+    const rect = event.currentTarget.getBoundingClientRect()
     const fraction = fractionAt(event)
-    setHover(fraction)
+    setHover({ fraction, recordIndex: recordIndexAt(event) })
     if (drag === null || drag.pointerId !== event.pointerId) return
-    setDraft(orderedRange(drag.anchor, fraction))
+    let nextDomainStart = domainStart
+    if (viewport !== null) {
+      const localX = event.clientX - rect.left
+      const edgeWidth = Math.min(
+        MAXIMUM_EDGE_PAN_PX,
+        Math.max(1, rect.width * EDGE_PAN_ZONE_FRACTION),
+      )
+      const direction = localX < edgeWidth
+        ? -1
+        : localX > rect.width - edgeWidth ? 1 : 0
+      if (direction !== 0) {
+        const edgeDistance = direction < 0
+          ? edgeWidth - localX
+          : localX - (rect.width - edgeWidth)
+        const strength = clampFraction(edgeDistance / edgeWidth)
+        const desiredStart = domainStart
+          + direction * domainDuration * EDGE_PAN_STEP_FRACTION
+          * Math.max(0.2, strength)
+        nextDomainStart = Math.min(
+          Math.max(desiredStart, model.start),
+          model.end - domainDuration,
+        )
+        if (nextDomainStart !== domainStart) {
+          setAnimateViewport(false)
+          setViewport({
+            start: nextDomainStart,
+            end: nextDomainStart + domainDuration,
+          })
+        }
+      }
+    }
+    const pointTime = nextDomainStart + fraction * domainDuration
+    setDraft(orderedRange(drag.anchorTime, pointTime))
   }
 
   const onPointerEnd = (event: PointerEvent<HTMLDivElement>) => {
     const drag = dragRef.current
     if (drag === null || drag.pointerId !== event.pointerId) return
-    const point = fractionAt(event)
-    const selected = orderedRange(drag.anchor, point)
-    setHover(point)
+    const pointFraction = fractionAt(event)
+    const pointTime = domainStart + pointFraction * domainDuration
+    const selected = orderedRange(drag.anchorTime, pointTime)
+    setHover({ fraction: pointFraction, recordIndex: recordIndexAt(event) })
     dragRef.current = null
     setDraft(null)
-    const click = (selected.end - selected.start) * drag.width < MINIMUM_DRAG_PX
-    const committedRange = selected.end - selected.start < minimumSelectionFraction
+    const click = Math.abs(event.clientX - drag.anchorClientX) < MINIMUM_DRAG_PX
+    const clickedSpan = click && drag.recordIndex !== null
+      ? model.spans.find(span => span.index === drag.recordIndex)
+      : undefined
+    if (clickedSpan !== undefined) {
+      onRangeChange(null)
+      onRecordSelect?.(clickedSpan.index)
+      return
+    }
+    const committedRange = selected.end - selected.start < minimumSelectionDuration
       ? centeredRange(
         click ? selected.start : (selected.start + selected.end) / 2,
-        minimumSelectionFraction,
+        minimumSelectionDuration,
+        model.start,
+        model.end,
       )
       : selected
     commit(committedRange)
     if (click) {
-      const timelinePoint = domainStart + selected.start * domainDuration
+      const timelinePoint = selected.start
       const nearest = model.spans.reduce((candidate, span) => {
         const candidateDistance = timelinePoint < candidate.start
           ? candidate.start - timelinePoint
@@ -233,6 +341,7 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
 
   const onWheel = (event: WheelEvent<HTMLDivElement>) => {
     event.preventDefault()
+    setAnimateViewport(false)
     const rect = event.currentTarget.getBoundingClientRect()
     const anchorFraction =
       clampFraction((event.clientX - rect.left) / Math.max(1, rect.width))
@@ -278,16 +387,18 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
           onWheel={onWheel}
           onContextMenu={(event) => {
             event.preventDefault()
+            setAnimateViewport(false)
             onRangeChange(null)
             setViewport(null)
           }}
         >
-          {hover !== null && draft === null && (
+          {hover !== null && hover.recordIndex === null && draft === null && (
             <div
               className={css.hoverLine}
+              data-timeline-hover-line
               aria-hidden="true"
               style={{
-                '--trajectory-hover-left': `${hover * 100}%`,
+                '--trajectory-hover-left': `${hover.fraction * 100}%`,
               } as CSSProperties}
             />
           )}
@@ -313,7 +424,12 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
               />
             </>
           )}
-          <div className={css.turnBoundaries} aria-hidden="true">
+          <div
+            className={css.turnBoundaries}
+            data-animate-viewport={animateViewport || undefined}
+            aria-hidden="true"
+            style={projectedDomainStyle}
+          >
             {model.turnBoundaries
               .slice(1)
               .filter(boundary =>
@@ -326,24 +442,35 @@ export const TrajectoryTimeline = memo(function TrajectoryTimeline({
                   key={boundary.turn}
                   style={{
                     '--trajectory-turn-left':
-                      `${(boundary.time - domainStart) / domainDuration * 100}%`,
+                      `${(boundary.time - model.start) / fullDuration * 100}%`,
                   } as CSSProperties}
                 />
               ))}
           </div>
-          <div className={css.lanes} aria-hidden="true">
+          <div
+            className={css.lanes}
+            data-animate-viewport={animateViewport || undefined}
+            data-timeline-domain
+            aria-hidden="true"
+            style={projectedDomainStyle}
+          >
             {model.spans
-              .filter(span => span.end >= domainStart && span.start <= domainStart + domainDuration)
+              .filter(span =>
+                span.index === selectedIndex
+                || (span.end >= domainStart && span.start <= domainStart + domainDuration))
               .map((span) => {
-                const left = (span.start - domainStart) / domainDuration
-                const width = (span.end - span.start) / domainDuration
+                const left = (span.start - model.start) / fullDuration
+                const width = (span.end - span.start) / fullDuration
                 const durationMs = durationByIndex.get(span.index)
                 return (
                   <span
                     className={css.span}
                     data-timeline-span={span.kind}
+                    data-timeline-record-index={span.index}
+                    data-error={span.isError || undefined}
                     data-equal-duration={mode === 'time' || undefined}
                     data-current={span.index === selectedIndex || undefined}
+                    data-hovered={hover?.recordIndex === span.index || undefined}
                     data-search-match={searchMatchIndexes === null
                       ? undefined
                       : searchMatchIndexes.has(span.index) ? 'true' : 'false'}

packages/client/ui-trajectory/src/client/TrajectoryView.tsx

@@ -147,6 +147,9 @@ export function TrajectoryView({
   const [actualTime, setActualTime] = useState(false)
   const [searchQuery, setSearchQuery] = useState('')
   const [selectedTimelineIndex, setSelectedTimelineIndex] = useState<number | null>(null)
+  const [timelineRecordSelection, setTimelineRecordSelection] = useState<{
+    readonly index: number
+  } | null>(null)
   const ledgerRef = useRef<HTMLDivElement>(null)
   const inspection = useHistory(snapshot => snapshot.inspection)
   const nodes = inspection.eventNodes
@@ -478,7 +481,20 @@ export function TrajectoryView({
         selectedIndex={selectedTimelineIndex}
         searchMatchIndexes={searchMatchIndexes}
         onRangeChange={(range) => {
-          setTimelineSelection(range === null ? null : { branchId: currentBranch.id, range })
+          setTimelineSelection(range === null ? null : {
+            branchId: currentBranch.id,
+            range,
+          })
+        }}
+        onRecordSelect={(index) => {
+          setTimelineSelection(null)
+          setTimelineRecordSelection({ index })
+          setSelectedTimelineIndex(index)
+          const row = ledgerRef.current
+            ?.querySelector<HTMLElement>(`tr[data-record-index="${index}"]`)
+          if (row !== undefined && row !== null && typeof row.scrollIntoView === 'function') {
+            row.scrollIntoView({ behavior: 'smooth', block: 'center' })
+          }
         }}
         onRecordFocus={(index) => {
           const row = ledgerRef.current
@@ -497,6 +513,7 @@ export function TrajectoryView({
           searchMatchIndexes={searchMatchIndexes}
           onSelectedIndexChange={setSelectedTimelineIndex}
           onRecordSelect={handleRecordSelect}
+          recordSelection={timelineRecordSelection}
           onClearSelection={() => { setTimelineSelection(null) }}
           collapsedTurns={collapsedTurns}
           onToggleTurn={toggleTurn}

packages/client/ui-trajectory/src/client/layout.ts

@@ -12,6 +12,7 @@ import type {
   RequestView,
   ToolResultNode,
 } from '@deepseek-ai/dsh-client-runtime/client'
+import { extractMarkdownPlainText } from '@deepseek-ai/dsh-client-ui-primitives'
 import type {
   TrajectoryCellProps,
   TrajectorySourceBlock,
@@ -66,6 +67,9 @@ interface TurnBucket {
   groups: LaidGroup[]
 }
 
+const PREVIEW_SOURCE_CHARACTERS = 2_048
+const PREVIEW_OUTPUT_CHARACTERS = 512
+
 type InputNode = Extract<
   ConversationSnapshot['nodes'][number],
   { kind: 'user' | 'steering' | 'context' }
@@ -126,6 +130,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
     nodes, partial, runningCalls, requests = [], callSchemas, codeDispatches,
   } = input
   const resultByCall = indexResults(nodes)
+  const emittedCallIds = indexAssistantCallIds(nodes)
   const callStartById = new Map<string, number>()
   for (const result of resultByCall.values()) {
     const startedAt = finiteTime(result.callTime)
@@ -353,7 +358,7 @@ export function deriveTrajectoryLayout(input: TrajectoryLayoutInput): readonly T
       continue
     }
     if (node.kind === 'tool-result') {
-      if (!callEmittedInAssistant(nodes, node.callId)) {
+      if (!emittedCallIds.has(node.callId)) {
         const toolName = node.call?.name
         const laidList: LaidCell[] = [{
           absTime: finiteTime(node.callTime ?? node.time),
@@ -764,12 +769,15 @@ function indexResults(nodes: ConversationSnapshot['nodes']): Map<string, ToolRes
   return map
 }
 
-function callEmittedInAssistant(nodes: ConversationSnapshot['nodes'], callId: string): boolean {
+function indexAssistantCallIds(nodes: ConversationSnapshot['nodes']): ReadonlySet<string> {
+  const ids = new Set<string>()
   for (const node of nodes) {
     if (node.kind !== 'assistant') continue
-    if (node.blocks.some(b => b.kind === 'tool-call' && b.callId === callId)) return true
+    for (const block of node.blocks) {
+      if (block.kind === 'tool-call') ids.add(block.callId)
+    }
   }
-  return false
+  return ids
 }
 
 function collectCallIds(
@@ -849,7 +857,7 @@ function expandSubCalls(
 }
 
 function summarizeCall(name: string, argsRaw: string): string {
-  const args = argsRaw.replace(/\s+/g, ' ').trim()
+  const args = trajectoryPreviewText(argsRaw)
   if (args === '') return name
   return `${name} · ${args}`
 }
@@ -907,5 +915,20 @@ function summarizeContent(content: readonly { type: string; text?: string }[]):
 }
 
 function summarizeText(text: string): string {
-  return text.replace(/\s+/g, ' ').trim()
+  return trajectoryPreviewText(text)
+}
+
+/**
+ * Build a bounded one-line ledger preview without parsing the complete Markdown document.
+ * Full source remains on the cell for the inspector.
+ * @param text - Untrusted message, reasoning, payload, or result text.
+ * @returns A compact preview capped independently from the retained source.
+ */
+export function trajectoryPreviewText(text: string): string {
+  const source = text.slice(0, PREVIEW_SOURCE_CHARACTERS)
+  const compact = extractMarkdownPlainText(source).replace(/\s+/g, ' ').trim()
+  const preview = compact.slice(0, PREVIEW_OUTPUT_CHARACTERS).trimEnd()
+  return source.length < text.length || preview.length < compact.length
+    ? `${preview}…`
+    : preview
 }

packages/client/ui-trajectory/src/client/timeline.ts

@@ -15,6 +15,7 @@ export interface TrajectoryTimeRange {
 /** One ledger record projected into the active timeline domain. */
 export interface TrajectoryTimelineSpan extends TrajectoryTimeRange {
   index: number
+  isError: boolean
   kind: TrajectoryCellKind
   label: string
   lane: number
@@ -94,6 +95,7 @@ export function deriveTrajectoryTimeline(
       start: spans.length + offset,
       end: spans.length + offset + 1,
       index: cell.index,
+      isError: cell.isError === true,
       kind: cell.kind,
       label: cell.text,
       lane: laneFor(cell.kind),
@@ -129,6 +131,7 @@ function deriveTimedTimeline(
           : [{
             ...range,
             index: cell.index,
+            isError: cell.isError === true,
             kind: cell.kind,
             label: cell.text,
             lane: laneFor(cell.kind),

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

@@ -176,6 +176,25 @@ describe('deriveTrajectoryLayout', () => {
     })
   })
 
+  it('bounds a long Markdown-like thinking preview while retaining its full detail', () => {
+    const thinking = `# Investigation\n\n**NAVIGATION_OK file_path** ${'- repeated detail '.repeat(1_000)}`
+    const nodes = [{
+      kind: 'assistant', seq: 1, time: 5_000, turn: 1, step: 0,
+      blocks: [{ kind: 'reasoning', text: thinking }],
+    }] as unknown as ConversationSnapshot['nodes']
+
+    const turns = deriveTrajectoryLayout({
+      codeDispatches: new Map(), nodes, partial: null, runningCalls: [],
+    })
+    const message = turns[0]?.groups.flatMap(group => group.cells)
+      .find(cell => cell.kind === 'message')
+
+    expect(message?.text.startsWith('Investigation NAVIGATION_OK file_path')).toBe(true)
+    expect(message?.text.endsWith('…')).toBe(true)
+    expect(message?.text.length).toBeLessThanOrEqual(513)
+    expect(message?.thinkingDetail).toBe(thinking)
+  })
+
   it('advances the duration cursor over context nodes', () => {
     const nodes = [
       { kind: 'user', seq: 1, time: 1_000, content: [{ type: 'text', text: 'hi' }], source: null },

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

@@ -83,6 +83,31 @@ describe('TrajectoryTable', () => {
     expect(screen.getByText('15 tok')).toBeTruthy()
   })
 
+  it('keeps long thinking collapsed until the user asks to render it', () => {
+    const thinking = 'private chain '.repeat(1_000)
+    const turns: readonly TrajectoryTurnModel[] = [{
+      turn: 1,
+      groups: [{
+        title: 'Step 1',
+        cells: [{
+          index: 1,
+          kind: 'message',
+          text: 'private chain…',
+          thinkingDetail: thinking,
+          timeSeconds: 1,
+        }],
+      }],
+    }]
+    render(<TrajectoryTable turns={turns} {...FOLD_PROPS} />)
+
+    fireEvent.click(screen.getByRole('row', { name: /ASSISTANT/ }))
+    const toggle = screen.getByRole('button', { name: 'Thinking ...' })
+    expect(screen.queryByText(thinking)).toBeNull()
+
+    fireEvent.click(toggle)
+    expect(toggle.parentElement?.textContent?.length).toBeGreaterThan(thinking.length)
+  })
+
   it('keeps raw HTML tags in a Markdown-derived context preview', () => {
     const html = [
       '<background-task-complete id="trajectory-ui-watch">',
@@ -144,8 +169,53 @@ describe('TrajectoryTable', () => {
     expect(screen.getByText('Pending')).toBeTruthy()
     fireEvent.click(screen.getByRole('row', { name: /TOOL, bash \{"command":"false"\}/ }))
     expect(screen.getByText('Failed')).toBeTruthy()
+    expect(screen.getByText('Failed').className).toContain('error')
     fireEvent.click(screen.getByRole('tab', { name: 'Result' }))
-    expect(screen.getByText('ToolError: non_zero_exit')).toBeTruthy()
+    const errorResult = screen.getByText('ToolError: non_zero_exit')
+    expect(errorResult.closest('[class*="errorPayload"]')).toBeTruthy()
+  })
+
+  it('renders responsive role icons with a custom tooltip', () => {
+    const view = render(<TrajectoryTable turns={TURNS} {...FOLD_PROPS} />)
+    const toolTag = view.container.querySelector<HTMLElement>('[data-role-kind="tool"]')
+
+    expect(toolTag).not.toBeNull()
+    expect(toolTag?.getAttribute('title')).toBeNull()
+    expect(toolTag?.querySelector('[data-role-icon="wrench"]')).toBeTruthy()
+
+    fireEvent.mouseEnter(toolTag as HTMLElement)
+    expect(screen.getByRole('tooltip').textContent).toBe('TOOL')
+    fireEvent.mouseLeave(toolTag as HTMLElement)
+    expect(screen.queryByRole('tooltip')).toBeNull()
+  })
+
+  it('uses information and compression glyphs for injected and compacted context', () => {
+    const turns: readonly TrajectoryTurnModel[] = [{
+      turn: 1,
+      groups: [{
+        title: 'Context',
+        cells: [
+          { index: 1, kind: 'context', text: 'Workspace context', timeSeconds: 0 },
+          { index: 2, kind: 'compacted', text: 'Compacted history', timeSeconds: 0 },
+        ],
+      }],
+    }]
+    const view = render(<TrajectoryTable turns={turns} {...FOLD_PROPS} />)
+
+    expect(view.container.querySelector(
+      '[data-role-kind="context"] [data-role-icon="information"]',
+    )).toBeTruthy()
+    expect(view.container.querySelector(
+      '[data-role-kind="compacted"] [data-role-icon="compacted"]',
+    )).toBeTruthy()
+  })
+
+  it('keeps a compact turn label available for narrow layouts', () => {
+    render(<TrajectoryTable turns={TURNS} {...FOLD_PROPS} />)
+    const turnLabel = screen.getByLabelText('Turn 1')
+
+    expect(turnLabel.textContent).toContain('Turn 1')
+    expect(turnLabel.textContent).toContain('#1')
   })
 
   it('renders a single-text JSON tool result as a JSON tree', () => {

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

@@ -25,6 +25,7 @@ import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/cli
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-trajectory/client'
 import { apply as nodeApply } from '@deepseek-ai/dsh-client-ui-trajectory'
 import type { TrajectoryTurnModel } from '../src/client/layout.ts'
+import { TrajectoryTimeline } from '../src/client/TrajectoryTimeline.tsx'
 import {
   TrajectoryView, type TrajectoryViewInjected,
 } from '../src/client/TrajectoryView.tsx'
@@ -309,6 +310,44 @@ describe('tab switching in ConversationRoot', () => {
       .toBeNull()
   })
 
+  it('clicking a timeline block clears the range, selects the record, and opens its inspector', async () => {
+    const b = await bench()
+    const view = mount(b.slots)
+    fireEvent.click(screen.getByRole('tab', { name: 'Trajectory' }))
+    const plot = screen.getByLabelText('Timeline overview; drag horizontally to focus events')
+    vi.spyOn(plot, 'getBoundingClientRect').mockReturnValue({
+      x: 0, y: 0, left: 0, top: 0, right: 100, bottom: 72, width: 100, height: 72,
+      toJSON: () => ({}),
+    })
+    const toolSpan = view.container.querySelector<HTMLElement>(
+      '[data-timeline-span="tool"]',
+    )
+    expect(toolSpan).not.toBeNull()
+    const recordIndex = toolSpan?.dataset.timelineRecordIndex
+    expect(recordIndex).toBeTruthy()
+
+    fireEvent.pointerMove(toolSpan as HTMLElement, { clientX: 50, pointerId: 1 })
+    expect(view.container.querySelector('[data-timeline-hover-line]')).toBeNull()
+    expect(toolSpan?.getAttribute('data-hovered')).toBe('true')
+
+    fireEvent.pointerDown(plot, { button: 0, clientX: 5, pointerId: 1 })
+    fireEvent.pointerMove(plot, { clientX: 95, pointerId: 1 })
+    fireEvent.pointerUp(plot, { clientX: 95, pointerId: 1 })
+    expect(view.container.querySelector('tr[data-timeline-focus]')).toBeTruthy()
+
+    fireEvent.pointerDown(toolSpan as HTMLElement, {
+      button: 0, clientX: 50, pointerId: 2,
+    })
+    fireEvent.pointerUp(toolSpan as HTMLElement, { clientX: 50, pointerId: 2 })
+
+    const selectedRow = view.container.querySelector<HTMLElement>(
+      `tr[data-record-index="${recordIndex}"]`,
+    )
+    expect(selectedRow?.getAttribute('aria-selected')).toBe('true')
+    expect(view.container.querySelector('tr[data-timeline-focus]')).toBeNull()
+    expect(screen.getByRole('complementary', { name: 'Event details' })).toBeTruthy()
+  })
+
   it('empty window keeps the toolbar and reports no timing data', async () => {
     const b = await bench(historySnapshot([]))
     mount(b.slots)
@@ -332,6 +371,97 @@ describe('timeline projection', () => {
       ],
     }],
   }] satisfies readonly TrajectoryTurnModel[]
+  const longTurns = [{
+    turn: 1,
+    groups: [{
+      title: 'Step 1',
+      cells: Array.from({ length: 10 }, (_, index) => ({
+        index,
+        kind: 'message' as const,
+        text: `record ${index}`,
+        timeSeconds: 1,
+      })),
+    }],
+  }] satisfies readonly TrajectoryTurnModel[]
+
+  it('pans the zoomed viewport only far enough to reveal a newly selected record', async () => {
+    const onRangeChange = vi.fn()
+    const view = render(
+      <TrajectoryTimeline
+        turns={longTurns}
+        mode="sequence"
+        range={null}
+        onRangeChange={onRangeChange}
+      />,
+    )
+    const plot = screen.getByLabelText('Timeline overview; drag horizontally to focus events')
+    vi.spyOn(plot, 'getBoundingClientRect').mockReturnValue({
+      x: 0, y: 0, left: 0, top: 0, right: 100, bottom: 72, width: 100, height: 72,
+      toJSON: () => ({}),
+    })
+    fireEvent.wheel(plot, { clientX: 50, deltaY: -1_000 })
+
+    view.rerender(
+      <TrajectoryTimeline
+        turns={longTurns}
+        mode="sequence"
+        range={null}
+        selectedIndex={1}
+        onRangeChange={onRangeChange}
+      />,
+    )
+    await vi.waitFor(() => {
+      const domain = view.container.querySelector<HTMLElement>(
+        '[data-timeline-domain]',
+      )
+      expect(domain?.style.getPropertyValue('--trajectory-domain-left')).toBe('-25%')
+    })
+
+    view.rerender(
+      <TrajectoryTimeline
+        turns={longTurns}
+        mode="sequence"
+        range={null}
+        selectedIndex={8}
+        onRangeChange={onRangeChange}
+      />,
+    )
+    await vi.waitFor(() => {
+      const domain = view.container.querySelector<HTMLElement>(
+        '[data-timeline-domain]',
+      )
+      expect(domain?.style.getPropertyValue('--trajectory-domain-left')).toBe('-125%')
+    })
+  })
+
+  it('auto-pans a zoomed viewport while a range drag pushes against an edge', () => {
+    const onRangeChange = vi.fn()
+    render(
+      <TrajectoryTimeline
+        turns={longTurns}
+        mode="sequence"
+        range={null}
+        onRangeChange={onRangeChange}
+      />,
+    )
+    const plot = screen.getByLabelText('Timeline overview; drag horizontally to focus events')
+    vi.spyOn(plot, 'getBoundingClientRect').mockReturnValue({
+      x: 0, y: 0, left: 0, top: 0, right: 100, bottom: 72, width: 100, height: 72,
+      toJSON: () => ({}),
+    })
+    fireEvent.wheel(plot, { clientX: 50, deltaY: -1_000 })
+    fireEvent.pointerDown(plot, { button: 0, clientX: 50, pointerId: 1 })
+    for (let index = 0; index < 24; index++) {
+      fireEvent.pointerMove(plot, { clientX: 99, pointerId: 1 })
+    }
+    fireEvent.pointerUp(plot, { clientX: 99, pointerId: 1 })
+
+    const selectedRange = onRangeChange.mock.calls.at(-1)?.[0] as
+      | { start: number; end: number }
+      | undefined
+    expect(selectedRange).toBeDefined()
+    expect((selectedRange?.end ?? 0) - (selectedRange?.start ?? 0)).toBeGreaterThan(4)
+  })
 
   it('uses equal-width operation slots and stable semantic lanes', () => {
     expect(deriveTrajectoryTimeline(turns)).toEqual({
@@ -339,15 +469,50 @@ describe('timeline projection', () => {
       end: 3,
       spans: [
         {
-          index: 1, kind: 'message', label: 'assistant', lane: 1, start: 0, end: 1,
+          index: 1, isError: false, kind: 'message', label: 'assistant',
+          lane: 1, start: 0, end: 1,
+        },
+        {
+          index: 2, isError: false, kind: 'tool', label: 'bash',
+          lane: 2, start: 1, end: 2,
+        },
+        {
+          index: 3, isError: false, kind: 'user', label: 'unknown',
+          lane: 0, start: 2, end: 3,
         },
-        { index: 2, kind: 'tool', label: 'bash', lane: 2, start: 1, end: 2 },
-        { index: 3, kind: 'user', label: 'unknown', lane: 0, start: 2, end: 3 },
       ],
       turnBoundaries: [{ turn: 1, time: 0 }],
     })
   })
 
+  it('marks error records directly on timeline spans', () => {
+    const errorTurns = [{
+      turn: 1,
+      groups: [{
+        title: 'Step 1',
+        cells: [{
+          index: 1,
+          kind: 'tool' as const,
+          text: 'failed tool',
+          timeSeconds: 0.1,
+          isError: true,
+        }],
+      }],
+    }] satisfies readonly TrajectoryTurnModel[]
+    const view = render(
+      <TrajectoryTimeline
+        turns={errorTurns}
+        mode="sequence"
+        range={null}
+        onRangeChange={() => {}}
+      />,
+    )
+
+    expect(view.container.querySelector(
+      '[data-timeline-span="tool"][data-error="true"]',
+    )).toBeTruthy()
+  })
+
   it('ignores durations and idle gaps while retaining turn boundaries', () => {
     const separatedTurns = [
       {

packages/client/ui-workspace/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-workspace/README.md
-README.md: a1b58f4abe0925be3b426d10344777e46caa9ba0
-README.zh.md: a472507bc45549c8feb55a75d294cbd7b3138cc5
+README.md: 860c24b8a25a1e9968261f586c16163579131a1c
+README.zh.md: 5a8e88051fc6f4fd46c5f2f6dcdc185eb4559ac6

packages/client/ui-workspace/README.md

@@ -6,6 +6,8 @@ Shared Workspace picker plugin. `WorkspaceBrowser` is registered into the sideba
 
 The picker lists real Host Workspace entities through the global `useWorkspaces` hook. Selecting a Workspace invokes the slot owner's `onPick` callback to retarget the frontend Session object. Each registration declares a **directory-flow child hole** (`single` kind: `conversation.hero.workspace.directoryFlow` / `sidebar.workspaces.directoryFlow`) that the composed picker package's client half fills with its picking interaction — the [`-native`](../../host/directory-picker-native/README.md) backend's renderless OS-chooser driver today, an in-app browsing dialog under a `-browse` composition. The flat **Open local folder...** action renders only while the surface's hole is occupied (occupancy read per menu render; an empty hole means the composition has no picking affordance — the seam's documented no-flow default). This package owns the trigger and the adoption: the occupant reports one picked path per open through the hole's owner conversation (`open`/`busy`/`onPicked`/`onCancel`/`onError`), and the owner adopts it through the object layer, selecting the committed Workspace only after its list projection has refreshed; cancellation is silent, and errors land in the retryable folder dialog whose **Choose again** reopens the flow. **Create a new workspace** retains the name dialog and disables names already present in that list, while the Host remains authoritative for concurrent or non-UI callers. The runtime Session and Workspace services own materialization. The Workspace row's Delete action opens a confirmation that states the retention boundary, blocks duplicate submission, and keeps failures open; success removes the group while its Sessions remain under Ungrouped. The Session row's Rename action opens the same browser-owned dialog pattern prefilled with the row's display title: no client-side conflict rule exists (the host normalizes and may reject with `title-invalid`, rendered in the dialog alert), and confirming an unchanged title is deliberately allowed — it pins the current automatic title against regeneration.
 
+The Session row's Fork action forks at the source's last completed turn, increments the inherited persisted title on the client, and then opens the child; a trailing ASCII or fullwidth parenthesized number is incremented in the same style, while an unnumbered title gets ` (1)` appended. The source and child always appear as peer rows within a workspace group, with lineage retained only as session data. A fork or rename failure leaves the current selection unchanged; after a rename failure, the created child remains in the list.
+
 Both target slots are declared by other plugins, so `apply` registers through declaration-aware deferral and re-registers after a declaring slot is restored.
 
 ## Model Experience
@@ -18,5 +20,5 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **No Session deletion or fork control** — the Session menu's Fork and Delete rows remain visual-only (Rename is wired); Workspace registration deletion does not delete Sessions.
+- **No Session deletion control** — the Session menu's Delete row remains visual-only; Workspace registration deletion does not delete Sessions.
 - **Native folder selection depends on the local Host carrier** — under the `-native` composition, fixture-only or remote browser deployments cannot open a local operating-system dialog; platform failures are shown in a retryable modal. Remote-capable picking is the `-browse` composition's in-app flow.

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

@@ -6,6 +6,8 @@
 
 该选择器通过全局 `useWorkspaces` hook 列出真实的 Host Workspace 实体。选择 Workspace 会调用 slot owner 的 `onPick` 回调，重新定位前端 Session 对象。每个注册各自声明一个**目录流子洞**（`single` kind：`conversation.hero.workspace.directoryFlow`／`sidebar.workspaces.directoryFlow`），由组合的选择器包 client half 填入其选取交互——今天是 [`-native`](../../host/directory-picker-native/README.md) 后端的无渲染 OS 选择器驱动，`-browse` 组合下则是应用内浏览对话框。平铺显示的 **打开本地文件夹…** 操作仅在本表层的洞被占用时渲染（每次菜单渲染读取占用状态；洞为空意味着该组合没有选目录能力——seam 文档化的无流程默认行为）。本包持有触发与接纳：占用者经洞的 owner 会话（`open`/`busy`/`onPicked`/`onCancel`/`onError`）每次打开上报一个所选路径，owner 通过对象层接纳它，并等待 Workspace 列表投影刷新后才选中已提交的 Workspace；取消操作不会显示提示，错误落入可重试的文件夹对话框，其 **重新选择** 会重新打开流程。**创建新工作区** 操作保留名称对话框，并禁用列表中已有的名称，而 Host 对并发或非 UI 调用方仍具有最终决定权。运行时 Session 与 Workspace 服务负责物化。Workspace 行内的 Delete 操作会打开确认框，说明保留边界、阻止重复提交，并在失败时保持打开；成功后，该分组会被移除，其 Session 则留在 Ungrouped 下。Session 行内的 Rename 操作打开同款浏览器持有的对话框，并以该行的显示标题预填：客户端不设名称冲突规则（host 负责规范化，可能以 `title-invalid` 拒绝，错误渲染在对话框告警区）；确认未修改的标题是有意允许的——这正是把当前自动标题钉住、不再被重新生成覆盖的手势。
 
+Session 行内的 Fork 操作在源会话最后一个已完成轮次处 fork，在 client 端递增继承的持久化标题后再打开子会话；尾部半角或全角括号编号会原样式递增，无编号标题追加 ` (1)`。源会话与子会话在 workspace 组内始终作为同级行展示，谱系只保留为 session 数据。Fork 或改名失败都不会改变当前选中项，改名失败时已创建的子会话仍会留在列表中。
+
 两个目标 slot 都由其他插件声明，因此 `apply` 通过声明感知的延迟机制完成注册，并在声明该 slot 的插件恢复后重新注册。
 
 ## 模型体验
@@ -18,5 +20,5 @@
 
 ## 已知限制与暂缓事项
 
-- **没有 Session 删除与 fork 控件**：Session 菜单的 Fork 与 Delete 行仍仅提供视觉效果（Rename 已接线）；删除 Workspace 注册记录不会删除 Session。
+- **没有 Session 删除控件**：Session 菜单的 Delete 行仍仅提供视觉效果；删除 Workspace 注册记录不会删除 Session。
 - **原生文件夹选择依赖本地 Host 载体**：在 `-native` 组合下，仅使用 fixture（测试前置数据）的部署或远程浏览器部署无法打开本地操作系统对话框；模态框会显示平台故障，并允许重试。可远程的选取是 `-browse` 组合的应用内流程。

packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx

@@ -83,7 +83,7 @@ interface DragState {
 
 type SessionTreeProps = Pick<
   WorkspaceBrowserProps,
-  'useSessions' | 'startSession' | 'open' | 'insertSessionBefore'
+  'useSessions' | 'startSession' | 'open' | 'forkSession' | 'insertSessionBefore'
 > & {
   workspaces: readonly WorkspaceView[]
   /** Live search filter owned by the browser root (the query outlives the tree). */
@@ -98,13 +98,12 @@ type SessionTreeProps = Pick<
 
 /** The scrolling session tree; unmounting at collapse settle drops the sessions subscription and expansion state. */
 function SessionTree({
-  useSessions, startSession, open, workspaces, query,
+  useSessions, startSession, open, forkSession, workspaces, query,
   onRenameRequest, onDeleteRequest, onSessionRename, insertSessionBefore,
 }: SessionTreeProps) {
   const list = useSessions(s => s)
   const current = list.current
   const [expandedProjects, setExpandedProjects] = useState<string[]>([])
-  const [expandedSessions, setExpandedSessions] = useState<string[]>([])
   // Transient drag viewing state (never store-bound; order truth stays Host-side).
   const [drag, setDrag] = useState<DragState | null>(null)
   const currentGroup = current === undefined
@@ -116,8 +115,8 @@ function SessionTree({
     setExpandedProjects(l => (l.includes(currentGroup) ? l : [...l, currentGroup]))
   }, [current, currentGroup])
   const groups = useMemo(
-    () => deriveGroups(list, workspaces, { expandedProjects, expandedSessions, query }),
-    [list, workspaces, expandedProjects, expandedSessions, query],
+    () => deriveGroups(list, workspaces, { expandedProjects, query }),
+    [list, workspaces, expandedProjects, query],
   )
   const now = Date.now()
 
@@ -128,7 +127,7 @@ function SessionTree({
           <div className={css.empty}>{query === '' ? 'No sessions yet' : 'No matches'}</div>
         )}
         {groups.map(group => (
-          // Group section: header row + expanded session subtree. The
+          // Group section: header row + expanded top-level session rows. The
           // inter-group breathing room (former flat-list batch separator)
           // is the section's own margin (WorkspaceBrowser.module.css).
           <div key={group.key} className={css.groupSection}>
@@ -152,7 +151,7 @@ function SessionTree({
                 }}
             />
             {group.sessions.map((node, index) => {
-              // Draggable: real-workspace group roots outside search. The drag
+              // Draggable: real-workspace session rows outside search. The drag
               // never leaves its group — rows of other groups show no markers
               // and reject drops (visual movement confined to this section).
               const draggable = group.workspaceId !== undefined && query === ''
@@ -170,15 +169,15 @@ function SessionTree({
                 drop: (half: 'before' | 'after') => {
                   /* v8 ignore next -- narrowing guard: Rows gates drop on `active`, which is false while the drag state is null. */
                   if (drag === null) return
-                  const roots = group.sessions
+                  const sessions = group.sessions
                   // Anchor = the row the insert line points at ('after' means
                   // the next root; end-of-list omits the anchor → append).
-                  const anchor = half === 'before' ? node.id : roots[index + 1]?.id
+                  const anchor = half === 'before' ? node.id : sessions[index + 1]?.id
                   setDrag(null)
                   if (anchor === drag.sessionId) return
                   // No-op when the drop lands back on the source position.
-                  const sourceIndex = roots.findIndex(r => r.id === drag.sessionId)
-                  const anchorIndex = anchor === undefined ? roots.length : roots.findIndex(r => r.id === anchor)
+                  const sourceIndex = sessions.findIndex(r => r.id === drag.sessionId)
+                  const anchorIndex = anchor === undefined ? sessions.length : sessions.findIndex(r => r.id === anchor)
                   if (sourceIndex !== -1 && (anchorIndex === sourceIndex || anchorIndex === sourceIndex + 1)) return
                   insertSessionBefore(drag.workspaceId, drag.sessionId, anchor).catch((reason: unknown) => {
                     console.warn('session reorder rejected:', reason)
@@ -190,12 +189,11 @@ function SessionTree({
                 <SessionNodeItem
                   key={node.id}
                   node={node}
-                  depth={0}
                   currentId={current}
                   now={now}
                   onOpen={open}
                   onRename={onSessionRename}
-                  onToggle={(id) => { setExpandedSessions(l => toggled(l, id)) }}
+                  onFork={forkSession}
                   drag={dragProps}
                 />
               )
@@ -209,7 +207,7 @@ function SessionTree({
 }
 
 /** The flat "In one list" body: every session a top-level row, newest-first. */
-function FlatList({ useSessions, open, onSessionRename, query }: Pick<SessionTreeProps, 'useSessions' | 'open' | 'onSessionRename' | 'query'>) {
+function FlatList({ useSessions, open, forkSession, onSessionRename, query }: Pick<SessionTreeProps, 'useSessions' | 'open' | 'forkSession' | 'onSessionRename' | 'query'>) {
   const list = useSessions(s => s)
   const rows = useMemo(() => deriveFlat(list, { query }), [list, query])
   const now = Date.now()
@@ -223,14 +221,11 @@ function FlatList({ useSessions, open, onSessionRename, query }: Pick<SessionTre
           <SessionNodeItem
             key={node.id}
             node={node}
-            depth={0}
             currentId={list.current}
             now={now}
             onOpen={open}
             onRename={onSessionRename}
-            /* v8 ignore next -- required-prop filler: flat rows render no twist, so it never fires. */
-            onToggle={() => {}}
-            flat
+            onFork={forkSession}
           />
         ))}
       </div>
@@ -254,6 +249,7 @@ export function WorkspaceBrowser({
   startSession,
   open,
   renameSession,
+  forkSession,
   renameWorkspace,
   deleteWorkspace,
   insertSessionBefore,
@@ -462,11 +458,12 @@ export function WorkspaceBrowser({
           itself is wide-only. */}
       <div className={css.listArea}>
         {wide && (groupBy === 'flat'
-          ? <FlatList useSessions={useSessions} open={open} onSessionRename={onSessionRename} query={query} />
+          ? <FlatList useSessions={useSessions} open={open} forkSession={forkSession} onSessionRename={onSessionRename} query={query} />
           : (
             <SessionTree
               useSessions={useSessions}
               onSessionRename={onSessionRename}
+              forkSession={forkSession}
               workspaces={workspaces}
               startSession={startSession}
               open={open}

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

@@ -95,6 +95,8 @@ export type WorkspaceBrowserInjected = DirectoryPickingInjected & {
   open: (sessionId: SessionId) => void
   /** Rename a Session (explicit user title; resolves on host acceptance). */
   renameSession: (sessionId: SessionId, title: string) => Promise<void>
+  /** Fork a Session at its last completed turn and open the child. */
+  forkSession: (sessionId: SessionId) => void
   /** Rename a Host Workspace (rejects on name conflict; resolves on durability). */
   renameWorkspace: (workspaceId: WorkspaceId, title: string) => Promise<void>
   /** Delete only a Host Workspace registration; directory and Session logs remain. */

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

@@ -59,6 +59,13 @@ export function apply(ctx: ClientContext): void {
       const result = await session.rename(title)
       if (!result.ok) throw new Error(result.error.message)
     },
+    forkSession: (sessionId) => {
+      ctx.sessions.fork({ sessionId, increaseTitle: true })
+        .then((childId) => { ctx.sessions.open(childId) })
+        .catch(() => {
+          // Fork or child-rename failure keeps the current selection.
+        })
+    },
     renameWorkspace: async (workspaceId, title) => { await ctx.workspaces.rename(workspaceId, title) },
     deleteWorkspace: async (workspaceId) => { await ctx.workspaces.delete(workspaceId) },
     insertSessionBefore: async (workspaceId, sessionId, beforeSessionId) => {

packages/client/ui-workspace/src/client/rows/Rows.module.css

@@ -39,9 +39,7 @@
   height: 20px;
 }
 
-/* Session cell (figma): pad 8, adjacent 16px twist + status slots, then a 4px
-   gap to the title — the slots butt together, so the row gap is zeroed and
-   the title carries its own margins. */
+/* Session cell (figma): pad 8, a 16px status slot, then a 4px title gap. */
 .sessionRow {
   height: 34px;
   gap: 0;
@@ -168,7 +166,7 @@
   background: var(--dsw-alias-interactive-bg-hover);
 }
 
-/* Drag reorder insert line (workspace-group roots): 2px accent above or
+/* Drag reorder insert line (workspace-group session rows): 2px accent above or
    below the hovered row, drawn with box-shadow so no layout shift. */
 .sessionRow.dropBefore {
   box-shadow: 0 -2px 0 0 var(--dsw-alias-state-business-primary);
@@ -233,33 +231,9 @@
   color: var(--dsw-alias-label-primary);
 }
 
-/* Session expand twist occupies the leading 16px slot; keep a spacer when absent
-   so titles align across sibling rows. Duplicates the .iconButton reset instead
-   of `composes:` — the tsdown CSS-modules pipeline drops composes mappings, which
-   left the raw UA button box showing. */
-.twist {
-  flex: none;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 16px;
-  height: 20px;
-  border: none;
-  border-radius: 4px;
-  padding: 0;
-  background: transparent;
-  cursor: pointer;
-}
-
-.twist:hover {
-  color: var(--dsw-alias-label-primary);
-}
-
-/* Chevrons and tree twists ride the caption grey (#ADB2B8); the folder glyph
-   stays one step darker (tertiary, #81858C) per the cell spec. Declared last
-   to win over the composed .iconButton color. */
-.chevron,
-.twist {
+/* Chevrons ride the caption grey (#ADB2B8); the folder glyph stays one step
+   darker (tertiary, #81858C) per the cell spec. */
+.chevron {
   color: var(--dsw-alias-label-caption);
 }
 

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

@@ -2,8 +2,8 @@
  * Workspace browser tree row components (figma Cell set 14:3080): pure presentational —
  * all data and callbacks arrive via props. Hover swaps (folder->chevron,
  * time->ellipsis, action buttons) are CSS-only. Row ... menus are visual-only
- * except workspace Rename/Delete and session Rename; the session and workspace
- * hover cards are suppressed while a menu is open.
+ * except workspace Rename/Delete and session Rename/Fork; the session and
+ * workspace hover cards are suppressed while a menu is open.
  */
 import { useState } from 'react'
 import clsx from 'clsx'
@@ -16,9 +16,6 @@ import type { GroupNode, SessionNode } from '../tree.ts'
 import { formatRelativeTime } from '../tree.ts'
 import css from './Rows.module.css'
 
-/** Indent step per tree level: one 16px slot (figma session cell). */
-const INDENT_STEP = 16
-
 const SESSION_MENU_ITEMS = [
   { id: 'rename', label: 'Rename', icon: <IconEditOutline16 /> },
   { id: 'fork', label: 'Fork session', icon: <IconBranchOutline16 /> },
@@ -135,16 +132,12 @@ export function ProjectRowItem({ group, onToggle, onCreate, actions }: {
 }
 
 /**
- * One session subtree: the node's own 34px row (indent by depth, expand
- * twist when it has children, running dot, relative time) plus its visible
- * children, recursively — the component tree mirrors the derived tree.
+ * One top-level 34px session row with running dot and relative time.
  * @param props.node - derived session node.
- * @param props.depth - 0 = directly under the group header.
  * @param props.currentId - selected session id (row highlight).
  * @param props.now - epoch ms for relative-time formatting.
  * @param props.onOpen - open a session by id.
- * @param props.onToggle - unfold/fold a subtree by id.
- * @returns the node's row followed by its children.
+ * @returns the session row.
  */
 /** Hover-card body: full title, relative time, and the status line (running/idle until wire status lands). */
 function SessionHoverContent({ node, now }: { node: SessionNode; now: number }) {
@@ -161,7 +154,7 @@ function SessionHoverContent({ node, now }: { node: SessionNode; now: number })
 }
 
 /**
- * Root-row drag wiring supplied by the group owner (workspace groups only).
+ * Session-row drag wiring supplied by the group owner (workspace groups only).
  * `drop` reports the half of the row the pointer released on: 'before'
  * inserts above this row, 'after' below it (the owner resolves the anchor).
  */
@@ -184,26 +177,22 @@ function rowHalf(e: { clientY: number; currentTarget: HTMLElement }): 'before' |
   return e.clientY < rect.top + rect.height / 2 ? 'before' : 'after'
 }
 
-export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename, onToggle, drag, flat = false }: {
+export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork, drag }: {
   node: SessionNode
-  depth: number
   currentId: string | undefined
   now: number
   onOpen: (id: SessionNode['id']) => void
   /** Open the browser-owned session rename dialog (row menu action). */
   onRename: (id: SessionNode['id'], currentTitle: string) => void
-  onToggle: (id: SessionNode['id']) => void
-  /** Present only on draggable rows (workspace-group roots outside search). */
+  /** Fork a session at its last completed turn (row menu action). */
+  onFork: (id: SessionNode['id']) => void
+  /** Present only on draggable rows (workspace-group sessions outside search). */
   drag?: RowDragProps | undefined
-  /** Flat-list variant: no twist slot (figma flat cell) — titles align on the status slot. */
-  flat?: boolean
 }) {
   const row = node
   const selected = node.id === currentId
   const [menuOpen, setMenuOpen] = useState(false)
-  // Rail (figma session cell: pad 8, twist slot 16, status slot 16, gap 4 to
-  // the title): both slots are always reserved so titles align whether or not
-  // the twist/dot is lit. Extra depth rides the left padding.
+  // Figma session cell: pad 8, status slot 16, then a 4px title gap.
   const ownRow = (
     <div
       className={clsx(
@@ -212,8 +201,6 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename,
       )}
       role="treeitem"
       aria-selected={selected}
-      {...(row.hasChildren ? { 'aria-expanded': row.expanded } : {})}
-      style={{ paddingLeft: 8 + depth * INDENT_STEP }}
       onClick={() => { onOpen(node.id) }}
       draggable={drag !== undefined}
       onDragStart={drag === undefined
@@ -239,18 +226,6 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename,
           drag.drop(rowHalf(e))
         }}
     >
-      {row.hasChildren && !flat
-        ? (
-          <button
-            type="button"
-            className={css.twist}
-            aria-label={row.expanded ? 'Collapse' : 'Expand'}
-            onClick={(e) => { e.stopPropagation(); onToggle(node.id) }}
-          >
-            <IconTriangleRightFill14 className={clsx(css.arrow, row.expanded && css.arrowOpen)} />
-          </button>
-        )
-        : null}
       <span className={css.slot}>{row.running && <StateDot state="ongoing" />}</span>
       <span className={css.title}>{row.title}</span>
       <span className={css.time}>{formatRelativeTime(row.updatedAt, now)}</span>
@@ -261,7 +236,8 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename,
           items={SESSION_MENU_ITEMS}
           onSelect={(id) => {
             setMenuOpen(false)
-            if (id === 'rename') onRename(node.id, row.title) // fork/delete stay visual-only.
+            if (id === 'rename') onRename(node.id, row.title)
+            if (id === 'fork') onFork(node.id) // delete stays visual-only.
           }}
           portal
           closeOnPointerLeave
@@ -280,24 +256,10 @@ export function SessionNodeItem({ node, depth, currentId, now, onOpen, onRename,
     </div>
   )
   return (
-    <>
-      <HoverCard
-        anchor={ownRow}
-        content={<SessionHoverContent node={node} now={now} />}
-        disabled={menuOpen || drag?.active === true}
-      />
-      {node.children.map(child => (
-        <SessionNodeItem
-          key={child.id}
-          node={child}
-          depth={depth + 1}
-          currentId={currentId}
-          now={now}
-          onOpen={onOpen}
-          onRename={onRename}
-          onToggle={onToggle}
-        />
-      ))}
-    </>
+    <HoverCard
+      anchor={ownRow}
+      content={<SessionHoverContent node={node} now={now} />}
+      disabled={menuOpen || drag?.active === true}
+    />
   )
 }

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

@@ -11,20 +11,15 @@ export const UNGROUPED_KEY = ''
 /** Display label for the ungrouped bucket row. */
 export const UNGROUPED_LABEL = 'Ungrouped'
 
-/** One session node of a group's visible tree (34px row; children render indented one step). */
+/** One top-level session row in a group or the flat list. */
 export interface SessionNode {
   id: SessionId
   title: string
-  /** Visible children, already expansion/search-filtered (empty when folded). */
-  children: readonly SessionNode[]
-  /** The session HAS children in the data (the twist renders even while folded). */
-  hasChildren: boolean
-  expanded: boolean
   running: boolean
   updatedAt: number
 }
 
-/** One workspace group section: header row facts + the visible session tree. */
+/** One workspace group section: header row facts + visible top-level session rows. */
 export interface GroupNode {
   /** Group key: the workspace id or {@link UNGROUPED_KEY}. */
   key: string
@@ -39,14 +34,13 @@ export interface GroupNode {
   expanded: boolean
   /** The group contains the selected session (active folder tint; supplied here so the renderer never scans). */
   containsCurrent: boolean
-  /** Visible roots (empty while the group is folded). */
+  /** Visible session rows (empty while the group is folded). */
   sessions: readonly SessionNode[]
 }
 
-/** Viewing state consumed by the derivation — the component's local useState arrays, taken as-is. */
+/** Viewing state consumed by the derivation. */
 export interface TreeView {
   expandedProjects: readonly string[]
-  expandedSessions: readonly string[]
   query: string
 }
 
@@ -56,9 +50,7 @@ interface Group {
   cwd: string | undefined
   createdAt: number | undefined
   label: string
-  summaries: Map<SessionId, SessionSummary>
-  roots: SessionId[]
-  children: Map<SessionId, SessionId[]>
+  sessions: SessionSummary[]
 }
 
 /**
@@ -89,7 +81,7 @@ function sessionTitle(session: SessionSummary): string {
   return session.blank ? 'New Session' : session.displayTitle
 }
 
-/** Build one group's parent/child tree from an ordered member list. */
+/** Build one group without projecting session lineage into presentation. */
 function buildGroup(
   key: string,
   workspaceId: WorkspaceId | undefined,
@@ -99,54 +91,11 @@ function buildGroup(
   members: readonly SessionSummary[],
   order: 'account' | 'recency',
 ): Group {
-  const summaries = new Map(members.map(m => [m.id, m]))
-  const children = new Map<SessionId, SessionId[]>()
-  const roots: SessionSummary[] = []
-  for (const m of members) {
-    // A session is a tree child only when its parent lives in the same
-    // group; cross-group or unknown parents degrade to group roots.
-    if (m.parentId !== undefined && m.parentId !== m.id && summaries.has(m.parentId)) {
-      const kids = children.get(m.parentId)
-      if (kids === undefined) children.set(m.parentId, [m.id])
-      else kids.push(m.id)
-    } else {
-      roots.push(m)
-    }
-  }
-  // Workspace order is the member iteration order (workspace.sessionIds), so
-  // attached groups keep insertion order; Ungrouped sorts by recency.
-  if (order === 'recency') {
-    roots.sort(byRecency)
-    for (const kids of children.values()) {
-      kids.sort((a, b) => {
-        const sa = summaries.get(a)
-        const sb = summaries.get(b)
-        /* v8 ignore next -- unreachable: kid ids are inserted alongside their summaries. */
-        if (sa === undefined || sb === undefined) return 0
-        return byRecency(sa, sb)
-      })
-    }
-  }
-  const rootIds = roots.map(r => r.id)
-  // parentId cycles (host bug) leave members unreachable from any root;
-  // surface them as extra roots — the flatten walk's visited set stops
-  // loops. Each node sits in at most one kids list and roots have no
-  // in-group parent, so the scan pushes every reachable node exactly once.
-  const reachable = new Set<SessionId>(rootIds)
-  const stack = [...rootIds]
-  while (stack.length > 0) {
-    const top = stack.pop()
-    /* v8 ignore next -- unreachable: the loop condition guarantees a non-empty stack. */
-    if (top === undefined) break
-    for (const kid of children.get(top) ?? []) {
-      reachable.add(kid)
-      stack.push(kid)
-    }
-  }
-  for (const m of members) {
-    if (!reachable.has(m.id)) rootIds.push(m.id)
-  }
-  return { key, workspaceId, cwd, createdAt, label, summaries, roots: rootIds, children }
+  const sessions = [...members]
+  // Workspace order is workspace.sessionIds; only Ungrouped lacks an account
+  // order and therefore falls back to recency.
+  if (order === 'recency') sessions.sort(byRecency)
+  return { key, workspaceId, cwd, createdAt, label, sessions }
 }
 
 /**
@@ -181,72 +130,24 @@ function groupByWorkspace(list: SessionListState, workspaces: readonly Workspace
   return groups
 }
 
-function sessionNode(s: SessionSummary, children: readonly SessionNode[], hasChildren: boolean, expanded: boolean): SessionNode {
+function sessionNode(s: SessionSummary): SessionNode {
   return {
     id: s.id,
     title: sessionTitle(s),
-    children,
-    hasChildren,
-    expanded,
     running: s.running,
     updatedAt: s.updatedAt,
   }
 }
 
-function buildVisible(g: Group, expandedSessions: ReadonlySet<string>): SessionNode[] {
-  const visited = new Set<SessionId>()
-  const walk = (id: SessionId): SessionNode | null => {
-    if (visited.has(id)) return null
-    visited.add(id)
-    const s = g.summaries.get(id)
-    /* v8 ignore next -- unreachable: walked ids come from the grouped summaries. */
-    if (s === undefined) return null
-    const kids = g.children.get(id) ?? []
-    const expanded = expandedSessions.has(id)
-    const children = expanded ? kids.map(walk).filter((n): n is SessionNode => n !== null) : []
-    return sessionNode(s, children, kids.length > 0, expanded)
-  }
-  return g.roots.map(walk).filter((n): n is SessionNode => n !== null)
-}
-
-/** Matched sessions plus their ancestor chains (forced visible under search). */
-function searchVisible(g: Group, q: string): Set<SessionId> {
-  const visible = new Set<SessionId>()
-  for (const m of g.summaries.values()) {
-    if (!sessionTitle(m).toLowerCase().includes(q)) continue
-    let cur: SessionSummary | undefined = m
-    while (cur !== undefined && !visible.has(cur.id)) {
-      visible.add(cur.id)
-      cur = cur.parentId !== undefined && cur.parentId !== cur.id ? g.summaries.get(cur.parentId) : undefined
-    }
-  }
-  return visible
-}
-
-function buildSearch(g: Group, visible: ReadonlySet<SessionId>): SessionNode[] {
-  const visited = new Set<SessionId>()
-  const walk = (id: SessionId): SessionNode | null => {
-    if (visited.has(id) || !visible.has(id)) return null
-    visited.add(id)
-    const s = g.summaries.get(id)
-    /* v8 ignore next -- unreachable: walked ids come from the grouped summaries. */
-    if (s === undefined) return null
-    const kids = (g.children.get(id) ?? []).filter(kid => visible.has(kid))
-    const children = kids.map(walk).filter((n): n is SessionNode => n !== null)
-    return sessionNode(s, children, kids.length > 0, kids.length > 0)
-  }
-  return g.roots.map(walk).filter((n): n is SessionNode => n !== null)
-}
-
 /**
- * Derive the nested workspace browser group structure.
+ * Derive the workspace browser groups with every session as a top-level row.
  *
  * Normal mode: every group shows; sessions populate under expanded groups,
- * descending only into expanded sessions. Search mode (non-blank query,
+ * preserving Host account order. Search mode (non-blank query,
  * case-insensitive display-title substring): expansion state is ignored —
- * matched sessions and their ancestor chains are forced visible, groups
- * without a display-title or label hit are dropped, and a label-only hit
- * keeps the bare group header. Blank sessions are excluded everywhere.
+ * matching sessions are forced visible, groups without a display-title or
+ * label hit are dropped, and a label-only hit
+ * keeps the bare group header. Non-current blank sessions are excluded.
  * @param list - sessions list snapshot (`current` feeds containsCurrent).
  * @param workspaces - real workspaces in stable Host order.
  * @param view - local expansion arrays and search query.
@@ -259,7 +160,6 @@ export function deriveGroups(
 ): GroupNode[] {
   const q = view.query.trim().toLowerCase()
   const expandedProjects = new Set(view.expandedProjects)
-  const expandedSessions = new Set(view.expandedSessions)
   const currentGroup = list.current === undefined
     ? undefined
     : (workspaces.find(w => w.sessionIds.includes(list.current as SessionId))?.workspaceId as string | undefined)
@@ -274,24 +174,24 @@ export function deriveGroups(
         cwd: g.cwd,
         createdAt: g.createdAt,
         label: g.label,
-        sessionCount: g.summaries.size,
+        sessionCount: g.sessions.length,
         expanded,
         containsCurrent: g.key === currentGroup,
-        sessions: expanded ? buildVisible(g, expandedSessions) : [],
+        sessions: expanded ? g.sessions.map(sessionNode) : [],
       })
     } else {
-      const visible = searchVisible(g, q)
-      if (visible.size === 0 && !g.label.toLowerCase().includes(q)) continue
+      const matches = g.sessions.filter(session => sessionTitle(session).toLowerCase().includes(q))
+      if (matches.length === 0 && !g.label.toLowerCase().includes(q)) continue
       groups.push({
         key: g.key,
         workspaceId: g.workspaceId,
         cwd: g.cwd,
         createdAt: g.createdAt,
         label: g.label,
-        sessionCount: g.summaries.size,
-        expanded: visible.size > 0,
+        sessionCount: g.sessions.length,
+        expanded: matches.length > 0,
         containsCurrent: g.key === currentGroup,
-        sessions: buildSearch(g, visible),
+        sessions: matches.map(sessionNode),
       })
     }
   }
@@ -301,9 +201,8 @@ export function deriveGroups(
 /**
  * Derive the flat session list ("In one list" mode): every session — fork
  * children included — as a top-level row, strictly newest-first. No grouping,
- * no parent/child adjacency; rows reuse SessionNode with children always
- * empty so the renderer stays branch-free. Search mode filters by
- * case-insensitive display-title substring.
+ * no parent/child adjacency. Search mode filters by case-insensitive
+ * display-title substring.
  * @param list - sessions list snapshot.
  * @param view - the search query (expansion state does not apply).
  * @returns flat rows in render order.
@@ -318,7 +217,7 @@ export function deriveFlat(list: SessionListState, view: Pick<TreeView, 'query'>
     rows.push(s)
   }
   rows.sort(byRecency)
-  return rows.map(s => sessionNode(s, [], false, false))
+  return rows.map(sessionNode)
 }
 
 /**

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

@@ -19,11 +19,17 @@ async function bench() {
   const insertSessionBefore = vi.fn(async () => ({}))
   const open = vi.fn()
   const clear = vi.fn()
+  const renameSession = vi.fn(async (title: string) => ({ ok: true, value: { title, seq: 1 } }))
+  const binding = vi.fn(() => ({ session: { rename: renameSession } }))
+  const fork = vi.fn(async () => 'forked' as never)
   ctx.provide('workspaces', {
     create, startSession, rename, insertSessionBefore,
   } as never)
-  ctx.provide('sessions', { open, clear } as never)
-  return { ctx, slots: ctx.get('slots') as SlotsService, create, startSession, rename, insertSessionBefore, open, clear }
+  ctx.provide('sessions', { open, clear, binding, fork } as never)
+  return {
+    ctx, slots: ctx.get('slots') as SlotsService, create, startSession, rename,
+    insertSessionBefore, open, clear, renameSession, binding, fork,
+  }
 }
 
 type HoleName = 'sidebar.workspaces' | 'conversation.hero.workspace' | 'conversation.empty.workspace'
@@ -66,6 +72,14 @@ describe('ui-workspace apply', () => {
     expect(b.startSession).toHaveBeenLastCalledWith(undefined)
     browser.open('session' as never)
     expect(b.open).toHaveBeenCalledWith('session')
+    await browser.renameSession('session' as never, 'renamed session')
+    expect(b.binding).toHaveBeenCalledWith('session')
+    expect(b.renameSession).toHaveBeenCalledWith('renamed session')
+    browser.forkSession('session' as never)
+    await vi.waitFor(() => {
+      expect(b.open).toHaveBeenCalledWith('forked')
+    })
+    expect(b.fork).toHaveBeenCalledWith({ sessionId: 'session', increaseTitle: true })
     await browser.renameWorkspace('ws' as never, 'renamed')
     expect(b.rename).toHaveBeenCalledWith('ws', 'renamed')
     await browser.insertSessionBefore('ws' as never, 's1' as never, 's2' as never)

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

@@ -56,46 +56,22 @@ describe('workspace browser rows', () => {
     expect(onToggle).toHaveBeenCalledOnce()
   })
 
-  it('renders and operates selected, running, recursive Session nodes', () => {
-    const child: SessionNode = {
-      id: sid('child'), title: 'Child', children: [], hasChildren: false,
-      expanded: false, running: false, updatedAt: 0,
-    }
-    const parent: SessionNode = {
-      id: sid('parent'), title: 'Parent', children: [child], hasChildren: true,
-      expanded: true, running: true, updatedAt: 0,
+  it('renders and opens a selected running Session row', () => {
+    const node: SessionNode = {
+      id: sid('session'), title: 'Session', running: true, updatedAt: 0,
     }
     const onOpen = vi.fn()
-    const onToggle = vi.fn()
-    const view = render(
-      <SessionNodeItem node={parent} depth={0} currentId={parent.id} now={0} onOpen={onOpen}
-        onRename={vi.fn()} onToggle={onToggle} />,
+    render(
+      <SessionNodeItem node={node} currentId={node.id} now={0} onOpen={onOpen}
+        onRename={vi.fn()} onFork={vi.fn()} />,
     )
 
-    const parentRow = screen.getByText('Parent').closest('[role="treeitem"]')!
-    const childRow = screen.getByText('Child').closest('[role="treeitem"]')!
-    expect(parentRow.getAttribute('aria-selected')).toBe('true')
-    expect(parentRow.getAttribute('aria-expanded')).toBe('true')
-    expect(childRow.getAttribute('aria-selected')).toBe('false')
-    expect(childRow.hasAttribute('aria-expanded')).toBe(false)
-
-    fireEvent.click(screen.getByRole('button', { name: 'Collapse' }))
-    expect(onToggle).toHaveBeenCalledWith(parent.id)
-    expect(onOpen).not.toHaveBeenCalled()
-    fireEvent.click(parentRow)
-    fireEvent.click(childRow)
-    expect(onOpen.mock.calls).toEqual([[parent.id], [child.id]])
-
-    view.rerender(
-      <SessionNodeItem
-        node={{ ...parent, children: [], expanded: false, running: false }}
-        depth={1} currentId={undefined} now={0} onOpen={onOpen}
-        onRename={vi.fn()} onToggle={onToggle}
-      />,
-    )
-    expect(screen.getByRole('button', { name: 'Expand' })).toBeTruthy()
-    expect(screen.getByRole('treeitem').getAttribute('aria-selected')).toBe('false')
-    expect(screen.getByRole('treeitem').style.paddingLeft).toBe('24px')
+    const row = screen.getByRole('treeitem')
+    expect(row.getAttribute('aria-selected')).toBe('true')
+    expect(row.hasAttribute('aria-expanded')).toBe(false)
+    expect(screen.queryByRole('button', { name: /Expand|Collapse/ })).toBeNull()
+    fireEvent.click(row)
+    expect(onOpen).toHaveBeenCalledWith(node.id)
   })
 
   it('workspace row menu opens on the ellipsis, renames, and shows the danger delete row', () => {
@@ -156,15 +132,15 @@ describe('workspace browser rows', () => {
     expect(screen.queryByRole('button', { name: /Workspace actions/ })).toBeNull()
   })
 
-  it('session row menu opens without opening the session and dispatches rename', () => {
+  it('session row menu opens without opening the session and dispatches rename and fork', () => {
     const onOpen = vi.fn()
     const onRename = vi.fn()
+    const onFork = vi.fn()
     const node: SessionNode = {
-      id: sid('s1'), title: 'One', children: [], hasChildren: false,
-      expanded: false, running: false, updatedAt: 0,
+      id: sid('s1'), title: 'One', running: false, updatedAt: 0,
     }
-    render(<SessionNodeItem node={node} depth={0} currentId={undefined} now={0} onOpen={onOpen}
-      onRename={onRename} onToggle={vi.fn()} />)
+    render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={onOpen}
+      onRename={onRename} onFork={onFork} />)
     fireEvent.click(screen.getByRole('button', { name: 'Session actions for One' }))
     expect(onOpen).not.toHaveBeenCalled()
     expect(screen.getByRole('menuitem', { name: 'Delete session' }).className).toMatch(/danger/)
@@ -173,9 +149,10 @@ describe('workspace browser rows', () => {
     expect(screen.queryByRole('menu')).toBeNull()
     expect(onRename).toHaveBeenCalledWith(node.id, 'One')
     expect(onOpen).not.toHaveBeenCalled()
-    // Fork and Delete stay visual-only.
     fireEvent.click(screen.getByRole('button', { name: 'Session actions for One' }))
     fireEvent.click(screen.getByRole('menuitem', { name: 'Fork session' }))
+    expect(onFork).toHaveBeenCalledWith(node.id)
+    // Delete stays visual-only.
     fireEvent.click(screen.getByRole('button', { name: 'Session actions for One' }))
     fireEvent.click(screen.getByRole('menuitem', { name: 'Delete session' }))
     expect(onRename).toHaveBeenCalledOnce()
@@ -185,25 +162,14 @@ describe('workspace browser rows', () => {
     expect(screen.queryByRole('menu')).toBeNull()
   })
 
-  it('flat variant renders no twist even for a parent and ignores toggling', () => {
-    const node: SessionNode = {
-      id: sid('p'), title: 'Parent', children: [], hasChildren: true,
-      expanded: false, running: false, updatedAt: 0,
-    }
-    render(<SessionNodeItem node={node} depth={0} currentId={undefined} now={0} onOpen={vi.fn()}
-      onRename={vi.fn()} onToggle={vi.fn()} flat />)
-    expect(screen.queryByRole('button', { name: 'Expand' })).toBeNull()
-  })
-
   it('shows the hover card after the dwell and suppresses it while the row menu is open', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s1'), title: 'Hovered', children: [], hasChildren: false,
-        expanded: false, running: true, updatedAt: 0,
+        id: sid('s1'), title: 'Hovered', running: true, updatedAt: 0,
       }
-      render(<SessionNodeItem node={node} depth={0} currentId={undefined} now={60_000} onOpen={vi.fn()}
-        onRename={vi.fn()} onToggle={vi.fn()} />)
+      render(<SessionNodeItem node={node} currentId={undefined} now={60_000} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} />)
       const wrapper = screen.getByRole('treeitem').parentElement as HTMLElement
       fireEvent.pointerEnter(wrapper)
       act(() => { vi.advanceTimersByTime(500) })
@@ -226,11 +192,10 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s1'), title: 'Quiet', children: [], hasChildren: false,
-        expanded: false, running: false, updatedAt: 0,
+        id: sid('s1'), title: 'Quiet', running: false, updatedAt: 0,
       }
-      render(<SessionNodeItem node={node} depth={0} currentId={undefined} now={0} onOpen={vi.fn()}
-        onRename={vi.fn()} onToggle={vi.fn()} />)
+      render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} />)
       fireEvent.pointerEnter(screen.getByRole('treeitem').parentElement as HTMLElement)
       act(() => { vi.advanceTimersByTime(500) })
       expect(screen.getByText('Idle')).toBeTruthy()
@@ -242,13 +207,12 @@ describe('workspace browser rows', () => {
 
   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', children: [], hasChildren: false,
-      expanded: false, running: false, updatedAt: 0,
+      id: sid('s1'), title: 'Drag me', running: false, updatedAt: 0,
     }
     const inactive = dragProps()
     const { rerender } = render(
-      <SessionNodeItem node={node} depth={0} currentId={undefined} now={0} onOpen={vi.fn()}
-        onRename={vi.fn()} onToggle={vi.fn()} drag={inactive} />,
+      <SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} drag={inactive} />,
     )
     const row = screen.getByRole('treeitem')
     stubRect(row)
@@ -265,8 +229,8 @@ describe('workspace browser rows', () => {
 
     const active = dragProps({ active: true, marker: 'before' })
     rerender(
-      <SessionNodeItem node={node} depth={0} currentId={undefined} now={0} onOpen={vi.fn()}
-        onRename={vi.fn()} onToggle={vi.fn()} drag={active} />,
+      <SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} drag={active} />,
     )
     stubRect(screen.getByRole('treeitem'))
     // Top half hovers/drops 'before'; bottom half 'after' (row mid = 117).
@@ -279,8 +243,8 @@ describe('workspace browser rows', () => {
 
     const after = dragProps({ active: true, marker: 'after' })
     rerender(
-      <SessionNodeItem node={node} depth={0} currentId={undefined} now={0} onOpen={vi.fn()}
-        onRename={vi.fn()} onToggle={vi.fn()} drag={after} />,
+      <SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} drag={after} />,
     )
     expect(screen.getByRole('treeitem').className).toMatch(/dropAfter/)
   })

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

@@ -21,7 +21,7 @@ const workspace = (id: string, sessionIds: string[]): WorkspaceView => ({
   sessionIds: sessionIds.map(sid), createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z',
 })
 const view = (expandedProjects: readonly string[] = [], query = '') => ({
-  expandedProjects, expandedSessions: [] as string[], query,
+  expandedProjects, query,
 })
 
 describe('deriveGroups', () => {
@@ -74,7 +74,7 @@ describe('deriveGroups', () => {
     expect(groups[0]!.sessionCount).toBe(1)
   })
 
-  it('builds, sorts, expands, and cycle-guards an ungrouped session tree', () => {
+  it('ignores fork lineage and sorts every ungrouped session as a top-level row', () => {
     const parent = summary('parent', 1)
     const oldChild = { ...summary('old-child', 10), parentId: parent.id }
     const newChild = { ...summary('new-child', 20), parentId: parent.id }
@@ -87,15 +87,13 @@ describe('deriveGroups', () => {
     const groups = deriveGroups(
       list(parent, oldChild, newChild, tieB, tieA, self, orphan, cycleA, cycleB),
       [],
-      { expandedProjects: [UNGROUPED_KEY], expandedSessions: [parent.id, cycleA.id, cycleB.id], query: '' },
+      { expandedProjects: [UNGROUPED_KEY], query: '' },
     )
 
     expect(groups).toHaveLength(1)
     expect(groups[0]!.sessions.map(node => node.id)).toEqual([
-      sid('orphan'), sid('self'), parent.id, sid('cycle-a'),
-    ])
-    expect(groups[0]!.sessions[2]!.children.map(node => node.id)).toEqual([
       newChild.id, tieA.id, tieB.id, oldChild.id,
+      cycleB.id, cycleA.id, orphan.id, self.id, parent.id,
     ])
 
     // Equal timestamps use ids as a deterministic tiebreak in either input order.
@@ -113,7 +111,7 @@ describe('deriveGroups', () => {
     expect(groups[0]!.sessions.map(node => node.id)).toEqual([sid('present')])
   })
 
-  it('searches descendants with ancestors and handles cycles, self parents, and label-only hits', () => {
+  it('searches rows independently of lineage and keeps label-only hits', () => {
     const root = { ...summary('root', 1), displayTitle: 'Ancestor' }
     const match = { ...summary('match', 2), displayTitle: 'Needle child', parentId: root.id }
     const sibling = { ...summary('sibling', 3), displayTitle: 'Other child', parentId: root.id }
@@ -124,8 +122,8 @@ describe('deriveGroups', () => {
     const sessions = list(root, match, sibling, self, orphan, cycleA, cycleB)
     const groups = deriveGroups(sessions, [workspace('project', sessions.ids)], view([], 'needle'))
 
-    expect(groups[0]!.sessions.flatMap(node => [node.id, ...node.children.map(child => child.id)])).toEqual([
-      root.id, match.id, self.id, orphan.id, cycleA.id, cycleB.id,
+    expect(groups[0]!.sessions.map(node => node.id)).toEqual([
+      match.id, self.id, orphan.id, cycleA.id, cycleB.id,
     ])
 
     const labelOnly = deriveGroups(
@@ -157,8 +155,6 @@ describe('deriveFlat', () => {
     const tieA = summary('tie-a', 20)
     const rows = deriveFlat(list(parent, child, tieB, tieA), { query: '' })
     expect(rows.map(row => row.id)).toEqual([sid('child'), sid('tie-a'), sid('tie-b'), sid('parent')])
-    // Rows are branch-free: no children, no expansion.
-    expect(rows.every(row => row.children.length === 0 && !row.hasChildren && !row.expanded)).toBe(true)
   })
 
   it('search filters by case-insensitive display-title substring', () => {

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

@@ -56,6 +56,7 @@ function mount(overrides: Partial<WorkspaceBrowserProps> = {}) {
     startSession: vi.fn(),
     open: vi.fn(),
     renameSession: vi.fn(async () => {}),
+    forkSession: vi.fn(),
     renameWorkspace: vi.fn(async () => {}),
     deleteWorkspace: vi.fn(async () => {}),
     insertSessionBefore: vi.fn(async () => {}),
@@ -124,7 +125,7 @@ describe('WorkspaceBrowser', () => {
     expect(screen.queryByText('alpha-s')).toBeNull()
   })
 
-  it('unfolds a session subtree through the row twist', () => {
+  it('renders a fork child as a top-level row without a session twist', () => {
     const parent = summary('parent-s', 2)
     const child = { ...summary('child-s', 1), parentId: parent.id }
     mount({
@@ -132,11 +133,9 @@ describe('WorkspaceBrowser', () => {
       useWorkspaces: hook(workspaceState([workspace('alpha', ['parent-s', 'child-s'])])),
     })
     fireEvent.click(screen.getByText('alpha'))
-    expect(screen.queryByText('child-s')).toBeNull()
-    fireEvent.click(screen.getByRole('button', { name: 'Expand' }))
     expect(screen.getByText('child-s')).toBeTruthy()
-    fireEvent.click(screen.getByRole('button', { name: 'Collapse' }))
-    expect(screen.queryByText('child-s')).toBeNull()
+    expect(screen.queryByRole('button', { name: /Expand|Collapse/ })).toBeNull()
+    expect(screen.getByText('child-s').closest('[role="treeitem"]')?.getAttribute('draggable')).toBe('true')
   })
 
   it('auto-expands the selected session group and starts a session from the group ＋', () => {

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

@@ -264,6 +264,28 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'credentials',
+    summary: 'Abstract credential service.',
+    methods: [
+      {
+        signature: 'abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>',
+        jsDoc: '/**\n * Resolve one reference to its current value. Resolution is per call:\n * consumers re-resolve at each operation and must not cache across\n * operations — that per-operation read is what makes a changed credential\n * reach the next operation without a restart.\n * @param ref - the reference to resolve.\n * @returns the value and its source, or `undefined` while unconfigured.\n */',
+      },
+      {
+        signature: 'abstract describe(ref: CredentialRef): Promise<CredentialInfo>',
+        jsDoc: '/**\n * Describe one reference for configuration surfaces without exposing the\n * value.\n * @param ref - the reference to describe.\n * @returns configured state, supplying source, and writability.\n */',
+      },
+      {
+        signature: 'abstract set(ref: CredentialRef, value: string): Promise<void>',
+        jsDoc: '/**\n * Durably store one value in the provider-managed writable source. Rejects\n * while a read-only source shadows the reference — the write would appear\n * to succeed while resolution keeps returning the shadowing value — and\n * rejects an empty value (use {@link unset}).\n * @param ref - the reference to store.\n * @param value - the non-empty secret value.\n */',
+      },
+      {
+        signature: 'abstract unset(ref: CredentialRef): Promise<void>',
+        jsDoc: '/**\n * Remove one reference from the provider-managed writable source; removing\n * an absent reference is a no-op. Rejects while a read-only source shadows\n * the reference, like {@link set}.\n * @param ref - the reference to remove.\n */',
+      },
+    ],
+  },
   {
     key: 'directoryPicker',
     summary: 'Abstract directory-picking service.',
@@ -383,8 +405,8 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.',
     methods: [
       {
-        signature: 'registerAdapter(providers: string[], adapter: LlmAdapter): () => void',
-        jsDoc: '/**\n * Register an adapter for the given provider routes. Throws `LlmError` with code\n * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).\n * Disposed with the fiber.\n * @param providers - every provider route this adapter should serve.\n * @param adapter - the adapter that streams calls for those providers.\n * @returns the disposer that unregisters all of them.\n */',
+        signature: 'registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle',
+        jsDoc: '/**\n * Register an adapter for the given provider routes. Throws `LlmError` with code\n * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).\n * Disposed with the fiber.\n * @param providers - every provider route this adapter should serve.\n * @param adapter - the adapter that streams calls for those providers.\n * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.\n */',
       },
       {
         signature: 'listProviders(): LlmProviderInfo[]',
@@ -748,6 +770,32 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'settings',
+    summary: 'Abstract settings service.',
+    methods: [
+      {
+        signature: 'register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>',
+        jsDoc: '/**\n * Register a namespace schema and receive its owner scope. The registration\n * is an effect on the calling plugin\'s fiber: disposing that fiber removes\n * the namespace and its observers. An invalid stored section fails the\n * registration itself — the earliest point where the schema can judge it.\n * @param ns - unique namespace; duplicate registration fails loud.\n * @param schema - schemastery schema resolving this namespace\'s value.\n * @param options - composition `base` layer and effect timing.\n * @returns the owner scope for reads, observation, and updates.\n */',
+      },
+      {
+        signature: 'describe(): SettingsDescriptor[]',
+        jsDoc: '/**\n * Describe every registered namespace for configuration surfaces.\n * @returns one descriptor per registered namespace, in registration order.\n */',
+      },
+      {
+        signature: 'get(ns: SettingsNamespace): unknown',
+        jsDoc: '/**\n * Read one registered namespace\'s resolved value.\n * @param ns - the namespace to read.\n * @returns the resolved value, or `undefined` while unregistered.\n */',
+      },
+      {
+        signature: 'async update(ns: SettingsNamespace, patch: object): Promise<void>',
+        jsDoc: '/**\n * Merge a patch into one registered namespace\'s user layer, validate the\n * resolved candidate, persist through the provider, then commit and emit.\n * A validation failure rejects before anything is persisted. Writes to one\n * namespace are serialized: concurrent updates apply in call order, each\n * merging over the previous write\'s committed section.\n * @param ns - the registered namespace to update.\n * @param patch - plain-object patch over the user section.\n */',
+      },
+      {
+        signature: 'async replace(ns: SettingsNamespace, section: object): Promise<void>',
+        jsDoc: '/**\n * Replace one registered namespace\'s user section wholesale, validate,\n * persist, then commit and emit. Keys absent from `section` fall back to the\n * composition `base` and schema defaults — this is the removal/reset path a\n * merge-only patch cannot express (`replace({})` re-inherits everything).\n * @param ns - the registered namespace to replace.\n * @param section - the complete next user section.\n */',
+      },
+    ],
+  },
   {
     key: 'skills',
     summary: 'Registry of skill providers.',
@@ -1245,6 +1293,13 @@ export const EVENT_API: readonly EventApiEntry[] = [
     jsDoc: '/**\n * A command was registered or unregistered. This is an unfiltered registry\n * notification because a global or scoped change may affect any UI view.\n * Observer failures are contained and cannot veto the registry mutation.\n * @mode emit\n */',
     summary: 'A command was registered or unregistered.',
   },
+  {
+    name: 'credentials/updated',
+    mode: 'emit',
+    signature: '\'credentials/updated\'(ref: CredentialRef): void',
+    jsDoc: '/**\n * Committed change to a provider-managed credential source: a `set`, an\n * `unset`, or an external edit observed in storage. Ambient\n * process-environment changes are not observable and never emit. Listener\n * failures are contained and logged — a sync throw and an async rejection\n * alike — without changing the committed operation\'s outcome, except\n * `INVARIANT`-coded failures, which rethrow after every listener ran;\n * that rethrow reaches the emitter only from synchronous listeners, so\n * invariant checks on this event must not be async functions.\n * @param ref - the reference whose stored value changed.\n * @mode emit\n */',
+    summary: 'Committed change to a provider-managed credential source: a `set`, an `unset`, or an external edit observed in storage.',
+  },
   {
     name: 'domain/changed',
     mode: 'emit',
@@ -1315,6 +1370,13 @@ export const EVENT_API: readonly EventApiEntry[] = [
     jsDoc: '/**\n * Awaited parallel durability checkpoint: every listener runs and the\n * caller awaits all of them, with no waterfall veto. Dispatch through\n * {@link SessionStore.flush}. Scope-filtered dispatch\n * (`@deepseek-ai/dsh-scope`) reuses the session\'s owner scope.\n * @param session - the session whose buffered events must reach durable storage.\n * @dshScopeScan unsupported\n * @mode parallel\n */',
     summary: 'Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto.',
   },
+  {
+    name: 'settings/updated',
+    mode: 'emit',
+    signature: '\'settings/updated\'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void',
+    jsDoc: '/**\n * Committed change to one registered namespace\'s resolved value. Emitted\n * after the provider persisted (for `update`) or published (`provider`)\n * the change; never emitted when the resolved value is deep-equal.\n * Listener failures are contained and logged — a sync throw and an async\n * rejection alike — except `INVARIANT`-coded failures, which rethrow\n * after every listener ran; that rethrow reaches the emitter only from\n * synchronous listeners, so invariant checks on this event must not be\n * async functions.\n * @param ns - the namespace whose resolved value changed.\n * @param next - the new resolved value.\n * @param prev - the previous resolved value.\n * @param source - whether the change entered through `update()` or the provider.\n * @mode emit\n */',
+    summary: 'Committed change to one registered namespace\'s resolved value.',
+  },
   {
     name: 'skills/change',
     mode: 'emit',
@@ -1459,6 +1521,10 @@ export const EVENT_API: readonly EventApiEntry[] = [
 
 /** Shapes of every exported type the SERVICE_API signatures reference (transitively), sorted by name. */
 export const TYPE_API: readonly TypeApiEntry[] = [
+  {
+    name: 'AdapterRegistrationHandle',
+    declaration: 'export interface AdapterRegistrationHandle {\n    (): void;\n    replace(providers: string[]): void;\n}',
+  },
   {
     name: 'Agent',
     declaration: 'export interface Agent {\n    readonly id: SessionId;\n    readonly options: AgentOptions;\n    readonly session: Session;\n    readonly status: AgentStatus;\n    readonly acceptsNextStep: boolean;\n    readonly ctx: Context;\n    send(message: UserMessage, options: SendOptions): void;\n    updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult;\n    cancel(cause: AgentCancelCause, options?: CancelOptions): void;\n    whenIdle(): Promise<void>;\n    followup(message: UserMessage): void;\n    steer(message: UserMessage): void;\n    inject(message: UserMessage): void;\n}',
@@ -1503,9 +1569,13 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'AskUserQuestionAnswerItem',
     declaration: 'export interface AskUserQuestionAnswerItem {\n    id: string;\n    selected: string[];\n    custom?: string;\n}',
   },
+  {
+    name: 'AskUserQuestionIntent',
+    declaration: 'export type AskUserQuestionIntent = {\n    kind: \'plan-review\';\n    approve: string;\n};',
+  },
   {
     name: 'AskUserQuestionItem',
-    declaration: 'export interface AskUserQuestionItem {\n    id: string;\n    question: string;\n    detail?: string;\n    header?: string;\n    options?: AskUserQuestionOption[];\n    multiSelect?: boolean;\n}',
+    declaration: 'export interface AskUserQuestionItem {\n    id: string;\n    question: string;\n    detail?: string;\n    header?: string;\n    options?: AskUserQuestionOption[];\n    multiSelect?: boolean;\n    intent?: AskUserQuestionIntent;\n}',
   },
   {
     name: 'AskUserQuestionOption',
@@ -1683,6 +1753,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'CreateSessionOptions',
     declaration: 'export interface CreateSessionOptions {\n    readonly seed?: readonly SessionEvent[];\n    readonly meta?: {\n        readonly cwd?: string;\n        readonly parentSession?: SessionId;\n        readonly createdAt?: number;\n        readonly seedLength?: number;\n        readonly delegationDepth?: number;\n    };\n}',
   },
+  {
+    name: 'CredentialInfo',
+    declaration: 'export interface CredentialInfo {\n    configured: boolean;\n    source?: string;\n    writable: boolean;\n}',
+  },
+  {
+    name: 'CredentialRef',
+    declaration: 'export type CredentialRef = Branded<\'CredentialRef\'>;',
+  },
   {
     name: 'DiffCallView',
     declaration: 'export interface DiffCallView {\n    card: \'diff\';\n    title: string;\n    diffs: FileDiff[];\n    locations?: FileLocation[];\n}',
@@ -2111,6 +2189,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'ResolvedAlwaysRetryPolicy',
     declaration: 'export interface ResolvedAlwaysRetryPolicy extends ResolvedRetryBackoff {\n    readonly mode: \'always\';\n}',
   },
+  {
+    name: 'ResolvedCredential',
+    declaration: 'export interface ResolvedCredential {\n    value: string;\n    source: string;\n}',
+  },
   {
     name: 'ResolvedNormalRetryPolicy',
     declaration: 'export interface ResolvedNormalRetryPolicy extends ResolvedRetryBackoff {\n    readonly mode: \'normal\';\n    readonly maxRetries: number;\n    readonly retryableCodes: readonly string[];\n}',
@@ -2371,6 +2453,26 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'SessionTitleUserMessage',
     declaration: 'export interface SessionTitleUserMessage {\n    readonly seq: number;\n    readonly text: string;\n}',
   },
+  {
+    name: 'SettingsApplies',
+    declaration: 'export type SettingsApplies = \'live\' | \'restart\';',
+  },
+  {
+    name: 'SettingsDescriptor',
+    declaration: 'export interface SettingsDescriptor {\n    ns: SettingsNamespace;\n    schema: unknown;\n    value: unknown;\n    applies: SettingsApplies;\n}',
+  },
+  {
+    name: 'SettingsNamespace',
+    declaration: 'export type SettingsNamespace = Branded<\'SettingsNamespace\'>;',
+  },
+  {
+    name: 'SettingsRegisterOptions',
+    declaration: 'export interface SettingsRegisterOptions<T> {\n    base?: Partial<T>;\n    applies?: SettingsApplies;\n}',
+  },
+  {
+    name: 'SettingsScope',
+    declaration: 'export interface SettingsScope<T> {\n    get(): T;\n    watch(callback: (next: T, prev: T) => void | Promise<void>): () => void;\n    update(patch: object): Promise<void>;\n    replace(section: object): Promise<void>;\n}',
+  },
   {
     name: 'SkillCandidate',
     declaration: 'export interface SkillCandidate extends SkillSummary {\n    readonly rank: number;\n    readonly locator: unknown;\n    readonly path?: string;\n    readonly metadata?: Readonly<Record<string, unknown>>;\n}',
@@ -2697,7 +2799,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'ToolResultView',
-    declaration: 'export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;',
+    declaration: 'export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | WebResultView;',
   },
   {
     name: 'ToolRunContext',
@@ -2803,6 +2905,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'WebFetchResult',
     declaration: 'export interface WebFetchResult {\n    readonly url: string;\n    readonly statusCode: number;\n    readonly body: WebFetchBody;\n    readonly truncated: boolean;\n}',
   },
+  {
+    name: 'WebFetchResultView',
+    declaration: 'export interface WebFetchResultView {\n    card: \'web\';\n    kind: \'fetch\';\n    title?: string;\n    url: string;\n    statusCode: number;\n    truncated: boolean;\n}',
+  },
+  {
+    name: 'WebResultView',
+    declaration: 'export type WebResultView = WebSearchResultView | WebFetchResultView;',
+  },
   {
     name: 'WebRoute',
     declaration: 'export interface WebRoute {\n    kind: WebRouteKind;\n    path: string;\n    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;\n}',
@@ -2823,10 +2933,18 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'WebSearchResult',
     declaration: 'export interface WebSearchResult {\n    readonly content?: string;\n    readonly sources: readonly WebSearchSource[];\n    readonly truncated: boolean;\n}',
   },
+  {
+    name: 'WebSearchResultView',
+    declaration: 'export interface WebSearchResultView {\n    card: \'web\';\n    kind: \'search\';\n    title?: string;\n    sources: WebSource[];\n    answer?: string;\n    truncated: boolean;\n}',
+  },
   {
     name: 'WebSearchSource',
     declaration: 'export interface WebSearchSource {\n    readonly url: string;\n    readonly title?: string;\n    readonly snippet?: string;\n    readonly publishedAt?: string;\n}',
   },
+  {
+    name: 'WebSource',
+    declaration: 'export interface WebSource {\n    url: string;\n    title?: string;\n    snippet?: string;\n    publishedAt?: string;\n}',
+  },
   {
     name: 'WorkflowMeta',
     declaration: 'export interface WorkflowMeta {\n    name: string;\n    description: string;\n    whenToUse?: string;\n    phases?: WorkflowPhase[];\n}',

packages/core/tools/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/tools/README.md
-README.md: e5adb153e77d7a2d8c4068b016194ab6abb6473e
-README.zh.md: c67a2f2ee4ac2a9d587c6efbf2b5c60d14fc58c2
+README.md: e7f395f8c1d6417db856e590f5267cf6887e4d12
+README.zh.md: acb4c047bf86e36c828882ff751d4be1f627f99e

packages/core/tools/README.md

@@ -108,7 +108,7 @@ Optional `isConcurrencySafe(args)` receives typed, softly validated arguments. E
 Tools optionally own pure `presentCall()` and `presentResult()` render intents, so UIs do not special-case tool names:
 
 - Call views are `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`, `{ card: 'terminal', title, description?, cwd? }`, or `{ card: 'diff', title, diffs, locations? }`.
-- Result views are `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }`, or `{ card: 'diff', title?, diffs }`.
+- Result views are `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }`, `{ card: 'diff', title?, diffs }`, or `{ card: 'web', kind: 'search' | 'fetch', title?, … }` (a completed web retrieval; the `kind` arms carry the structured search sources or the fetch summary, and a UI without the `web` capability falls back to the raw result content).
 
 Returning `undefined` selects generic fallback. Presenters depend only on their arguments and the durable result because UIs call them during live streaming and log replay. `output.presentationMeta(args, value)` derives JSON metadata for direct surface calls; that metadata persists with `tool/result` and returns to `presentResult`, while the canonical value itself remains execution-local and is never replayed. Nested Code dispatches do not compute metadata. `defineTool` soft-validates older logged arguments and falls back instead of crashing replay. `dsh-tool-bash` and `dsh-tool-fs` are the reference implementations; the [canonical-output Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md) owns the value/presentation split and the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) owns card vocabulary.
 

packages/core/tools/README.zh.md

@@ -108,7 +108,7 @@ ctx.tools.register(defineTool({
 工具可以选择拥有纯 `presentCall()` 和 `presentResult()` 呈现意图，使 UI 无需特殊处理工具名称：
 
 - 调用视图为 `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`、`{ card: 'terminal', title, description?, cwd? }` 或 `{ card: 'diff', title, diffs, locations? }`。
-- 结果视图为 `{ card: 'generic', title?, content? }`、`{ card: 'terminal', title?, output?, exitCode?, signal? }` 或 `{ card: 'diff', title?, diffs }`。
+- 结果视图为 `{ card: 'generic', title?, content? }`、`{ card: 'terminal', title?, output?, exitCode?, signal? }`、`{ card: 'diff', title?, diffs }` 或 `{ card: 'web', kind: 'search' | 'fetch', title?, … }`（已完成的 web 检索；`kind` 各分支携带结构化的搜索来源或抓取摘要，不具备 `web` 能力的 UI 回退到原始结果内容）。
 
 返回 `undefined` 会选择通用回退。呈现器只依赖其参数和持久结果，因为 UI 会在实时流式输出和日志回放期间调用它们。`output.presentationMeta(args, value)` 为直接接口调用派生 JSON 元数据；该元数据随 `tool/result` 持久化并传回 `presentResult`，而规范值本身仍只存在于执行局部，绝不会回放。嵌套 Code 分发不会计算元数据。`defineTool` 会软验证较旧的日志参数并回退，而不会使回放崩溃。`dsh-tool-bash` 与 `dsh-tool-fs` 是参考实现；[规范输出 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md) 规定值／呈现拆分，[呈现意图 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) 规定卡片词汇。
 

packages/core/tools/src/index.ts

@@ -82,6 +82,10 @@ export type {
   GenericResultView,
   TerminalResultView,
   DiffResultView,
+  WebResultView,
+  WebSearchResultView,
+  WebFetchResultView,
+  WebSource,
 } from './presentation.ts'
 
 declare module 'cordis' {

packages/core/tools/src/presentation.ts

@@ -125,7 +125,7 @@ export interface DiffCallView {
  * `ToolDefinition.presentResult`; omitting the method keeps the pending
  * title and renders the raw result content.
  */
-export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView
+export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | WebResultView
 
 /**
  * The default completed card: an optional replacement title and reformatted
@@ -176,3 +176,84 @@ export interface DiffResultView {
   /** The change to show, in file order — applied contextual hunks, or a whole-file diff when there is no before-image. */
   diffs: FileDiff[]
 }
+
+/**
+ * One citeable source in a completed {@link WebSearchResultView}, the faithful
+ * projection of one web-search source. The presentation projection of `dsh-web`'s
+ * `WebSearchSource`: that seam type is the authoritative shape (core cannot depend
+ * on the web seam, so the two are declared separately and MUST evolve together).
+ * A web tool projects this shape through `output.presentationMeta` because the
+ * render text cannot losslessly carry it (see the web-result-card Agent Note); its
+ * `presentResult` reads it back.
+ */
+export interface WebSource {
+  /** The source URL. */
+  url: string
+  /** The source title, when the provider returned one. */
+  title?: string
+  /** A short excerpt or summary, when the provider returned one. */
+  snippet?: string
+  /** Publication/crawl timestamp as a provider-supplied ISO-8601 string, when present. */
+  publishedAt?: string
+}
+
+/**
+ * A completed web retrieval rendered as a structured card by a capable UI. Set
+ * by a web tool whose call retrieves from the web (`web_search`, `web_fetch`).
+ * One `kind`-tagged union carries both shapes because both are web retrieval and
+ * a UI renders them with one component family; a UI switches on `kind`. An
+ * incapable UI falls back to the raw `tool/result` content (this view carries no
+ * `content` copy — see the web-result-card Agent Note). This is the result-time
+ * analogue of the `web_search`/`web_fetch` calls' generic call views
+ * (`kind: 'search'`/`'fetch'`); those tools keep their generic pending card and
+ * add only this completed card.
+ *
+ * The `kind` field here is this union's own discriminant, NOT a
+ * {@link ToolCallKind}: the two values deliberately match the tools' pending
+ * `ToolCallKind` (`'search'`/`'fetch'`) so a call and its result read as one
+ * category, but a new arm is a union edit plus a consumer branch, not any
+ * arbitrary `ToolCallKind` value.
+ */
+export type WebResultView = WebSearchResultView | WebFetchResultView
+
+/**
+ * The completed state of a `web_search` call: the structured sources the model
+ * cited, an optional provider answer, and whether the source list was cut to the
+ * result cap. A capable UI renders the sources as a citation list; a UI without
+ * the `web` capability falls back to the raw `tool/result` content.
+ */
+export interface WebSearchResultView {
+  card: 'web'
+  kind: 'search'
+  /** Replacement title for the completed call. Omit to keep the pending-state title. */
+  title?: string
+  /** The faithful, structured sources — the field render text cannot losslessly carry. */
+  sources: WebSource[]
+  /** The provider-generated answer text, when any. */
+  answer?: string
+  /** True when the seam cut the source list to honor the result cap. */
+  truncated: boolean
+}
+
+/**
+ * The completed state of a `web_fetch` call: the fetched URL, its HTTP status,
+ * and whether the content was cut. The body itself is already markdown in the
+ * raw `tool/result` content, so this card carries only the retrieval summary and
+ * a UI without the `web` capability falls back to that content.
+ */
+export interface WebFetchResultView {
+  card: 'web'
+  kind: 'fetch'
+  /** Replacement title for the completed call. Omit to keep the pending-state title. */
+  title?: string
+  /** The final URL after allowed redirects. */
+  url: string
+  /** HTTP status code of the fetched response. */
+  statusCode: number
+  /**
+   * True when the provider capped the decoded body, or the output cap or a
+   * pre-conversion source cut trimmed the rendered text (the effective
+   * truncation the model-facing text also reflects).
+   */
+  truncated: boolean
+}

packages/credentials/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/credentials/README.md
+README.md: 1d450cbeef84750fa57ca0151563c496aed0ce12
+README.zh.md: 843230c3cebf35f234d3ad812165b16ea734678b

packages/credentials/README.md

@@ -0,0 +1,14 @@
+# credentials/
+
+English | [中文](README.zh.md)
+
+The credential capability seam, as three-package shape dictates (interface / implementation / consumers):
+
+| Package | Role |
+|---|---|
+| [`credentials/`](credentials/README.md) | Abstract `ctx.credentials`: branded `CredentialRef` references, per-operation `resolve`, UI-safe `describe`, fail-loud `set`/`unset`, the `credentials/updated` commit event |
+| [`credentials-local/`](credentials-local/README.md) | File/environment provider: the live process environment (read-only, wins) layered over `$DSH_HOME/.env` (writable, byte-preserving line edits, hot-reloaded) |
+
+Configuration files carry *references* to secrets (`apiKeyEnv: DEEPSEEK_API_KEY`), never the secrets: the settings document stays safe to sync and render, and rotating a value touches no configuration. The LLM adapters are the first consumers — they resolve their reference once per model request, which is what makes a key stored moments ago reach the very next request without restarting anything.
+
+The seam shape leaves room for keyring-, helper-command-, and KMS-backed providers.

packages/credentials/README.zh.md

@@ -0,0 +1,14 @@
+# credentials/
+
+[English](README.md) | 中文
+
+凭据能力 seam，按三包形态的要求组织（接口／实现／消费方）：
+
+| 包 | 角色 |
+|---|---|
+| [`credentials/`](credentials/README.md) | 抽象 `ctx.credentials`：品牌化 `CredentialRef` 引用、按操作 `resolve`、对 UI 安全的 `describe`、响亮失败的 `set`/`unset`，以及 `credentials/updated` 提交事件 |
+| [`credentials-local/`](credentials-local/README.md) | 文件／环境 provider：活跃进程环境（只读、优先）叠加在 `$DSH_HOME/.env`（可写、保字节行级编辑、热重载）之上 |
+
+配置文件携带的是对机密的*引用*（`apiKeyEnv: DEEPSEEK_API_KEY`），绝不携带机密本身：设置文档可以放心同步与渲染，轮换值不触碰任何配置。LLM 适配器是第一批消费方——它们每次模型请求解析一次引用，正因如此，片刻前存入的密钥无需重启任何组件即可作用于紧随其后的下一次请求。
+
+seam 形状为 keyring、辅助命令与 KMS 后端的 provider 留有余地。

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

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/credentials/credentials-local/README.md
+README.md: 126140b10719dc6f7bc458a118ba1feb1f440270
+README.zh.md: c22575115ab44b5e86a847ffe8f1fa1a795b580d

packages/credentials/credentials-local/README.md

@@ -0,0 +1,54 @@
+# dsh-credentials-local
+
+English | [中文](README.zh.md)
+
+File-backed [credentials](../credentials/README.md) provider: two layers, one honest precedence.
+
+| Layer | Source id | Writable | Wins |
+|---|---|---|---|
+| Live process environment | `env` | no | always |
+| `$DSH_HOME/.env` document | `file` | yes (`set`/`unset`) | otherwise |
+
+The environment wins because a launch-time override (`DEEPSEEK_API_KEY=… dsh`, CI secrets, a dev shell sourcing the repo `.env`) is operator intent for this run — and because it cannot be edited from inside, it must be *visibly* read-only: `describe()` reports `source: 'env', writable: false`, and `set`/`unset` reject instead of writing a change the reader would never see. Resolution reads `process.env` live and never writes it back.
+
+## Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `path` | `<harness home>/.env` | Credentials document location. |
+| `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home used when `path` is omitted. |
+| `watch` | `true` | Hot-publish external edits. |
+| `debounceMs` | `100` | Watcher write-settle window. |
+
+## The document
+
+dotenv format, parsed with `dotenv` and edited by a physical-line editor that preserves every byte it does not own: `set` rewrites the first assignment of its key in place with that line's own ending (dropping later duplicates, which dotenv's last-wins reading would otherwise let override the edit), `unset` removes only the owning line, and comments, unrelated lines, CRLF endings, and the continuation lines of another key's quoted multi-line value all survive verbatim. Every write first re-reads the document under the cross-process writer lock of [`dsh-atomic-write`](../../util/atomic-write/README.md) and publishes anything it had not observed, then commits atomically with mode `0600` under an owner-only (`0700`) directory — so a concurrent writer or an external edit inside the watcher's debounce window is folded in rather than overwritten.
+
+Values are rendered in the narrowest style dotenv reads back verbatim — bare, then single-quoted (fully literal), then double-quoted (only without backslashes, which double-quote reading expands). A value no style can represent, and any entry that already spans multiple physical lines, fails loud instead of being corrupted silently. An empty stored value is absent, per the seam rule.
+
+## Hot reload
+
+External edits publish `credentials/updated` per changed reference after the snapshot is replaced **wholesale** — an entry deleted on disk never lingers in memory. The provider's own writes are recognized by content and publish exactly their one commit event. An unreadable document at runtime keeps the last good snapshot and warns; an absent file is an empty store; an unreadable file at boot fails loud. Keys that are not POSIX identifiers are preserved file content the seam cannot address.
+
+## Security boundary
+
+The document is `0600` under a `0700` directory, which stops other OS users — **not** the model. Tool processes (bash, the filesystem tools) run as the same user, so under the shipped `danger-full-access` default they can read this file exactly like any other file the user owns, and no sandbox mode singles it out. What the harness does hold to is narrower: it never hands the model a resolved path to the document, and never loads it into the process environment (see [app-boot's Personal config](../../ui/app-boot/README.md#personal-config)), so reaching the value takes a deliberate read of a path the agent was not given.
+
+That is discretion, not a boundary. A deployment that must keep provider keys away from its own agent cannot get there with file permissions; an OS-keychain provider — a store the model's processes cannot read at all — is the deferred answer and belongs beside this provider as a sibling package.
+
+## Model Experience
+
+Indirectly, through the consuming LLM adapters: stored values authorize their provider requests, and the adapter owns every model-visible surface.
+
+#### KV Cache effect
+
+No direct invalidation; credentials never enter a request prefix.
+
+## Known Limitations and Deferred Work
+
+- **Multi-line entries refuse `set`/`unset`** — the line editor will not rewrite an entry it would corrupt; `describe` reports them `writable: false` and edits must go to the file directly.
+- **Same-reference concurrent writes are last-write-wins** — the writer lock and the read-modify-write keep concurrent writers from dropping each other's entries, but two writers editing one reference still resolve to the later write; there is no revision check.
+- **A same-UID process can read the document** — see [Security boundary](#security-boundary): only a confining sandbox mode denies it, and an OS-keychain provider is deferred.
+- **Unrepresentable values fail loud** — control characters, or a mix of both quote styles with backslashes, cannot round-trip the dotenv line format.
+- **Environment changes are invisible** — `process.env` is read live per resolution, but no event can announce a change there.
+- **Atomic, not crash-durable** — inherited from `dsh-atomic-write`; the store re-reads on boot.

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

@@ -0,0 +1,54 @@
+# dsh-credentials-local
+
+[English](README.md) | 中文
+
+文件型[凭据](../credentials/README.md) provider：两层来源，一条诚实的优先级。
+
+| 层 | 来源 id | 可写 | 优先 |
+|---|---|---|---|
+| 活跃进程环境 | `env` | 否 | 恒定优先 |
+| `$DSH_HOME/.env` 文档 | `file` | 是（`set`/`unset`） | 其余情况 |
+
+环境优先，因为启动时覆盖（`DEEPSEEK_API_KEY=… dsh`、CI 机密、加载了仓库 `.env` 的开发 shell）代表本次运行的操作者意图——而它无法从进程内部修改，就必须*可见地*只读：`describe()` 报告 `source: 'env', writable: false`，`set`/`unset` 直接拒绝，而不是写下一个读取方永远看不到的变更。解析实时读取 `process.env`，绝不写回。
+
+## 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `path` | `<harness home>/.env` | 凭据文档位置。 |
+| `dshHome` | `$DSH_HOME` 或 `~/.dsh` | `path` 缺省时使用的 harness home。 |
+| `watch` | `true` | 热发布外部编辑。 |
+| `debounceMs` | `100` | watcher 写入稳定窗口。 |
+
+## 文档本身
+
+dotenv 格式，用 `dotenv` 解析；写回用物理行级编辑器，保留一切不属于本次编辑的字节：`set` 原位改写该键的第一条赋值行、沿用该行自身的行尾（丢弃后续重复行——dotenv 按最后一条生效，重复行会反过来覆盖这次编辑），`unset` 只删除所属行，注释、无关行、CRLF 行尾，以及另一个键的引号多行值的续行，都逐字保留。每次写入都先在 [`dsh-atomic-write`](../../util/atomic-write/README.md) 的跨进程写锁下重读文档、把此前未观察到的一切发布出去，再在仅属主可访问（`0700`）的目录下以 `0600` 权限原子提交——因此并发写入者、或落在 watcher 防抖窗口内的外部编辑会被并入，而不是被覆盖。
+
+值按 dotenv 能逐字读回的最窄样式渲染——裸值，其次单引号（完全字面），再次双引号（仅限无反斜杠，双引号读取会展开转义）。任何样式都无法表示的值，以及已经跨越多个物理行的条目，都会响亮失败而不是被静默破坏。空的存储值等于不存在（seam 规则）。
+
+## 热重载
+
+外部编辑在快照**整体替换**后按变更引用逐个发布 `credentials/updated`——磁盘上删掉的条目绝不在内存滞留。provider 自己的写入按内容识别，只发布属于该次提交的一个事件。运行期文档不可读时保留最后可用快照并告警；文件不存在即空存储；启动时不可读则响亮失败。非 POSIX 标识符的键属于被保留的文件内容，seam 无法寻址。
+
+## 安全边界
+
+文档在 `0700` 目录下以 `0600` 权限存放，这挡得住其他 OS 用户，**挡不住**模型。工具进程（bash、文件系统工具）以同一用户身份运行，因此在出厂默认的 `danger-full-access` 下，它们读这个文件与读该用户拥有的任何其他文件毫无二致，也没有任何沙箱模式会把它单独挑出来。harness 真正守住的更窄：它绝不把该文档的解析后路径交给模型，也绝不把它载入进程环境（见 [app-boot 的个人配置](../../ui/app-boot/README.md#personal-config)），因此要拿到这个值，需要刻意去读一条并未交给 agent 的路径。
+
+这是审慎，不是边界。必须让提供方密钥远离自身 agent 的部署无法靠文件权限做到；OS 钥匙串 provider——一个模型的进程根本读不到的存储——才是延后的答案，它应当作为平级包与本 provider 并列。
+
+## Model Experience
+
+经由消费它的 LLM 适配器间接生效：存储的值为适配器的提供方请求授权，每个模型可见面都归适配器所有。
+
+#### KV Cache effect
+
+无直接失效；凭据绝不进入请求前缀。
+
+## Known Limitations and Deferred Work
+
+- **多行条目拒绝 `set`/`unset`**——行编辑器不改写会被它破坏的条目；`describe` 把它们报为 `writable: false`，编辑必须直接落到文件上。
+- **同一引用的并发写入是后写胜出**——写锁加读-改-写让并发写入者不会丢掉彼此的条目，但两个写入者编辑同一个引用时仍以较后的写入为准；没有修订检查。
+- **同 UID 进程可以读取该文档**——见[安全边界](#security-boundary)：只有受限沙箱模式会拒绝它，OS 钥匙串 provider 仍是延后项。
+- **无法表示的值响亮失败**——控制字符，或同时混用两种引号又含反斜杠的值，无法在 dotenv 行格式中往返。
+- **环境变化不可见**——每次解析实时读取 `process.env`，但那里的变化不可能发出事件。
+- **原子但不保证崩溃持久**——继承自 `dsh-atomic-write`；存储在启动时重新读取。

packages/credentials/credentials-local/package.json

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

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

@@ -0,0 +1,464 @@
+/**
+ * File-backed credentials provider layering the live process environment over
+ * a `$DSH_HOME/.env` document. The environment is authoritative and read-only
+ * (a launch-time override must win, and must be visibly read-only rather than
+ * silently shadow writes); the file is the provider-managed writable source:
+ * every write re-reads the document under a cross-process writer lock before
+ * rewriting only its own line — preserving every other byte, physical line
+ * endings and quoted multi-line values included — external edits hot-publish
+ * through the seam, and each reload replaces the snapshot wholesale so a
+ * deleted entry never lingers in memory.
+ * @module @deepseek-ai/dsh-credentials-local
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import { watch as chokidarWatch } from 'chokidar'
+import { mkdir, readFile } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { parse } from 'dotenv'
+import { withFileLock, writeFileAtomic } from '@deepseek-ai/dsh-atomic-write'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { Credentials, credentialRef } from '@deepseek-ai/dsh-credentials'
+import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepseek-ai/dsh-credentials'
+
+/** Plugin config: file location and hot-reload behavior. */
+export interface Config {
+  /** Credentials document path; defaults to `.env` under the harness home. */
+  path?: string
+  /** Harness home used when `path` is omitted; defaults to `$DSH_HOME` or `~/.dsh`. */
+  dshHome?: string
+  /** Watch the document and hot-publish external edits; defaults to true. */
+  watch?: boolean
+  /** Watcher write-settle window in milliseconds; defaults to 100. */
+  debounceMs?: number
+}
+
+/** Fully resolved provider parameters; defaulting happens here, never inline. */
+interface ResolvedSpec {
+  filename: string
+  watch: boolean
+  debounceMs: number
+}
+
+/**
+ * Resolve the runtime spec from plugin config: an explicit `path` wins,
+ * otherwise the document lives at `<harness home>/.env`.
+ * @param config - raw plugin config.
+ * @returns the resolved file location and watch behavior.
+ */
+export function resolveSpec(config: Config): ResolvedSpec {
+  return {
+    filename: resolve(config.path ?? join(resolveDshHome(config.dshHome), '.env')),
+    watch: config.watch ?? true,
+    debounceMs: config.debounceMs ?? 100,
+  }
+}
+
+/** Whether a filesystem error means absence; every non-ENOENT failure must surface. */
+function isENOENT(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | null)?.code === 'ENOENT'
+}
+
+/** Values that survive a dotenv round-trip without quoting. */
+const BARE_VALUE = /^[A-Za-z0-9_@%+:,./-]+$/
+
+/** Whether a value contains C0 control characters (newlines included) no dotenv style reads back. */
+function hasControlCharacters(value: string): boolean {
+  for (const char of value) {
+    if (char.charCodeAt(0) < 0x20) return true
+  }
+  return false
+}
+
+/**
+ * Render one `KEY=value` line in the narrowest style dotenv reads back
+ * verbatim: bare, then single quotes (fully literal), then double quotes
+ * (safe only without backslashes, which double-quote reading expands).
+ * A value no style can represent fails loud instead of corrupting silently.
+ */
+function renderLine(ref: CredentialRef, value: string): string {
+  if (BARE_VALUE.test(value)) return `${ref}=${value}`
+  if (hasControlCharacters(value)) {
+    throw new Error(`credentials-local: the value for "${ref}" contains control characters the .env line format cannot represent`)
+  }
+  if (!value.includes('\'')) return `${ref}='${value}'`
+  if (!value.includes('"') && !value.includes('\\')) return `${ref}="${value}"`
+  throw new Error(`credentials-local: the value for "${ref}" mixes quoting no .env style can represent; edit the file directly`)
+}
+
+/** Split text into physical lines with their terminators attached. */
+function physicalLines(text: string): string[] {
+  return text.length === 0 ? [] : text.split(/(?<=\n)/)
+}
+
+/** One physical line's content without its terminator. */
+function lineContent(line: string): string {
+  if (line.endsWith('\r\n')) return line.slice(0, -2)
+  if (line.endsWith('\n')) return line.slice(0, -1)
+  return line
+}
+
+/** One physical line's terminator (empty on a final unterminated line). */
+function lineTerminator(line: string): string {
+  return line.slice(lineContent(line).length)
+}
+
+/** An assignment line: optional export, a POSIX identifier, `=`, the value part. */
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/
+
+/** Quote characters dotenv reads across physical lines. */
+const MULTILINE_QUOTES = ['\'', '"', '`']
+
+/**
+ * The quote character an assignment's value part opens without closing on its
+ * own line — the following physical lines are that value's continuation, not
+ * assignments — or `undefined` for a single-line value.
+ */
+function opensMultiline(valuePart: string): string | undefined {
+  const trimmed = valuePart.trimStart()
+  const quote = trimmed[0]
+  if (quote === undefined || !MULTILINE_QUOTES.includes(quote)) return undefined
+  const rest = trimmed.slice(1)
+  const body = quote === '"' ? rest.replaceAll('\\"', '') : rest
+  return body.includes(quote) ? undefined : quote
+}
+
+/** Whether a continuation line closes the given quote. */
+function closesQuote(content: string, quote: string): boolean {
+  const body = quote === '"' ? content.replaceAll('\\"', '') : content
+  return body.includes(quote)
+}
+
+/**
+ * Replace, insert, or delete one reference's assignment while preserving
+ * every other byte: untouched lines keep their exact content and terminators
+ * (CRLF included), and the physical lines inside another key's quoted
+ * multi-line value are never mistaken for assignments. The first matching
+ * assignment is rewritten in place with its own line ending; later duplicates
+ * drop (dotenv reads the last one, so a surviving duplicate would override
+ * the edit); an insert appends in the document's dominant ending style.
+ */
+function upsertLine(text: string | undefined, ref: CredentialRef, rendered: string | undefined): string {
+  const lines = physicalLines(text ?? '')
+  const dominant = lines.some(line => line.endsWith('\r\n')) ? '\r\n' : '\n'
+  const out: string[] = []
+  let placed = false
+  let pendingQuote: string | undefined
+  for (const line of lines) {
+    const content = lineContent(line)
+    if (pendingQuote !== undefined) {
+      // Inside a quoted multi-line value: never an assignment, always kept.
+      if (closesQuote(content, pendingQuote)) pendingQuote = undefined
+      out.push(line)
+      continue
+    }
+    const match = ASSIGNMENT.exec(content)
+    if (match === null) {
+      out.push(line)
+      continue
+    }
+    const [, key, valuePart] = match
+    if (key !== ref) {
+      /* v8 ignore next -- the value group is `(.*)`, which always participates; the fallback only satisfies noUncheckedIndexedAccess */
+      pendingQuote = opensMultiline(valuePart ?? '')
+      out.push(line)
+      continue
+    }
+    // The write path refuses multi-line targets before rendering, so the
+    // matched assignment is single-line and drops or rewrites wholesale.
+    if (rendered !== undefined && !placed) {
+      out.push(`${rendered}${lineTerminator(line) === '' ? dominant : lineTerminator(line)}`)
+      placed = true
+    }
+  }
+  if (rendered !== undefined && !placed) {
+    const last = out[out.length - 1]
+    if (last !== undefined && lineTerminator(last) === '') {
+      out[out.length - 1] = `${last}${dominant}`
+    }
+    out.push(`${rendered}${dominant}`)
+  }
+  return out.join('')
+}
+
+/** File-backed credentials provider (`$DSH_HOME/.env`). */
+export class CredentialsLocal extends Credentials {
+  /* jscpd:ignore-start -- deliberate config-surface and lifecycle symmetry with
+     settings-local (prefer symmetry for parallel values); extracting the shared
+     shape would couple the two providers' teardown semantics across packages. */
+  static Config: z<Config> = z.object({
+    path: z.string(),
+    dshHome: z.string(),
+    watch: z.boolean().default(true),
+    debounceMs: z.number().min(0).default(100),
+  })
+
+  private readonly spec: ResolvedSpec
+  /**
+   * Raw text of the last read or persisted document; `undefined` while the
+   * file is absent. Watcher events whose content equals this cache are no-ops,
+   * which is also the self-write suppression.
+   */
+  private text: string | undefined
+  /** Parsed document snapshot; replaced wholesale on every reload. */
+  private values = new Map<string, string>()
+  /**
+   * Single exclusive operation chain: watcher reloads and line edits run one
+   * at a time in queue order (settled tail), so an edit can never render from
+   * text a concurrent reload is busy replacing.
+   */
+  private operations: Promise<void> = Promise.resolve()
+  /** Set at dispose: refuse new writes and let in-flight work no-op. */
+  private closed = false
+
+  /** Opaque read of {@link closed}: control flow cannot narrow it across awaits. */
+  private isClosed(): boolean {
+    return this.closed
+  }
+  /* jscpd:ignore-end */
+
+  constructor(ctx: Context, public config: Config) {
+    super(ctx)
+    // Programmatic construction may bypass Schemastery normalization; resolve
+    // the same defaults in one explicit step either way.
+    this.spec = resolveSpec(config)
+  }
+
+  async* [Service.init](): AsyncGenerator<() => Promise<void> | void, void, void> {
+    yield async () => {
+      // Drain: refuse new operations, then settle the queued ones so disposal
+      // completes only once storage is quiescent.
+      this.closed = true
+      await this.operations
+    }
+    await this.loadInitial()
+    if (!this.spec.watch) return
+    /* jscpd:ignore-start -- same watcher discipline as settings-local by design:
+       the serialized-refresh and quiesce-on-dispose shape is the reviewed
+       lifecycle contract, not accidental repetition. */
+    const watcher = chokidarWatch(this.spec.filename, {
+      ignoreInitial: true,
+      awaitWriteFinish: {
+        stabilityThreshold: this.spec.debounceMs,
+        pollInterval: Math.max(1, Math.min(this.spec.debounceMs, 10)),
+      },
+    })
+    watcher.on('all', () => {
+      if (this.closed) return
+      this.queueRefresh()
+    })
+    watcher.on('ready', () => {
+      // The initial load raced the watcher's own setup: a change written
+      // between that read and the watcher becoming active never fires an
+      // event. One reconcile at ready closes the gap.
+      if (this.closed) return
+      this.queueRefresh()
+    })
+    watcher.on('error', (error) => {
+      this.ctx.logger.warn('credentials-local: watcher error on %s', this.spec.filename)
+      this.ctx.logger.warn(error)
+    })
+    yield async () => {
+      // Quiesce: stop accepting events, close the watcher, then wait out any
+      // queued or in-flight operation so nothing publishes after disposal.
+      this.closed = true
+      await watcher.close()
+      await this.operations
+    }
+    /* jscpd:ignore-end */
+  }
+
+  override resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined> {
+    const env = process.env[ref]
+    if (env !== undefined && env.length > 0) return Promise.resolve({ value: env, source: 'env' })
+    const stored = this.values.get(ref)
+    if (stored !== undefined && stored.length > 0) return Promise.resolve({ value: stored, source: 'file' })
+    return Promise.resolve(undefined)
+  }
+
+  override describe(ref: CredentialRef): Promise<CredentialInfo> {
+    const env = process.env[ref]
+    if (env !== undefined && env.length > 0) {
+      return Promise.resolve({ configured: true, source: 'env', writable: false })
+    }
+    const stored = this.values.get(ref)
+    if (stored !== undefined && stored.length > 0) {
+      // A quoted multi-line value resolves fine but the line editor refuses to
+      // rewrite it, so writability must say what set() would actually do.
+      return Promise.resolve({ configured: true, source: 'file', writable: !stored.includes('\n') })
+    }
+    return Promise.resolve({ configured: false, writable: true })
+  }
+
+  override async set(ref: CredentialRef, value: string): Promise<void> {
+    if (value.length === 0) {
+      throw new Error(`credentials-local: an empty value cannot be stored for "${ref}"; use unset`)
+    }
+    await this.write(ref, value)
+  }
+
+  override async unset(ref: CredentialRef): Promise<void> {
+    await this.write(ref, undefined)
+  }
+
+  /* jscpd:ignore-start -- the operation-chain and reload lifecycle is the same
+     reviewed contract as settings-local, deliberately mirrored (prefer symmetry
+     for parallel values); the two providers own different documents and
+     failure policies, so extracting the shape would couple their teardown
+     semantics across packages for a handful of lines. */
+  /** Queue one exclusive document operation behind every earlier one. */
+  private enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const task = this.operations.then(operation)
+    this.operations = task.then(() => undefined, () => undefined)
+    return task
+  }
+
+  /** Queue a reload; only an invariant violation escaping the fan-out can reject it. */
+  private queueRefresh(): void {
+    void this.enqueue(() => this.refresh()).catch((error: unknown) => {
+      // Only an invariant violation escaping the update fan-out can reject a
+      // refresh; keep the operation queue alive and surface it as an error so
+      // one poisoned commit cannot silently end hot reloading forever.
+      this.ctx.logger.error('credentials-local: reload commit failed at %s', this.spec.filename)
+      this.ctx.logger.error(error)
+    })
+  }
+  /* jscpd:ignore-end */
+
+  /** Queue one line edit; entry checks reject early, the queue re-judges them at run time. */
+  private async write(ref: CredentialRef, value: string | undefined): Promise<void> {
+    const verb = value === undefined ? 'unset' : 'set'
+    if (this.isClosed()) {
+      throw new Error(`credentials-local is disposed: cannot ${verb} "${ref}"`)
+    }
+    this.assertUnshadowed(ref, verb)
+    return this.enqueue(async () => {
+      if (this.isClosed()) {
+        throw new Error(`credentials-local was disposed before the queued "${ref}" ${verb} ran`)
+      }
+      // Re-judged at run time: the environment may have changed while queued.
+      this.assertUnshadowed(ref, verb)
+      // The writer lock's exclusive create needs the parent to exist; 0700
+      // because the harness home holds user-private data.
+      await mkdir(dirname(this.spec.filename), { recursive: true, mode: 0o700 })
+      await withFileLock(this.spec.filename, async () => {
+        // Read-modify-write: fold in any on-disk state this process has not
+        // observed yet — an external edit still inside the watcher debounce
+        // window, a change the watcher missed, or another process's write —
+        // so the line edit below can never resurrect a stale document.
+        await this.reconcileFromDisk()
+        const existing = this.values.get(ref)
+        if (value === undefined && existing === undefined) return
+        if (existing !== undefined && existing.includes('\n')) {
+          throw new Error(
+            `credentials-local: "${ref}" is a multi-line entry this line editor would corrupt; edit ${this.spec.filename} directly`,
+          )
+        }
+        const nextText = upsertLine(this.text, ref, value === undefined ? undefined : renderLine(ref, value))
+        // 0600: a document holding secrets is never world-readable.
+        await writeFileAtomic(this.spec.filename, nextText, { mode: 0o600, dirMode: 0o700 })
+        this.text = nextText
+        if (value === undefined) this.values.delete(ref)
+        else this.values.set(ref, value)
+        // After the commit: a broken observer must never make the durable
+        // write look failed (an INVARIANT failure still rethrows).
+        this.notifyUpdated(ref)
+      }, {
+        onStaleBreak: (lockPath) => {
+          this.ctx.logger.warn('credentials-local: breaking a stale writer lock at %s', lockPath)
+        },
+      })
+    })
+  }
+
+  /** Reject a write the live environment would shadow into apparent no-effect. */
+  private assertUnshadowed(ref: CredentialRef, verb: 'set' | 'unset'): void {
+    const env = process.env[ref]
+    if (env !== undefined && env.length > 0) {
+      throw new Error(
+        `credentials-local: "${ref}" is supplied read-only by the process environment, so ${verb} would be`
+        + ' shadowed; change the launching environment instead',
+      )
+    }
+  }
+
+  /** Boot read: an absent file is an empty store; any other failure is loud. */
+  private async loadInitial(): Promise<void> {
+    let text: string
+    try {
+      text = await readFile(this.spec.filename, 'utf8')
+    } catch (error) {
+      if (!isENOENT(error)) throw error
+      return
+    }
+    this.text = text
+    this.values = new Map(Object.entries(parse(text)))
+  }
+
+  /* jscpd:ignore-start -- same deliberate mirror of settings-local's reload and
+     reconcile policy: warn-and-keep on a reload, throw on a write, invariant
+     failures propagate. */
+  /**
+   * Re-read the document after a watcher event. Unchanged content (including
+   * this provider's own writes) is a no-op; an unreadable document keeps the
+   * last good snapshot and warns — a live hot-reload must never take the
+   * process down. An invariant violation escaping the fan-out is not a reload
+   * failure and propagates to the queue's error surface.
+   */
+  private async refresh(): Promise<void> {
+    if (this.closed) return
+    try {
+      await this.reconcileFromDisk()
+    } catch (error) {
+      if ((error as { code?: unknown } | null)?.code === 'INVARIANT') throw error
+      this.ctx.logger.warn('credentials-local: reload failed at %s; keeping the last good document', this.spec.filename)
+      this.ctx.logger.warn(error)
+    }
+  }
+
+  /**
+   * Compare the on-disk text against the cache and publish any difference
+   * into the seam. Absence publishes the empty store; an unreadable file
+   * throws, so each caller picks its policy — a reload warns and keeps the
+   * last good snapshot, a write fails loud. dotenv parsing is lenient by
+   * design and cannot fail.
+   */
+  private async reconcileFromDisk(): Promise<void> {
+    let text: string | undefined
+    try {
+      text = await readFile(this.spec.filename, 'utf8')
+    } catch (error) {
+      if (!isENOENT(error)) throw error
+      text = undefined
+    }
+    if (text === this.text || this.isClosed()) return
+    const next = text === undefined ? new Map<string, string>() : new Map(Object.entries(parse(text)))
+    const changed = this.changedRefs(this.values, next)
+    this.text = text
+    this.values = next
+    for (const ref of changed) this.notifyUpdated(ref)
+  }
+  /* jscpd:ignore-end */
+
+  /** Seam-addressable entries whose effective (non-empty) value changed. */
+  private changedRefs(prev: Map<string, string>, next: Map<string, string>): CredentialRef[] {
+    const changed: CredentialRef[] = []
+    for (const key of new Set([...prev.keys(), ...next.keys()])) {
+      const before = prev.get(key)
+      const after = next.get(key)
+      const effectiveBefore = before !== undefined && before.length > 0 ? before : undefined
+      const effectiveAfter = after !== undefined && after.length > 0 ? after : undefined
+      if (effectiveBefore === effectiveAfter) continue
+      try {
+        changed.push(credentialRef(key))
+      } catch (_unaddressableKey) {
+        // A key that is not a POSIX identifier is preserved file content the
+        // seam cannot address, so no observer could ever see it change.
+      }
+    }
+    return changed
+  }
+}
+
+export default CredentialsLocal

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

@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-credentials-local`.
+ * @module @deepseek-ai/dsh-credentials-local/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-credentials-local'
+
+/** Cordis companion plugin name. */
+export const name = 'credentials-local-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the seam companion (`dsh-credentials/invariant`) owns the
+ * `credentials/updated` lifecycle contract; this provider's file/environment layering is
+ * asynchronous I/O pinned by its unit suite.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/credentials/credentials-local/tests/drain.spec.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { CredentialsLocal } from '../src/index.ts'
+
+// The atomic write is the gated asynchronous hold point inside a queued
+// write; gating it makes the dispose-versus-queued-write race fully
+// deterministic. The lock helper passes through so the gated operation still
+// runs inside its real acquire/release cycle.
+vi.mock('@deepseek-ai/dsh-atomic-write', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@deepseek-ai/dsh-atomic-write')>()
+  let gate: Promise<void> = Promise.resolve()
+  return {
+    ...actual,
+    writeFileAtomic: vi.fn(() => gate),
+    __setGate: (next: Promise<void>) => {
+      gate = next
+    },
+  }
+})
+
+async function setGate(next: Promise<void>): Promise<void> {
+  const mocked = await import('@deepseek-ai/dsh-atomic-write') as unknown as { __setGate: (next: Promise<void>) => void }
+  mocked.__setGate(next)
+}
+
+const KEY = credentialRef('DSH_CRED_DRAIN_A')
+const OTHER = credentialRef('DSH_CRED_DRAIN_B')
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  await setGate(Promise.resolve())
+  while (cleanups.length > 0) await cleanups.pop()!()
+})
+
+describe('write-drain teardown', () => {
+  it('lets the in-flight write land and fails the queued one after disposal', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-credentials-drain-'))
+    cleanups.push(() => rm(dir, { recursive: true, force: true }))
+    const ctx = new Context()
+    const fiber = ctx.plugin(CredentialsLocal, { path: join(dir, '.env'), watch: false })
+    await fiber
+    const service = ctx.credentials
+
+    let release!: () => void
+    await setGate(new Promise<void>((resolveGate) => {
+      release = resolveGate
+    }))
+    const first = service.set(KEY, 'one')
+    // Let the first task pass its liveness checks and park on the gate, so it
+    // is genuinely in-flight when disposal begins.
+    await new Promise(resolvePause => setTimeout(resolvePause, 5))
+    // Attach the rejection handler up front: the queued write fails while the
+    // drain is still awaited, before any later `await expect` could run.
+    const secondRejects = expect(service.set(OTHER, 'two')).rejects.toThrow(/disposed before the queued/)
+    const disposal = fiber.dispose()
+    // Give the drain disposer its first turn (set closed) before opening the gate.
+    await new Promise(resolvePause => setTimeout(resolvePause, 10))
+    release()
+    await disposal
+
+    await expect(first).resolves.toBeUndefined()
+    await secondRejects
+    expect(await service.resolve(KEY)).toEqual({ value: 'one', source: 'file' })
+    expect(await service.resolve(OTHER)).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,244 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
+import { CredentialsLocal, resolveSpec } from '../src/index.ts'
+
+const KEY = credentialRef('DSH_CRED_TEST')
+const OTHER = credentialRef('DSH_CRED_OTHER')
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  vi.unstubAllEnvs()
+  while (cleanups.length > 0) await cleanups.pop()!()
+})
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-credentials-local-'))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function boot(config: ConstructorParameters<typeof CredentialsLocal>[1]): Promise<Context> {
+  const ctx = new Context()
+  const fiber = ctx.plugin(CredentialsLocal, config)
+  cleanups.push(async () => {
+    await fiber.dispose()
+  })
+  await fiber
+  return ctx
+}
+
+function updates(ctx: Context): CredentialRef[] {
+  const seen: CredentialRef[] = []
+  ctx.on('credentials/updated', (ref) => {
+    seen.push(ref)
+  })
+  return seen
+}
+
+describe('resolveSpec', () => {
+  it('defaults to .env under the harness home with watching on', () => {
+    const spec = resolveSpec({ dshHome: '/custom/home' })
+    expect(spec).toEqual({ filename: resolve('/custom/home/.env'), watch: true, debounceMs: 100 })
+  })
+
+  it('lets an explicit path win over the home', () => {
+    const spec = resolveSpec({ path: '/etc/dsh/creds.env', dshHome: '/ignored', watch: false, debounceMs: 5 })
+    expect(spec).toEqual({ filename: resolve('/etc/dsh/creds.env'), watch: false, debounceMs: 5 })
+  })
+})
+
+describe('layering and reads', () => {
+  it('treats an absent file as an empty writable store', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.env'), watch: false })
+    expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
+    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: false, writable: true })
+  })
+
+  it('serves file entries, including export-prefixed and quoted values', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, '# notes\nexport DSH_CRED_TEST=plain\nDSH_CRED_OTHER="with space"\n')
+    const ctx = await boot({ path, watch: false })
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'plain', source: 'file' })
+    expect(await ctx.credentials.resolve(OTHER)).toEqual({ value: 'with space', source: 'file' })
+    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'file', writable: true })
+  })
+
+  it('lets a non-empty process environment win read-only over the file', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, 'DSH_CRED_TEST=from-file\n')
+    const ctx = await boot({ path, watch: false })
+    vi.stubEnv('DSH_CRED_TEST', 'from-env')
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'from-env', source: 'env' })
+    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: true, source: 'env', writable: false })
+  })
+
+  it('treats empty values as absent in both layers', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, 'DSH_CRED_TEST=\n')
+    const ctx = await boot({ path, watch: false })
+    vi.stubEnv('DSH_CRED_TEST', '')
+    expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
+    expect(await ctx.credentials.describe(KEY)).toEqual({ configured: false, writable: true })
+  })
+
+  it('fails boot loud when the document exists but cannot be read', async () => {
+    const dir = await tempDir()
+    const path = join(dir, 'occupied')
+    await mkdir(path)
+    const ctx = new Context()
+    await expect(ctx.plugin(CredentialsLocal, { path, watch: false })).rejects.toThrow()
+  })
+})
+
+describe('line-editing writes', () => {
+  it('appends a missing key to a fresh 0600 document and emits the commit', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, watch: false })
+    const seen = updates(ctx)
+    await ctx.credentials.set(KEY, 'sk-fresh')
+    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_TEST=sk-fresh\n')
+    expect((await stat(path)).mode & 0o777).toBe(0o600)
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'sk-fresh', source: 'file' })
+    expect(seen).toEqual([KEY])
+  })
+
+  it('rewrites one line in place, preserving every other byte and dropping duplicates', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, '# deployment notes\nFIRST=one\n\nDSH_CRED_TEST=old\nTRAILING=x\nDSH_CRED_TEST=older')
+    const ctx = await boot({ path, watch: false })
+    await ctx.credentials.set(KEY, 'new value!')
+    expect(await readFile(path, 'utf8')).toBe('# deployment notes\nFIRST=one\n\nDSH_CRED_TEST=\'new value!\'\nTRAILING=x\n')
+  })
+
+  it('quotes hostile values so they round-trip through a fresh provider', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, watch: false })
+    const singleQuoted = 'with "quote", back\\slash and space'
+    const doubleQuoted = "it's got an apostrophe"
+    await ctx.credentials.set(KEY, singleQuoted)
+    await ctx.credentials.set(OTHER, doubleQuoted)
+    const reread = await boot({ path, watch: false })
+    expect(await reread.credentials.resolve(KEY)).toEqual({ value: singleQuoted, source: 'file' })
+    expect(await reread.credentials.resolve(OTHER)).toEqual({ value: doubleQuoted, source: 'file' })
+  })
+
+  it('fails loud on values no .env quoting style reads back verbatim', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.env'), watch: false })
+    await expect(ctx.credentials.set(KEY, 'line one\nline two')).rejects.toThrow(/control characters/)
+    await expect(ctx.credentials.set(KEY, 'both \' and "')).rejects.toThrow(/mixes quoting/)
+  })
+
+  it('unsets only the owning line and keeps an absent unset silent', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, '# keep\nDSH_CRED_TEST=gone\nDSH_CRED_OTHER=stays\n')
+    const ctx = await boot({ path, watch: false })
+    const seen = updates(ctx)
+    await ctx.credentials.unset(KEY)
+    expect(await readFile(path, 'utf8')).toBe('# keep\nDSH_CRED_OTHER=stays\n')
+    await ctx.credentials.unset(KEY)
+    expect(seen).toEqual([KEY])
+  })
+
+  it('rejects empty values, shadowed writes, and multi-line entries', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, 'DSH_CRED_TEST="line one\nline two"\n')
+    const ctx = await boot({ path, watch: false })
+
+    await expect(ctx.credentials.set(KEY, '')).rejects.toThrow(/empty value/)
+    await expect(ctx.credentials.set(KEY, 'next')).rejects.toThrow(/multi-line/)
+    await expect(ctx.credentials.unset(KEY)).rejects.toThrow(/multi-line/)
+
+    vi.stubEnv('DSH_CRED_TEST', 'shadowing')
+    await expect(ctx.credentials.set(KEY, 'next')).rejects.toThrow(/shadowed/)
+    await expect(ctx.credentials.unset(KEY)).rejects.toThrow(/shadowed/)
+  })
+
+  it('leaves an empty document after unsetting the only entry', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, 'DSH_CRED_TEST=only\n')
+    const ctx = await boot({ path, watch: false })
+    await ctx.credentials.unset(KEY)
+    expect(await readFile(path, 'utf8')).toBe('')
+  })
+
+  it('chains past a rejected write so one bad value cannot poison the queue', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, watch: false })
+    const bad = expect(ctx.credentials.set(KEY, 'both \' and "')).rejects.toThrow(/mixes quoting/)
+    const good = ctx.credentials.set(OTHER, 'lands')
+    await bad
+    await good
+    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_OTHER=lands\n')
+  })
+
+  it('serializes concurrent writes so both land in the one document', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, watch: false })
+    await Promise.all([
+      ctx.credentials.set(KEY, 'one'),
+      ctx.credentials.set(OTHER, 'two'),
+    ])
+    expect(await readFile(path, 'utf8')).toBe('DSH_CRED_TEST=one\nDSH_CRED_OTHER=two\n')
+  })
+
+  it('refuses writes after disposal', async () => {
+    const dir = await tempDir()
+    const ctx = new Context()
+    const fiber = ctx.plugin(CredentialsLocal, { path: join(dir, '.env'), watch: false })
+    await fiber
+    // Capture the handle first: disposal also removes the ctx.credentials service.
+    const service = ctx.credentials
+    await fiber.dispose()
+    await expect(service.set(KEY, 'late')).rejects.toThrow(/disposed/)
+  })
+})
+
+describe('real hot reload', () => {
+  it('publishes external edits, replaces the snapshot wholesale, and suppresses self-writes', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    // Watching starts on an existing document: creation racing watcher setup
+    // is a chokidar readiness gap, not the reload contract under test.
+    await writeFile(path, 'DSH_CRED_TEST=boot\n')
+    const ctx = await boot({ path, debounceMs: 10 })
+    const seen = updates(ctx)
+
+    await writeFile(path, 'DSH_CRED_TEST=live\nDSH_CRED_OTHER=extra\n')
+    await vi.waitFor(async () => {
+      expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'live', source: 'file' })
+    })
+
+    // Wholesale replacement: an entry deleted on disk never lingers in memory.
+    await writeFile(path, 'DSH_CRED_TEST=live\n')
+    await vi.waitFor(async () => {
+      expect(await ctx.credentials.resolve(OTHER)).toBeUndefined()
+    })
+
+    const before = seen.length
+    await ctx.credentials.set(KEY, 'self-written')
+    await new Promise(resolvePause => setTimeout(resolvePause, 200))
+    // Exactly the committed write's own event: the watcher echo of our own
+    // content is recognized by the text cache and publishes nothing extra.
+    expect(seen.length).toBe(before + 1)
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'self-written', source: 'file' })
+  })
+})

packages/credentials/credentials-local/tests/review-fixes.spec.ts

@@ -0,0 +1,202 @@
+// Third-review behaviors: read-modify-write under the writer lock (external
+// edits survive an API write), the contained credentials/updated fan-out (a
+// broken observer never fails a committed write), and the physical-line
+// editor's multi-line and CRLF discipline.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { mkdtemp, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { CredentialsLocal } from '../src/index.ts'
+
+const ALPHA = credentialRef('DSH_REVIEW_ALPHA')
+const BETA = credentialRef('DSH_REVIEW_BETA')
+const INNER = credentialRef('DSH_REVIEW_INNER')
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  while (cleanups.length > 0) await cleanups.pop()!()
+})
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-cred-review-'))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function boot(config: ConstructorParameters<typeof CredentialsLocal>[1]): Promise<Context> {
+  const ctx = new Context()
+  const fiber = ctx.plugin(CredentialsLocal, config)
+  cleanups.push(async () => { await fiber.dispose() })
+  await fiber
+  return ctx
+}
+
+describe('read-modify-write', () => {
+  it('folds an unobserved external edit into a write instead of overwriting it', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, watch: false })
+    const seen: string[] = []
+    ctx.on('credentials/updated', (ref) => { seen.push(ref) })
+    await ctx.credentials.set(ALPHA, 'one')
+    // The external edit has landed on disk but no watcher reported it (watch
+    // is off — the same blind spot as a debounce window or a missed event).
+    await writeFile(path, `${ALPHA}=one\n${BETA}=external\n`)
+    await ctx.credentials.set(ALPHA, 'two')
+    const text = await readFile(path, 'utf8')
+    expect(text).toContain(`${BETA}=external`)
+    expect(text).toContain(`${ALPHA}=two`)
+    // The fold published the unobserved entry before the write's own commit.
+    expect(seen).toEqual([ALPHA, BETA, ALPHA])
+    expect(await ctx.credentials.resolve(BETA)).toEqual({ value: 'external', source: 'file' })
+  })
+
+  it('keeps both refs when two providers write the same document concurrently', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const first = await boot({ path, watch: false })
+    const second = await boot({ path, watch: false })
+    await Promise.all([
+      (async () => { for (const value of ['1', '2', '3'] as const) await first.credentials.set(ALPHA, value) })(),
+      (async () => { for (const value of ['1', '2', '3'] as const) await second.credentials.set(BETA, value) })(),
+    ])
+    const third = await boot({ path, watch: false })
+    expect(await third.credentials.resolve(ALPHA)).toEqual({ value: '3', source: 'file' })
+    expect(await third.credentials.resolve(BETA)).toEqual({ value: '3', source: 'file' })
+  })
+
+  it('breaks a stale writer lock with a warning and writes through', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, watch: false })
+    await writeFile(`${path}.lock`, 'crashed-holder\n')
+    const past = (Date.now() - 60_000) / 1000
+    await utimes(`${path}.lock`, past, past)
+    await ctx.credentials.set(ALPHA, 'nine')
+    expect(await readFile(path, 'utf8')).toContain(`${ALPHA}=nine`)
+  })
+
+  it('creates the credentials directory owner-only', async () => {
+    const dir = await tempDir()
+    const home = join(dir, 'home')
+    const ctx = await boot({ path: join(home, '.env'), watch: false })
+    await ctx.credentials.set(ALPHA, 'one')
+    expect((await stat(home)).mode & 0o777).toBe(0o700)
+  })
+})
+
+describe('contained update fan-out', () => {
+  it('does not fail a committed set when a listener throws, and later listeners still run', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.env'), watch: false })
+    ctx.on('credentials/updated', () => {
+      throw new Error('observer boom')
+    })
+    const second = vi.fn()
+    ctx.on('credentials/updated', second)
+    await expect(ctx.credentials.set(ALPHA, 'one')).resolves.toBeUndefined()
+    expect(second).toHaveBeenCalledWith(ALPHA)
+    expect(await ctx.credentials.resolve(ALPHA)).toEqual({ value: 'one', source: 'file' })
+  })
+
+  it('contains an async listener rejection', async () => {
+    const dir = await tempDir()
+    const ctx = await boot({ path: join(dir, '.env'), watch: false })
+    // An unknown-returning function keeps the typed surface legal while the
+    // runtime value is still the rejected promise the containment must handle.
+    const boom = (): unknown => Promise.reject(new Error('async observer boom'))
+    ctx.on('credentials/updated', boom)
+    await expect(ctx.credentials.set(ALPHA, 'one')).resolves.toBeUndefined()
+    await new Promise(resolve => setTimeout(resolve, 10))
+  })
+
+  it('rethrows an invariant-coded failure after the commit and the remaining listeners', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, watch: false })
+    ctx.on('credentials/updated', () => {
+      throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' })
+    })
+    const second = vi.fn()
+    ctx.on('credentials/updated', second)
+    await expect(ctx.credentials.set(ALPHA, 'one')).rejects.toThrow(/forged relation/)
+    // Harness-fatal by design — but the write itself committed first.
+    expect(second).toHaveBeenCalledWith(ALPHA)
+    expect(await readFile(path, 'utf8')).toContain(`${ALPHA}=one`)
+    expect(await ctx.credentials.resolve(ALPHA)).toEqual({ value: 'one', source: 'file' })
+  })
+})
+
+describe('physical-line editor', () => {
+  it('never mistakes a quoted multi-line continuation for an assignment', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const wrapped = `DSH_REVIEW_WRAPPED="line1\n${INNER}=looks-like-one\nline3"\n${ALPHA}=a\n`
+    await writeFile(path, wrapped)
+    const ctx = await boot({ path, watch: false })
+    await ctx.credentials.set(ALPHA, 'b')
+    // The wrapped value survives byte-for-byte; only ALPHA's line changed.
+    const afterAlpha = await readFile(path, 'utf8')
+    expect(afterAlpha).toBe(`DSH_REVIEW_WRAPPED="line1\n${INNER}=looks-like-one\nline3"\n${ALPHA}=b\n`)
+    // Setting the inner-looking ref appends a real assignment; the
+    // continuation line inside the quoted value stays untouched.
+    await ctx.credentials.set(INNER, 'real')
+    const afterInner = await readFile(path, 'utf8')
+    expect(afterInner).toBe(`DSH_REVIEW_WRAPPED="line1\n${INNER}=looks-like-one\nline3"\n${ALPHA}=b\n${INNER}=real\n`)
+    expect(await ctx.credentials.resolve(INNER)).toEqual({ value: 'real', source: 'file' })
+  })
+
+  it('preserves CRLF line endings on untouched and edited lines', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, `# note\r\n${ALPHA}=a\r\n${BETA}=keep\r\n`)
+    const ctx = await boot({ path, watch: false })
+    await ctx.credentials.set(ALPHA, 'b')
+    expect(await readFile(path, 'utf8')).toBe(`# note\r\n${ALPHA}=b\r\n${BETA}=keep\r\n`)
+    await ctx.credentials.set(INNER, 'new')
+    expect(await readFile(path, 'utf8')).toBe(`# note\r\n${ALPHA}=b\r\n${BETA}=keep\r\n${INNER}=new\r\n`)
+  })
+
+  it('terminates a final unterminated line before appending', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, `${ALPHA}=a`)
+    const ctx = await boot({ path, watch: false })
+    await ctx.credentials.set(BETA, 'b')
+    expect(await readFile(path, 'utf8')).toBe(`${ALPHA}=a\n${BETA}=b\n`)
+  })
+
+  it('rewrites a final unterminated assignment in the dominant ending style', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, `${ALPHA}=a`)
+    const ctx = await boot({ path, watch: false })
+    await ctx.credentials.set(ALPHA, 'b')
+    expect(await readFile(path, 'utf8')).toBe(`${ALPHA}=b\n`)
+  })
+
+  it('tracks a single-quoted multi-line value through its continuation', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, `DSH_REVIEW_SQ='line1\n${INNER}=shadow\nline3'\n`)
+    const ctx = await boot({ path, watch: false })
+    await ctx.credentials.set(ALPHA, 'x')
+    expect(await readFile(path, 'utf8'))
+      .toBe(`DSH_REVIEW_SQ='line1\n${INNER}=shadow\nline3'\n${ALPHA}=x\n`)
+  })
+
+  it('reports a multi-line entry as unwritable and refuses to edit it', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, `${ALPHA}="line1\nline2"\n`)
+    const ctx = await boot({ path, watch: false })
+    expect(await ctx.credentials.describe(ALPHA)).toEqual({ configured: true, source: 'file', writable: false })
+    await expect(ctx.credentials.set(ALPHA, 'flat')).rejects.toThrow(/multi-line entry/)
+    await expect(ctx.credentials.unset(ALPHA)).rejects.toThrow(/multi-line entry/)
+    // Resolution still serves the multi-line value.
+    expect(await ctx.credentials.resolve(ALPHA)).toEqual({ value: 'line1\nline2', source: 'file' })
+  })
+})

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

@@ -0,0 +1,223 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { CredentialsLocal } from '../src/index.ts'
+
+// chokidar is the nondeterministic OS boundary: faking it lets these tests
+// drive the event pipeline (error events, races with unreadable files)
+// deterministically. Real end-to-end watching stays covered by local.spec.ts.
+vi.mock('chokidar', async () => {
+  const { EventEmitter } = await import('node:events')
+  class FakeWatcher extends EventEmitter {
+    close = vi.fn(() => Promise.resolve())
+  }
+  const instances: Array<{ path: string; options: unknown; watcher: InstanceType<typeof FakeWatcher> }> = []
+  return {
+    watch: vi.fn((path: string, options: unknown) => {
+      const watcher = new FakeWatcher()
+      instances.push({ path, options, watcher })
+      return watcher
+    }),
+    __instances: instances,
+  }
+})
+
+interface FakeChokidar {
+  __instances: Array<{
+    path: string
+    options: { awaitWriteFinish: { stabilityThreshold: number; pollInterval: number } }
+    watcher: import('node:events').EventEmitter
+  }>
+}
+
+async function fakeInstances(): Promise<FakeChokidar['__instances']> {
+  const chokidar = await import('chokidar') as unknown as FakeChokidar
+  return chokidar.__instances
+}
+
+const KEY = credentialRef('DSH_CRED_PIPE')
+
+const cleanups: Array<() => Promise<void>> = []
+
+afterEach(async () => {
+  while (cleanups.length > 0) await cleanups.pop()!()
+  ;(await fakeInstances()).length = 0
+})
+
+async function tempDir(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-credentials-watch-'))
+  cleanups.push(() => rm(dir, { recursive: true, force: true }))
+  return dir
+}
+
+async function boot(config: ConstructorParameters<typeof CredentialsLocal>[1]): Promise<Context> {
+  const ctx = new Context()
+  const fiber = ctx.plugin(CredentialsLocal, config)
+  cleanups.push(async () => {
+    await fiber.dispose()
+  })
+  await fiber
+  return ctx
+}
+
+describe('watcher pipeline', () => {
+  it('clamps the write-settle poll interval for a zero debounce', async () => {
+    const dir = await tempDir()
+    await boot({ path: join(dir, '.env'), debounceMs: 0 })
+    const [instance] = await fakeInstances()
+    expect(instance!.options.awaitWriteFinish).toEqual({ stabilityThreshold: 0, pollInterval: 1 })
+  })
+
+  it('survives a watcher error and keeps publishing later edits', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const [instance] = await fakeInstances()
+
+    instance!.watcher.emit('error', new Error('watch backend failure'))
+    expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
+
+    await writeFile(path, 'DSH_CRED_PIPE=arrived\n')
+    instance!.watcher.emit('all', 'change', path)
+    await vi.waitFor(async () => {
+      expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'arrived', source: 'file' })
+    })
+  })
+
+  it('keeps the last good snapshot when the file turns unreadable at runtime', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, 'DSH_CRED_PIPE=good\n')
+    const ctx = await boot({ path, debounceMs: 5 })
+
+    await chmod(path, 0o000)
+    cleanups.push(() => chmod(path, 0o600))
+    const [instance] = await fakeInstances()
+    instance!.watcher.emit('all', 'change', path)
+    // The warn-and-keep path is asynchronous; give the serialized refresh a turn.
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'good', source: 'file' })
+  })
+
+  it('keeps the reload queue alive after an invariant violation escapes the fan-out', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, debounceMs: 5 })
+    let arm = true
+    ctx.on('credentials/updated', () => {
+      if (!arm) return
+      throw Object.assign(new Error('forged relation'), { code: 'INVARIANT' })
+    })
+    const [instance] = await fakeInstances()
+
+    await writeFile(path, 'DSH_CRED_PIPE=first\n')
+    instance!.watcher.emit('all', 'change', path)
+    // The snapshot commits before the fan-out, so the value lands even though
+    // the listener threw out of the refresh.
+    await vi.waitFor(async () => {
+      expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'first', source: 'file' })
+    })
+
+    arm = false
+    await writeFile(path, 'DSH_CRED_PIPE=second\n')
+    instance!.watcher.emit('all', 'change', path)
+    await vi.waitFor(async () => {
+      expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'second', source: 'file' })
+    })
+  })
+
+  it('quiesces the refresh pipeline before dispose completes', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, 'DSH_CRED_PIPE=initial\n')
+    const ctx = new Context()
+    const fiber = ctx.plugin(CredentialsLocal, { path, debounceMs: 5 })
+    await fiber
+    let disposed = false
+    let postDisposeCommits = 0
+    ctx.on('credentials/updated', () => {
+      if (disposed) postDisposeCommits += 1
+    })
+
+    await writeFile(path, 'DSH_CRED_PIPE=changed\n')
+    const [instance] = await fakeInstances()
+    // Two queued refreshes: dispose interrupts one mid-flight and the other
+    // before it starts, so both closed guards must hold.
+    instance!.watcher.emit('all', 'change', path)
+    instance!.watcher.emit('all', 'change', path)
+    await fiber.dispose()
+    disposed = true
+    instance!.watcher.emit('all', 'change', path)
+    instance!.watcher.emit('ready')
+    await new Promise(resolve => setTimeout(resolve, 100))
+    expect(postDisposeCommits).toBe(0)
+  })
+
+  it('empties the snapshot when the document is deleted and emits the removals', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, 'DSH_CRED_PIPE=doomed\n')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const seen: string[] = []
+    ctx.on('credentials/updated', (ref) => {
+      seen.push(ref)
+    })
+
+    await rm(path)
+    const [instance] = await fakeInstances()
+    instance!.watcher.emit('all', 'unlink', path)
+    await vi.waitFor(async () => {
+      expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
+    })
+    expect(seen).toEqual([KEY])
+  })
+
+  it('publishes only seam-addressable keys and preserves the rest untouched', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, 'BAD-KEY=1\nDSH_CRED_PIPE=a\n')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const seen: string[] = []
+    ctx.on('credentials/updated', (ref) => {
+      seen.push(ref)
+    })
+
+    await writeFile(path, 'BAD-KEY=2\nDSH_CRED_PIPE=b\n')
+    const [instance] = await fakeInstances()
+    instance!.watcher.emit('all', 'change', path)
+    await vi.waitFor(async () => {
+      expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'b', source: 'file' })
+    })
+    // The dash-named key is preserved file content the seam cannot address:
+    // its change publishes nothing and breaks nothing.
+    expect(seen).toEqual([KEY])
+  })
+
+  it('treats an event for a still-absent file as a no-op', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    const ctx = await boot({ path, debounceMs: 5 })
+    const [instance] = await fakeInstances()
+    instance!.watcher.emit('all', 'add', path)
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(await ctx.credentials.resolve(KEY)).toBeUndefined()
+  })
+
+  it('reconciles at watcher ready so a change during setup is not missed', async () => {
+    const dir = await tempDir()
+    const path = join(dir, '.env')
+    await writeFile(path, `${KEY}=a\n`)
+    const ctx = await boot({ path, debounceMs: 5 })
+    // Written after the initial load but before the watcher became active:
+    // no 'all' event will ever fire for it.
+    await writeFile(path, `${KEY}=written-before-ready\n`)
+    const [instance] = await fakeInstances()
+    instance!.watcher.emit('ready')
+    await vi.waitFor(async () => {
+      expect(await ctx.credentials.resolve(KEY)).toEqual({ value: 'written-before-ready', source: 'file' })
+    })
+  })
+})

packages/credentials/credentials-local/tsconfig.json

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

packages/credentials/credentials/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/credentials/credentials/README.md
+README.md: 1c18c4762360ad081227b7097cd82ddab4fcdefc
+README.zh.md: 751fb7c1e8326cef91b925c5f8b9f40d92e1bba6

packages/credentials/credentials/README.md

@@ -0,0 +1,48 @@
+# dsh-credentials
+
+English | [中文](README.zh.md)
+
+Abstract credential seam (`ctx.credentials`). One doctrine, three consequences:
+
+**Configuration carries references to secrets, never the secrets.** A settings section or `cordis.yml` entry says `apiKeyEnv: DEEPSEEK_API_KEY`; the value behind that reference lives with a credential provider. So the settings document stays safe to sync and to render in a configuration UI, `describe()` can answer "is this configured, where from, can I write it" without ever holding a value, and rotating a secret touches no configuration file.
+
+**Consumers resolve per operation.** `resolve(ref)` is called at the start of each operation (the LLM adapters resolve once per model request) and never cached across operations — that read is what makes a changed credential reach the very next request without restarting any plugin.
+
+**An empty stored value is absent.** Everywhere: `resolve` skips it, `describe` reports it unconfigured. A blank can never masquerade as a configured secret.
+
+## Surface
+
+```ts
+import type { Context } from 'cordis'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+
+declare const ctx: Context
+
+const ref = credentialRef('DEEPSEEK_API_KEY')            // POSIX shell identifier, branded
+const hit = await ctx.credentials.resolve(ref)           // { value, source } | undefined
+const info = await ctx.credentials.describe(ref)         // { configured, source?, writable } — never the value
+await ctx.credentials.set(ref, 'sk-…')                   // rejects while a read-only source shadows the ref
+await ctx.credentials.unset(ref)                         // no-op when absent; same shadowing rule
+```
+
+`credentials/updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration UIs refreshing a "configured" badge.
+
+The shadowing rule on `set`/`unset` is deliberate fail-loud: when a read-only source (the live process environment, in the local provider) currently supplies the reference, a write would appear to succeed while resolution keeps returning the shadowing value — the seam rejects instead, and `describe().writable` lets a UI render the reference read-only up front.
+
+## Providers
+
+[`dsh-credentials-local`](../credentials-local/README.md) layers the live process environment over a `$DSH_HOME/.env` file. The seam shape leaves room for keyring-, helper-command-, and KMS-backed providers; a remote settings provider never needs to carry secrets.
+
+## Model Experience
+
+Indirectly, through the consuming LLM adapters: a resolved value authorizes their provider requests, and the adapter owns every model-visible surface.
+
+#### KV Cache effect
+
+No direct invalidation; credentials never enter a request prefix.
+
+## Known Limitations and Deferred Work
+
+- **No enumeration** — the seam answers questions about references it is given; configuration surfaces learn the references from settings schemas, so a `list()` has no current consumer.
+- **References are environment-variable-shaped** — one flat POSIX-identifier namespace until a provider needs richer addressing.
+- **Process-environment changes are invisible** — no event can fire for them; a UI only re-reads `describe()` on its own navigation.

packages/credentials/credentials/README.zh.md

@@ -0,0 +1,48 @@
+# dsh-credentials
+
+[English](README.md) | 中文
+
+抽象凭据 seam（`ctx.credentials`）。一条准则，三个推论：
+
+**配置只携带对机密的引用，绝不携带机密本身。** settings 分节或 `cordis.yml` 条目写 `apiKeyEnv: DEEPSEEK_API_KEY`，引用背后的值归凭据 provider 所有。于是设置文档可以放心同步、放心渲染进配置界面；`describe()` 无需持有值就能回答「配置了吗、来自哪层、能否写入」；轮换机密不触碰任何配置文件。
+
+**消费方按操作解析。** `resolve(ref)` 在每个操作开始时调用（LLM 适配器每次模型请求解析一次），绝不跨操作缓存——正是这次读取让改过的凭据无需重启任何插件就作用于下一次请求。
+
+**空的存储值等于不存在。**处处如此：`resolve` 跳过它，`describe` 报告未配置。空白永远不会伪装成已配置的机密。
+
+## 接口面
+
+```ts
+import type { Context } from 'cordis'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+
+declare const ctx: Context
+
+const ref = credentialRef('DEEPSEEK_API_KEY')            // POSIX shell identifier, branded
+const hit = await ctx.credentials.resolve(ref)           // { value, source } | undefined
+const info = await ctx.credentials.describe(ref)         // { configured, source?, writable } — never the value
+await ctx.credentials.set(ref, 'sk-…')                   // rejects while a read-only source shadows the ref
+await ctx.credentials.unset(ref)                         // no-op when absent; same shadowing rule
+```
+
+`credentials/updated (ref)` 在 provider 管理的来源发生已提交变更后触发——`set`、`unset` 或在存储中观察到的外部编辑。进程环境变量的变化不可观测，永不触发。消费方不需要该事件（它们按操作重新解析）；它服务于配置界面刷新「已配置」徽标。
+
+`set`/`unset` 的遮蔽规则是刻意的响亮失败：当只读来源（本地 provider 中即活跃进程环境）正在提供该引用时，写入会表面成功而解析仍返回遮蔽值——seam 选择直接拒绝，并通过 `describe().writable` 让界面提前把该引用渲染为只读。
+
+## Providers
+
+[`dsh-credentials-local`](../credentials-local/README.md) 把活跃进程环境叠加在 `$DSH_HOME/.env` 文件之上。seam 形状为 keyring、辅助命令、KMS 后端的 provider 留好了位置；远端 settings provider 永远不必携带机密。
+
+## Model Experience
+
+经由消费它的 LLM 适配器间接生效：解析出的值为适配器的提供方请求授权，每个模型可见面都归适配器所有。
+
+#### KV Cache effect
+
+无直接失效；凭据绝不进入请求前缀。
+
+## Known Limitations and Deferred Work
+
+- **不提供枚举**——seam 只回答被问到的引用；配置界面从 settings schema 得知引用集合，`list()` 没有当前消费方。
+- **引用限定为环境变量形状**——在有 provider 需要更丰富寻址前，保持单一扁平的 POSIX 标识符命名空间。
+- **进程环境变化不可见**——不可能为其发事件；界面只能在自身导航时重新读取 `describe()`。

packages/credentials/credentials/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@deepseek-ai/dsh-credentials",
+  "description": "Abstract credential seam (ctx.credentials): settings carry references to secrets, providers own the values",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/credentials/credentials/src/index.ts

@@ -0,0 +1,162 @@
+/**
+ * Credential seam (`ctx.credentials`). Settings and composition files carry
+ * *references* to secrets — environment-variable names — while providers own
+ * the actual values and their storage. Consumers resolve a reference once per
+ * operation, so a changed credential reaches the next operation without any
+ * plugin restart, and configuration surfaces describe a reference without
+ * ever seeing its value.
+ * @module @deepseek-ai/dsh-credentials
+ */
+
+import { Context, Service } from 'cordis'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/** Nominal reference to one credential: a POSIX-style environment-variable name. */
+export type CredentialRef = Branded<'CredentialRef'>
+
+const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/**
+ * Brand a raw string as a {@link CredentialRef}.
+ * @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
+ * @returns the branded reference.
+ */
+export function credentialRef(value: string): CredentialRef {
+  if (!REF_PATTERN.test(value)) {
+    throw new TypeError(`credential ref "${value}" must match ${String(REF_PATTERN)}`)
+  }
+  return value as CredentialRef
+}
+
+/** One resolved credential value and the source layer that supplied it. */
+export interface ResolvedCredential {
+  /** The non-empty secret value. */
+  value: string
+  /** Provider-defined source layer id (the local provider uses `env` and `file`). */
+  source: string
+}
+
+/** Source and writability facts for one reference, safe for configuration UIs — never the value. */
+export interface CredentialInfo {
+  /** Whether {@link Credentials.resolve} would currently return a value. */
+  configured: boolean
+  /** Source layer currently supplying the value; absent while unconfigured. */
+  source?: string
+  /** Whether {@link Credentials.set} would currently succeed for this reference. */
+  writable: boolean
+}
+
+declare module 'cordis' {
+  interface Context {
+    credentials: Credentials
+  }
+
+  interface Events {
+    /**
+     * Committed change to a provider-managed credential source: a `set`, an
+     * `unset`, or an external edit observed in storage. Ambient
+     * process-environment changes are not observable and never emit. Listener
+     * failures are contained and logged — a sync throw and an async rejection
+     * alike — without changing the committed operation's outcome, except
+     * `INVARIANT`-coded failures, which rethrow after every listener ran;
+     * that rethrow reaches the emitter only from synchronous listeners, so
+     * invariant checks on this event must not be async functions.
+     * @param ref - the reference whose stored value changed.
+     * @mode emit
+     */
+    'credentials/updated'(ref: CredentialRef): void
+  }
+}
+
+/**
+ * Abstract credential service. Providers implement the four operations over
+ * their source layers; one seam-wide rule binds them all: an empty stored
+ * value is absent everywhere — `resolve` skips it, `describe` reports it
+ * unconfigured — so a blank never masquerades as a configured secret.
+ */
+export abstract class Credentials extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'credentials')
+  }
+
+  /**
+   * Resolve one reference to its current value. Resolution is per call:
+   * consumers re-resolve at each operation and must not cache across
+   * operations — that per-operation read is what makes a changed credential
+   * reach the next operation without a restart.
+   * @param ref - the reference to resolve.
+   * @returns the value and its source, or `undefined` while unconfigured.
+   */
+  abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>
+
+  /**
+   * Describe one reference for configuration surfaces without exposing the
+   * value.
+   * @param ref - the reference to describe.
+   * @returns configured state, supplying source, and writability.
+   */
+  abstract describe(ref: CredentialRef): Promise<CredentialInfo>
+
+  /**
+   * Durably store one value in the provider-managed writable source. Rejects
+   * while a read-only source shadows the reference — the write would appear
+   * to succeed while resolution keeps returning the shadowing value — and
+   * rejects an empty value (use {@link unset}).
+   * @param ref - the reference to store.
+   * @param value - the non-empty secret value.
+   */
+  abstract set(ref: CredentialRef, value: string): Promise<void>
+
+  /**
+   * Remove one reference from the provider-managed writable source; removing
+   * an absent reference is a no-op. Rejects while a read-only source shadows
+   * the reference, like {@link set}.
+   * @param ref - the reference to remove.
+   */
+  abstract unset(ref: CredentialRef): Promise<void>
+
+  /* jscpd:ignore-start -- deliberate symmetry with the settings seam's commit
+     fan-out: the contained-dispatch shape is the reviewed listener-lifecycle
+     contract, and extracting it would couple the two seams' event semantics. */
+  /**
+   * Fan `credentials/updated` out with contained listener failures: every
+   * listener runs, and a sync throw or async rejection is logged without
+   * changing the committed operation's outcome — except `INVARIANT`-coded
+   * failures, which rethrow after every listener ran (the rethrow reaches the
+   * caller only from synchronous listeners, so invariant checks on this event
+   * must not be async functions). Providers call this only after the write or
+   * reload actually committed, so a broken observer can never make a durable
+   * change look failed.
+   * @param ref - the reference whose stored value changed.
+   */
+  protected notifyUpdated(ref: CredentialRef): void {
+    let invariantFailure: unknown
+    const args = ['credentials/updated', ref]
+    for (const listener of this.ctx.events.dispatch('emit', args) as Array<(...listenerArgs: unknown[]) => unknown>) {
+      try {
+        const returned = listener(ref)
+        if (returned != null && typeof (returned as PromiseLike<unknown>).then === 'function') {
+          void Promise.resolve(returned as PromiseLike<unknown>).then(undefined, (error: unknown) => {
+            this.warnListenerFailure(ref, error)
+          })
+        }
+      } catch (error) {
+        if ((error as { code?: unknown } | null)?.code === 'INVARIANT') {
+          invariantFailure ??= error
+          continue
+        }
+        this.warnListenerFailure(ref, error)
+      }
+    }
+    if (invariantFailure !== undefined) throw invariantFailure as Error
+  }
+  /* jscpd:ignore-end */
+
+  /** Contained-listener diagnostic shared by the sync and async failure paths. */
+  private warnListenerFailure(ref: CredentialRef, error: unknown): void {
+    this.ctx.logger.warn('credentials: a credentials/updated listener for "%s" failed', ref)
+    this.ctx.logger.warn(error)
+  }
+}
+
+export default Credentials