Merge origin/master into worktree/install-interface-choice

2026-08-01 18:06:49 +08:00
parent 4ada0017cf d7289febdb
commit 1892d97930
168 changed files with 3390 additions and 644 deletions
@@ -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 .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
-2026-07-25-web-input-machine-and-slash-pipeline.md: c3deadb34d3a633525dde701c92bcc98c05e5d6e
-2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 7a6988423dcdffebb0a28735146439c8ade0a862
+2026-07-25-web-input-machine-and-slash-pipeline.md: 977df6508e1a1cd54cf1ddb469a6bfb835f60071
+2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 929a885bf54a31605805814ba1e15c901e560434
@@ -72,7 +72,7 @@ A trigger/menu/pick pipeline with zero knowledge of "commands":
 - Each materialized Session has exactly one `SessionInputShell` (the facade), created and torn down with the session scope; with no session, no input machine is built. `ConversationRoot` is itself the `session-maybe` resident shell, holding HeroShell, the Workspace picker, the composer stack, and the chain-fallback frame.
 - The composer bar is one `session-maybe` slot entry rendered unconditionally: with no session the same InputBar renders inert (machine faces absent, `disabled` owner prop), and once `connectWorkspace` returns a blank session the same instance goes live — the textarea DOM survives the no-session → blank transition and every later phase flip; `ConversationRoot`, the Hero, and the layout skeleton hold throughout.
 - ConversationRoot's Hero criterion is `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || openState === 'loading'))`. The first submit enters engaging synchronously, and a failure keeps the composer and the error context rather than falling back to the blank Hero; the sidebar's blank bit flips false only after a prompt is successfully accepted.
- Sending unifies in the hub defaultSink: after an optimistic draft clear it goes only through `session.prompt {mode:'queue'|'steer'}`; backfill happens only when it fails and the live draft is still empty — a user who has kept typing is never overwritten. No Draft materialize or attach transaction exists.
+- Sending unifies in the hub defaultSink: after an optimistic draft clear it goes only through `session.prompt` with `mode:'queue'` (the Web UI has no steer entry; host-wire `mode:'steer'` remains outside this machine); backfill happens only when it fails and the live draft is still empty — a user who has kept typing is never overwritten. No Draft materialize or attach transaction exists.
 - When the blank Hero re-picks the Workspace, the shell calls `connectWorkspace`; if the target session differs, the non-empty draft moves from the current shell to the target shell before the new id is opened, and the old blank session survives but is no longer current.
 - The Notifier's two-bit contract: `dirty` (snapshot freshness, clearable by an `ensureFresh` pull) and `notifyPending` (notification debt, cleared only by a flush) are mutually independent — a pull must not swallow a push, and object-layer push subscribers (watchTransaction) depend on this guarantee.

@@ -72,7 +72,7 @@ occurrence 表与 chip 三投影：
 - 每个实体 Session 只有一个 `SessionInputShell`（facade），随 session scope 创建和拆除；无 session 时不造 input machine。`ConversationRoot` 自身是 `session-maybe` 常驻外壳，持有 HeroShell、Workspace picker、composer stack 与 chain fallback 外框。
 - composer bar 是一个无条件渲染的 `session-maybe` slot entry：无 session 时同一个 InputBar 以惰性态渲染（machine face 缺席、`disabled` owner prop），`connectWorkspace` 返回 blank session 后同一实例转为 live——textarea DOM 在无 session → blank 切换及其后每次 phase 翻转中都不重建；`ConversationRoot`、Hero 与布局骨架全程保持。
 - ConversationRoot 的 Hero 判据是 `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || openState === 'loading'))`。首次 submit 同步进入 engaging，失败也保留 composer 与错误上下文，不退回 blank Hero；sidebar 的 blank 位只在 prompt 成功受理后翻 false。
- 发送统一在 hub defaultSink：乐观清稿后只走 `session.prompt {mode:'queue'|'steer'}`；失败且 live draft 仍为空才回填，用户已经继续输入则不覆盖。不存在 Draft materialize 或 attach 事务。
+- 发送统一在 hub defaultSink：乐观清稿后只走 `session.prompt` 且固定 `mode:'queue'`（Web UI 无 steer 入口；host 线缆上的 `mode:'steer'` 不经此 machine）；失败且 live draft 仍为空才回填，用户已经继续输入则不覆盖。不存在 Draft materialize 或 attach 事务。
 - blank Hero 改选 Workspace 时，外壳调用 `connectWorkspace`；目标 session 不同时把非空 draft 从当前 shell 搬到目标 shell，再 open 新 id，旧 blank session 留存但不再 current。
 - Notifier 双位契约：`dirty`（快照新鲜度，`ensureFresh` 拉取可清）与 `notifyPending`（通知欠账，只有 flush 清）各自独立——拉取不得吞推送，对象层推订阅者（watchTransaction）依赖这一保证。

@@ -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 .agents/notes/implemented/architecture/2026-07-28-launcher-owned-resume-identity.md
-2026-07-28-launcher-owned-resume-identity.md: e11431716305ff18e951ca45921c71dcd105974c
-2026-07-28-launcher-owned-resume-identity.zh.md: e4078023cb1519288f0367f8973788f361aaa0bd
+2026-07-28-launcher-owned-resume-identity.md: da9b4571d154137d34ef3690e7b4aa9bc7bb9082
+2026-07-28-launcher-owned-resume-identity.zh.md: 51ccffd7bb9c8eeda03afe2528d3cb4250e2d906
@@ -25,7 +25,7 @@ Both sit beside the existing `tuiResumeHost` host capability, which set the prec

 Identity belongs to `agent-loop` because that is the plugin which creates configured agents, and because a patch replaces a row's whole `config`: an overlay repointing the agent row's model route would erase a launcher-set identity key. See [the shared-base overlay note](../simplification/2026-07-29-shared-base-config-overlays.md).

-`apps/cli` mints or selects the id and builds the line from the invocation it is reproducing, sharing one `resumeArgs` helper with the `/resume` execve handoff so the printed command and the in-place handoff cannot diverge. The line now names `--config` when one was passed, and reproduces `dsh meta --resume <id>` in meta mode — closing the mode-aware hint deferred by the `dsh meta` note, where a copied hint previously only worked from the checkout.
+`apps/cli` mints or selects the id and builds the line from the invocation it is reproducing, sharing one `resumeArgs` helper with the `/resume` execve handoff so the printed command and the in-place handoff cannot diverge. The line names `--config` when one was passed. Resume always re-enters the default surface through `dsh --resume <id>`; `dsh meta` accepts no default-surface options and always starts fresh.

 **`ctx.provide` is the only channel from launcher argv into a Loader-mounted plugin.** Config `!!js` expressions evaluate as `with (entry.ctx) { eval(expr) }` (`vendor/loader/src/config/utils.ts`), so a bare identifier resolves against the entry's context and nothing else reaches it. The slot therefore cannot be removed while the app bundle is mounted from YAML; what changes is that it is now internal launcher↔app plumbing instead of a documented key a config author must wire correctly.

@@ -25,7 +25,7 @@ Status: implemented

 身份归属于 `agent-loop`，因为它才是创建所配置 agent 的插件；也因为 patch 会整体替换配置项的 `config`：重新指向 agent 配置项模型路由的 overlay 会抹掉启动器设置的身份键。参见[共享 base overlay note](../simplification/2026-07-29-shared-base-config-overlays.md)。

-`apps/cli` 铸造或选定 id，并依据它所复现的那次调用构建该行，与 `/resume` 的 execve 移交共用同一个 `resumeArgs` 助手，从而使打印出的命令与原地移交不会分歧。该行现在会在传入了 `--config` 时命名它，并在 meta 模式下复现 `dsh meta --resume <id>`——从而收口了 `dsh meta` note 所推迟的随 mode 变化的提示，在那里被复制的提示此前只有在检出目录中才有效。
+`apps/cli` 铸造或选定 id，并依据它所复现的那次调用构建该行，与 `/resume` 的 execve 移交共用同一个 `resumeArgs` 助手，从而使打印出的命令与原地移交不会分歧。该行会在传入了 `--config` 时将其写入命令。恢复始终通过 `dsh --resume <id>` 重新进入默认界面；`dsh meta` 不接受任何默认界面选项，并且总是启动新会话。

 **`ctx.provide` 是从启动器 argv 进入被 Loader 挂载的插件的唯一通道。** 配置的 `!!js` 表达式会以 `with (entry.ctx) { eval(expr) }`（`vendor/loader/src/config/utils.ts`）求值，因此一个裸标识符会针对该条目的上下文解析，别无它物可达。于是只要应用 bundle 仍从 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 .agents/notes/implemented/bug-fix/2026-07-30-source-checkout-workdir-distinction.md
+2026-07-30-source-checkout-workdir-distinction.md: ba6d9dd12b55a54d4ae8d2e91ad83ac3c1dc47fd
+2026-07-30-source-checkout-workdir-distinction.zh.md: ffc2ac7baa2b1bb8ce54607638c35869fc338825
@@ -0,0 +1,33 @@
+# Agent Note: Source checkout paths do not define working directories
+
+Status: implemented
+
+English | [中文](2026-07-30-source-checkout-workdir-distinction.zh.md)
+
+## Problem
+
+The `harness:source` prompt section follows the [source-location decision](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md), but its original wording called the checkout “your own source code” without distinguishing that path from the session workspace. In a normal TUI configuration that does not state `{{cwd}}` in its persona, this may be the only fixed absolute path near the start of the system prompt. DeepSeek V4 could therefore answer “what's the workdir?” with the harness checkout instead of determining the session's current working directory.
+
+A blanket statement that the checkout is not the working directory would also be false. `dsh meta` intentionally makes the source checkout both values.
+
+## Decision
+
+The section identifies the path as the “DeepSeek Harness implementation checkout.” It says that the checkout location and current working directory are separate values that may differ, forbids inferring the working directory from the checkout path, directs the model to use `pwd`, and limits the checkout's purpose to inspecting or extending DSH itself.
+
+The path derivation, global `harness:source` ownership, and `-99` ordering remain unchanged. Describing the values as conceptually separate rather than always unequal keeps the instruction accurate in both ordinary project sessions and `dsh meta`.
+
+## Verification
+
+The `dsh-app-boot` unit test pins the exact text and its ordering. The CLI keyless PTY smoke inspects the assembled request header. The TUI `source-checkout-workdir` snapshot mounts the section with `/opt/dsh-source`, asks “what's the workdir?” through a recorded DeepSeek V4 turn, and requires the replayed transcript to run `pwd` and report the generated workspace rather than the checkout.
+
+## Alternatives considered
+
+**Say that the checkout is never the working directory.** Rejected because `dsh meta` deliberately makes them the same path.
+
+**Put the current working directory in the global source section.** Rejected because the source section is launcher-global while the working directory belongs to each session; combining them would duplicate the loop's `cwd` ownership and make a stable source fact vary per agent.
+
+**Remove the source path from the prompt.** Rejected because self-referential DSH tools still need a reliable checkout location when the launcher starts from an unrelated project.
+
+## Consequences
+
+The prompt is longer and a direct working-directory question may spend one inexpensive `pwd` tool call. In exchange, the model no longer treats the harness implementation path as an implicit task workspace, while meta mode remains truthful when both values coincide.
@@ -0,0 +1,33 @@
+# Agent Note: 源码 checkout 路径不定义工作目录
+
+Status: implemented
+
+[English](2026-07-30-source-checkout-workdir-distinction.md) | 中文
+
+## Problem
+
+`harness:source` 提示词段遵循[源码位置决策](../../archived/feature/2026-07-21-dsh-system-prompt-source-path.md)，但原有措辞把 checkout 称为“你自己的源代码”，却没有区分该路径与会话 workspace。在 persona 不声明 `{{cwd}}` 的普通 TUI 配置中，这可能是系统提示词开头附近唯一固定的绝对路径。因此，DeepSeek V4 可能会直接用 harness checkout 回答“what's the workdir?”，而不是确定会话的当前工作目录。
+
+直接断言 checkout 不是工作目录同样不准确。`dsh meta` 会有意让源码 checkout 同时充当这两个值。
+
+## Decision
+
+该提示词段将路径标识为“DeepSeek Harness implementation checkout”。它说明 checkout 位置与当前工作目录是两个可能不同的值，禁止从 checkout 路径推断工作目录，指示模型使用 `pwd`，并限定该 checkout 只用于检查或扩展 DSH 自身。
+
+路径推导方式、全局 `harness:source` 所有权和 `-99` 顺序均保持不变。将两者描述为概念上独立、而不是始终不相等，使这条指令在普通项目会话和 `dsh meta` 中都准确。
+
+## Verification
+
+`dsh-app-boot` 单元测试固定了完整文本及其顺序。CLI 无密钥 PTY 冒烟测试检查组装后的请求 header。TUI 的 `source-checkout-workdir` 快照把该提示词段挂载为 `/opt/dsh-source`，通过录制的 DeepSeek V4 turn 提问“what's the workdir?”，并要求回放 transcript 运行 `pwd`，报告生成的 workspace 而不是 checkout。
+
+## Alternatives considered
+
+**声明 checkout 永远不是工作目录。**拒绝：`dsh meta` 会有意让它们指向同一路径。
+
+**把当前工作目录写入全局源码提示词段。**拒绝：源码提示词段由 launcher 全局持有，而工作目录属于各个会话；将两者合并会重复 loop 对 `cwd` 的所有权，还会让稳定的源码事实随 agent 变化。
+
+**从提示词中删除源码路径。**拒绝：launcher 从无关项目启动时，自引用 DSH 工具仍需要可靠的 checkout 位置。
+
+## Consequences
+
+提示词会变长，直接询问工作目录时可能多花一次廉价的 `pwd` 工具调用。作为交换，模型不再把 harness 实现路径当作隐含的任务 workspace；当 meta 模式使两个值重合时，提示词仍然准确。
@@ -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 .agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.md
+2026-07-31-fork-anchor-floors-to-event-seq.md: 2cc8d66942442aca69c930be880cc41d56bced13
+2026-07-31-fork-anchor-floors-to-event-seq.zh.md: 9f443f3d5165c01c6585d33bd6a37e90e9b3bf95
@@ -0,0 +1,35 @@
+# Agent Note: Fork anchor floors to an event seq
+
+Status: implemented
+
+English | [中文](2026-07-31-fork-anchor-floors-to-event-seq.zh.md)
+
+## Problem
+
+The fork button on a stopped assistant message did nothing at all — no child session, no error, no visible reaction.
+
+The frozen node behind that message is not a log event. Both the live projection and the history replay mint it with a flow-ordering seq of `turnEnd.seq - 0.9`, placing it strictly after every event of the aborted turn and before the next one, and the chat view hands that node seq to the fork entry point unchanged. `session.fork` accepts a non-negative integer on the wire, so a fractional anchor is rejected as invalid-params before the request reaches the host, and the chat entry's fork call swallows failures. Nothing distinguished the rejection from an inert button.
+
+The host's cut rule was never the obstacle. An aborted turn ends with a logged `turn/end` carrying reason `aborted`, so it is a completed prefix like any other and the anchor simply never arrived.
+
+## Decision
+
+`SessionsService.fork` floors `atSeq` before the RPC. The fractional-seq convention belongs to `dsh-client-runtime`, which mints it in both the live and replay projections, so the same package converts it back to a real event seq at the wire boundary instead of every UI caller remembering to. Integer anchors are unaffected.
+
+Flooring lands inside the anchor's own turn rather than clipping backward: every turn opens with `turn/start`, so `turnEnd.seq - 1` cannot itself be an earlier turn's `turn/end`. The host's first-`turn/end`-at-or-after rule then closes on the turn the reader clicked, matching the whole-turn semantics the message-level fork button already promised for completed turns.
+
+The apiproxy fork suite pins the host half of the contract: a floored anchor inside an aborted turn cuts through that turn and seeds the child with it.
+
+## Alternatives considered
+
+**Accept fractional `atSeq` on the wire.** Rejected because the host contract is an event seq, not a position on a continuum; the fractional form is one client's rendering convention, and admitting it would leave `atSeq` alone among the seq-carrying payloads in taking non-integers.
+
+**Hide the fork button on interrupted messages.** Rejected because forking a turn the reader deliberately stopped is one of the strongest reasons to fork at all, and the capability worked host-side the whole time.
+
+**Floor in the chat entry's `forkAt` adapter.** Rejected because `ui-conversation` consumes the fractional convention without owning it; any second fork entry point would have to rediscover the same conversion.
+
+## Consequences
+
+Forking from a stopped turn produces a child seeded through that turn's `turn/end`. The frozen partial text is reconstructed from chunk events and was never an `assistant/message`, so it stays out of the child's model transcript exactly as it stays out of the source's on resume — the child resumes from the same context the source would.
+
+Fork failures stay silent in the chat entry. This bug survived because that call site discards its rejection; surfacing fork errors in the UI is a separate change.
@@ -0,0 +1,35 @@
+# Agent Note: fork 锚点向下取整到事件 seq
+
+Status: implemented
+
+[English](2026-07-31-fork-anchor-floors-to-event-seq.md) | 中文
+
+## 问题
+
+在已停止的助手消息上点 fork 毫无反应——没有子会话，没有报错，也没有任何可见变化。
+
+这条消息背后的冻结节点并不是日志事件。实时投影和历史回放都用 `turnEnd.seq - 0.9` 这个排序坐标来生成它，让它严格落在被中断轮次的所有事件之后、下一轮之前，而 chat 视图原样把这个节点 seq 交给 fork 入口。`session.fork` 在 wire 上只接受非负整数，因此分数锚点在抵达 host 之前就被判为 invalid-params，而 chat 入口的 fork 调用又吞掉了失败。于是被拒绝和按钮失灵在表现上毫无区别。
+
+host 的切分规则从来不是障碍。被中止的轮次会记录一条 reason 为 `aborted` 的 `turn/end`，它和其他轮次一样是可切分的完整前缀——只是锚点根本没送到。
+
+## 决策
+
+`SessionsService.fork` 在发起 RPC 前对 `atSeq` 向下取整。分数 seq 这个约定属于 `dsh-client-runtime`，实时投影和回放投影都由它生成，因此也由同一个包在跨出 wire 边界时把它换回真实事件 seq，而不是要求每个 UI 调用方各自记得转换。整数锚点不受影响。
+
+向下取整落在锚点自身所在的轮次内，不会回退：每一轮都以 `turn/start` 开头，所以 `turnEnd.seq - 1` 不可能是上一轮的 `turn/end`。host 随后按「首个位于锚点或其之后的 `turn/end`」收口，命中的正是读者点击的那一轮，与消息级 fork 按钮在已完成轮次上一贯承诺的整轮语义一致。
+
+apiproxy 的 fork 用例固定了 host 这一侧的契约：落在被中止轮次内的取整锚点会切穿该轮，并把它种进子会话。
+
+## 备选方案
+
+**让 wire 接受分数 `atSeq`。** 否决：host 契约要的是事件 seq，而不是连续坐标上的某个位置；分数形式只是某一个客户端的渲染约定，一旦放行，`atSeq` 会成为所有携带 seq 的载荷中唯一容忍非整数的字段。
+
+**在已中断的消息上隐藏 fork 按钮。** 否决：从读者主动叫停的那一轮分叉，恰恰是最需要 fork 的场景之一，而 host 侧这个能力一直是好的。
+
+**在 chat 入口的 `forkAt` 适配器里取整。** 否决：`ui-conversation` 只是分数约定的消费方，并不拥有它；将来任何第二个 fork 入口都得把同样的转换重新发现一遍。
+
+## 影响
+
+从已停止的轮次 fork 会得到一个种子切到该轮 `turn/end` 的子会话。被冻结的残缺文本是从 chunk 事件重建出来的，从未成为 `assistant/message`，因此它不会进入子会话的模型上下文——正如源会话恢复时它也不会进入一样，子会话拿到的上下文与源会话一致。
+
+fork 失败在 chat 入口仍然是静默的。这个 bug 能存活至今，正是因为该调用点丢弃了自己的 rejection；把 fork 错误呈现到 UI 上是另一件事。
@@ -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 .agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.md
+2026-07-31-web-stop-preserves-queue.md: 943e95d6951a28929c4f8ce4d0b6e17224b08ede
+2026-07-31-web-stop-preserves-queue.zh.md: bbadd8adf8fd5bb0604ef87d322e48ce4c2ed759
@@ -0,0 +1,37 @@
+# Agent Note: Web stop preserves pending Queue
+
+Status: implemented
+
+English | [中文](2026-07-31-web-stop-preserves-queue.zh.md)
+
+## Problem
+
+The Web stop button reached `session.cancel`, which mapped to broad `agent.cancel({ kind: 'user' })`. During an active turn, ordinary composer submissions are already accepted as independently addressable Queue occurrences. Broad cancellation discarded every occurrence when the user intended to stop only the current generation, conflating turn interruption with the Queue's explicit delete operation.
+
+The browser cannot repair that loss by resending visible rows. It does not own their live `InboxItemId`, wake policy, or claim race, and a resend can duplicate work that the Host has already claimed.
+
+## Decision
+
+`session.cancel` is the Web Host API's active-turn stop. It calls `agent.cancel({ kind: 'user' }, { keepInbox: true })`, preserving pending inbox work while cooperatively aborting the current turn. The underlying option preserves queued and steering entries; the Web Queue projection continues to expose only queued entries.
+
+The AgentLoop starts no concurrent replacement turn. It closes and flushes the interrupted turn, reaches cancellation quiescence, and then claims the next waking queued occurrence through its existing FIFO driver. That claim emits `agent/inbox/dequeue`, so the Host's authoritative `session/queue` snapshot retires the claimed row and leaves the remaining tail visible. The browser neither resends nor promotes any row. Work that ignores cancellation delays this handoff until it settles.
+
+This mapping changes only the Host `session.cancel` endpoint used by Web clients. The default `Agent.cancel()` contract remains broad, ACP and TUI retain their existing cancellation policies, and `AgentHandle.dispose()` still clears pending work during teardown. Queue row removal remains the explicit Web action for discarding one pending occurrence.
+
+## Alternatives considered
+
+**Keep broad cancellation for the stop button.** Rejected because stopping one generation should not destroy independently queued user intent; the Queue already owns explicit deletion.
+
+**Resend the next row from the browser after cancellation.** Rejected because the Host owns occurrence identity and claim order. Client resubmission can duplicate work, reorder the FIFO, or race an authoritative dequeue.
+
+**Start the next turn before cancelled work reaches quiescence.** Rejected because two turns would concurrently mutate one session log and share Agent-owned resources. Cooperative cancellation waits truthfully for the active work to settle.
+
+**Add a wire option for broad versus preserving cancellation.** Rejected until the Web product has a separate “stop and clear Queue” interaction. The existing stop button has one policy, while per-row delete already supplies the current discard control.
+
+## Verification
+
+AgentLoop coverage holds an active model stream, queues two waking turns, cancels with `keepInbox`, and pins the aborted-then-completed turn reasons, FIFO user-message order, absence of discard events, and eventual idle state. The keyless Web scenario drives the built composition over HTTP/SSE: it stops one hung turn, observes the next queued occurrence start while the tail remains visible, stops that turn, and observes the final queued occurrence complete. Its accessibility snapshot pins the intermediate preserved-Queue state.
+
+## Consequences
+
+Web stop preserves accepted queued intent and advances it automatically after truthful cancellation settlement. Queue rows may remain visible while uncooperative active work winds down, and external steering preserved by the same inbox option can enter the next admitted turn even though Web does not render steering in QueueDock. A future bulk-clear interaction requires an explicit product action rather than overloading stop.
@@ -0,0 +1,37 @@
+# Agent Note: Web 停止操作保留待处理 Queue
+
+Status: implemented
+
+[English](2026-07-31-web-stop-preserves-queue.md) | 中文
+
+## 问题
+
+Web 停止按钮调用 `session.cancel`，后者映射到广义 `agent.cancel({ kind: 'user' })`。在活动轮次期间，普通 composer 提交已经被接纳为可独立寻址的 Queue 入队项。用户只想停止当前生成时，广义取消却会丢弃所有入队项，混淆了轮次中断与 Queue 的显式删除操作。
+
+浏览器无法通过重发可见行修复这一损失。它不拥有这些行的实时 `InboxItemId`、唤醒策略或认领竞态；重发还可能重复 Host 已认领的工作。
+
+## 决策
+
+`session.cancel` 是 Web Host API 的活动轮次停止操作。它调用 `agent.cancel({ kind: 'user' }, { keepInbox: true })`，在协作式中止当前轮次的同时保留待处理 inbox 工作。底层选项会保留 queued 和 steering 入队项；Web Queue 投影继续只暴露 queued 入队项。
+
+AgentLoop 不会启动并发的替代轮次。它会关闭并 flush 被中断的轮次，达到取消的完全停稳，然后通过现有 FIFO 驱动器认领下一个可唤醒的 queued 入队项。该认领会发出 `agent/inbox/dequeue`，因此 Host 的权威 `session/queue` 快照会退役已认领行，并使剩余队尾保持可见。浏览器既不重发，也不提升任何行。忽略取消的工作会延迟这一交接，直到该工作结算。
+
+该映射只更改 Web 客户端使用的 Host `session.cancel` 端点。`Agent.cancel()` 默认契约仍为广义取消，ACP 和 TUI 保留既有取消策略，`AgentHandle.dispose()` 在拆卸期间仍会清除待处理工作。移除 Queue 行仍是用于丢弃单个待处理入队项的显式 Web 操作。
+
+## 考虑过的替代方案
+
+**停止按钮继续使用广义取消。** 之所以否决：停止一次生成不应销毁已独立排队的用户意图；Queue 已拥有显式删除操作。
+
+**取消后由浏览器重发下一行。** 之所以否决：Host 拥有入队项标识和认领顺序。客户端重新提交可能重复工作、重排 FIFO，或与权威出队产生竞态。
+
+**被取消工作达到完全停稳之前启动下一轮次。** 之所以否决：两个轮次会并发修改同一会话日志，并共享 Agent 拥有的资源。协作式取消会如实等待活动工作结算。
+
+**为广义取消与保留式取消添加协议选项。** 之所以否决：在 Web 产品提供独立的「停止并清空 Queue」交互之前，不需要此选项。现有停止按钮只有一项策略，而逐行删除已提供当前的丢弃控件。
+
+## 验证
+
+AgentLoop 覆盖会保持一个活动模型流，将两个可唤醒轮次排队，使用 `keepInbox` 取消，并固定验证先中止、后完成的轮次原因，FIFO 用户消息顺序，不存在 discard 事件，以及最终空闲状态。无密钥 Web 场景通过 HTTP／SSE 驱动已组装组合：它停止一个卡住的轮次，观察队尾保持可见时下一个 queued 入队项开始，再停止该轮次，并观察最后一个 queued 入队项完成。其可访问性快照固定了中间的 Queue 保留状态。
+
+## 后果
+
+Web 停止会保留已接纳的排队意图，并在取消如实结算后自动推进。不配合取消的活动工作收尾时，Queue 行可能仍保持可见；由同一 inbox 选项保留的外部 steering 可以进入下一个已接纳轮次，尽管 Web 不会在 QueueDock 中渲染 steering。未来的批量清空交互需要显式的产品操作，而不是过载停止。
@@ -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 .agents/notes/implemented/feature/2026-07-28-dsh-guided-skill-session-commands.md
-2026-07-28-dsh-guided-skill-session-commands.md: a11807dca9ad1640857cd95a8b528df691b8a27e
-2026-07-28-dsh-guided-skill-session-commands.zh.md: e48420ed77496d8c336031473364f9008fccced7
+2026-07-28-dsh-guided-skill-session-commands.md: 8a091f7a03c85b0723d96b4fc546875a4e6c0f95
+2026-07-28-dsh-guided-skill-session-commands.zh.md: 861e6cf6cf07c41fde4f78b0833e3f8eb9508767
@@ -16,7 +16,7 @@ The seed reuses the existing TUI skill path, not a new one. `createTuiChat` alre

 **Freshness is gated in the launcher, not the TUI.** `runSkillSession` always mints a fresh session and provides the slot only when `resumeSessionId === undefined`, so a later `dsh --resume <id>` of that session is an ordinary TUI session with no re-injection. The TUI stays generic: it invokes whatever skill it is handed, once, at startup.

-**`migrate`/`upgrade` take no options.** Unlike `meta`, they carry no `--resume`, `--config`, or `-p`; a guided fresh-session entry has nothing to resume or reconfigure. Any leaked default-surface option fails loud, matching the `web`/`meta` rejection pattern in the Commander adapter. The two modes share one `SkillSessionInvocation` discriminant (`mode: 'migrate' | 'upgrade'`); `bin.ts` maps the mode to `dsh-${mode}`.
+**`migrate`/`upgrade` take no default-surface options** (`upgrade` additionally carries the [experimental gate](2026-07-31-experimental-subcommand-gate.md)'s `--experimental`). They carry no `--resume`, `--config`, or `-p`; a guided fresh-session entry has nothing to resume or reconfigure. Any leaked default-surface option fails loud, matching the `web`/`meta` rejection pattern in the Commander adapter. The two modes share one `SkillSessionInvocation` discriminant (`mode: 'migrate' | 'upgrade'`); `bin.ts` maps the mode to `dsh-${mode}`.

 The `dsh-migrate` skill is bundled under `skills/` (shipped through `DSH_BUNDLED_SKILL_DIR`, like `dsh-upgrade`). It asks which source agent (opencode/pi/Claude Code/Codex) if unstated, then maps each capability — workspace instructions, personal overlay, skills, hooks, MCP, API/env — to its DSH equivalent, grounded in the actual repo surfaces (the `hooks-claude`/`hooks-codex` bridges, `~/.dsh/{config.yaml,.env,AGENTS.md,skills/}`, `AGENTS.md`/`CLAUDE.md`, `mcporter`), and states plainly when a capability has no equivalent.

@@ -16,7 +16,7 @@ Status: implemented

 **新鲜性在启动器而非 TUI 中把关。** `runSkillSession` 总是创建全新会话，且仅在 `resumeSessionId === undefined` 时提供该槽，因此之后 `dsh --resume <id>` 恢复该会话时是普通 TUI 会话，不会重复注入。TUI 保持通用：它只是把接到的 skill 在启动时调用一次。

-**`migrate`/`upgrade` 不接受任何选项。** 与 `meta` 不同，它们不带 `--resume`、`--config` 或 `-p`；引导式全新会话入口没有可恢复或可重配置的内容。任何泄漏的默认界面选项都会明确报错，与 Commander 适配器中 `web`/`meta` 的拒绝模式一致。两个 mode 共用一个 `SkillSessionInvocation` 判别式（`mode: 'migrate' | 'upgrade'`）；`bin.ts` 将 mode 映射为 `dsh-${mode}`。
+**`migrate`/`upgrade` 不接受任何默认界面选项**（`upgrade` 另带[实验性门槛](2026-07-31-experimental-subcommand-gate.md)的 `--experimental`）。它们不带 `--resume`、`--config` 或 `-p`；引导式全新会话入口没有可恢复或可重配置的内容。任何泄漏的默认界面选项都会明确报错，与 Commander 适配器中 `web`/`meta` 的拒绝模式一致。两个 mode 共用一个 `SkillSessionInvocation` 判别式（`mode: 'migrate' | 'upgrade'`）；`bin.ts` 将 mode 映射为 `dsh-${mode}`。

 `dsh-migrate` skill 内置于 `skills/`（经 `DSH_BUNDLED_SKILL_DIR` 交付，与 `dsh-upgrade` 相同）。若未说明源 agent，它会先询问是哪个（opencode/pi/Claude Code/Codex），再把每项能力——workspace 指令、个人覆盖、skills、hooks、MCP、API/env——映射到对应的 DSH 等价物，并基于仓库实际的表面（`hooks-claude`/`hooks-codex` 桥、`~/.dsh/{config.yaml,.env,AGENTS.md,skills/}`、`AGENTS.md`/`CLAUDE.md`、`mcporter`）落地；当某能力无等价物时明确说明。

@@ -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 .agents/notes/implemented/feature/2026-07-28-dsh-meta-source-workspace.md
-2026-07-28-dsh-meta-source-workspace.md: d65e0e6ff092b63931dd58c52fa76fb76a071dff
-2026-07-28-dsh-meta-source-workspace.zh.md: 72a0c65e6eeda7d63dccc2306a3d7625cdb54362
+2026-07-28-dsh-meta-source-workspace.md: 95270a276cd5df03ffd2dfb419a33289d7b5b901
+2026-07-28-dsh-meta-source-workspace.zh.md: 645b20705386a3501d026fb58ca224c49cc69a17
@@ -14,36 +14,28 @@ English | [中文](2026-07-28-dsh-meta-source-workspace.zh.md)

 The target is `SOURCE_ROOT` in `apps/cli/src/tui.ts` — `fileURLToPath(new URL('../../..', import.meta.url))`, three hops up from `apps/cli/{src,lib}` — the same constant the `harness:source` prompt section already names, so the workspace and the path advertised to the model cannot drift. It follows the launcher's real path, so a PATH symlink through `current` resolves to whichever staging worktree is active.

-The mechanism is one `process.chdir(workspace)` inside `runTui`, guarded by a new optional third parameter that only `runMeta` passes. The cwd *is* the workspace seam in the shipped tree: `examples/tui-agent/cordis.yml` derives the session cwd (`!!js process.cwd()`), the `./.sessions` persistence root, and the HMR watch root (`root: ['.']`) from it, so one chdir moves all three together and meta sessions land in the checkout's gitignored `.sessions/`. It runs after both `.env` layers are loaded — the bin's invoking-directory load and the personal one — so the ambient > project > personal precedence is untouched. `DEFAULT_CONFIG` and `SOURCE_ROOT` are absolute and TUI mode passes no snapshot mode, so config resolution is chdir-independent.
+The mechanism is one `process.chdir(workspace)` inside `runTui`, guarded by an optional third parameter that only the `meta` dispatch passes. The cwd *is* the workspace seam in the shipped tree: `examples/tui-agent/cordis.yml` derives the session cwd (`!!js process.cwd()`), the `./.sessions` persistence root, and the HMR watch root (`root: ['.']`) from it, so one chdir moves all three together and meta sessions land in the checkout's gitignored `.sessions/`. It runs after both `.env` layers are loaded — the bin's invoking-directory load and the personal one — so the ambient > project > personal precedence is untouched. `DEFAULT_CONFIG` and `SOURCE_ROOT` are absolute and TUI mode passes no snapshot mode, so config resolution is chdir-independent.

-`meta` accepts only `--resume <id>`. `--config` would boot a foreign tree against the harness workspace, which is the `--config` case rather than this one; `-p` is not interactive. Both fail loud, as does an empty `--resume=` — matching the default surface, where a swallowed empty id would silently start a fresh session.
-
-**`meta` does not redeclare `--resume`.** Commander parses an option a subcommand shares with its parent into `program.opts()` and leaves the subcommand's own options object empty, so redeclaring it silently dropped the id (found by probing the adapter, not by review). The action reads `program.opts()`, which also accepts the flag on either side of the subcommand; `--help` still lists it among the parent's options.
+`meta` always starts a fresh session and accepts no default-surface options; its only option is the [experimental gate](2026-07-31-experimental-subcommand-gate.md)'s `--experimental`. `--config` would boot a foreign tree against the harness workspace, which is the default surface's `--config` case rather than this command; `-p` is not interactive, and resume re-enters the persisted session's own workspace through `dsh --resume <id>`. Any leaked default-surface option fails loud.

 ## Testing

-`apps/cli/tests/args.spec.ts` extends its two existing cases rather than adding a file: routing for `meta`, `meta --resume <id>`, and `--resume <id> meta` (pinning the shared-option behavior above), and exit-1 for `meta --resume=`, `meta --config`, and `meta -p`. `runMeta` itself is composition inside the module's existing `v8 ignore` block, like `runTui`.
+`apps/cli/tests/args.spec.ts` pins routing for `meta`, rejection of every leaked default-surface option, and rejection of the former `experimental-meta` name. The dispatch itself is composition inside `bin.ts`'s existing `v8 ignore` block.

 There is no keyless PTY smoke for this mode. The smoke harness gives each run a temp cwd, but `dsh meta` deliberately chdirs to the real checkout, so a smoke would write `.sessions/` into the live tree mid-test. Covering it properly needs an injectable target directory — a test-only seam this note declines to add for a one-line chdir.

 The mode was verified interactively instead. Launched from `$HOME`, a `pwd` tool call reports the checkout, git resolves to its branch, the session log lands under the checkout's `.sessions/` (leaving `~/.sessions` untouched and the tree free of unignored residue), and plain `dsh` from another directory still uses the invoking one.

-`dsh meta --resume <valid-id>` once started a *fresh* session instead of resuming — a pre-existing defect on the default surface, not one this mode introduced. [Launcher-owned resume identity](../architecture/2026-07-28-launcher-owned-resume-identity.md) found the cause and fixed it: a personal overlay had replaced the whole `tui-agent` config block, overwriting the shipped `resumeSessionId` intake with a read of an unset environment variable, so a valid id was silently ignored. Session identity is now a launcher-owned context slot that no config key can displace, and `meta` routes through it.
-
 ## Alternatives considered

 **Thread an explicit workspace through `boot` and the config tree.** Avoids mutating process-wide state, but the shipped config reads the cwd in three places (`!!js process.cwd()`, `persistenceRoot`, HMR `root`), so each would need its own new plumbing and config key to stay consistent. `chdir` before boot expresses "this is the workspace" once, at the seam that already means it.

-**A `--meta` flag on the default surface.** Rejected: the default surface is option-only so that subcommands do not collide with a positional, and a flag that silently relocates the workspace reads as a modifier of the current directory rather than a different target. `meta` alongside `web` matches the existing shape.
+**An `--experimental-meta` flag on the default surface.** Rejected: the default surface is option-only so that subcommands do not collide with a positional, and a flag that silently relocates the workspace reads as a modifier of the current directory rather than a different target. `meta` alongside `web` matches the existing shape.

 **Resolve `~/.dsh/source/current` instead of the launcher's own path.** Rejected: it would diverge from the `harness:source` prompt path whenever a non-installed checkout's `bin/dsh` is invoked directly, telling the model one source root while working in another.

-**Make the printed resume hint mode-aware.** Deferred here as a known cost, then delivered by [launcher-owned resume identity](../architecture/2026-07-28-launcher-owned-resume-identity.md): the exit line became a launcher-provided context slot, so meta mode prints `dsh meta --resume <id>` and a copied hint works from any directory. It previously came from static config as `dsh --resume {session}` and only worked when re-run from the checkout.
-
 ## Consequences

-Starting a session on dsh's own source is `dsh meta` from anywhere, and the workspace is guaranteed to be the same checkout the model is told about. Meta sessions are isolated in the checkout's `.sessions/`, so `dsh meta --resume` sees only other meta sessions — intended, since a session's logged cwd belongs to its workspace.
-
-The resume hint was this mode's original cost and is now resolved. [Launcher-owned resume identity](../architecture/2026-07-28-launcher-owned-resume-identity.md) made both the printed line and the in-place `/resume` handoff reproduce the mode as `dsh meta --resume <id>` from one shared argv helper, so a copied hint works from any directory and the handoff no longer depends implicitly on `execve` preserving the process cwd.
+Starting a session on dsh's own source is `dsh meta --experimental` from anywhere (or bare `dsh meta` under `DSH_EXPERIMENTAL=1`), and the workspace is guaranteed to be the same checkout the model is told about. The command always starts fresh; an ordinary `dsh --resume <id>` later restores the session and enters its persisted workspace.

 `runTui` gains an optional third parameter, so the workspace override is visible at the one function that owns TUI composition rather than hidden in a second copy of it.
@@ -14,36 +14,28 @@ Status: implemented

 目标是 `apps/cli/src/tui.ts` 中的 `SOURCE_ROOT`——`fileURLToPath(new URL('../../..', import.meta.url))`，从 `apps/cli/{src,lib}` 向上三级——与 `harness:source` 提示词段所用的常量完全相同，因此 workspace 与告知模型的路径不可能发生偏离。它跟随启动器的真实路径，所以经由 `current` 的 PATH 符号链接会解析到当前生效的那个 staging 工作树。

-机制是 `runTui` 内的一次 `process.chdir(workspace)`，由一个新的可选第三参数把守，只有 `runMeta` 会传入。在已交付的配置树中，cwd *就是* workspace 的接缝：`examples/tui-agent/cordis.yml` 由它派生出会话 cwd（`!!js process.cwd()`）、`./.sessions` 持久化根目录以及 HMR 监视根目录（`root: ['.']`），因此一次 chdir 会让三者一并移动，meta 会话则落在检出目录中被 gitignore 的 `.sessions/` 内。它在两层 `.env` 都加载之后执行——bin 对调用目录的加载与个人层加载——因此“环境中已有的值 > 项目 > 个人”的优先级不受影响。`DEFAULT_CONFIG` 与 `SOURCE_ROOT` 都是绝对路径，且 TUI 模式不传 snapshot mode，所以配置解析与 chdir 无关。
+机制是 `runTui` 内的一次 `process.chdir(workspace)`，由一个可选第三参数把守，只有 `meta` 分派会传入。在已交付的配置树中，cwd *就是* workspace 的接缝：`examples/tui-agent/cordis.yml` 由它派生出会话 cwd（`!!js process.cwd()`）、`./.sessions` 持久化根目录以及 HMR 监视根目录（`root: ['.']`），因此一次 chdir 会让三者一并移动，meta 会话则落在检出目录中被 gitignore 的 `.sessions/` 内。它在两层 `.env` 都加载之后执行——bin 对调用目录的加载与个人层加载——因此“环境中已有的值 > 项目 > 个人”的优先级不受影响。`DEFAULT_CONFIG` 与 `SOURCE_ROOT` 都是绝对路径，且 TUI 模式不传 snapshot mode，所以配置解析与 chdir 无关。

-`meta` 只接受 `--resume <id>`。`--config` 会以 harness workspace 启动其他配置树，那属于 `--config` 的场景而非本场景；`-p` 并非交互式。两者都会明确报错，空的 `--resume=` 亦然——与默认界面一致，在那里被吞掉的空 id 会静默开启一个新会话。
-
-**`meta` 不重新声明 `--resume`。** 对于子命令与父命令共享的选项，Commander 会将其解析进 `program.opts()`，而把子命令自身的 options 对象留空；因此重新声明会静默丢弃该 id（这是通过实测适配器发现的，而非评审发现）。action 读取 `program.opts()`，这同时也允许该标志出现在子命令的任意一侧；`--help` 仍会在父命令的选项中列出它。
+`meta` 始终启动新会话，且不接受任何默认界面选项；它唯一的选项是[实验性门槛](2026-07-31-experimental-subcommand-gate.md)的 `--experimental`。`--config` 会针对 harness workspace 启动其他配置树，那是默认界面的 `--config` 场景，而不是该命令的场景；`-p` 并非交互式，恢复则通过 `dsh --resume <id>` 重新进入已持久化会话自身的 workspace。任何泄漏的默认界面选项都会明确报错。

 ## Testing

-`apps/cli/tests/args.spec.ts` 扩展其已有的两个用例而非新增文件：`meta`、`meta --resume <id>` 与 `--resume <id> meta` 的路由（钉住上述共享选项行为），以及 `meta --resume=`、`meta --config`、`meta -p` 的退出码 1。`runMeta` 自身与 `runTui` 一样，属于该模块既有 `v8 ignore` 块内的组合代码。
+`apps/cli/tests/args.spec.ts` 钉住 `meta` 的路由、对每个泄漏的默认界面选项的拒绝，以及对旧名称 `experimental-meta` 的拒绝。该分派本身是 `bin.ts` 既有 `v8 ignore` 块内的组合代码。

 该 mode 没有 keyless PTY 冒烟测试。冒烟框架会为每次运行提供临时 cwd，但 `dsh meta` 刻意 chdir 到真实检出目录，因此冒烟测试会在测试中途把 `.sessions/` 写入实际工作树。要正确覆盖它需要一个可注入的目标目录——为了一行 chdir 而引入的测试专用 seam，本 note 不予采纳。

 取而代之的是交互式验证。从 `$HOME` 启动后，`pwd` 工具调用报告的是该检出目录，git 解析到其分支，会话日志落在该检出的 `.sessions/` 下（`~/.sessions` 未被触及，工作树也没有未被忽略的残留），并且从其他目录运行的普通 `dsh` 仍使用调用目录。

-`dsh meta --resume <有效 id>` 曾经开启一个*新*会话而非恢复——这是默认界面上既已存在的缺陷，并非本 mode 引入。[由启动器持有的会话身份与退出行](../architecture/2026-07-28-launcher-owned-resume-identity.md) 查明了原因并将其修复：一个个人 overlay 替换了整个 `tui-agent` 配置块，用对一个未设置的环境变量的读取覆盖了已交付的 `resumeSessionId` 入口，因此有效的 id 会被静默忽略。会话标识如今是一个启动器拥有的上下文槽位，没有任何配置键能取代它，而 `meta` 经由它进行路由。
-
 ## Alternatives considered

 **通过 `boot` 与配置树显式传递 workspace。** 这可避免修改进程级状态，但已交付的配置在三处读取 cwd（`!!js process.cwd()`、`persistenceRoot`、HMR `root`），每一处都需要各自新增管线与配置键才能保持一致。启动前 chdir 只在本就表达该含义的接缝上表达一次“这就是 workspace”。

-**在默认界面上加一个 `--meta` 标志。** 拒绝：默认界面是纯选项形式，以免子命令与位置参数冲突；而一个会静默改变 workspace 的标志读起来像是对当前目录的修饰，而非另一个目标。`meta` 与 `web` 并列符合既有形态。
+**在默认界面上加一个 `--experimental-meta` 标志。** 拒绝：默认界面是纯选项形式，以免子命令与位置参数冲突；而一个会静默改变 workspace 的标志读起来像是对当前目录的修饰，而非另一个目标。`meta` 与 `web` 并列符合既有形态。

 **解析 `~/.dsh/source/current` 而非启动器自身路径。** 拒绝：当直接调用某个非安装检出的 `bin/dsh` 时，它会与 `harness:source` 提示词路径产生偏离——告知模型一个源码根目录，却在另一个目录中工作。

-**让打印的恢复提示随 mode 变化。** 在此作为已知代价推迟，随后由 [由启动器持有的会话身份与退出行](../architecture/2026-07-28-launcher-owned-resume-identity.md) 交付：退出行变成了一个启动器提供的上下文槽位，因此 meta 模式打印 `dsh meta --resume <id>`，被复制的提示在任意目录下都有效。它此前来自静态配置，固定为 `dsh --resume {session}`，且只有在检出目录中重新运行才有效。
-
 ## Consequences

-在 dsh 自身源码上开启会话变成了在任意位置执行 `dsh meta`，且该 workspace 必然就是告知模型的那个检出目录。meta 会话被隔离在检出目录的 `.sessions/` 内，因此 `dsh meta --resume` 只能看到其他 meta 会话——这是预期行为，因为会话记录的 cwd 属于它的 workspace。
-
-恢复提示曾是本 mode 的原初代价，如今已解决。[由启动器持有的会话身份与退出行](../architecture/2026-07-28-launcher-owned-resume-identity.md) 让打印的行与原地 `/resume` 移交都从同一个共享的 argv 辅助函数将该 mode 复现为 `dsh meta --resume <id>`，因此被复制的提示在任意目录下都有效，且移交不再隐式依赖于 `execve` 保留进程 cwd。
+在 dsh 自身源码上开启会话变成了在任意位置执行 `dsh meta --experimental`（在 `DSH_EXPERIMENTAL=1` 下可直接执行 `dsh meta`），且该 workspace 必然就是告知模型的那个检出目录。该命令始终启动新会话；之后，普通的 `dsh --resume <id>` 会恢复该会话并进入其已持久化的 workspace。

 `runTui` 新增一个可选第三参数，因此 workspace 覆盖是在拥有 TUI 组合逻辑的那唯一一个函数上可见的，而不是隐藏在它的第二份副本中。
@@ -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 .agents/notes/implemented/feature/2026-07-29-addressable-queue-operations.md
-2026-07-29-addressable-queue-operations.md: 7a08b889c958e583dc430d33a1855fe3725f3d48
-2026-07-29-addressable-queue-operations.zh.md: 701b028c7494fd7cb608d05a5d170c9075b155d7
+2026-07-29-addressable-queue-operations.md: 57527730d0f43a3a6c7801806fb9cc136daa5f14
+2026-07-29-addressable-queue-operations.zh.md: 65617e492c16e41d19ba296c7d117f8a2771a67d
@@ -18,7 +18,7 @@ The Web queue rendered pending messages but could not edit or delete one row. `M

 **Queue addresses require a live Agent.** `session.updateQueue` queries only the mounted Agent registry and never resumes a cold session: an `InboxItemId` is process-local and cannot name work after restart or disposal. A missing Agent and a driver-claimed occurrence both return `queue-item-not-found`.

-**Web actions address Queue only.** The Host excludes pending steering from `session/queue`; steering retains its existing durable transcript path after consumption. QueueDock hides while empty, renders one pending occurrence directly, and defaults two or more occurrences to a collapsed `"<n> 条排队消息"` header that 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. Visible rows expose edit and delete, but no send-now control. The UI derives queue row and mutation types from the runtime `SessionFace` contract rather than importing the connection plugin, so plugin cooperation continues through services and snapshots. Edit is available only when all content blocks are text; the editor cannot silently drop non-text blocks. An editing row exposes only save and cancel, with Enter and Escape as their keyboard equivalents. Delete removes the exact occurrence.
+**Web actions address Queue only.** The Host excludes pending steering from `session/queue`; steering retains its existing durable transcript path after consumption. QueueDock hides while empty, renders one pending occurrence directly, and defaults two or more occurrences to a collapsed `"<n> 条排队消息"` header that 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. Visible rows expose edit and delete, but no send-now control. The UI derives queue row and mutation types from the runtime `SessionFace` contract rather than importing the connection plugin, so plugin cooperation continues through services and snapshots. Edit is available only when all content blocks are text; the editor cannot silently drop non-text blocks. An editing row exposes only save and cancel, with Enter and Escape as their keyboard equivalents. Delete removes the exact occurrence. The Web stop action preserves pending Queue work; AgentLoop claims the next waking occurrence only after the interrupted turn reaches quiescence, and its dequeue event retires that row without a browser resend.

 ## Alternatives considered

@@ -34,10 +34,10 @@ The Web queue rendered pending messages but could not edit or delete one row. `M

 ## Verification

-AgentLoop contract tests hold prompt admission while editing and removing exact queued occurrences, reject mutations of steering occurrences, and verify the resulting independent turn and terminal lifecycle events. Host schema and proxy tests cover queued-only authoritative snapshots, synchronous re-entrant mutation order, reconnect, cold-Agent rejection, typed not-found errors, and the RPC transport. Client runtime and QueueDock tests cover non-optimistic projection, single-row presentation, default multi-row collapse, interaction-forced visibility, reset after emptying, expansion, text-only editing, save and cancel affordances, removal, retirement races, and disabled mixed-content editing. Keyless browser scenarios capture the default collapsed header before expanding the queue and driving its exposed edit and delete actions through the built Web composition and real HTTP/SSE wire.
+AgentLoop contract tests hold prompt admission while editing and removing exact queued occurrences, reject mutations of steering occurrences, and verify the resulting independent turn and terminal lifecycle events. Host schema and proxy tests cover queued-only authoritative snapshots, synchronous re-entrant mutation order, reconnect, cold-Agent rejection, typed not-found errors, and the RPC transport. Client runtime and QueueDock tests cover non-optimistic projection, single-row presentation, default multi-row collapse, interaction-forced visibility, reset after emptying, expansion, text-only editing, save and cancel affordances, removal, retirement races, and disabled mixed-content editing. A keyless browser scenario captures the default collapsed header, drives edit and delete through the built Web composition and real HTTP/SSE wire, then stops consecutive active turns to prove the preserved FIFO advances without clearing its tail.

 ## Consequences

-Queued work gains precise row operations without becoming durable session history. Occurrence identity is a live process-local capability and disappears at claim, cancellation, disposal, or restart; reconnect recovers only queued items still held by the live Agent. Editing excludes mixed content until an editor can preserve every block, while pending steering remains outside this operation surface.
+Queued work gains precise row operations without becoming durable session history. Occurrence identity is a live process-local capability and disappears at claim, broad cancellation, disposal, or restart; the Web stop action preserves it until a later claim, while reconnect recovers only queued items still held by the live Agent. Editing excludes mixed content until an editor can preserve every block, while pending steering remains outside this operation surface.

 The protocol now carries full queue snapshots on each change. Queues are expected to remain short, so deterministic recovery and multi-client convergence are preferred over an incremental mutation protocol.
@@ -18,7 +18,7 @@ Web 队列能够渲染待处理消息，但无法编辑或删除其中某一行

 **Queue 寻址要求 Agent 存活。** `session.updateQueue` 只查询已挂载的 Agent 注册表，绝不恢复冷会话：`InboxItemId` 属于进程本地标识，无法在重启或资源释放后继续指向工作。Agent 缺失和单次入队项已被驱动器认领这两种情况都返回 `queue-item-not-found`。

-**Web 操作只面向 Queue。** Host 从 `session/queue` 中排除待处理 steering；steering 消费后仍沿用既有的持久 transcript（文本记录）路径。QueueDock 在队列为空时隐藏，只有一个待处理项时直接渲染该行，存在两个或更多待处理项时则默认收起为可展开或收起完整列表的 `"<n> 条排队消息"` 表头。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。可见行暴露编辑和删除操作，不提供立即发送控件。UI 从运行时 `SessionFace` 契约派生队列行与变更类型，而不是导入连接插件，因此插件仍通过服务和快照协作。仅当所有内容块都是文本时才提供编辑功能；编辑器不能静默丢弃非文本块。编辑中的行只展示保存和取消操作，对应的键盘操作分别是 Enter 和 Escape。删除会移除对应的精确入队项。
+**Web 操作只面向 Queue。** Host 从 `session/queue` 中排除待处理 steering；steering 消费后仍沿用既有的持久 transcript（文本记录）路径。QueueDock 在队列为空时隐藏，只有一个待处理项时直接渲染该行，存在两个或更多待处理项时则默认收起为可展开或收起完整列表的 `"<n> 条排队消息"` 表头。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。可见行暴露编辑和删除操作，不提供立即发送控件。UI 从运行时 `SessionFace` 契约派生队列行与变更类型，而不是导入连接插件，因此插件仍通过服务和快照协作。仅当所有内容块都是文本时才提供编辑功能；编辑器不能静默丢弃非文本块。编辑中的行只展示保存和取消操作，对应的键盘操作分别是 Enter 和 Escape。删除会移除对应的精确入队项。Web 停止操作会保留待处理 Queue 工作；只有在被中断轮次达到完全停稳后，AgentLoop 才认领下一个可唤醒入队项，其出队事件会退役该行，无需浏览器重发。

 ## 考虑过的替代方案

@@ -34,10 +34,10 @@ Web 队列能够渲染待处理消息，但无法编辑或删除其中某一行

 ## 验证

-AgentLoop 契约测试会在编辑和移除精确 queued 入队项时阻塞提示词接纳，拒绝对 steering 入队项的变更，并验证所得独立轮次及终态生命周期事件。Host schema 与代理测试覆盖仅含 queued 项的权威快照、同步可重入变更顺序、重连、拒绝冷 Agent、类型化 not-found 错误和 RPC 传输。客户端运行时和 QueueDock 测试覆盖非乐观投影、单行呈现、多行默认收起、交互期间强制保持可见、清空后重置、展开、仅文本编辑、保存与取消入口、移除、退役竞态，以及禁用混合内容编辑。无密钥浏览器场景会先捕获默认收起的表头，再展开队列，并通过构建后的 Web 组合和真实 HTTP／SSE 协议操作其公开的编辑和删除。
+AgentLoop 契约测试会在编辑和移除精确 queued 入队项时阻塞提示词接纳，拒绝对 steering 入队项的变更，并验证所得独立轮次及终态生命周期事件。Host schema 与代理测试覆盖仅含 queued 项的权威快照、同步可重入变更顺序、重连、拒绝冷 Agent、类型化 not-found 错误和 RPC 传输。客户端运行时和 QueueDock 测试覆盖非乐观投影、单行呈现、多行默认收起、交互期间强制保持可见、清空后重置、展开、仅文本编辑、保存与取消入口、移除、退役竞态，以及禁用混合内容编辑。一个无密钥浏览器场景会捕获默认收起的表头，通过构建后的 Web 组合和真实 HTTP／SSE 协议执行编辑和删除，随后连续停止活动轮次，证明保留的 FIFO 会继续推进且不清空队尾。

 ## 后果

-queued 工作获得精确的行操作，但不会因此成为持久会话历史。单次入队标识是进程本地的实时寻址凭据，会在认领、取消、dispose 或重启时消失；重连只能恢复仍由活跃 Agent 持有的 queued 项。编辑会排除混合内容，直至编辑器能够保留每个块；待处理 steering 则不属于此操作接口。
+queued 工作获得精确的行操作，但不会因此成为持久会话历史。单次入队标识是进程本地的实时寻址凭据，会在认领、广义取消、dispose 或重启时消失；Web 停止操作会将其保留到后续认领，而重连只能恢复仍由活跃 Agent 持有的 queued 项。编辑会排除混合内容，直至编辑器能够保留每个块；待处理 steering 则不属于此操作接口。

 现在，协议会在每次变更时携带完整队列快照。队列预期保持较短，因此系统优先选择确定性恢复和多客户端收敛，而非增量变更协议。
@@ -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 .agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md
+2026-07-30-versioned-tui-first-run-welcome.md: 5270c239f0bccbf58e68364e195ff2175355a816
+2026-07-30-versioned-tui-first-run-welcome.zh.md: cd132fde5ff0601cef6cd3cd433fdd15dc05f7f0
@@ -0,0 +1,43 @@
+# Agent Note: Versioned TUI first-run welcome
+
+Status: implemented
+
+English | [中文](2026-07-30-versioned-tui-first-run-welcome.zh.md)
+
+## Problem
+
+The shipped `dsh` terminal starts directly in the editor and gives first-time internal testers no durable orientation about the product's maturity or feedback channel. The existing one-line `welcome` banner subtitle cannot carry the supplied notice without crowding the normal session header, and putting onboarding in the session log would create a user turn or model-visible context that is unrelated to the user's work.
+
+The notice also needs a recognizable DeepSeek composition without copying another product's startup art or maintaining a hand-drawn approximation that drifts from the official mark.
+
+## Decision
+
+The official `dsh` launcher owns one versioned acknowledgement marker under the resolved `DSH_HOME`. It checks the immutable marker before boot, then mounts an effect-owned consumer of `ctx.tui.openOverlay()` only after the real TUI service is available. Enter is the sole acknowledgement action: the plugin creates and synchronizes the fixed per-version marker before closing. Escape and unrecognized input leave the overlay open; Ctrl+C and Ctrl+D use the normal exit path without acknowledging. Disposal waits for an acknowledgement already started by Enter, while disposal or process exit before Enter writes nothing. The version is part of the marker filename, so incrementing the centrally owned notice version presents materially revised copy once without migrating or rewriting an aggregate settings document.
+
+The marker is launcher state rather than session persistence because eligibility spans sessions and workspaces but is scoped to one Harness home. Each Enter syncs a random same-directory file before atomically replacing the fixed marker; concurrent launches publish the same immutable fact, so same-value last-writer-wins replacement has no lost-update shape and needs no lock or dependency on the settings stack. The notice never appends a session event, injects model context, or creates a user turn; resume therefore presents it only when the same Harness home has not acknowledged that version and never replays it from the session log.
+
+The supplied official `24x24` DeepSeek SVG is committed as the visual source. Static full, compact, and minimal terminal rasters sample that exact path at decreasing square resolutions; they do not redraw the contour. Unicode `▀`/`▄`/`█` cells preserve two vertical source pixels per terminal cell, while an explicitly ASCII-only locale uses the bit-equivalent `'`/`_`/`#` fallback. ANSI styling stays outside both the SVG and editable copy: `ctx.tui` supplies a semantic `brand` role, using the official `#4D6BFE` ink when truecolor is available, standard ANSI blue otherwise, and plain text when color is disabled. The normal startup banner retains its existing gradient.
+
+The overlay is centered and consumes the available terminal width, while its height follows actual content and treats 90% of the viewport only as an upper bound. Wide terminals place the full icon beside the title and prose; medium and narrow terminals stack the compact or minimal icon above them; low height removes the icon before reducing prose space. The prose scrolls while the title and only action remain fixed. Every locale uses the same centrally owned Chinese copy, and the quotation is promoted to its own visual paragraph without changing that string. Closing through Enter returns modal ownership to the existing FIFO manager, which restores the editor and leaves the normal startup banner, transcript, and focus behavior intact.
+
+## Verification
+
+Focused unit coverage pins the supplied SVG and Chinese copy hashes, version bumps, exclusive concurrent acknowledgement, malformed markers, persistence retry, Escape behavior, ASCII fallback, width-tier selection, bounded rendering, and low-height scrolling. Real Loader/PTY cases cover 60, 80, 120, and 160 columns plus a low-height viewport, emit semantic terminal snapshots, prove first launch then second-launch suppression under one `DSH_HOME`, and prove a resumed session appends no notice-derived user message or turn; ordinary terminal-exit lifecycle events remain unchanged.
+
+## Alternatives considered
+
+**Reuse the TUI `welcome` subtitle.** It is one transient header line whose normal job is to identify an untitled session. The required prose and action would either be clipped or permanently crowd ordinary launches.
+
+**Copy Claude Code's startup art or composition.** Its strong hierarchy is useful product evidence, but its graphic, layout, and brand treatment belong to another product. The official DeepSeek SVG provides a direct brand source, and the terminal composition is derived independently around this notice's copy and responsive constraints.
+
+**Hand-draw an original whale.** A freehand silhouette can be recognizable yet still disagree with the official mark's body, internal negative space, fin, and tail. Exact-path raster sampling keeps the terminal limitation explicit and makes every tier traceable to one source asset.
+
+**Store a boolean in session events or a shared settings document.** Session state has the wrong lifetime and would pollute replay or model-visible history. An aggregate document would require cross-process read-modify-write locking for one immutable fact; an atomically replaced version marker has no lost-update shape.
+
+**Allow Escape or a later-reminder action.** Either would make dismissal indistinguishable from acknowledgement or introduce reminder policy that the notice does not need. Normal process exit remains the abort path and leaves the version unacknowledged.
+
+## Consequences
+
+Each Harness home receives the notice once per copy version, only after a successful Enter acknowledgement. Maintainers can edit the all-locale Chinese wording and version in one small owner file, and can update the official SVG and derived static rasters in their separate visual owner without chasing snapshots for full prose copies.
+
+The terminal cannot display SVG vectors directly, so its faithful representation is resolution-bounded. Smaller tiers preserve the sampled silhouette but necessarily lose fine detail; low-height terminals prefer readable prose and an always-reachable action over brand art. The marker format is intentionally one-file-per-version during the pre-release period; old markers are harmless and no compatibility reader is required.
@@ -0,0 +1,43 @@
+# Agent Note: 版本化 TUI 首次运行欢迎页
+
+Status: implemented
+
+[English](2026-07-30-versioned-tui-first-run-welcome.md) | 中文
+
+## 问题
+
+已交付的 `dsh` 终端会直接进入编辑器，没有为首次使用的内部测试者提供持久的产品成熟度说明或反馈渠道指引。现有单行 `welcome` banner 副标题无法容纳指定通知，否则会挤占正常的会话 header；如果把 onboarding 写入会话日志，还会创建一个与用户工作无关的用户轮次或模型可见上下文。
+
+该通知还需要形成具有辨识度的 DeepSeek 视觉构图，同时不能复制其他产品的启动图形，也不能维护一份会偏离官方标志的手绘近似图。
+
+## 决策
+
+官方 `dsh` 启动器在解析后的 `DSH_HOME` 下持有一个版本化确认标记。它会在启动前检查该不可变标记，并仅在真实 TUI 服务可用后，挂载一个由 effect 持有的 `ctx.tui.openOverlay()` 消费方。Enter 是唯一确认操作：插件先创建并同步固定的逐版本标记，再关闭浮层。Escape 和无法识别的输入会让浮层保持打开；Ctrl+C 与 Ctrl+D 通过普通退出路径离开且不确认。资源释放会等待已经由 Enter 启动的确认任务；在按 Enter 前进行资源释放或退出进程不会写入任何内容。版本号属于标记文件名的一部分，因此只需递增集中持有的通知版本，即可让有实质修改的文案重新展示一次，无需迁移或改写聚合设置文档。
+
+该标记属于启动器状态，而非会话持久化，因为展示资格跨越会话与 workspace，但作用域仅限一个 Harness 主目录。每次 Enter 都会先同步一个同目录随机文件，再以原子方式替换固定标记；并发启动发布的是同一个不可变事实，因此同值的最后写入者胜出不会丢失更新，也无需加锁或依赖设置栈。该通知绝不追加会话事件、注入模型上下文或创建用户轮次；因此，恢复会话只会在同一个 Harness 主目录尚未确认该版本时展示通知，也绝不会从会话日志中回放通知。
+
+指定的官方 `24x24` DeepSeek SVG 作为视觉真源提交。静态的完整、紧凑和最小终端栅格图以逐级降低的方形分辨率对该精确路径取样，不会重新绘制轮廓。Unicode `▀`/`▄`/`█` 单元格让每个终端单元格保留两个垂直方向的源像素；明确仅支持 ASCII 的 locale 则使用位级等价的 `'`/`_`/`#` 回退。ANSI 样式与 SVG 和可编辑文案完全分离：`ctx.tui` 提供语义化 `brand` 角色，在真彩色可用时使用官方 `#4D6BFE` 色值，否则使用标准 ANSI 蓝色；禁用颜色时则使用纯文本。普通启动 banner 保留现有渐变。
+
+浮层居中显示，并使用可用的终端宽度；高度则跟随实际内容，仅将 viewport 的 90% 作为上限。宽终端将完整图标置于标题与正文旁边；中等和窄终端把紧凑或最小图标堆叠在正文上方；高度不足时，先移除图标，再减少正文空间。正文可以滚动，而标题和唯一操作保持固定。所有 locale 共用同一份集中持有的中文文案，引用内容会提升为独立的视觉段落，但不会改变该字符串。通过 Enter 关闭浮层后，模态所有权会交还给现有 FIFO 管理器；该管理器恢复编辑器，同时保持正常的启动 banner、transcript（文本记录）和焦点行为不变。
+
+## 验证
+
+聚焦单元测试固定指定 SVG 与中文文案的 hash、版本递增、并发独占确认、格式错误的标记、持久化重试、Escape 行为、ASCII 回退、宽度分级选择、有界渲染和低高度滚动。真实 Loader/PTY 用例覆盖 60、80、120、160 列以及一个低高度 viewport，产出语义终端快照，证明同一个 `DSH_HOME` 下首次启动后再次启动会抑制展示，并证明恢复会话不会追加任何由通知衍生的用户消息或轮次；普通终端退出的生命周期事件保持不变。
+
+## 曾考虑的替代方案
+
+**复用 TUI 的 `welcome` 副标题。** 它是一行瞬态 header，正常职责是标识无标题会话。所需正文和操作要么会被裁剪，要么会永久挤占普通启动界面。
+
+**复制 Claude Code 的启动图形或构图。** 其清晰的视觉层级是有用的产品证据，但图形、布局和品牌处理属于另一个产品。官方 DeepSeek SVG 提供直接的品牌来源，而终端构图围绕本通知的文案与响应式约束独立推导。
+
+**手绘原创鲸鱼。** 自由绘制的轮廓可以具有辨识度，却仍可能与官方标志的身体、内部负空间、鳍和尾部不一致。对精确路径进行栅格取样，可以明确呈现终端限制，并让每个分级都能追溯到同一个源资产。
+
+**在会话事件或共享设置文档中存储布尔值。** 会话状态的生命周期不正确，还会污染回放或模型可见历史。聚合文档为记录一个不可变事实，需要承担跨进程读取、修改、写入锁；以原子方式替换的版本标记不存在更新丢失问题。
+
+**允许 Escape 或稍后提醒操作。** 两者都会让取消与确认无法区分，或引入本通知并不需要的提醒策略。正常退出进程仍是中止路径，并会让该版本保持未确认状态。
+
+## 后果
+
+每个 Harness 主目录在每个文案版本中都会收到一次通知，且仅在用户成功按 Enter 确认后停止展示。维护者可以在一个小型 owner 文件中编辑所有 locale 共用的中文文案和版本，也可以在独立的视觉 owner 中更新官方 SVG 与衍生静态栅格图，无需到各个快照中查找完整正文副本。
+
+终端无法直接显示 SVG 矢量图，因此其忠实呈现受分辨率限制。较小分级会保留取样后的轮廓，但必然损失精细细节；低高度终端优先保障正文可读和操作始终可达，而非展示品牌图形。在预发布阶段，标记格式有意采用每个版本一个文件；旧标记无害，也无需兼容性读取器。
@@ -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 .agents/notes/implemented/feature/2026-07-31-experimental-subcommand-gate.md
+2026-07-31-experimental-subcommand-gate.md: 41447c2d23bc71964f990298de3c48b2fe7ef309
+2026-07-31-experimental-subcommand-gate.zh.md: 35598a61d98ff7490b34d175fc915043f5b5236a
@@ -0,0 +1,35 @@
+# Agent Note: experimental subcommands gate behind `--experimental` or `DSH_EXPERIMENTAL=1`
+
+Status: implemented
+
+English | [中文](2026-07-31-experimental-subcommand-gate.zh.md)
+
+## Problem
+
+The `meta` and `upgrade` entry points carried their experimental status in their names: `dsh experimental-meta` and `dsh experimental-upgrade`. The prefix made every invocation verbose, and renaming a command at stabilization would break every reference to it — muscle memory, scripts, and docs alike. The status belongs in an opt-in gate, not in the name.
+
+## Decision
+
+`dsh experimental-meta` is `dsh meta` and `dsh experimental-upgrade` is `dsh upgrade`. Each runs only when the invocation passes its `--experimental` flag or the environment carries `DSH_EXPERIMENTAL=1`; otherwise the command fails loud on stderr with exit 1, naming both opt-ins. Per the pre-release stance, the old names are gone with no aliases, and `args.spec.ts` pins their rejection.
+
+The gate has two halves with one owner each. The per-invocation half is a Commander `--experimental` option on each experimental subcommand, checked inside its action after the leaked-parent-option rejection. The environment half is a boolean `parseDshArgs` parameter: `bin.ts` reads `process.env.DSH_EXPERIMENTAL === '1'` at the process boundary (after `loadEnv`, so a project `.env` can set it) and passes the result down, so the parser's environment dependency is explicit in its signature and the tests need no env mutation. `1` is the only enabling value — the variable is an explicit opt-in, not a truthiness check.
+
+Stabilizing a command later means deleting its `--experimental` option and `requireExperimental` call; the name does not move.
+
+## Testing
+
+`args.spec.ts` pins both admit paths, bare-name rejection, old-name rejection, and leaked-option rejection under the env opt-in. `built-bin.e2e.ts` proves the assembled entry end to end: the gate diagnostic on stderr with exit 1, and that `--experimental`, `DSH_EXPERIMENTAL=1`, but not `DSH_EXPERIMENTAL=0`, reach the TUI's piped-stdio refusal — the next gate past this one. Both gated commands were also verified interactively in tmux: `dsh meta --experimental` and `DSH_EXPERIMENTAL=1 dsh meta` boot the TUI over the checkout, and `DSH_EXPERIMENTAL=1 dsh upgrade` seeds the `dsh-upgrade` skill.
+
+## Alternatives considered
+
+**Keep the `experimental-` name prefix.** Rejected by the user's direction: the prefix taxes every invocation, and stabilization would be a breaking rename instead of deleting a gate.
+
+**A parent-level `--experimental` flag (`dsh --experimental meta`).** Rejected: the default surface is deliberately option-only with `enablePositionalOptions`, so parent options that leak across the subcommand boundary are treated as mistyped invocations. A parent flag consumed only by two subcommands would be exactly the leaked-option shape the adapter rejects everywhere else.
+
+**Read `process.env` inside `parseDshArgs`.** Rejected: the repo validates at the process boundary and keeps typed seams pure; tests would have to mutate and restore `process.env` around each case.
+
+**Accept any non-empty `DSH_EXPERIMENTAL`.** Rejected: the telemetry switch prefers off-by-mistake for a privacy control, but an experimental gate is an acknowledgement — `DSH_EXPERIMENTAL=0` must not enable the commands it names.
+
+## Consequences
+
+Daily invocations shorten to `dsh meta --experimental` and `dsh upgrade --experimental`, and a developer who sets `DSH_EXPERIMENTAL=1` in their environment gets the bare `dsh meta`/`dsh upgrade`. `dsh --help` marks both commands `(experimental)`. The gate costs one extra flag or env var until a command stabilizes, at which point the gate is deleted and the name is already final.
@@ -0,0 +1,35 @@
+# Agent Note：实验性子命令由 `--experimental` 或 `DSH_EXPERIMENTAL=1` 把守
+
+Status: implemented
+
+[English](2026-07-31-experimental-subcommand-gate.md) | 中文
+
+## Problem
+
+`meta` 与 `upgrade` 两个入口把实验性状态写在名字里：`dsh experimental-meta` 和 `dsh experimental-upgrade`。前缀让每次调用都变得冗长，而在稳定时重命名命令会破坏对它的所有引用——肌肉记忆、脚本与文档皆然。这种状态应当由一个显式选择加入的门槛承载，而不是由名字承载。
+
+## Decision
+
+`dsh experimental-meta` 改为 `dsh meta`，`dsh experimental-upgrade` 改为 `dsh upgrade`。二者只有在调用时传入各自的 `--experimental` 标志、或环境中带有 `DSH_EXPERIMENTAL=1` 时才会运行；否则命令在 stderr 上明确报错并以退出码 1 结束，同时指明两种选择加入方式。依据发布前立场，旧名称已移除且没有别名，`args.spec.ts` 钉住了对它们的拒绝。
+
+该门槛分为两半，各有其归属。按调用的一半是每个实验性子命令上的 Commander `--experimental` 选项，在其 action 内、泄漏父级选项的拒绝之后检查。环境的一半是 `parseDshArgs` 的一个布尔参数：`bin.ts` 在进程边界读取 `process.env.DSH_EXPERIMENTAL === '1'`（在 `loadEnv` 之后，因此项目 `.env` 也可以设置它）并向下传递结果，因此解析器对环境的依赖显式体现在签名中，测试也无需改动环境变量。`1` 是唯一的启用值——该变量是显式的选择加入，而不是真值判断。
+
+之后要稳定某个命令，只需删除它的 `--experimental` 选项和 `requireExperimental` 调用；名字不再变动。
+
+## Testing
+
+`args.spec.ts` 钉住两条准入路径、裸名称拒绝、旧名称拒绝，以及在环境选择加入下对泄漏选项的拒绝。`built-bin.e2e.ts` 端到端地证明组装后的入口：stderr 上的门槛诊断与退出码 1，以及 `--experimental`、`DSH_EXPERIMENTAL=1`（而非 `DSH_EXPERIMENTAL=0`）会到达 TUI 的管道 stdio 拒绝——即此门之后的下一道关卡。两个被把守的命令还在 tmux 中做了交互式验证：`dsh meta --experimental` 与 `DSH_EXPERIMENTAL=1 dsh meta` 以检出目录为 workspace 启动 TUI，`DSH_EXPERIMENTAL=1 dsh upgrade` 播种 `dsh-upgrade` skill。
+
+## Alternatives considered
+
+**保留 `experimental-` 名称前缀。** 按用户的指示拒绝：前缀让每次调用都付出代价，稳定时也会变成破坏性的重命名，而不是删除一个门槛。
+
+**父级 `--experimental` 标志（`dsh --experimental meta`）。** 拒绝：默认界面刻意保持纯选项形式并启用 `enablePositionalOptions`，跨子命令边界泄漏的父级选项都被视为拼错的调用。一个只被两个子命令消费的父级标志，恰恰就是适配器在其他所有地方都拒绝的泄漏选项形态。
+
+**在 `parseDshArgs` 内部读取 `process.env`。** 拒绝：本仓库在进程边界做验证，并保持类型化接缝的纯粹性；否则测试必须在每个用例前后修改并恢复 `process.env`。
+
+**接受任何非空的 `DSH_EXPERIMENTAL`。** 拒绝：遥测开关作为隐私控制倾向于误关而非误开，但实验性门槛是一种确认——`DSH_EXPERIMENTAL=0` 绝不能启用它所指名的命令。
+
+## Consequences
+
+日常调用缩短为 `dsh meta --experimental` 和 `dsh upgrade --experimental`；在环境中设置了 `DSH_EXPERIMENTAL=1` 的开发者可以直接使用 `dsh meta`/`dsh upgrade`。`dsh --help` 将这两个命令标注为 `(experimental)`。在命令稳定之前，门槛的代价是一个额外的标志或环境变量；稳定时删除门槛即可，名字已是最终形态。
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-2026-06-20-public-agent-stop-surface.md: e22c4389df18f3c9ca96763fc097eabefcc5b761
-2026-06-20-public-agent-stop-surface.zh.md: e2647b498a8c906579b4fd2b50f94d1c326fe784
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.md
+2026-06-20-public-agent-stop-surface.md: 7e8f6f691c999fd78c9b4133eaeac40f2d1c1ba9
+2026-06-20-public-agent-stop-surface.zh.md: 041d666eb817450add2d7a1746f7f5b81223568a
@@ -8,15 +8,15 @@ English | [中文](2026-06-20-public-agent-stop-surface.zh.md)

 ## Problem

-The public `Agent` handle exposed two overlapping ways to stop in-flight work: step-only `abort()` and queue-aware `cancel()`. The former preserved queued input while the latter clears queued and steering work and aborts the active turn. In production, ACP uses `cancel()` for `session/cancel`, while lifecycle owners tear down agents through `AgentHandle.dispose()`. No production caller needs a bare step-only abort.
+The public `Agent` handle exposed two overlapping ways to stop in-flight work: step-only `abort()` and queue-aware `cancel()`. The former preserved queued input while the latter originally only exposed its broad default, which clears queued and steering work while aborting the active turn. `cancel(cause, { keepInbox: true })` now covers the production Web stop policy without exposing the private turn holder; ACP retains broad cancellation, while lifecycle owners tear down agents through `AgentHandle.dispose()`. No production caller needs a bare step-only abort.

-The behavioral distinction is real, but no shipping code needs the narrower operation. AgentLoop instead owns one private cancellation holder for the whole turn. `cancel(cause?)` carries a typed `user` or `parent` cause, defaults to `user`, and drops pending input; disposal remains a separate lifecycle interruption. The complete ownership and propagation contract lives in the [explicit turn cancellation RFC](../architecture/2026-07-16-explicit-turn-cancellation.md).
+The behavioral distinction is real, but no shipping code needs a separate narrower verb. AgentLoop owns one private cancellation holder for the whole turn. `cancel(cause, options?)` carries an explicit typed `user` or `parent` cause; its broad default drops pending input, while `keepInbox` preserves pending work for later turns. Disposal remains a separate lifecycle interruption. The complete ownership and propagation contract lives in the [explicit turn cancellation RFC](../architecture/2026-07-16-explicit-turn-cancellation.md).

-The extra surface area made the loop carry a public verb that is mostly a teardown internal: `abort()` had to be documented as distinct from queue-aware cancellation even though a UI cancellation almost always wants the broader operation.
+The extra surface area made the loop carry a public verb that was mostly a teardown internal. An options-bearing `cancel()` expresses caller policy without exposing a second holder-shaped operation.

 ## Decision

-`cancel()` is the only public *stop* primitive on `Agent`. Lifecycle owners use `AgentHandle.dispose()` to stop and unregister an agent; non-owners use `cancel()` to abandon current and queued work. The implementation keeps a private turn cancellation holder, but it is not part of the plugin-facing `Agent` contract.
+`cancel()` is the only public *stop* primitive on `Agent`. Lifecycle owners use `AgentHandle.dispose()` to stop and unregister an agent; non-owners use broad `cancel()` to abandon current and queued work or `keepInbox` to abort the active turn while retaining pending work. The implementation keeps a private turn cancellation holder, but it is not part of the plugin-facing `Agent` contract. The [Web stop decision](../bug-fix/2026-07-31-web-stop-preserves-queue.md) is the production `keepInbox` consumer.

 `whenIdle()` is **retained** as the public quiescence-observation primitive (resolve once the agent settles out of `running`, resolve immediately when already idle, await the loop exit when disposed). It is not a stop verb; it is how a non-owner observes the stop *completing* without disposing the agent. Its live consumers are ACP and agent tests that await settlement through this public seam (`packages/acp/acp/tests`, `packages/core/agent-loop/tests`); the production ACP bridge owns its agents and tears them down through `AgentHandle.dispose()`, so `packages/acp/acp/src` itself has no `whenIdle()` call.

@@ -28,11 +28,11 @@ Public `abort()` is absent, and the disposer remains async and waits for the loo

 ## Verification

-`Agent` exposes no public `abort()` while `cancel()`, `whenIdle()`, and `steer()` remain; ACP cancellation calls `cancel()`; teardown awaits quiescence through handle disposal, with `whenIdle()` resolving on quiescence for non-owner observers; and the suites cover cancellation and disposal as the two supported stop paths.
+`Agent` exposes no public `abort()` while `cancel()`, `whenIdle()`, and `steer()` remain; ACP cancellation calls broad `cancel()`, Web stop calls `cancel(..., { keepInbox: true })`, and teardown awaits quiescence through handle disposal. `whenIdle()` resolves on quiescence for non-owner observers, and the suites cover cancellation and disposal as the two supported stop paths.

 ## Consequences

-A future plugin cannot abort only the current model/tool step while preserving queued prompts through the public interface. If that use case becomes real, it should return with a named consumer and a narrower contract. Today it is latent generality that keeps a private loop mechanic public.
+A plugin can abort the active turn while preserving queued prompts through `keepInbox`, but it cannot abort only one model/tool step while leaving that turn running. A step-only use case would need a named consumer and a narrower contract; exposing the private loop mechanic remains unjustified.

 ## Related

@@ -8,15 +8,15 @@ Status: implemented

 ## 问题

-公共 `Agent` handle 暴露了两种相互重叠的在途工作停止方式：仅针对步骤的 `abort()` 和感知队列的 `cancel()`。前者保留已排队输入，后者则清除已排队和 steering（中途引导）工作，并中止活动轮次。在生产中，ACP（Agent Client Protocol）对 `session/cancel` 使用 `cancel()`，生命周期拥有者则通过 `AgentHandle.dispose()` 拆除 agent（智能体）。没有生产调用方需要一个裸的、仅针对步骤的 abort。
+公共 `Agent` handle 暴露了两种相互重叠的在途工作停止方式：仅针对步骤的 `abort()` 和感知队列的 `cancel()`。前者保留已排队输入，后者原本只暴露广义默认行为，该行为会清除已排队和 steering（中途引导）工作，同时中止活动轮次。`cancel(cause, { keepInbox: true })` 现在无需暴露私有轮次 holder 即可覆盖生产环境的 Web 停止策略；ACP 保留广义取消，生命周期拥有者则通过 `AgentHandle.dispose()` 拆除 agent（智能体）。没有生产调用方需要一个裸的、仅针对步骤的 abort。

-行为差异确实存在，但已发布代码不需要较窄的操作。AgentLoop 改为为整个轮次拥有一个私有取消 holder。`cancel(cause?)` 携带类型化的 `user` 或 `parent` 原因，默认为 `user`，并丢弃待处理输入；释放仍是单独的生命周期中断。完整的归属与传播契约位于[显式轮次取消 Agent Note（agent 决策记录）](../architecture/2026-07-16-explicit-turn-cancellation.md)。
+行为差异确实存在，但已发布代码不需要独立的更窄动词。AgentLoop 为整个轮次拥有一个私有取消 holder。`cancel(cause, options?)` 携带显式且类型化的 `user` 或 `parent` 原因；其广义默认行为丢弃待处理输入，`keepInbox` 则为后续轮次保留待处理工作。资源释放仍是单独的生命周期中断。完整的归属与传播契约位于[显式轮次取消 Agent Note（agent 决策记录）](../architecture/2026-07-16-explicit-turn-cancellation.md)。

-多余的公开接口使得循环不得不承载一个本质上属于内部拆卸的公开动词：`abort()` 必须被文档描述为有别于队列感知的取消，尽管 UI 取消几乎总是需要更广泛的操作。
+多余的公开接口使循环承载了一个本质上属于内部拆卸的公开动词。带选项的 `cancel()` 可以表达调用方策略，而无需暴露第二个 holder 形态的操作。

 ## 决策

-`cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用 `cancel()` 放弃当前和已排队工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 契约。
+`cancel()` 是 `Agent` 上唯一的公共*停止*原语。生命周期拥有者使用 `AgentHandle.dispose()` 停止并注销 agent；非拥有者使用广义 `cancel()` 放弃当前和已排队工作，或使用 `keepInbox` 中止活动轮次并保留待处理工作。实现保留一个私有轮次取消 holder，但它不属于面向插件的 `Agent` 契约。[Web 停止决策](../bug-fix/2026-07-31-web-stop-preserves-queue.md)是生产环境中的 `keepInbox` 消费方。

 `whenIdle()` **保留**为公开的完全停稳观测原语（agent 从 `running` 状态稳定后 resolve，已处于 idle 时立即 resolve，dispose 后等待循环退出）。它不是停止动词；它是非所有者在不 dispose agent 的前提下观测停止*完成*的方式。它的活跃消费方是 ACP 和通过此公开 seam 等待结算的 agent 测试（`packages/acp/acp/tests`、`packages/core/agent-loop/tests`）；生产环境的 ACP 桥接层拥有其 agent 并通过 `AgentHandle.dispose()` 销毁它们，因此 `packages/acp/acp/src` 本身没有 `whenIdle()` 调用。

@@ -28,11 +28,11 @@ Status: implemented

 ## 验证

-`Agent` 不再暴露公开的 `abort()`，而 `cancel()`、`whenIdle()` 和 `steer()` 保留；ACP 取消调用 `cancel()`；拆卸通过 handle disposal 等待完全停稳，`whenIdle()` 在完全停稳时为非所有者观测者 resolve；测试套件覆盖取消和 disposal 作为两条受支持的停止路径。
+`Agent` 不再暴露公开的 `abort()`，而 `cancel()`、`whenIdle()` 和 `steer()` 保留；ACP 取消调用广义 `cancel()`，Web 停止调用 `cancel(..., { keepInbox: true })`，拆卸则通过 handle disposal 等待完全停稳。`whenIdle()` 在完全停稳时为非所有者观测者 resolve；测试套件覆盖取消和资源释放这两条受支持的停止路径。

 ## 后果

-未来的插件无法通过公开接口仅中止当前模型/工具步骤而保留队列中的提示词。如果该用例变为现实需求，它应当带着一个具名消费方和更窄的契约回归。目前它是将私有循环机制保持公开的潜在泛化。
+插件可以通过 `keepInbox` 在保留已排队提示词的同时中止活动轮次，但不能只中止某一个模型／工具步骤而让该轮次继续运行。仅步骤用例需要具名消费方和更窄契约；暴露私有循环机制仍缺乏正当理由。

 ## 相关

@@ -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 .agents/notes/implemented/simplification/2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md
+2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md: 6f397668106a6c74f327fc799327752c54824d8c
+2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md: f127bd57006747465a1ece87406f5f97086b6a34
@@ -0,0 +1,38 @@
+# Agent Note: Web UI drops steer entry and interjection chrome
+
+Status: implemented
+
+English | [中文](2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.zh.md)
+
+## Problem
+
+Mid-turn steering is a host/agent-loop capability (`mode:'steer'`, durable `steering/message`). The Web product already locked the composer while a turn runs and never shipped a queue/steer menu, yet the client still threaded `'queue' | 'steer'` through the input machine, `conversation.send`, and locale keys, and rendered consumed steering as a badged 「插话」/「Interjection」 bubble. That left a half-built UI surface: an unused submit mode, a product label for a gesture users cannot perform, and e2e goldens that pinned chrome the product does not own.
+
+## Decision
+
+Keep host and runtime steering intact. Remove only the Web UI entry and chrome:
+
+- `InputMachine` / `SessionInput` / `InputActions.submit` / hub `defaultSink` are queue-only; they always call `session.prompt(..., 'queue')`.
+- `ConversationService.send(text)` drops its mode argument and always queues.
+- `MessageItem`'s `steering` arm still folds durable `steering/message` content into a plain right-aligned bubble (no badge, no user IconActions) so external/host steers stay visible on replay.
+- Delete `message.steering` locale strings and the unused badge CSS.
+- The web steering e2e still POSTs `mode:'steer'` over `/api/session.prompt` and asserts durable + model-visible obedience; it no longer expects interjection chrome. Update [web input machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) fact lines to match.
+
+## Alternatives considered
+
+**Delete host steering entirely.** Out of scope; the user asked only for Web UI display and entry. Agent-loop drain, session events, and the wire mode remain load-bearing for ACP/TUI/automation.
+
+**Hide `steering/message` from the transcript.** Would lie on replay when an external client steers; rejected in favor of a plain bubble.
+
+**Keep the mode parameter but only ever pass `'queue'`.** Leaves dead API surface and tests that invent `'steer'` paths the composer cannot reach.
+
+## Consequences
+
+- Web users cannot steer from the composer or `ctx.conversation.send`; stop/cancel and Queue remain the only mid-turn controls.
+- Host-wire and non-Web clients can still steer; the Web client shows those messages without labeling them as interjections.
+- Reintroducing a dedicated steer UI would need a new product decision; do not revive the mode union or badge without one.
+
+## Testing
+
+- `packages/client/ui-conversation` unit/jsdom coverage: input machine enter/sink, ConversationService routing, MessageItem steering arm (no 「插话」), InputBar submit.
+- `apps/web/tests/steering.e2e.ts` keyless replay plus updated `settled.expected.md` (steer text without badge).
@@ -0,0 +1,38 @@
+# Agent Note: Web UI 去掉 steer 入口与插话 chrome
+
+Status: implemented
+
+[English](2026-07-31-web-ui-no-steer-entry-or-interjection-chrome.md) | 中文
+
+## 问题
+
+中途 steering 是 host／agent-loop 能力（`mode:'steer'`、持久 `steering/message`）。Web 产品已在 turn 运行中锁定 composer，且从未交付排队／steer 菜单，但客户端仍把 `'queue' | 'steer'` 穿进 input machine、`conversation.send` 与 locale 键，并把已消费的 steering 渲染成带「插话」／「Interjection」徽章的气泡。这留下半成品 UI：用不到的提交 mode、用户做不到的手势却有产品文案，以及把产品并不拥有的 chrome 钉死在 e2e golden 上。
+
+## 决策
+
+保留 host 与 runtime 的 steering。只去掉 Web UI 入口与 chrome：
+
+- `InputMachine`／`SessionInput`／`InputActions.submit`／hub `defaultSink` 仅 queue；始终调用 `session.prompt(..., 'queue')`。
+- `ConversationService.send(text)` 去掉 mode 参数，始终排队。
+- `MessageItem` 的 `steering` 分支仍把持久 `steering/message` 内容折成右对齐普通气泡（无徽章、无用户 IconActions），以便外部／host steer 在回放时仍可见。
+- 删除 `message.steering` locale 字符串与未使用的徽章 CSS。
+- web steering e2e 仍通过 `/api/session.prompt` POST `mode:'steer'`，并断言持久化与模型可见服从；不再期望插话 chrome。同步更新 [web input machine note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) 中的事实行。
+
+## 曾考虑的替代方案
+
+**整段删除 host steering。** 超出范围；用户只要求清 Web UI 展示与入口。agent-loop 排空、session 事件与线缆 mode 对 ACP／TUI／自动化仍是承重能力。
+
+**在 transcript 中隐藏 `steering/message`。** 外部客户端 steer 时回放会撒谎；改为普通气泡。
+
+**保留 mode 参数但永远只传 `'queue'`。** 留下死 API 面与只会虚构 composer 到不了的 `'steer'` 路径的测试。
+
+## 后果
+
+- Web 用户无法从 composer 或 `ctx.conversation.send` steer；中途控制只剩停止／取消与 Queue。
+- Host 线缆与非 Web 客户端仍可 steer；Web 客户端展示这些消息时不再标成插话。
+- 若要重新引入专用 steer UI，需要新的产品决策；没有决策就不要复活 mode 联合类型或徽章。
+
+## 测试
+
+- `packages/client/ui-conversation` unit／jsdom 覆盖：input machine enter／sink、ConversationService 路由、MessageItem steering 分支（无「插话」）、InputBar submit。
+- `apps/web/tests/steering.e2e.ts` 无密钥回放，以及更新后的 `settled.expected.md`（有 steer 正文、无徽章）。
@@ -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 README.md
-README.md: e297ff32c4086df0fcc17310dabbebfaae2691ca
-README.zh.md: 5995acdf8d1c5a9aab5dcae39f3ab1e3c8b0a679
+README.md: 8ecd0928ee630eeca1cb8ce8b9c59d19f6984969
+README.zh.md: 9ffb3b3086415550df4a0f776c7b91c94122dd97
@@ -16,10 +16,12 @@ It uses an architecture where **everything is a plugin**.

 ## Install

-Install `dsh` with one command:
+Clone the repository, then run the installer:

 ```sh
-curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh
+git clone <repo-url>
+cd deepseek-harness
+scripts/install.sh
 ```

 The installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, prompts for a DeepSeek API key, then lets you launch the Web UI or TUI. Choosing Web UI builds the required repository artifacts first.
@@ -16,10 +16,12 @@ DeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源

 ## 安装

-使用一条命令安装 `dsh`：
+克隆仓库，然后运行安装器：

 ```sh
-curl -fsSL https://raw.githubusercontent.com/deepseek-harness/deepseek-harness/master/scripts/install.sh | sh
+git clone <repo-url>
+cd deepseek-harness
+scripts/install.sh
 ```

 安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，随后让你选择启动 Web UI 或 TUI。选择 Web UI 时，安装器会先构建所需的仓库产物。
@@ -58,6 +58,7 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`immer`](https://github.com/immerjs/immer) | MIT |
 | [`js-yaml`](https://github.com/nodeca/js-yaml) | MIT |
 | [`jsonc-parser`](https://github.com/microsoft/node-jsonc-parser) | MIT |
+| [`katex`](https://github.com/KaTeX/KaTeX) | MIT |
 | [`koffi`](https://github.com/Koromix/koffi) | MIT |
 | [`mdast-util-from-markdown`](https://github.com/syntax-tree/mdast-util-from-markdown) | MIT |
 | [`mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm) | MIT |
@@ -68,7 +69,9 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | [`react`](https://github.com/facebook/react) | MIT |
 | [`react-dom`](https://github.com/facebook/react) | MIT |
 | [`react-markdown`](https://github.com/remarkjs/react-markdown) | MIT |
+| [`rehype-katex`](https://github.com/remarkjs/remark-math/tree/main/packages/rehype-katex) | MIT |
 | [`remark-gfm`](https://github.com/remarkjs/remark-gfm) | MIT |
+| [`remark-math`](https://github.com/remarkjs/remark-math/tree/main/packages/remark-math) | MIT |
 | [`saxes`](https://github.com/lddubeau/saxes) | ISC |
 | [`shiki`](https://github.com/shikijs/shiki) | MIT |
 | [`supports-color`](https://github.com/chalk/supports-color) | MIT |
@@ -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 apps/cli/README.md
-README.md: 43524950ae7d3379406a0c859b6449f0697d204b
-README.zh.md: 01954f1229a6f4d076155d42566ed29d568631ca
+README.md: 3d3e5413f208e57ba03b5b51c670e6eed4bad373
+README.zh.md: 66d467995a2257af067a4d877fcba426e88e840d
@@ -3,7 +3,7 @@
 English | [中文](README.zh.md)


-Argv is parsed once through a [Commander](https://github.com/tj/commander.js) adapter ([`src/args.ts`](src/args.ts)): one program whose default (no subcommand) is the TUI/headless surface (`--config`, `-p`/`--prompt`, `--resume`, `--dump-config`, `--dump-default-config`), whose `meta` subcommand is the same TUI over this checkout, whose `upgrade` subcommand is an option-less guided-session entry, and whose `web` subcommand is the browser UI. `src/bin.ts` switches on the resolved mode and dynamic-imports only that mode's module. `dsh --help` lists every mode and `dsh web --help` renders the web usage, `dsh --version` prints this app's version, and an unknown option or a mistyped `--resume` fails loud (stderr, exit 1) instead of misrouting. Every subcommand that shares no option with the default surface — `upgrade`, `web`, `meta` — rejects a leaked `--config`/`-p`/`--resume`/dump flag rather than running and dropping it. `dsh web`'s `--host`/`--port` are unvalidated pass-through overrides: the `dsh-host-webserver` schema is the single source of both the default (the shipped Web overlay value when a flag is absent) and validity, and rejects a bad value at boot. `--trusted-host` appends named authorities for the /api browser-trust fence; an all-interfaces bind additionally derives the machine's LAN IP literals itself ([`src/app-cli-entry.ts`](src/app-cli-entry.ts)), so the printed LAN URL works without flags.
+Argv is parsed once through a [Commander](https://github.com/tj/commander.js) adapter ([`src/args.ts`](src/args.ts)): one program whose default (no subcommand) is the TUI/headless surface (`--config`, `-p`/`--prompt`, `--resume`, `--dump-config`, `--dump-default-config`), whose `meta` subcommand is the same TUI over this checkout, whose `upgrade` subcommand is a guided-session entry, and whose `web` subcommand is the browser UI. `meta` and `upgrade` are experimental: each runs only with its `--experimental` flag or with `DSH_EXPERIMENTAL=1` in the environment, and fails loud (stderr, exit 1) otherwise. `src/bin.ts` switches on the resolved mode and dynamic-imports only that mode's module. `dsh --help` lists every mode and `dsh web --help` renders the web usage, `dsh --version` prints this app's version, and an unknown option or a mistyped `--resume` fails loud (stderr, exit 1) instead of misrouting. Every subcommand that shares no option with the default surface — `upgrade`, `web`, `meta` — rejects a leaked `--config`/`-p`/`--resume`/dump flag rather than running and dropping it. `dsh web`'s `--host`/`--port` are unvalidated pass-through overrides: the `dsh-host-webserver` schema is the single source of both the default (the shipped Web overlay value when a flag is absent) and validity, and rejects a bad value at boot. `--trusted-host` appends named authorities for the /api browser-trust fence; an all-interfaces bind additionally derives the machine's LAN IP literals itself ([`src/app-cli-entry.ts`](src/app-cli-entry.ts)), so the printed LAN URL works without flags.

 The TUI surface:

@@ -12,11 +12,12 @@ The TUI surface:
 - treats the **invoking directory** as the workspace — sessions, relative paths, and workspace instructions resolve from the cwd (`dsh meta` is the sole exception, below);
 - tells the agent where its own source lives: after boot it adds a prompt section naming this harness checkout, resolved from the launcher's real path so it holds under a PATH symlink and an arbitrary cwd, so the self-referential `cordis` toolset can read and modify it;
 - applies the personal overlay from `~/.dsh` (see [app-boot's Personal config](../../packages/ui/app-boot/README.md#personal-config)): `config.yaml` patches the booted tree, while `.env` there is the credential provider's own store (never hoisted into the environment, so keys stay rotatable). Environment precedence is ambient > project `.env`.
+- presents the [versioned first-run welcome](../../.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md) through the mounted TUI overlay service when its immutable marker is absent under `DSH_HOME`; only Enter creates that version's marker, while Escape, disposal, or process exit leaves it eligible. The official DeepSeek icon, responsive terminal rasters, all-locale Chinese copy, and notice version are static local owners; the overlay never writes a session event or model context.
 - registers bare `/compact`: while the agent is idle, it summarizes useful older history even below automatic pressure, rejects arguments, and reports success only after the standalone replacement bracket is durable. A prompt submitted during compaction keeps its queue identity and starts after that checkpoint; injected context remains visible.

 `dsh meta` is that same TUI with this harness checkout as the workspace, so working on dsh itself needs no `cd`. It chdirs to the checkout root — resolved from the launcher's real path, the same root the source-path prompt section names — after the environment is settled, so precedence is unchanged while the session cwd and HMR watch root move together. Meta always starts a fresh session and accepts no default-surface options; use ordinary `dsh --resume <id>` to resume a persisted session.

-`dsh upgrade` is a guided fresh-session entry over the default TUI surface: it mints a fresh session in the invoking directory and seeds its first turn with the bundled `dsh-upgrade` skill, exactly as if the user typed `/skill:<name>`. The launcher passes the skill name on the boot context ([`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)), which the TUI auto-invokes once the chat is live. Both take no options — `--config`, `-p`, and `--resume` fail loud — and seed only on this first launch, so a later `dsh --resume <id>` of the session is an ordinary TUI session with no re-injection.
+`dsh upgrade` is a guided fresh-session entry over the default TUI surface: it mints a fresh session in the invoking directory and seeds its first turn with the bundled `dsh-upgrade` skill, exactly as if the user typed `/skill:<name>`. The launcher passes the skill name on the boot context ([`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)), which the TUI auto-invokes once the chat is live. The command takes no options beyond the experimental gate — `--config`, `-p`, and `--resume` fail loud — and seeds only on this first launch, so a later `dsh --resume <id>` of the session is an ordinary TUI session with no re-injection.

 `dsh --dump-config` and `dsh web --dump-config` print the composed config tree — the shipped base, the surface overlay, and the `--config` or personal overlay, exactly the layers that surface would boot — as YAML on stdout and exit without booting; `--dump-default-config` stops at the surface overlay, so diffing the two shows precisely what the user layer changes. Each run of rows is preceded by a `# ==` comment naming the file it comes from and the layers that patched it (e.g. `# == base.cordis.yml, patched by tui.cordis.yml`), so the output shows provenance while staying one loadable document. Composition runs through the include's own patch algorithm and YAML dialect (`applyEntryPatches`/`entryListSchema` from `@cordisjs/plugin-include`), so the dump cannot drift from what boots; `!!js` expressions print verbatim and unevaluated, and a patch whose target row is absent is reported on stderr with its layer, mirroring the Loader's boot-time warning. Launcher-owned boot-context values (session identity, CLI-flag patches) are per-invocation facts outside the config tree and do not appear. The dump flags reject boot-only flags (`-p`, `--resume`, `--config-replace`) rather than silently ignoring them, and `--dump-default-config` takes no `--config`.

@@ -3,7 +3,7 @@
 [English](README.md) | 中文


-Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`src/args.ts`](src/args.ts)）解析一次：同一个程序的默认形式（无子命令）是 TUI／无头界面（`--config`、`-p`/`--prompt`、`--resume`、`--dump-config`、`--dump-default-config`），`meta` 子命令是以本 checkout 为 workspace 的同一个 TUI，`upgrade` 子命令是无选项的引导会话入口，`web` 子命令则是浏览器 UI。`src/bin.ts` 按解析后的 mode 分支，仅动态导入该 mode 的模块。`dsh --help` 列出所有 mode，`dsh web --help` 渲染 Web 用法，`dsh --version` 打印此应用的版本；未知选项或拼错的 `--resume` 会明确报错（stderr，退出码 1），而不会被错路由。凡与默认界面不共享任何选项的子命令（`upgrade`、`web`、`meta`）都会拒绝泄漏进来的 `--config`/`-p`/`--resume`/dump 标志，而不会照常运行并丢弃它。`dsh web` 的 `--host`/`--port` 是未验证的直通覆盖：`dsh-host-webserver` schema 是默认值（标志缺失时使用已交付的 Web 覆盖层值）和有效性的唯一真源，并在启动时拒绝错误值。`--trusted-host` 为 /api 浏览器信任栅栏追加具名权威；全接口绑定还会自行推导本机的 LAN IP 字面量（[`src/app-cli-entry.ts`](src/app-cli-entry.ts)），因此打印出的 LAN URL 无需任何标志即可使用。
+Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`src/args.ts`](src/args.ts)）解析一次：同一个程序的默认形式（无子命令）是 TUI／无头界面（`--config`、`-p`/`--prompt`、`--resume`、`--dump-config`、`--dump-default-config`），`meta` 子命令是以本 checkout 为 workspace 的同一个 TUI，`upgrade` 子命令是引导会话入口，`web` 子命令则是浏览器 UI。`meta` 与 `upgrade` 是实验性命令：只有带上各自的 `--experimental` 标志或在环境中设置 `DSH_EXPERIMENTAL=1` 才会运行，否则明确报错（stderr，退出码 1）。`src/bin.ts` 按解析后的 mode 分支，仅动态导入该 mode 的模块。`dsh --help` 列出所有 mode，`dsh web --help` 渲染 Web 用法，`dsh --version` 打印此应用的版本；未知选项或拼错的 `--resume` 会明确报错（stderr，退出码 1），而不会被错路由。凡与默认界面不共享任何选项的子命令（`upgrade`、`web`、`meta`）都会拒绝泄漏进来的 `--config`/`-p`/`--resume`/dump 标志，而不会照常运行并丢弃它。`dsh web` 的 `--host`/`--port` 是未验证的直通覆盖：`dsh-host-webserver` schema 是默认值（标志缺失时使用已交付的 Web 覆盖层值）和有效性的唯一真源，并在启动时拒绝错误值。`--trusted-host` 为 /api 浏览器信任栅栏追加具名权威；全接口绑定还会自行推导本机的 LAN IP 字面量（[`src/app-cli-entry.ts`](src/app-cli-entry.ts)），因此打印出的 LAN URL 无需任何标志即可使用。

 TUI 界面：

@@ -12,11 +12,12 @@ TUI 界面：
 - 将 **调用目录** 视为 workspace：会话、相对路径和 workspace 指令都从 cwd 解析（`dsh meta` 是唯一例外，见下文）；
 - 告知 agent 自身源码所在位置：启动后添加一个命名此 harness checkout 的提示词段。该路径从启动器的真实路径解析，因此在 PATH 符号链接和任意 cwd 下仍然有效，使自指的 `cordis` 工具集可以读取并修改它；
 - 应用 `~/.dsh` 中的个人覆盖（参见 [app-boot 的个人配置](../../packages/ui/app-boot/README.md#personal-config)）：`config.yaml` 修补已启动的树，而那里的 `.env` 是凭据 provider 自己的存储（绝不会被提升进环境，因此密钥始终可轮换）。环境优先级为环境中已有的值 > 项目 `.env`。
+- 当 `DSH_HOME` 下不存在不可变确认标记时，通过已挂载的 TUI overlay 服务呈现[版本化首次运行欢迎页](../../.agents/notes/implemented/feature/2026-07-30-versioned-tui-first-run-welcome.md)；只有 Enter 会创建该版本的标记，Escape、资源释放或进程退出仍保留展示资格。官方 DeepSeek 图标、响应式终端栅格图、所有 locale 共用的中文文案和通知版本均由静态本地文件持有；overlay 不会写入会话事件或模型上下文。
 - 注册裸 `/compact`：agent 空闲时，即使未达到自动压力，也会摘要有效的较早历史；该命令拒绝参数，并只在独立替换标记对持久化后报告成功。压缩（compaction）期间提交的提示词保留其队列身份，并在该检查点之后启动；注入的上下文仍保持可见。

 `dsh meta` 是以本 harness checkout 为 workspace 的同一个 TUI，因此开发 dsh 自身无需 `cd`。它在环境确定之后才 chdir 到 checkout 根目录（从启动器的真实路径解析，与源码路径提示词段所指的根目录相同），因此环境优先级不变，而会话 cwd 与 HMR 监视根目录会一并移动。Meta 始终创建新会话，不接受默认界面的任何选项；恢复已持久化会话应使用普通的 `dsh --resume <id>`。

-`dsh upgrade` 是默认 TUI 界面之上的引导式全新会话入口：它在调用目录中创建一个全新会话，并以内置 `dsh-upgrade` skill 播种其首轮，效果等同于用户手动键入 `/skill:<name>`。启动器将 skill 名称提供到启动上下文（[`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)），TUI 在聊天就绪后自动调用它。两者都不接受任何选项——`--config`、`-p`、`--resume` 都会明确报错——且仅在首次启动时播种，因此之后 `dsh --resume <id>` 恢复该会话时是普通 TUI 会话，不会重复注入。
+`dsh upgrade` 是默认 TUI 界面之上的引导式全新会话入口：它在调用目录中创建一个全新会话，并以内置 `dsh-upgrade` skill 播种其首轮，效果等同于用户手动键入 `/skill:<name>`。启动器将 skill 名称提供到启动上下文（[`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)），TUI 在聊天就绪后自动调用它。该命令除实验性门槛外不接受任何选项——`--config`、`-p`、`--resume` 都会明确报错——且仅在首次启动时播种，因此之后 `dsh --resume <id>` 恢复该会话时是普通 TUI 会话，不会重复注入。

 `dsh --dump-config` 和 `dsh web --dump-config` 把合成后的配置树——已交付的基础配置、界面覆盖层，以及 `--config` 或个人覆盖层，恰好是该界面启动时组装的那些层——以 YAML 打印到 stdout 后退出，不启动任何东西；`--dump-default-config` 止步于界面覆盖层，因此对两份输出做 diff 就能精确看出用户层改了什么。每段连续的行之前都有一条 `# ==` 注释，标明该段来自哪个文件以及被哪些层修补过（例如 `# == base.cordis.yml, patched by tui.cordis.yml`），因此输出既展示来源，又仍是一份可加载的文档。合成通过 include 自己的补丁算法和 YAML 方言（`@cordisjs/plugin-include` 的 `applyEntryPatches`/`entryListSchema`）完成，因此 dump 不可能与实际启动漂移；`!!js` 表达式原样打印、不求值，目标行不存在的补丁会连同其所在层报到 stderr，与 Loader 启动时的警告一致。由启动器持有的启动上下文值（会话身份、CLI 标志补丁）是每次调用的事实，位于配置树之外，不会出现。dump 标志会拒绝仅用于启动的标志（`-p`、`--resume`、`--config-replace`）而不是静默忽略它们，`--dump-default-config` 不接受 `--config`。

@@ -0,0 +1 @@
+<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>DeepSeek</title><path d="M23.748 4.482c-.254-.124-.364.113-.512.234-.051.039-.094.09-.137.136-.372.397-.806.657-1.373.626-.829-.046-1.537.214-2.163.848-.133-.782-.575-1.248-1.247-1.548-.352-.156-.708-.311-.955-.65-.172-.241-.219-.51-.305-.774-.055-.16-.11-.323-.293-.35-.2-.031-.278.136-.356.276-.313.572-.434 1.202-.422 1.84.027 1.436.633 2.58 1.838 3.393.137.093.172.187.129.323-.082.28-.18.552-.266.833-.055.179-.137.217-.329.14a5.526 5.526 0 01-1.736-1.18c-.857-.828-1.631-1.742-2.597-2.458a11.365 11.365 0 00-.689-.471c-.985-.957.13-1.743.388-1.836.27-.098.093-.432-.779-.428-.872.004-1.67.295-2.687.684a3.055 3.055 0 01-.465.137 9.597 9.597 0 00-2.883-.102c-1.885.21-3.39 1.102-4.497 2.623C.082 8.606-.231 10.684.152 12.85c.403 2.284 1.569 4.175 3.36 5.653 1.858 1.533 3.997 2.284 6.438 2.14 1.482-.085 3.133-.284 4.994-1.86.47.234.962.327 1.78.397.63.059 1.236-.03 1.705-.128.735-.156.684-.837.419-.961-2.155-1.004-1.682-.595-2.113-.926 1.096-1.296 2.746-2.642 3.392-7.003.05-.347.007-.565 0-.845-.004-.17.035-.237.23-.256a4.173 4.173 0 001.545-.475c1.396-.763 1.96-2.015 2.093-3.517.02-.23-.004-.467-.247-.588zM11.581 18c-2.089-1.642-3.102-2.183-3.52-2.16-.392.024-.321.471-.235.763.09.288.207.486.371.739.114.167.192.416-.113.603-.673.416-1.842-.14-1.897-.167-1.361-.802-2.5-1.86-3.301-3.307-.774-1.393-1.224-2.887-1.298-4.482-.02-.386.093-.522.477-.592a4.696 4.696 0 011.529-.039c2.132.312 3.946 1.265 5.468 2.774.868.86 1.525 1.887 2.202 2.891.72 1.066 1.494 2.082 2.48 2.914.348.292.625.514.891.677-.802.09-2.14.11-3.054-.614zm1-6.44a.306.306 0 01.415-.287.302.302 0 01.2.288.306.306 0 01-.31.307.303.303 0 01-.304-.308zm3.11 1.596c-.2.081-.399.151-.59.16a1.245 1.245 0 01-.798-.254c-.274-.23-.47-.358-.552-.758a1.73 1.73 0 01.016-.588c.07-.327-.008-.537-.239-.727-.187-.156-.426-.199-.688-.199a.559.559 0 01-.254-.078c-.11-.054-.2-.19-.114-.358.028-.054.16-.186.192-.21.356-.202.767-.136 1.146.016.352.144.618.408 1.001.782.391.451.462.576.685.914.176.265.336.537.445.848.067.195-.019.354-.25.452z" fill="#4D6BFE"></path></svg>
@@ -9,6 +9,7 @@
  },
  "files": [
    "lib/bin.js",
+    "assets",
    "config",
    "src"
  ],
@@ -132,6 +133,7 @@
    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^",
    "@deepseek-ai/dsh-workspace": "workspace:^",
    "@deepseek-ai/dsh-workspace-context": "workspace:^",
+    "@earendil-works/pi-tui": "0.80.7",
    "commander": "^15.0.0",
    "cordis": "^4.0.0-rc.7",
    "js-yaml": "^4.2.0"
@@ -2,8 +2,11 @@
 * Commander adapter for the `dsh` command-line entry: the one place argv is
 * parsed and routed to a mode. `bin.ts` switches on the returned discriminant
 * and dynamic-imports that mode's module. One program: the default (no
- * subcommand) is the TUI/headless surface with option-only flags; `meta` and
- * `web` are real subcommands. Commander owns `--help`/`--version` and parse
+ * subcommand) is the TUI/headless surface with option-only flags;
+ * `meta`, `upgrade`, and `web` are real subcommands; the experimental ones
+ * (`meta`, `upgrade`) run only under the `--experimental` flag or
+ * `DSH_EXPERIMENTAL=1`. Commander owns
+ * `--help`/`--version` and parse
 * errors — it prints and exits at the point of failure (a domain failure routes through
 * `command.error`), so this returns only a resolved mode.
 * @module @deepseek-ai/dsh/args
@@ -45,16 +48,17 @@ interface HeadlessInvocation {
  prompt: string
 }

-/** Interactive fresh TUI over this harness checkout; accepts no default-surface options. */
+/** Interactive fresh TUI over this harness checkout; accepts no default-surface options, only the experimental gate. */
 interface MetaInvocation {
  mode: 'meta'
 }

 /**
- * Guided fresh-session entry: `dsh upgrade` seeds the first turn with the
- * `dsh-upgrade` skill. It always mints a
- * fresh session in the invoking directory and takes no options — `--resume`,
- * `--config`, and `-p` are rejected as mistyped, so there is nothing to carry.
+ * Guided fresh-session entry: `dsh upgrade` seeds the first turn
+ * with the `dsh-upgrade` skill. It always mints a
+ * fresh session in the invoking directory and takes no options beyond the
+ * experimental gate — `--resume`, `--config`, and `-p` are rejected as
+ * mistyped, so there is nothing to carry.
 */
 interface SkillSessionInvocation {
  mode: 'upgrade'
@@ -153,9 +157,11 @@ function resolveWeb(options: WebOptions): WebInvocation {
 * TUI/headless surface; `web` is a subcommand.
 * @param argv - the arguments after the node binary and script (`process.argv.slice(2)`).
 * @param version - the version string `--version` prints; read from this app's package.json.
+ * @param experimentalEnv - whether the environment opts into experimental
+ * subcommands (`DSH_EXPERIMENTAL=1`); the caller reads the process boundary.
 * @returns the resolved invocation (only reached on a valid, non-help invocation).
 */
-export function parseDshArgs(argv: readonly string[], version: string): DshInvocation {
+export function parseDshArgs(argv: readonly string[], version: string, experimentalEnv: boolean): DshInvocation {
  let resolved: DshInvocation | undefined
  const program = new Command()
    .name('dsh')
@@ -247,15 +253,27 @@ Examples:
    }
  }

+  // `meta` and `upgrade` are experimental: each runs only under its own
+  // `--experimental` flag or an environment-wide `DSH_EXPERIMENTAL=1` opt-in,
+  // and fails loud otherwise so the gate is never silently skipped.
+  const requireExperimental = (command: string, flag: boolean | undefined): void => {
+    if (flag !== true && !experimentalEnv) {
+      program.error(`error: ${command} is experimental; pass --experimental or set DSH_EXPERIMENTAL=1`)
+    }
+  }
+
  // Registration order is the rendered help order, so daily use comes first
-  // and the harness-development surfaces (`web --dev`, `meta`) come last.
-  // `upgrade` is a guided fresh-session entry: it takes no options and always
-  // mints a fresh session, so nothing is left to carry.
+  // and the harness-development surfaces (`web --dev`, `meta`)
+  // come last. `upgrade` is a guided fresh-session entry: beyond the
+  // experimental gate it takes no options and always mints a fresh session,
+  // so nothing is left to carry.
  program
    .command('upgrade')
-    .description('update this dsh installation to the latest version')
-    .action(() => {
+    .description('update this dsh installation to the latest version (experimental)')
+    .option('--experimental', 'acknowledge this subcommand is experimental')
+    .action((options: { experimental?: boolean }) => {
      rejectParentOptions('upgrade')
+      requireExperimental('upgrade', options.experimental)
      resolved = { mode: 'upgrade' }
    })

@@ -284,9 +302,11 @@ Examples:

  program
    .command('meta')
-    .description('work on the dsh source that runs this command, from any directory')
-    .action(() => {
+    .description('work on the dsh source that runs this command, from any directory (experimental)')
+    .option('--experimental', 'acknowledge this subcommand is experimental')
+    .action((options: { experimental?: boolean }) => {
      rejectParentOptions('meta')
+      requireExperimental('meta', options.experimental)
      resolved = { mode: 'meta' }
    })

@@ -25,7 +25,8 @@ function readVersion(): string {
 }

 loadEnv('dsh')
-const invocation = parseDshArgs(process.argv.slice(2), readVersion())
+// The env opt-in is read at the process boundary; `1` is the documented value.
+const invocation = parseDshArgs(process.argv.slice(2), readVersion(), process.env.DSH_EXPERIMENTAL === '1')

 switch (invocation.mode) {
  case 'web': {
@@ -0,0 +1,111 @@
+/**
+ * Static terminal rasters derived from the official 24x24 DeepSeek icon.
+ *
+ * Source: `../../assets/deepseek-color.svg`, whose path data is copied exactly
+ * from the supplied official icon (viewBox `0 0 24 24`, fill `#4D6BFE`). Each
+ * tier rasterizes that path into a square binary
+ * mask without redrawing its contour. The Unicode form packs two source rows
+ * into `▀`/`▄`/`█`; the ASCII fallback packs the same two bits into
+ * `'`/`_`/`#`. Assets contain no ANSI and are never generated at runtime.
+ * @module @deepseek-ai/dsh/tui-onboarding/tui-first-run-welcome-art
+ */
+
+/** Responsive official-icon raster tier. */
+export type TuiFirstRunWelcomeArtTier = 'full' | 'compact' | 'minimal'
+
+/** One raster with a block-cell primary and bit-equivalent ASCII fallback. */
+export interface TuiFirstRunWelcomeArt {
+  /** Two vertical source pixels per terminal cell. */
+  readonly unicode: readonly string[]
+  /** Same two-bit cells encoded as top `'`, bottom `_`, and both `#`. */
+  readonly ascii: readonly string[]
+}
+
+const fullUnicode = Object.freeze([
+  '                           ▄',
+  '       ▄▄▄▄▄▄▄▄▄▄███▀      ██▄',
+  '    ▄███████████████▄      ████▄  ▄▄▄▄██',
+  '  ▄███████████████████▄    ████████████▀',
+  ' ▄██████████████████████▄   ▀█████████▀',
+  '▄███▀█████████████████████▄   ████▀▀',
+  '███       ▀▀█████████▀▀▀█████████▀',
+  '███          ▀███████▀█  ▀███████',
+  '███▄           ▀███████▄  ▀█████▀',
+  '▀███             ▀██████████████',
+  ' ▀███▄            ▀███████████▀',
+  '  ▀███▄      ▄▄▄    ▀████████▀',
+  '    █████▄    ███▄▄   ▀█████▄▄',
+  '      ▀█████████████▄▄▄▄█▀█████▀',
+  '        ▀▀███████████▀▀',
+])
+
+const fullAscii = Object.freeze([
+  '                           _',
+  "       __________###'      ##_",
+  '    _###############_      ####_  ____##',
+  "  _###################_    ############'",
+  " _######################_   '#########'",
+  "_###'#####################_   ####''",
+  "###       ''#########'''#########'",
+  "###          '#######'#  '#######",
+  "###_           '#######_  '#####'",
+  "'###             '##############",
+  " '###_            '###########'",
+  "  '###_      ___    '########'",
+  "    #####_    ###__   '#####__",
+  "      '#############____#'#####'",
+  "        ''###########''",
+])
+
+const compactUnicode = Object.freeze([
+  '     ▄▄▄▄▄▄▄██▀    █▄      ▄',
+  '  ▄███████████▄▄   ███▄▄████',
+  ' ████████████████▄ ▀██████▀',
+  '██▀▀▀▀▀████████████▄▄██▀',
+  '██       ▀█████▄ ▀█████',
+  '██▄        ▀████▄ ▄████',
+  ' ██▄         ████████▀',
+  '  ██▄    ▄▄   ▀█████▀',
+  '   ▀███▄▄▄███▄  ████▄▄',
+  '     ▀▀▀███████▀▀',
+])
+
+const compactAscii = Object.freeze([
+  "     _______##'    #_      _",
+  '  _###########__   ###__####',
+  " ################_ '######'",
+  "##'''''############__##'",
+  "##       '#####_ '#####",
+  "##_        '####_ _####",
+  " ##_         ########'",
+  "  ##_    __   '#####'",
+  "   '###___###_  ####__",
+  "     '''#######''",
+])
+
+const minimalUnicode = Object.freeze([
+  '   ▄▄▄▄▄▄   ▄▄',
+  ' ▄████████▄ ▀████▀',
+  '█▀▀▀▀███████▄██▀',
+  '█▄    ▀███ ▀███',
+  '▀█▄     ▀█████',
+  ' ▀█▄▄ █▄▄▀███▄',
+  '    ▀▀▀▀▀▀',
+])
+
+const minimalAscii = Object.freeze([
+  '   ______   __',
+  " _########_ '####'",
+  "#''''#######_##'",
+  "#_    '### '###",
+  "'#_     '#####",
+  " '#__ #__'###_",
+  "    ''''''",
+])
+
+/** Exact-path terminal rasters by responsive tier. */
+export const TUI_FIRST_RUN_WELCOME_WHALE = Object.freeze({
+  full: Object.freeze({ unicode: fullUnicode, ascii: fullAscii }),
+  compact: Object.freeze({ unicode: compactUnicode, ascii: compactAscii }),
+  minimal: Object.freeze({ unicode: minimalUnicode, ascii: minimalAscii }),
+}) satisfies Readonly<Record<TuiFirstRunWelcomeArtTier, TuiFirstRunWelcomeArt>>
@@ -0,0 +1,49 @@
+/**
+ * Centrally owned version and all-locale Chinese copy for the shipped TUI first-run notice.
+ *
+ * A material wording change increments {@link TUI_FIRST_RUN_WELCOME_NOTICE_VERSION}
+ * so every Harness home presents the revised notice once.
+ * @module @deepseek-ai/dsh/tui-onboarding/tui-first-run-welcome-copy
+ */
+
+/** Copy version persisted after the user explicitly continues. */
+export const TUI_FIRST_RUN_WELCOME_NOTICE_VERSION = 4
+
+/** Locale-shaped text rendered by the first-run welcome overlay. */
+export interface TuiFirstRunWelcomeNoticeCopy {
+  /** Overlay heading. */
+  readonly title: string
+  /** Ordered prose paragraphs. */
+  readonly paragraphs: readonly string[]
+  /** Enter action label. */
+  readonly continueLabel: string
+  /** Hint shown when the prose is scrollable. */
+  readonly scrollHint: string
+  /** Status shown while the acknowledgement reaches disk. */
+  readonly saving: string
+  /** Retry message shown when the acknowledgement cannot be persisted. */
+  readonly saveError: string
+}
+
+/** Complete Chinese notice used for every locale. */
+const TUI_FIRST_RUN_WELCOME_CHINESE_COPY = Object.freeze<TuiFirstRunWelcomeNoticeCopy>({
+  title: 'DeepSeek Harness',
+  paragraphs: Object.freeze([
+    '感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能仍待完善，体验难免有些粗糙。',
+    '“如切如磋，如琢如磨。” 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的问题，也可能促使我们重新审视，甚至推翻已有的设计。',
+    '为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 Session Log；如需关闭，请设置环境变量 DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把它打磨得更好。',
+  ]),
+  continueLabel: '继续',
+  scrollHint: '↑/↓ 滚动',
+  saving: '正在保存确认…',
+  saveError: '无法保存确认，请按 Enter 重试。',
+})
+
+/** Locale map whose entries deliberately share the single Chinese owner copy. */
+export const TUI_FIRST_RUN_WELCOME_NOTICE_COPY = Object.freeze({
+  'zh-CN': TUI_FIRST_RUN_WELCOME_CHINESE_COPY,
+  en: TUI_FIRST_RUN_WELCOME_CHINESE_COPY,
+})
+
+/** Locale presented by the shipped first-run notice. */
+export const TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE = 'zh-CN' as const
@@ -0,0 +1,385 @@
+/**
+ * Effect-owned first-run overlay for the shipped `dsh` TUI.
+ *
+ * The launcher owns the per-DSH_HOME acknowledgement boundary; the component
+ * reaches the terminal only through the mounted `ctx.tui` overlay service and
+ * never touches the session or model context.
+ * @module @deepseek-ai/dsh/tui-onboarding/tui-first-run-welcome
+ */
+
+import { randomUUID } from 'node:crypto'
+import { lstat, mkdir, open, rename, rm } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import type { Context } from 'cordis'
+import {
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from '@earendil-works/pi-tui'
+import {
+  disposeRootAndExit,
+  type TuiComponent,
+  type TuiFocusable,
+  type TuiOverlayHost,
+} from '@deepseek-ai/dsh-tui'
+import {
+  TUI_FIRST_RUN_WELCOME_NOTICE_COPY,
+  TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE,
+  TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+  type TuiFirstRunWelcomeNoticeCopy,
+} from './tui-first-run-welcome-copy.ts'
+import {
+  TUI_FIRST_RUN_WELCOME_WHALE,
+  type TuiFirstRunWelcomeArtTier,
+} from './tui-first-run-welcome-art.ts'
+
+// TODO: Move acknowledgement persistence behind @deepseek-ai/dsh-storage once
+// its backend contract supports concurrent host processes. This same-value
+// marker must not inherit JSON lost updates or SQLite busy failures.
+const ACKNOWLEDGEMENT_DIRECTORY = 'notices'
+const ACKNOWLEDGEMENT_BASENAME = 'tui-first-run-welcome'
+
+/** Cordis plugin name. */
+export const name = 'tui-first-run-welcome'
+/** The notice can open only after the terminal-local overlay service mounts. */
+export const inject = ['tui']
+
+/** Launcher-resolved configuration for the terminal-local notice. */
+interface Config {
+  /** Absolute DeepSeek Harness home owning this acknowledgement. */
+  readonly dshHome: string
+  /** Render the bit-equivalent printable ASCII icon fallback. */
+  readonly asciiArt?: boolean
+}
+
+/**
+ * Detect an explicitly non-Unicode terminal locale for the static ASCII art fallback.
+ * @param env - Process environment carrying locale and terminal declarations.
+ * @returns `true` only when the environment explicitly declares an ASCII-only locale or dumb terminal.
+ */
+export function needsTuiFirstRunWelcomeAsciiArt(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  const locale = env.LC_ALL ?? env.LC_CTYPE ?? env.LANG
+  return env.TERM === 'dumb' || locale === 'C' || locale === 'POSIX'
+}
+
+/**
+ * Resolve the immutable marker for one notice version.
+ * @param dshHome - Resolved Harness home.
+ * @param version - Copy version whose acknowledgement is queried.
+ * @returns Absolute marker path beneath the Harness home.
+ */
+export function tuiFirstRunWelcomeAcknowledgementPath(dshHome: string, version: number): string {
+  return join(
+    dshHome,
+    ACKNOWLEDGEMENT_DIRECTORY,
+    `${ACKNOWLEDGEMENT_BASENAME}-v${String(version)}.ack`,
+  )
+}
+
+/**
+ * Test whether one notice version has been acknowledged.
+ * @param dshHome - Resolved Harness home.
+ * @param version - Copy version to inspect.
+ * @returns `true` only for a regular marker file; a malformed marker fails loud.
+ */
+export async function hasTuiFirstRunWelcomeAcknowledgement(
+  dshHome: string,
+  version: number = TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+): Promise<boolean> {
+  const path = tuiFirstRunWelcomeAcknowledgementPath(dshHome, version)
+  try {
+    const info = await lstat(path)
+    if (!info.isFile()) throw new Error(`TUI welcome acknowledgement is not a file: ${path}`)
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+/**
+ * Persist one version acknowledgement by syncing a random same-directory file
+ * before atomically replacing the immutable marker. Concurrent launches publish
+ * the same fact, so same-value last-writer-wins replacement loses no state.
+ * @param dshHome - Resolved Harness home.
+ * @param version - Copy version being acknowledged.
+ */
+export async function acknowledgeTuiFirstRunWelcome(
+  dshHome: string,
+  version: number = TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+): Promise<void> {
+  const path = tuiFirstRunWelcomeAcknowledgementPath(dshHome, version)
+  const directory = dirname(path)
+  const temp = join(directory, `.${basename(path)}.${randomUUID()}.tmp`)
+  await mkdir(directory, { recursive: true, mode: 0o700 })
+  await syncDirectory(dirname(directory))
+  let handle: Awaited<ReturnType<typeof open>> | undefined
+  try {
+    handle = await open(temp, 'wx', 0o600)
+    await handle.sync()
+    const created = handle
+    handle = undefined
+    await created.close()
+    await rename(temp, path)
+  } catch (error) {
+    /* v8 ignore start -- fault-injected UI coverage proves failed acknowledgements stay uncommitted and retryable */
+    try {
+      await handle?.close()
+    } finally {
+      await rm(temp, { force: true })
+    }
+    throw error
+    /* v8 ignore stop */
+  }
+  try {
+    await syncDirectory(directory)
+  /* v8 ignore next -- rename is the commit point; directory-fsync fault injection is platform-specific */
+  } catch {
+    // Swallow post-rename directory fsync failure: the marker is already committed,
+    // and crash loss can only make the notice reappear on the safe side.
+  }
+}
+
+/** Sync one POSIX directory after publishing a child entry. */
+/* v8 ignore start -- Windows rejects directory opens; POSIX unit coverage owns this path. */
+async function syncDirectory(path: string): Promise<void> {
+  if (process.platform === 'win32') return
+  const handle = await open(path, 'r')
+  try {
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+/* v8 ignore stop */
+
+/** Render one visible-width-padded line inside the notice frame. */
+function framed(content: string, innerWidth: number, host: TuiOverlayHost): string {
+  const clipped = truncateToWidth(content, innerWidth, '')
+  return `${host.theme.dim('│')} ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} ${host.theme.dim('│')}`
+}
+
+/** Center one line by terminal column width. */
+function centered(content: string, width: number): string {
+  const clipped = truncateToWidth(content, width, '')
+  const remaining = Math.max(0, width - visibleWidth(clipped))
+  return `${' '.repeat(Math.floor(remaining / 2))}${clipped}`
+}
+
+/**
+ * Select the art tier for the actual overlay width and viewport height.
+ * @param innerWidth - Columns inside the frame.
+ * @param viewportRows - Current terminal rows.
+ * @returns full, compact, minimal, or no art when prose must take priority.
+ */
+export function tuiFirstRunWelcomeArtTier(
+  innerWidth: number,
+  viewportRows: number,
+): TuiFirstRunWelcomeArtTier | undefined {
+  const compositionCapacity = Math.max(1, Math.max(7, Math.floor(viewportRows * 0.9)) - 5)
+  if (innerWidth >= 96 && TUI_FIRST_RUN_WELCOME_WHALE.full.unicode.length <= compositionCapacity) return 'full'
+  if (innerWidth >= 80 && TUI_FIRST_RUN_WELCOME_WHALE.compact.unicode.length + 4 <= compositionCapacity) return 'compact'
+  if (innerWidth >= 64 && TUI_FIRST_RUN_WELCOME_WHALE.minimal.unicode.length + 4 <= compositionCapacity) return 'minimal'
+  return undefined
+}
+
+/** Wrap the centrally owned prose while promoting its opening quotation. */
+function proseLines(
+  copy: TuiFirstRunWelcomeNoticeCopy,
+  width: number,
+  host: TuiOverlayHost,
+): string[] {
+  const lines: string[] = []
+  for (const [index, paragraph] of copy.paragraphs.entries()) {
+    if (index > 0) lines.push('')
+    const quoteEnd = paragraph.startsWith('“') ? paragraph.indexOf('”') : -1
+    if (quoteEnd > 0) {
+      const quote = paragraph.slice(0, quoteEnd + 1)
+      const remainder = paragraph.slice(quoteEnd + 1).trimStart()
+      lines.push(...wrapTextWithAnsi(host.theme.bold(host.theme.text(host.display(quote))), width))
+      lines.push('')
+      if (remainder !== '') lines.push(...wrapTextWithAnsi(host.theme.text(host.display(remainder)), width))
+    } else {
+      lines.push(...wrapTextWithAnsi(host.theme.text(host.display(paragraph)), width))
+    }
+  }
+  return lines
+}
+
+/** Render centered static brand art without putting ANSI into its owner file. */
+function artLines(
+  tier: TuiFirstRunWelcomeArtTier,
+  width: number,
+  host: TuiOverlayHost,
+  asciiArt: boolean,
+): string[] {
+  const art = TUI_FIRST_RUN_WELCOME_WHALE[tier][asciiArt ? 'ascii' : 'unicode']
+  return art.map(line => centered(host.theme.brand(line), width))
+}
+
+/** Responsive, scrollable notice whose only completion input is Enter. */
+export class TuiFirstRunWelcomeComponent implements TuiComponent, TuiFocusable {
+  focused = false
+  private scrollOffset = 0
+  private bodyCapacity = 1
+  private maxScrollOffset = 0
+  private saving = false
+  private saveFailed = false
+
+  constructor(
+    private readonly host: TuiOverlayHost,
+    private readonly copy: TuiFirstRunWelcomeNoticeCopy,
+    private readonly acknowledge: () => Promise<void>,
+    private readonly exit: () => void,
+    private readonly asciiArt = false,
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const frameWidth = Math.max(6, width)
+    const innerWidth = Math.max(1, frameWidth - 4)
+    const viewportRows = this.host.viewport.rows
+    const tier = tuiFirstRunWelcomeArtTier(innerWidth, viewportRows)
+    const availableRows = Math.max(7, Math.floor(viewportRows * 0.9))
+    const title = this.host.theme.bold(this.host.theme.brand(this.copy.title))
+    let fixedHeader: string[] = []
+    let fullContentHeader: string[] = []
+    let body: string[]
+    let fullArt: string[] | undefined
+    const fullArtWidth = 44
+
+    if (tier === 'full') {
+      fullArt = artLines(tier, fullArtWidth, this.host, this.asciiArt)
+      const contentWidth = Math.max(1, innerWidth - fullArtWidth - 3)
+      fullContentHeader = [centered(title, contentWidth), '']
+      body = proseLines(this.copy, contentWidth, this.host)
+    } else {
+      const art = tier === undefined ? [] : artLines(tier, innerWidth, this.host, this.asciiArt)
+      fixedHeader = [...art, ...art.length === 0 ? [] : [''], centered(title, innerWidth), '']
+      body = proseLines(this.copy, innerWidth, this.host)
+    }
+
+    const compositionCapacity = Math.max(1, availableRows - 5)
+    const bodyLimit = Math.max(1, compositionCapacity - fixedHeader.length - fullContentHeader.length)
+    this.bodyCapacity = Math.min(body.length, bodyLimit)
+    const maxOffset = Math.max(0, body.length - this.bodyCapacity)
+    this.maxScrollOffset = maxOffset
+    this.scrollOffset = Math.min(this.scrollOffset, maxOffset)
+    const visibleBody = body.slice(this.scrollOffset, this.scrollOffset + this.bodyCapacity)
+
+    const top = this.host.theme.dim(`╭${'─'.repeat(Math.max(0, frameWidth - 2))}╮`)
+    const separator = this.host.theme.dim(`├${'─'.repeat(Math.max(0, frameWidth - 2))}┤`)
+    const bottom = this.host.theme.dim(`╰${'─'.repeat(Math.max(0, frameWidth - 2))}╯`)
+    const action = this.host.theme.bold(this.host.theme.accent(`Enter  ${this.copy.continueLabel}`))
+    const hasAbove = this.scrollOffset > 0
+    const hasBelow = this.scrollOffset < maxOffset
+    const scroll = hasAbove || hasBelow
+      ? `${hasAbove ? '↑' : ' '} ${this.copy.scrollHint} ${hasBelow ? '↓' : ' '}`
+      : ''
+    const status = this.saveFailed
+      ? this.host.theme.error(this.copy.saveError)
+      : this.saving
+        ? this.host.theme.dim(this.copy.saving)
+        : this.host.theme.dim(scroll)
+
+    const fullContent = [...fullContentHeader, ...visibleBody]
+    const composition = fullArt === undefined
+      ? [...fixedHeader, ...visibleBody]
+      : Array.from({ length: Math.max(fullArt.length, fullContent.length) }, (_, index) => {
+        const art = fullArt[index] ?? ''
+        const line = fullContent[index] ?? ''
+        const left = `${art}${' '.repeat(Math.max(0, fullArtWidth - visibleWidth(art)))}`
+        return `${left}   ${line}`
+      })
+
+    return [
+      top,
+      ...composition.map(line => framed(line, innerWidth, this.host)),
+      separator,
+      framed(centered(action, innerWidth), innerWidth, this.host),
+      framed(centered(status, innerWidth), innerWidth, this.host),
+      bottom,
+    ]
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.ctrl('c')) || matchesKey(data, Key.ctrl('d'))) {
+      this.exit()
+      return
+    }
+    if (matchesKey(data, Key.enter)) {
+      if (!this.saving) void this.commit()
+      return
+    }
+    if (this.saving || matchesKey(data, Key.escape)) return
+    if (matchesKey(data, Key.up)) this.scrollBy(-1)
+    else if (matchesKey(data, Key.down)) this.scrollBy(1)
+    else if (matchesKey(data, Key.pageUp)) this.scrollBy(-this.bodyCapacity)
+    else if (matchesKey(data, Key.pageDown)) this.scrollBy(this.bodyCapacity)
+    else if (matchesKey(data, Key.home)) this.scrollTo(0)
+    else if (matchesKey(data, Key.end)) this.scrollTo(this.maxScrollOffset)
+  }
+
+  private scrollBy(delta: number): void {
+    this.scrollTo(this.scrollOffset + delta)
+  }
+
+  private scrollTo(offset: number): void {
+    this.scrollOffset = Math.min(this.maxScrollOffset, Math.max(0, offset))
+    this.host.invalidate()
+  }
+
+  private async commit(): Promise<void> {
+    this.saving = true
+    this.saveFailed = false
+    this.host.invalidate()
+    try {
+      await this.acknowledge()
+      this.host.close()
+    } catch {
+      this.saving = false
+      this.saveFailed = true
+      this.host.invalidate()
+    }
+  }
+}
+
+/**
+ * Open the first-run notice through the mounted TUI's FIFO overlay owner.
+ * @param ctx - Plugin context carrying the terminal-local TUI service.
+ * @param config - Launcher-resolved Harness home.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const copy = TUI_FIRST_RUN_WELCOME_NOTICE_COPY[TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE]
+  const pending = new Set<Promise<void>>()
+  const acknowledge = (): Promise<void> => {
+    const task = acknowledgeTuiFirstRunWelcome(config.dshHome)
+    pending.add(task)
+    const settled = (): void => { pending.delete(task) }
+    void task.then(settled, settled)
+    return task
+  }
+  ctx.effect(() => async () => {
+    await Promise.allSettled(pending)
+  }, 'tui first-run welcome acknowledgement')
+  ctx.tui.openOverlay({
+    create: host => new TuiFirstRunWelcomeComponent(
+      host,
+      copy,
+      acknowledge,
+      () => { disposeRootAndExit(ctx, 0) },
+      config.asciiArt ?? false,
+    ),
+    options: {
+      width: '100%',
+      maxHeight: '90%',
+      anchor: 'center',
+      margin: 0,
+    },
+  })
+}
@@ -8,10 +8,11 @@
 * from it, so `dsh` acts on whatever project it is launched in. Session storage
 * is the exception — it lives under the Harness home so `/resume` reaches every
 * workspace, and an in-place resume enters the selected session's own directory.
- * `dsh meta` is the one exception — it makes this harness checkout the
- * workspace. `dsh upgrade` is a fresh session whose first turn auto-invokes a
- * bundled skill. After boot, the agent's system prompt is told the path to this
- * harness checkout so it can find its own source.
+ * `dsh meta` is the one exception — it makes this harness
+ * checkout the workspace. `dsh upgrade` is a fresh session whose
+ * first turn auto-invokes a bundled skill. After boot, the agent's system
+ * prompt is told the path to this harness checkout so it can find its own
+ * source.
 * @module @deepseek-ai/dsh/tui
 */

@@ -28,6 +29,7 @@ import {
  loadPersonalPatches,
  resolveConfigPath,
 } from '@deepseek-ai/dsh-app-boot'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { configHasTelemetryRow, resolveTelemetryPatch } from './app-cli-entry.ts'
 import { SESSION_QUERY_SQLITE_PATH_KEY } from '@deepseek-ai/dsh-session-query-sqlite'
@@ -40,6 +42,16 @@ import {
  type MainSessionIdentity,
  type TuiResumeHost,
 } from '@deepseek-ai/dsh-tui'
+import {
+  apply as applyTuiFirstRunWelcome,
+  hasTuiFirstRunWelcomeAcknowledgement,
+  inject as tuiFirstRunWelcomeInject,
+  name as tuiFirstRunWelcomeName,
+  needsTuiFirstRunWelcomeAsciiArt,
+} from './tui-onboarding/tui-first-run-welcome.ts'
+import {
+  TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+} from './tui-onboarding/tui-first-run-welcome-copy.ts'

 const NAME = 'dsh'

@@ -78,8 +90,9 @@ export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
 * @param workspace - a directory to make the workspace instead of the invoking
 * one, or `undefined` to keep the cwd. Only `dsh meta` passes it.
 * @param initialSkill - a bundled skill to auto-invoke as a fresh session's
- * first turn, or `undefined`. Set only by `dsh upgrade` and ignored on a resume,
- * so it never re-fires; reaches the app through {@link INITIAL_SKILL_KEY}.
+ * first turn, or `undefined`. Set only by `dsh upgrade` and
+ * ignored on a resume, so it never re-fires; reaches the app through
+ * {@link INITIAL_SKILL_KEY}.
 * @param configReplace - a config path to boot as the ENTIRE tree, bypassing the
 * shared base, the TUI overlay, and the personal overlay alike, or `undefined`
 * to compose them; already parsed from `--config-replace`.
@@ -111,6 +124,11 @@ export async function runTui(
  // both together. Sessions themselves live under the Harness home so `/resume`
  // spans every workspace, and are unaffected by this chdir.
  if (workspace !== undefined) process.chdir(workspace)
+  const dshHome = resolveDshHome()
+  const showFirstRunWelcome = !await hasTuiFirstRunWelcomeAcknowledgement(
+    dshHome,
+    TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+  )
  process.env.DSH_BUNDLED_SKILL_DIR = join(SOURCE_ROOT, 'skills')
  // The in-place `/resume` handoff re-execs `dsh` with a normalized `--resume`
  // flag, so the resumed process rehydrates through this same intake. The
@@ -122,8 +140,9 @@ export async function runTui(
  const entry = process.argv[1]
  const execve = process.execve?.bind(process)
  const app: { current?: Context } = {}
-  // Resume always enters the default surface because meta rejects parent
-  // options, including `--resume`. The resumed session already persists its cwd.
+  // Resume always enters the default surface because meta rejects
+  // parent options, including `--resume`. The resumed session already persists
+  // its cwd.
  const resumeArgs = (sessionId: string): string[] => [
    `--resume=${sessionId}`,
    // Both config flags must survive the handoff: resuming into a different
@@ -229,5 +248,15 @@ export async function runTui(
  )
  app.current = ctx
  addHarnessSourceSection(ctx, SOURCE_ROOT)
+  if (showFirstRunWelcome) {
+    await ctx.plugin({
+      name: tuiFirstRunWelcomeName,
+      inject: tuiFirstRunWelcomeInject,
+      apply: applyTuiFirstRunWelcome,
+    }, {
+      dshHome,
+      asciiArt: needsTuiFirstRunWelcomeAsciiArt(),
+    })
+  }
 }
 /* v8 ignore stop */
@@ -1,18 +1,18 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { parseDshArgs } from '../src/args.ts'

-const parse = (argv: string[]) => parseDshArgs(argv, '1.2.3')
+const parse = (argv: string[], experimentalEnv = false) => parseDshArgs(argv, '1.2.3', experimentalEnv)

 /**
 * `parseDshArgs` calls `process.exit` for `--help`/`--version`/errors and lets
 * Commander print to the real streams; capture the exit code and mute output.
 */
-function exitCode(argv: string[]): number {
+function exitCode(argv: string[], experimentalEnv = false): number {
  const exit = vi.spyOn(process, 'exit').mockImplementation(() => { throw new Error('exit') })
  vi.spyOn(process.stdout, 'write').mockReturnValue(true)
  vi.spyOn(process.stderr, 'write').mockReturnValue(true)
  try {
-    parse(argv)
+    parse(argv, experimentalEnv)
    throw new Error(`expected ${JSON.stringify(argv)} to exit`)
  } catch {
    return exit.mock.calls.at(-1)?.[0] as number
@@ -24,13 +24,15 @@ function exitCode(argv: string[]): number {
 afterEach(() => { vi.restoreAllMocks() })

 describe('parseDshArgs', () => {
-  it('routes each mode by its shape: default TUI, -p headless, meta and web subcommands', () => {
+  it('routes each mode by its shape: default TUI, -p headless, experimental and web subcommands', () => {
    expect(parse([])).toEqual({ mode: 'tui' })
    expect(parse(['--config', 'custom.yml'])).toEqual({ mode: 'tui', config: 'custom.yml' })
    expect(parse(['--config-replace', 'tree.yml'])).toEqual({ mode: 'tui', configReplace: 'tree.yml' })
    expect(parse(['--resume', 'sess', '--config', 'app.yml'])).toEqual({ mode: 'tui', config: 'app.yml', resume: 'sess' })
    expect(parse(['-p', 'do the thing'])).toEqual({ mode: 'headless', prompt: 'do the thing' })
-    expect(parse(['meta'])).toEqual({ mode: 'meta' })
+    // Experimental subcommands run under the per-invocation flag or the env opt-in.
+    expect(parse(['meta', '--experimental'])).toEqual({ mode: 'meta' })
+    expect(parse(['meta'], true)).toEqual({ mode: 'meta' })
    // Bare `web` carries no host/port: the shipped Web overlay owns the default.
    expect(parse(['web'])).toEqual({ mode: 'web', dev: false })
    expect(parse(['web', '--config', 'web.yml'])).toEqual({ mode: 'web', dev: false, config: 'web.yml' })
@@ -39,7 +41,8 @@ describe('parseDshArgs', () => {
    expect(parse(['web', '--host', '0.0.0.0', '--port', '8080', '--dev', '--workspace-root', '/w']))
      .toEqual({ mode: 'web', host: '0.0.0.0', port: 8080, dev: true, workspaceRoot: '/w' })
    // Guided fresh-session entries carry nothing: bare mode discriminant only.
-    expect(parse(['upgrade'])).toEqual({ mode: 'upgrade' })
+    expect(parse(['upgrade', '--experimental'])).toEqual({ mode: 'upgrade' })
+    expect(parse(['upgrade'], true)).toEqual({ mode: 'upgrade' })
    // --trusted-host is variadic and repeatable; authorities pass through unvalidated.
    expect(parse(['web', '--trusted-host', 'harness.internal:3080', 'lab.internal', '--trusted-host', '10.0.0.9']))
      .toEqual({ mode: 'web', dev: false, trustedHosts: ['harness.internal:3080', 'lab.internal', '10.0.0.9'] })
@@ -64,8 +67,8 @@ describe('parseDshArgs', () => {
    expect(exitCode(['web', '--dump-config', '--dump-default-config'])).toBe(1)
    expect(exitCode(['web', '--dump-default-config', '--config', 'w.yml'])).toBe(1)
    // A leaked dump flag on a subcommand that has none is a mistyped invocation.
-    expect(exitCode(['meta', '--dump-config'])).toBe(1)
-    expect(exitCode(['upgrade', '--dump-config'])).toBe(1)
+    expect(exitCode(['meta', '--experimental', '--dump-config'])).toBe(1)
+    expect(exitCode(['upgrade', '--experimental', '--dump-config'])).toBe(1)
  })

  it('exits nonzero instead of silently starting fresh or dropping inputs', () => {
@@ -88,17 +91,32 @@ describe('parseDshArgs', () => {
    expect(exitCode(['--config-replace', 'tree.yml', 'web'])).toBe(1)
    // Same rule for each subcommand that shares no option with the default
    // surface, so a leaked flag is a typo, not something to ignore.
-    // `meta` fixes its own config tree and always starts fresh, so every
-    // default-surface option is rejected.
-    expect(exitCode(['meta', '--resume', 's'])).toBe(1)
-    expect(exitCode(['meta', '--config', 'c.yml'])).toBe(1)
-    expect(exitCode(['meta', '--config-replace', 'tree.yml'])).toBe(1)
-    expect(exitCode(['meta', '-p', 'task'])).toBe(1)
-    // `upgrade` takes no options: any leaked default-surface flag is a
-    // mistyped invocation, not a silently-dropped input.
-    expect(exitCode(['upgrade', '--resume', 's'])).toBe(1)
-    expect(exitCode(['upgrade', '--config', 'c.yml'])).toBe(1)
-    expect(exitCode(['-p', 'task', 'upgrade'])).toBe(1)
+    // `meta` fixes its own config tree and always starts fresh,
+    // so every default-surface option is rejected.
+    expect(exitCode(['meta', '--experimental', '--resume', 's'])).toBe(1)
+    expect(exitCode(['meta', '--experimental', '--config', 'c.yml'])).toBe(1)
+    expect(exitCode(['meta', '--experimental', '--config-replace', 'tree.yml'])).toBe(1)
+    expect(exitCode(['meta', '--experimental', '-p', 'task'])).toBe(1)
+    // `upgrade` takes no options beyond the gate: any leaked default-surface
+    // flag is a mistyped invocation, not a silently-dropped input.
+    expect(exitCode(['upgrade', '--experimental', '--resume', 's'])).toBe(1)
+    expect(exitCode(['upgrade', '--experimental', '--config', 'c.yml'])).toBe(1)
+    expect(exitCode(['-p', 'task', 'upgrade', '--experimental'])).toBe(1)
+    // The pre-release command names have no compatibility aliases.
+    expect(exitCode(['experimental-meta'])).toBe(1)
+    expect(exitCode(['experimental-upgrade'])).toBe(1)
+  })
+
+  it('gates experimental subcommands behind --experimental or the env opt-in', () => {
+    // Bare `meta`/`upgrade` without either opt-in must fail loud, not run.
+    expect(exitCode(['meta'])).toBe(1)
+    expect(exitCode(['upgrade'])).toBe(1)
+    // A leaked default-surface flag stays a typo even when the gate is passed
+    // by the environment alone.
+    expect(exitCode(['meta', '--resume', 's'], true)).toBe(1)
+    // The flag and the env opt-in may coexist.
+    expect(parse(['meta', '--experimental'], true)).toEqual({ mode: 'meta' })
+    expect(parse(['upgrade', '--experimental'], true)).toEqual({ mode: 'upgrade' })
  })

  it('exits 0 for --help (disclosing web) and --version', () => {
@@ -54,6 +54,31 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
    expect(stdout).toBe('')
  }, 30_000)

+  describe('experimental subcommand gate', () => {
+    // The gate has two halves: a per-invocation --experimental flag parsed by
+    // Commander and an env opt-in read by bin.ts as exactly '1'. Passing the
+    // gate is proven by reaching the NEXT failure — the TUI's piped-stdio
+    // refusal — instead of the gate diagnostic.
+    it('rejects bare `meta`/`upgrade` LOUD, naming both opt-ins', async () => {
+      for (const command of ['meta', 'upgrade']) {
+        const { code, stderr } = await runBuiltBin([command], { DSH_EXPERIMENTAL: '' })
+        expect(code).toBe(1)
+        expect(stderr).toContain(`${command} is experimental; pass --experimental or set DSH_EXPERIMENTAL=1`)
+      }
+    }, 30_000)
+
+    it('admits --experimental and DSH_EXPERIMENTAL=1, but not other env values', async () => {
+      const flagged = await runBuiltBin(['meta', '--experimental'], { DSH_EXPERIMENTAL: '' })
+      expect(flagged.stderr).toContain('requires stdin and stdout to be interactive TTYs')
+      const env = await runBuiltBin(['meta'], { DSH_EXPERIMENTAL: '1' })
+      expect(env.stderr).toContain('requires stdin and stdout to be interactive TTYs')
+      // The env opt-in is exact: '0' (or any other value) does not enable.
+      const zero = await runBuiltBin(['meta'], { DSH_EXPERIMENTAL: '0' })
+      expect(zero.code).toBe(1)
+      expect(zero.stderr).toContain('meta is experimental')
+    }, 30_000)
+  })
+
  describe('dsh --dump-config', () => {
    let home: string
    beforeEach(() => { home = mkdtempSync(join(tmpdir(), 'dsh-dump-bin-')) })
@@ -6,11 +6,11 @@ import { execa } from 'execa'
 import { resolveExampleLaunch, type ExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'

 const POSIX_PTY_DRIVER = String.raw`
-import errno, json, os, pty, select, signal, sys, time
-node, launch_args_json, launch_env_json, cwd, actions_json, expected_exit, timeout_seconds = sys.argv[1:]
+import errno, fcntl, json, os, pty, select, signal, struct, sys, termios, time
+node, launch_args_json, launch_env_json, cwd, actions_json, expected_exit, timeout_seconds, columns, rows = sys.argv[1:]
 env = os.environ.copy()
 env.update(json.loads(launch_env_json))
-env.update({"COLUMNS": "100", "LINES": "30"})
+env.update({"COLUMNS": columns, "LINES": rows})
 # Deterministic banner: a developer shell's COLORTERM=truecolor would switch the
 # banner to the per-letter gradient (one SGR per letter), breaking literal
 # DEEPSEEK assertions. The gradient path has its own unit and snapshot coverage.
@@ -20,6 +20,7 @@ pid, fd = pty.fork()
 if pid == 0:
    os.chdir(cwd)
    os.execvpe(node, [node, *json.loads(launch_args_json)], env)
+fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", int(rows), int(columns), 0, 0))

 output = bytearray()
 action_index = 0
@@ -36,9 +37,14 @@ while time.monotonic() < deadline:
            chunk = b""
        if chunk:
            output.extend(chunk)
-    while action_index < len(actions) and actions[action_index]["waitFor"].encode() in output:
+    while action_index < len(actions):
+        marker = actions[action_index]["waitFor"].encode()
+        if output.count(marker) < actions[action_index].get("occurrence", 1):
+            break
        action = actions[action_index]
-        if "writeFile" in action:
+        if "signal" in action:
+            os.kill(pid, getattr(signal, action["signal"]))
+        elif "writeFile" in action:
            target = os.path.join(cwd, action["writeFile"]["path"])
            os.makedirs(os.path.dirname(target), exist_ok=True)
            with open(target, "w", encoding="utf-8") as handle:
@@ -68,9 +74,15 @@ if actual_exit != int(expected_exit):

 /** One terminal input or workspace mutation performed after its marker renders. */
 type TuiPtyAction =
-  | { readonly waitFor: string; readonly send: string }
  | {
    readonly waitFor: string
+    readonly occurrence?: number
+    readonly send: string
+  }
+  | { readonly waitFor: string; readonly occurrence?: number; readonly signal: 'SIGTERM' }
+  | {
+    readonly waitFor: string
+    readonly occurrence?: number
    readonly writeFile: { readonly path: string; readonly content: string }
    readonly send?: string
  }
@@ -89,6 +101,12 @@ export interface TuiPtySmokeOptions {
  readonly env?: Readonly<NodeJS.ProcessEnv>
  readonly expectedExitCode?: number
  readonly timeoutMs?: number
+  /** Existing isolated workspace to reuse; when omitted the harness creates and removes one. */
+  readonly cwd?: string
+  /** Pseudo-terminal columns; defaults to 100. */
+  readonly columns?: number
+  /** Pseudo-terminal rows; defaults to 30. */
+  readonly rows?: number
  /** Seed the isolated workspace (`cwd`, with `$DSH_HOME` at `.dsh` and the agents home at `.agents`) before launch. */
  readonly prepare?: (cwd: string) => Promise<void>
  /** Inspect the workspace after a passing run, before the temp dir is removed. */
@@ -119,6 +137,8 @@ async function runPosixPtySmoke(
    JSON.stringify(options.actions ?? []),
    String(options.expectedExitCode ?? 0),
    String(timeoutMs / 1_000),
+    String(options.columns ?? 100),
+    String(options.rows ?? 30),
  ], {
    stdin: 'ignore',
    timeout: timeoutMs + 5_000,
@@ -150,8 +170,8 @@ async function runWindowsPtySmoke(
    let timedOut = false
    const terminal = pty.spawn(launch.command, launch.args, {
      name: 'xterm-256color',
-      cols: 100,
-      rows: 30,
+      cols: options.columns ?? 100,
+      rows: options.rows ?? 30,
      cwd,
      env: definedEnv({
        ...process.env,
@@ -159,8 +179,8 @@ async function runWindowsPtySmoke(
        // Match the POSIX driver: no COLORTERM, so the banner never takes the
        // truecolor gradient path under a developer's shell.
        COLORTERM: undefined,
-        COLUMNS: '100',
-        LINES: '30',
+        COLUMNS: String(options.columns ?? 100),
+        LINES: String(options.rows ?? 30),
      }),
    })
    const timer = setTimeout(() => {
@@ -169,9 +189,14 @@ async function runWindowsPtySmoke(
    }, timeoutMs)
    terminal.onData((chunk) => {
      output += chunk
-      while (actionIndex < actions.length && output.includes(actions[actionIndex]!.waitFor)) {
+      while (
+        actionIndex < actions.length
+        && output.split(actions[actionIndex]!.waitFor).length - 1 >= (actions[actionIndex]!.occurrence ?? 1)
+      ) {
        const action = actions[actionIndex]!
-        if ('writeFile' in action) {
+        if ('signal' in action) {
+          terminal.kill(action.signal)
+        } else if ('writeFile' in action) {
          const target = join(cwd, action.writeFile.path)
          mkdirSync(dirname(target), { recursive: true })
          writeFileSync(target, action.writeFile.content)
@@ -205,7 +230,8 @@ async function runWindowsPtySmoke(
 * @returns complete pseudo-terminal output.
 */
 export async function runTuiPtySmoke(options: TuiPtySmokeOptions): Promise<string> {
-  const cwd = await mkdtemp(join(tmpdir(), options.tempDirPrefix))
+  const ownedCwd = options.cwd === undefined
+  const cwd = options.cwd ?? await mkdtemp(join(tmpdir(), options.tempDirPrefix))
  const timeoutMs = options.timeoutMs ?? 25_000
  try {
    await options.prepare?.(cwd)
@@ -231,6 +257,6 @@ export async function runTuiPtySmoke(options: TuiPtySmokeOptions): Promise<strin
    await options.inspect?.(cwd)
    return output
  } finally {
-    await rm(cwd, { recursive: true, force: true })
+    if (ownedCwd) await rm(cwd, { recursive: true, force: true })
  }
 }
@@ -7,6 +7,7 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { COMPOSITION_REPLY_TEXT } from './fixtures/composition-echo-llm.ts'
 import { COMPOSITION_SETTLED_MARKER } from './fixtures/composition-settled.ts'
 import { runTuiPtySmoke } from './pty-harness.ts'
+import { acknowledgeTuiFirstRunWelcome } from '../src/tui-onboarding/tui-first-run-welcome.ts'

 const dshBinScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
@@ -105,6 +106,7 @@ describe('shipped dsh composition (real Loader tree in a PTY)', () => {
      tsconfigPath,
      configPath: keylessTail,
      env: { DEEPSEEK_API_KEY: 'keyless-composition-no-call', DSH_TELEMETRY_DISABLED: '1' },
+      prepare: cwd => acknowledgeTuiFirstRunWelcome(join(cwd, '.dsh')),
      // Artifact CI builds and smokes concurrently on a contended runner.
      ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? { timeoutMs: 60_000 } : {}),
      actions: [
@@ -0,0 +1,30 @@
+{"type":"session","version":0,"id":"main-session","createdAt":1784606400000,"cwd":"{{cwd}}"}
+{"type":"turn/start","seq":0,"time":1784606400000,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1784606400000,"data":{"content":[{"type":"text","text":"what's the workdir?"}],"source":{"kind":"user"},"role":"user","id":"3fdc2885-1bea-4c6c-b4af-dbd5af7594f8"},"surfaceOp":"append"}
+{"type":"session/title","seq":2,"time":1784606400000,"data":{"title":"what's the workdir?","messageSeqs":[1],"source":{"kind":"fallback"}}}
+{"type":"step/start","seq":3,"time":1784606400000,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":4,"time":1784606400000,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash","reasoningEffort":"high"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":5,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"reasoning-chunks","seq0":6,"time0":1784606400000,"data":{"turn":1,"step":1,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," user"," is"," asking"," about"," the"," current"," working"," directory","."," Let"," me"," check"," using"," p","wd","."]}}
+{"type":"assistant/chunk","seq":23,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":24,"time0":1784606400000,"data":{"turn":1,"step":1,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_AqoWTncquNel5ZHsJHOo7491","name":"bash","args":["","{","\"","command","\"",": ","\"","p","wd","\"",", ","\"","description","\"",": ","\"","Print"," current"," working"," directory","\"","}"]}}
+{"type":"assistant/chunk","seq":46,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user is asking about the current working directory. Let me check using pwd."}}}}
+{"type":"assistant/chunk","seq":47,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_AqoWTncquNel5ZHsJHOo7491","name":"bash","arguments":"{\"command\": \"pwd\", \"description\": \"Print current working directory\"}"}}}}
+{"type":"assistant/chunk","seq":48,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3332,"outputTokens":80,"cacheReadTokens":0,"reasoningTokens":17}}}}
+{"type":"assistant/chunk","seq":49,"time":1784606400000,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":50,"time":1784606400000,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user is asking about the current working directory. Let me check using pwd."},{"type":"tool-call","id":"call_00_AqoWTncquNel5ZHsJHOo7491","name":"bash","arguments":"{\"command\": \"pwd\", \"description\": \"Print current working directory\"}"}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"063a9245-32c3-4551-9ace-d43f10ed5582"},"usage":{"inputTokens":3332,"outputTokens":80,"cacheReadTokens":0,"reasoningTokens":17}},"sourceEventSeqs":[5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49],"surfaceOp":"append"}
+{"type":"tool/call","seq":51,"time":1784606400000,"data":{"turn":1,"step":1,"callId":"call_00_AqoWTncquNel5ZHsJHOo7491","name":"bash","arguments":"{\"command\": \"pwd\", \"description\": \"Print current working directory\"}"}}
+{"type":"tool/result","seq":52,"time":1784606400000,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_AqoWTncquNel5ZHsJHOo7491"},"content":[{"type":"tool-result","toolCallId":"call_00_AqoWTncquNel5ZHsJHOo7491","content":[{"type":"text","text":"{{cwd}}\n"}],"isError":false}],"role":"user","id":"16086d3b-6dfa-4970-a06e-78561475af8c"}},"sourceEventSeqs":[51],"surfaceOp":"append"}
+{"type":"step/end","seq":53,"time":1784606400000,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":54,"time":1784606400000,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":55,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"reasoning-chunks","seq0":56,"time0":1784606400000,"data":{"turn":1,"step":2,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," current"," working"," directory"," is"," `/","private","/t","mp","/d","sh","-t","ui","-s","n","apshot","-source","-check","out","-work","dir","-","61","I","wn","K","`."]}}
+{"type":"assistant/chunk","seq":83,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"text-chunks","seq0":84,"time0":1784606400000,"data":{"turn":1,"step":2,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The"," current"," working"," directory"," is",":\n\n","```\n","/","private","/t","mp","/d","sh","-t","ui","-s","n","apshot","-source","-check","out","-work","dir","-","61","I","wn","K","\n","```\n\n","Note"," that"," the"," Deep","Se","ek"," Har","ness"," SDK"," checkout"," is"," at"," `/","opt","/d","sh","-source","`"," —"," that","'s"," a"," separate"," location"," used"," for"," inspecting"," or"," extending"," D","SH"," itself",","," while"," the"," working"," directory"," above"," is"," the"," current"," working"," directory"," for"," this"," session","."]}}
+{"type":"assistant/chunk","seq":161,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The current working directory is `{{cwd}}`."}}}}
+{"type":"assistant/chunk","seq":162,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"The current working directory is:\n\n```\n{{cwd}}\n```\n\nNote that the DeepSeek Harness SDK checkout is at `/opt/dsh-source` — that's a separate location used for inspecting or extending DSH itself, while the working directory above is the current working directory for this session."}}}}
+{"type":"assistant/chunk","seq":163,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":117,"outputTokens":105,"cacheReadTokens":3328,"reasoningTokens":27}}}}
+{"type":"assistant/chunk","seq":164,"time":1784606400000,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":165,"time":1784606400000,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The current working directory is `{{cwd}}`."},{"type":"text","text":"The current working directory is:\n\n```\n{{cwd}}\n```\n\nNote that the DeepSeek Harness SDK checkout is at `/opt/dsh-source` — that's a separate location used for inspecting or extending DSH itself, while the working directory above is the current working directory for this session."}],"source":{"kind":"model","provider":"deepseek","model":"deepseek-v4-flash"},"id":"76c18b85-00aa-45f6-a32f-a2bd75412470"},"usage":{"inputTokens":117,"outputTokens":105,"cacheReadTokens":3328,"reasoningTokens":27}},"sourceEventSeqs":[55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164],"surfaceOp":"append"}
+{"type":"step/end","seq":166,"time":1784606400000,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":167,"time":1784606400000,"data":{"turn":1,"reason":{"kind":"completed"}}}
@@ -0,0 +1,67 @@
+terminal 100x36 buffer=normal length=36 base=0 viewport=0
+lifecycle started=1 stopped=0 progress=inactive
+title "what's the workdir? — DSH TUI snapshot"
+cursor hidden column=7 viewportRow=32 bufferRow=32
+buffer
+0| " DEEPSEEK HARNESS"
+  style 1-8 fg=bright-magenta bold
+  style 10-16 bold
+1| " what's the workdir?"
+  style 1-19 dim
+2| " main-session"
+  style 1-12 dim
+3| <blank>
+4| "You                                                                                                 "
+  style 0-2 fg=bright-magenta bold underline
+5| "what's the workdir?                                                                                 "
+6| <blank>
+7| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+8| "Reasoning                                                                                           "
+  style 0-8 dim italic
+9| "The user is asking about the current working directory. Let me check using pwd.                     "
+  style 0-78 dim italic
+10| <blank>
+11| "● Tool / bash / Print current working directory"
+  style 0-46 fg=green
+12| "$ pwd                                                                                               "
+  style 0-4 dim
+13| "/workspace/project                                                                                  "
+  style 0-17 dim
+14| "[exit 0]                                                                                            "
+  style 0-7 dim
+15| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+16| <blank>
+17| "Assistant                                                                                           "
+  style 0-8 fg=bright-magenta bold underline
+18| "Reasoning                                                                                           "
+  style 0-8 dim italic
+19| "The current working directory is /workspace/project.              "
+  style 0-32 dim italic
+  style 33-84 fg=cyan
+  style 85-85 dim italic
+20| "The current working directory is:                                                                   "
+21| "                                                                                                    "
+22| "                                                                                                    "
+23| "  /workspace/project                                              "
+  style 2-53 fg=cyan
+24| "                                                                                                    "
+25| "                                                                                                    "
+26| "Note that the DeepSeek Harness SDK checkout is at /opt/dsh-source — that's a separate location used "
+  style 50-64 fg=cyan
+27| "for inspecting or extending DSH itself, while the working directory above is the current working    "
+28| "directory for this session.                                                                         "
+29| "Model wait 0.0s · Completed 2026-07-21 12:00:00                                                     "
+  style 0-46 dim
+30| <blank>
+31| "/workspace/project  deepseek-v4-flash  ↑3.4k ↓185  cache 49%  3% c"
+  style 0-51 fg=bright-magenta bold
+  style 54-70 dim
+  style 73-93 dim
+  style 96-99 dim
+32| " dsh ◍                                                                                              "
+  style 1-3 fg=bright-magenta bold
+  style 5-6 dim
+  style 7-7 inverse
+33-35| <blank>
@@ -0,0 +1,76 @@
+overlay 120x30 rows=20
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-119 dim
+1| "│                                    ▄                                     DeepSeek Harness                            │"
+  style 0-0 dim
+  style 10-37 fg=blue
+  style 75-90 fg=blue bold
+  style 119-119 dim
+2| "│               ▄▄▄▄▄▄▄▄▄▄███▀      ██▄                                                                                │"
+  style 0-0 dim
+  style 9-38 fg=blue
+  style 119-119 dim
+3| "│       ▄███████████████▄      ████▄  ▄▄▄▄██     感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能 │"
+  style 0-0 dim
+  style 4-43 fg=blue
+  style 119-119 dim
+4| "│     ▄███████████████████▄    ████████████▀     仍待完善，体验难免有些粗糙。                                          │"
+  style 0-0 dim
+  style 4-43 fg=blue
+  style 119-119 dim
+5| "│    ▄██████████████████████▄   ▀█████████▀                                                                            │"
+  style 0-0 dim
+  style 4-42 fg=blue
+  style 119-119 dim
+6| "│     ▄███▀█████████████████████▄   ████▀▀       “如切如磋，如琢如磨。”                                                │"
+  style 0-0 dim
+  style 6-41 fg=blue
+  style 49-70 bold
+  style 119-119 dim
+7| "│      ███       ▀▀█████████▀▀▀█████████▀                                                                              │"
+  style 0-0 dim
+  style 7-40 fg=blue
+  style 119-119 dim
+8| "│      ███          ▀███████▀█  ▀███████         产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的  │"
+  style 0-0 dim
+  style 7-39 fg=blue
+  style 119-119 dim
+9| "│      ███▄           ▀███████▄  ▀█████▀         问题，也可能促使我们重新审视，甚至推翻已有的设计。                    │"
+  style 0-0 dim
+  style 7-39 fg=blue
+  style 119-119 dim
+10| "│       ▀███             ▀██████████████                                                                               │"
+  style 0-0 dim
+  style 8-39 fg=blue
+  style 119-119 dim
+11| "│        ▀███▄            ▀███████████▀          为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有    │"
+  style 0-0 dim
+  style 8-38 fg=blue
+  style 119-119 dim
+12| "│          ▀███▄      ▄▄▄    ▀████████▀          Session Log；如需关闭，请设置环境变量 DSH_TELEMETRY_DISABLED=1。另外  │"
+  style 0-0 dim
+  style 9-38 fg=blue
+  style 119-119 dim
+13| "│            █████▄    ███▄▄   ▀█████▄▄          ，如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈，  │"
+  style 0-0 dim
+  style 9-38 fg=blue
+  style 119-119 dim
+14| "│             ▀█████████████▄▄▄▄█▀█████▀         都会帮助我们把它打磨得更好。                                          │"
+  style 0-0 dim
+  style 8-39 fg=blue
+  style 119-119 dim
+15| "│                   ▀▀███████████▀▀                                                                                    │"
+  style 0-0 dim
+  style 12-34 fg=blue
+  style 119-119 dim
+16| "├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤"
+  style 0-119 dim
+17| "│                                                     Enter  继续                                                      │"
+  style 0-0 dim
+  style 54-64 fg=bright-magenta bold
+  style 119-119 dim
+18| "│                                                                                                                      │"
+  style 0-0 dim
+  style 119-119 dim
+19| "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-119 dim
@@ -0,0 +1,76 @@
+overlay 160x30 rows=20
+0| "╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮"
+  style 0-159 dim
+1| "│                                    ▄                                                         DeepSeek Harness                                                │"
+  style 0-0 dim
+  style 10-37 fg=blue
+  style 95-110 fg=blue bold
+  style 159-159 dim
+2| "│               ▄▄▄▄▄▄▄▄▄▄███▀      ██▄                                                                                                                        │"
+  style 0-0 dim
+  style 9-38 fg=blue
+  style 159-159 dim
+3| "│       ▄███████████████▄      ████▄  ▄▄▄▄██     感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能仍待完善，体验难免有些粗糙。             │"
+  style 0-0 dim
+  style 4-43 fg=blue
+  style 159-159 dim
+4| "│     ▄███████████████████▄    ████████████▀                                                                                                                   │"
+  style 0-0 dim
+  style 4-43 fg=blue
+  style 159-159 dim
+5| "│    ▄██████████████████████▄   ▀█████████▀      “如切如磋，如琢如磨。”                                                                                        │"
+  style 0-0 dim
+  style 4-42 fg=blue
+  style 49-70 bold
+  style 159-159 dim
+6| "│     ▄███▀█████████████████████▄   ████▀▀                                                                                                                     │"
+  style 0-0 dim
+  style 6-41 fg=blue
+  style 159-159 dim
+7| "│      ███       ▀▀█████████▀▀▀█████████▀        产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的问题，也可能促使我们重新审视，甚至推翻已  │"
+  style 0-0 dim
+  style 7-40 fg=blue
+  style 159-159 dim
+8| "│      ███          ▀███████▀█  ▀███████         有的设计。                                                                                                    │"
+  style 0-0 dim
+  style 7-39 fg=blue
+  style 159-159 dim
+9| "│      ███▄           ▀███████▄  ▀█████▀                                                                                                                       │"
+  style 0-0 dim
+  style 7-39 fg=blue
+  style 159-159 dim
+10| "│       ▀███             ▀██████████████         为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 Session Log；如需关闭，请设置环境变量      │"
+  style 0-0 dim
+  style 8-39 fg=blue
+  style 159-159 dim
+11| "│        ▀███▄            ▀███████████▀          DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我  │"
+  style 0-0 dim
+  style 8-38 fg=blue
+  style 159-159 dim
+12| "│          ▀███▄      ▄▄▄    ▀████████▀          们把它打磨得更好。                                                                                            │"
+  style 0-0 dim
+  style 9-38 fg=blue
+  style 159-159 dim
+13| "│            █████▄    ███▄▄   ▀█████▄▄                                                                                                                        │"
+  style 0-0 dim
+  style 9-38 fg=blue
+  style 159-159 dim
+14| "│             ▀█████████████▄▄▄▄█▀█████▀                                                                                                                       │"
+  style 0-0 dim
+  style 8-39 fg=blue
+  style 159-159 dim
+15| "│                   ▀▀███████████▀▀                                                                                                                            │"
+  style 0-0 dim
+  style 12-34 fg=blue
+  style 159-159 dim
+16| "├──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤"
+  style 0-159 dim
+17| "│                                                                         Enter  继续                                                                          │"
+  style 0-0 dim
+  style 74-84 fg=bright-magenta bold
+  style 159-159 dim
+18| "│                                                                                                                                                              │"
+  style 0-0 dim
+  style 159-159 dim
+19| "╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯"
+  style 0-159 dim
@@ -0,0 +1,31 @@
+overlay 60x12 rows=10
+0| "╭──────────────────────────────────────────────────────────╮"
+  style 0-59 dim
+1| "│                     DeepSeek Harness                     │"
+  style 0-0 dim
+  style 22-37 fg=blue bold
+  style 59-59 dim
+2| "│                                                          │"
+  style 0-0 dim
+  style 59-59 dim
+3| "│ 感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部  │"
+  style 0-0 dim
+  style 59-59 dim
+4| "│ 测试阶段，功能仍待完善，体验难免有些粗糙。               │"
+  style 0-0 dim
+  style 59-59 dim
+5| "│                                                          │"
+  style 0-0 dim
+  style 59-59 dim
+6| "├──────────────────────────────────────────────────────────┤"
+  style 0-59 dim
+7| "│                       Enter  继续                        │"
+  style 0-0 dim
+  style 24-34 fg=bright-magenta bold
+  style 59-59 dim
+8| "│                         ↑/↓ 滚动 ↓                       │"
+  style 0-0 dim
+  style 24-35 dim
+  style 59-59 dim
+9| "╰──────────────────────────────────────────────────────────╯"
+  style 0-59 dim
@@ -0,0 +1,64 @@
+overlay 60x30 rows=21
+0| "╭──────────────────────────────────────────────────────────╮"
+  style 0-59 dim
+1| "│                     DeepSeek Harness                     │"
+  style 0-0 dim
+  style 22-37 fg=blue bold
+  style 59-59 dim
+2| "│                                                          │"
+  style 0-0 dim
+  style 59-59 dim
+3| "│ 感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部  │"
+  style 0-0 dim
+  style 59-59 dim
+4| "│ 测试阶段，功能仍待完善，体验难免有些粗糙。               │"
+  style 0-0 dim
+  style 59-59 dim
+5| "│                                                          │"
+  style 0-0 dim
+  style 59-59 dim
+6| "│ “如切如磋，如琢如磨。”                                   │"
+  style 0-0 dim
+  style 2-23 bold
+  style 59-59 dim
+7| "│                                                          │"
+  style 0-0 dim
+  style 59-59 dim
+8| "│ 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实 │"
+  style 0-0 dim
+  style 59-59 dim
+9| "│ 使用中发现的问题，也可能促使我们重新审视，甚至推翻已有的 │"
+  style 0-0 dim
+  style 59-59 dim
+10| "│ 设计。                                                   │"
+  style 0-0 dim
+  style 59-59 dim
+11| "│                                                          │"
+  style 0-0 dim
+  style 59-59 dim
+12| "│ 为了帮助我们更准确地还原您真实使用中的问题，内测版本默认 │"
+  style 0-0 dim
+  style 59-59 dim
+13| "│ 会上传所有 Session Log；如需关闭，请设置环境变量         │"
+  style 0-0 dim
+  style 59-59 dim
+14| "│ DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反馈与建议， │"
+  style 0-0 dim
+  style 59-59 dim
+15| "│ 请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把 │"
+  style 0-0 dim
+  style 59-59 dim
+16| "│ 它打磨得更好。                                           │"
+  style 0-0 dim
+  style 59-59 dim
+17| "├──────────────────────────────────────────────────────────┤"
+  style 0-59 dim
+18| "│                       Enter  继续                        │"
+  style 0-0 dim
+  style 24-34 fg=bright-magenta bold
+  style 59-59 dim
+19| "│                                                          │"
+  style 0-0 dim
+  style 59-59 dim
+20| "╰──────────────────────────────────────────────────────────╯"
+  style 0-59 dim
@@ -0,0 +1,89 @@
+overlay 80x30 rows=27
+0| "╭──────────────────────────────────────────────────────────────────────────────╮"
+  style 0-79 dim
+1| "│                                   ▄▄▄▄▄▄   ▄▄                                │"
+  style 0-0 dim
+  style 33-46 fg=blue
+  style 79-79 dim
+2| "│                               ▄████████▄ ▀████▀                              │"
+  style 0-0 dim
+  style 31-48 fg=blue
+  style 79-79 dim
+3| "│                               █▀▀▀▀███████▄██▀                               │"
+  style 0-0 dim
+  style 32-47 fg=blue
+  style 79-79 dim
+4| "│                               █▄    ▀███ ▀███                                │"
+  style 0-0 dim
+  style 32-46 fg=blue
+  style 79-79 dim
+5| "│                                ▀█▄     ▀█████                                │"
+  style 0-0 dim
+  style 33-46 fg=blue
+  style 79-79 dim
+6| "│                                 ▀█▄▄ █▄▄▀███▄                                │"
+  style 0-0 dim
+  style 33-46 fg=blue
+  style 79-79 dim
+7| "│                                      ▀▀▀▀▀▀                                  │"
+  style 0-0 dim
+  style 35-44 fg=blue
+  style 79-79 dim
+8| "│                                                                              │"
+  style 0-0 dim
+  style 79-79 dim
+9| "│                               DeepSeek Harness                               │"
+  style 0-0 dim
+  style 32-47 fg=blue bold
+  style 79-79 dim
+10| "│                                                                              │"
+  style 0-0 dim
+  style 79-79 dim
+11| "│ 感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能仍待完  │"
+  style 0-0 dim
+  style 79-79 dim
+12| "│ 善，体验难免有些粗糙。                                                       │"
+  style 0-0 dim
+  style 79-79 dim
+13| "│                                                                              │"
+  style 0-0 dim
+  style 79-79 dim
+14| "│ “如切如磋，如琢如磨。”                                                       │"
+  style 0-0 dim
+  style 2-23 bold
+  style 79-79 dim
+15| "│                                                                              │"
+  style 0-0 dim
+  style 79-79 dim
+16| "│ 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的问题，也 │"
+  style 0-0 dim
+  style 79-79 dim
+17| "│ 可能促使我们重新审视，甚至推翻已有的设计。                                   │"
+  style 0-0 dim
+  style 79-79 dim
+18| "│                                                                              │"
+  style 0-0 dim
+  style 79-79 dim
+19| "│ 为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 Session   │"
+  style 0-0 dim
+  style 79-79 dim
+20| "│ Log；如需关闭，请设置环境变量 DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反 │"
+  style 0-0 dim
+  style 79-79 dim
+21| "│ 馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把它打磨得更 │"
+  style 0-0 dim
+  style 79-79 dim
+22| "│ 好。                                                                         │"
+  style 0-0 dim
+  style 79-79 dim
+23| "├──────────────────────────────────────────────────────────────────────────────┤"
+  style 0-79 dim
+24| "│                                 Enter  继续                                  │"
+  style 0-0 dim
+  style 34-44 fg=bright-magenta bold
+  style 79-79 dim
+25| "│                                                                              │"
+  style 0-0 dim
+  style 79-79 dim
+26| "╰──────────────────────────────────────────────────────────────────────────────╯"
+  style 0-79 dim
@@ -0,0 +1,346 @@
+import { createHash } from 'node:crypto'
+import { mkdir, mkdtemp, readFile, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Context } from 'cordis'
+import { visibleWidth } from '@earendil-works/pi-tui'
+import {
+  type TuiOverlayHost,
+  type TuiOverlayRequest,
+  type TuiTheme,
+} from '@deepseek-ai/dsh-tui'
+import {
+  acknowledgeTuiFirstRunWelcome,
+  apply,
+  hasTuiFirstRunWelcomeAcknowledgement,
+  needsTuiFirstRunWelcomeAsciiArt,
+  TuiFirstRunWelcomeComponent,
+  tuiFirstRunWelcomeAcknowledgementPath,
+  tuiFirstRunWelcomeArtTier,
+} from '../src/tui-onboarding/tui-first-run-welcome.ts'
+import {
+  TUI_FIRST_RUN_WELCOME_NOTICE_COPY,
+  TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE,
+  TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+} from '../src/tui-onboarding/tui-first-run-welcome-copy.ts'
+import { TUI_FIRST_RUN_WELCOME_WHALE } from '../src/tui-onboarding/tui-first-run-welcome-art.ts'
+
+const mockDisposeRootAndExit = vi.hoisted(() => vi.fn())
+vi.mock('@deepseek-ai/dsh-tui', async importOriginal => ({
+  ...await importOriginal<typeof import('@deepseek-ai/dsh-tui')>(),
+  disposeRootAndExit: mockDisposeRootAndExit,
+}))
+
+const identityTheme: TuiTheme = Object.freeze({
+  text: (value: string) => value,
+  brand: (value: string) => value,
+  dim: (value: string) => value,
+  accent: (value: string) => value,
+  success: (value: string) => value,
+  warning: (value: string) => value,
+  error: (value: string) => value,
+  bold: (value: string) => value,
+})
+
+function hostFixture(rows: number): {
+  host: TuiOverlayHost
+  closed: () => boolean
+  invalidations: () => number
+} {
+  let closed = false
+  let invalidations = 0
+  const controller = new AbortController()
+  return {
+    host: Object.freeze({
+      signal: controller.signal,
+      viewport: Object.freeze({ columns: 160, rows }),
+      theme: identityTheme,
+      display: (value: string) => value,
+      invalidate: () => { invalidations += 1 },
+      close: () => { closed = true },
+    }),
+    closed: () => closed,
+    invalidations: () => invalidations,
+  }
+}
+
+const copy = TUI_FIRST_RUN_WELCOME_NOTICE_COPY[TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE]
+const openingSentence = `${copy.paragraphs[0]!.split('。', 1)[0]}。`
+const temporaryHomes: string[] = []
+
+function artAnchor(tier: keyof typeof TUI_FIRST_RUN_WELCOME_WHALE): string {
+  return TUI_FIRST_RUN_WELCOME_WHALE[tier].unicode[tier === 'full' ? 2 : 0]!.trim()
+}
+
+function withoutWhitespace(value: string): string {
+  return value.replace(/\s/gu, '')
+}
+
+async function temporaryHome(prefix: string): Promise<string> {
+  const home = await mkdtemp(join(tmpdir(), prefix))
+  temporaryHomes.push(home)
+  return home
+}
+
+afterEach(async () => {
+  mockDisposeRootAndExit.mockClear()
+  await Promise.all(temporaryHomes.splice(0).map(home => rm(home, { recursive: true, force: true })))
+})
+
+describe('TUI first-run welcome acknowledgement', () => {
+  it('publishes one immutable per-version marker safely across concurrent acknowledgements', async () => {
+    const home = await temporaryHome('dsh-tui-welcome-ack-')
+    expect(await hasTuiFirstRunWelcomeAcknowledgement(home)).toBe(false)
+
+    await Promise.all(Array.from({ length: 8 }, () => acknowledgeTuiFirstRunWelcome(home)))
+
+    expect(await hasTuiFirstRunWelcomeAcknowledgement(home)).toBe(true)
+    const info = await stat(tuiFirstRunWelcomeAcknowledgementPath(home, TUI_FIRST_RUN_WELCOME_NOTICE_VERSION))
+    expect(info.isFile()).toBe(true)
+    if (process.platform !== 'win32') expect(info.mode & 0o777).toBe(0o600)
+  })
+
+  it('treats a notice-version bump as a new one-time acknowledgement', async () => {
+    const home = await temporaryHome('dsh-tui-welcome-version-')
+    await acknowledgeTuiFirstRunWelcome(home)
+    const nextVersion = TUI_FIRST_RUN_WELCOME_NOTICE_VERSION + 1
+
+    expect(await hasTuiFirstRunWelcomeAcknowledgement(home, nextVersion)).toBe(false)
+    await acknowledgeTuiFirstRunWelcome(home, nextVersion)
+    expect(await hasTuiFirstRunWelcomeAcknowledgement(home, nextVersion)).toBe(true)
+  })
+
+  it('rejects a malformed marker instead of silently acknowledging it', async () => {
+    const home = await temporaryHome('dsh-tui-welcome-malformed-')
+    await mkdir(tuiFirstRunWelcomeAcknowledgementPath(home, TUI_FIRST_RUN_WELCOME_NOTICE_VERSION), {
+      recursive: true,
+    })
+    await expect(hasTuiFirstRunWelcomeAcknowledgement(home)).rejects.toThrow('is not a file')
+    await expect(acknowledgeTuiFirstRunWelcome(home)).rejects.toThrow()
+  })
+
+  it('detects only explicit ASCII-only terminal environments', () => {
+    expect(needsTuiFirstRunWelcomeAsciiArt({ TERM: 'dumb' })).toBe(true)
+    expect(needsTuiFirstRunWelcomeAsciiArt({ LC_ALL: 'C' })).toBe(true)
+    expect(needsTuiFirstRunWelcomeAsciiArt({ LC_CTYPE: 'POSIX' })).toBe(true)
+    expect(needsTuiFirstRunWelcomeAsciiArt({ LANG: 'C' })).toBe(true)
+    expect(needsTuiFirstRunWelcomeAsciiArt({ LANG: 'en_US.UTF-8' })).toBe(false)
+    expect(typeof needsTuiFirstRunWelcomeAsciiArt()).toBe('boolean')
+  })
+})
+
+describe('TUI first-run welcome composition', () => {
+  it('pins the supplied official icon and exact Chinese copy at their owner boundaries', async () => {
+    const icon = (await readFile(new URL('../assets/deepseek-color.svg', import.meta.url), 'utf8')).trimEnd()
+    expect(createHash('sha256').update(icon).digest('hex'))
+      .toBe('deba5f98a5c1796e20fcac3149bcd7eb8a32f0bdd04d048819400b1f28bd1439')
+    expect(createHash('sha256').update(copy.paragraphs.join('\n')).digest('hex'))
+      .toBe('99f9a828b4f083b28de21bf5e03f939c00238531e765db78911957c44c6e98da')
+    expect(TUI_FIRST_RUN_WELCOME_NOTICE_COPY.en).toBe(copy)
+  })
+
+  it.each([
+    { columns: 60, inner: 50, rows: 30, tier: undefined },
+    { columns: 80, inner: 68, rows: 30, tier: 'minimal' },
+    { columns: 100, inner: 84, rows: 34, tier: 'compact' },
+    { columns: 120, inner: 104, rows: 30, tier: 'full' },
+    { columns: 160, inner: 140, rows: 30, tier: 'full' },
+  ] as const)('renders the responsive composition at $columns columns without overdraw', ({ inner, rows, tier }) => {
+    const fixture = hostFixture(rows)
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => {}, () => {})
+    const renderWidth = inner + 4
+    const lines = component.render(renderWidth)
+
+    expect(tuiFirstRunWelcomeArtTier(inner, rows)).toBe(tier)
+    expect(lines.every(line => visibleWidth(line) <= renderWidth)).toBe(true)
+    if (tier === undefined) {
+      expect(lines.join('\n')).not.toMatch(/[▀▄█]/u)
+    } else {
+      expect(lines.join('\n')).toContain(artAnchor(tier))
+    }
+    const rendered = lines.join('\n')
+    const optOut = copy.paragraphs.at(-1)!.match(/[A-Z_]+=1/u)![0]
+    expect(rendered).not.toContain(copy.scrollHint)
+    expect(rendered).toContain(copy.paragraphs.at(-1)!.match(/[A-Za-z]+ [A-Za-z]+/u)![0])
+    expect(rendered).toContain(optOut)
+    expect(lines.join('\n')).toContain(`Enter  ${copy.continueLabel}`)
+    expect(lines.length).toBeLessThanOrEqual(Math.floor(rows * 0.9))
+    expect(lines.length).toBeGreaterThan(5)
+  })
+
+  it.each([
+    { inner: 68, rows: 14, tier: undefined },
+    { inner: 68, rows: 17, tier: undefined },
+    { inner: 68, rows: 18, tier: 'minimal' },
+    { inner: 84, rows: 21, tier: 'minimal' },
+    { inner: 84, rows: 22, tier: 'compact' },
+  ] as const)('degrades art to preserve the action at $rows rows', ({ inner, rows, tier }) => {
+    const fixture = hostFixture(rows)
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => {}, () => {})
+    const lines = component.render(inner + 4)
+    expect(tuiFirstRunWelcomeArtTier(inner, rows)).toBe(tier)
+    expect(lines.length).toBeLessThanOrEqual(Math.floor(rows * 0.9))
+    expect(lines.join('\n')).toContain(`Enter  ${copy.continueLabel}`)
+  })
+
+  it('drops the whale at low height while keeping prose, scrolling, and Enter reachable', () => {
+    const fixture = hostFixture(10)
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => {}, () => {})
+    const initial = component.render(54).join('\n')
+    expect(tuiFirstRunWelcomeArtTier(50, 10)).toBeUndefined()
+    expect(initial).toContain(openingSentence)
+    expect(initial).toContain(`Enter  ${copy.continueLabel}`)
+
+    component.handleInput('\x1b[F')
+    const end = component.render(54).join('\n')
+    expect(withoutWhitespace(end)).toContain(withoutWhitespace(copy.paragraphs.at(-1)!.slice(-7)))
+    expect(end).toContain(`Enter  ${copy.continueLabel}`)
+
+    for (const key of ['\x1b[A', '\x1b[B', '\x1b[5~', '\x1b[6~', '\x1b[H', 'x']) {
+      component.handleInput(key)
+    }
+    component.invalidate()
+  })
+
+  it('renders a tiny viewport and a quotation-only paragraph without overdraw', () => {
+    const fixture = hostFixture(5)
+    const quoteOnly = { ...copy, paragraphs: ['“如切如磋，如琢如磨。”'] }
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, quoteOnly, async () => {}, () => {})
+    const lines = component.render(2)
+    expect(lines.every(line => visibleWidth(line) <= 6)).toBe(true)
+  })
+
+  it('keeps the side-by-side composition aligned when prose outgrows the full raster', () => {
+    const fixture = hostFixture(40)
+    const longCopy = { ...copy, paragraphs: [copy.paragraphs.join(' ').repeat(4)] }
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, longCopy, async () => {}, () => {})
+    const lines = component.render(100)
+    expect(lines.length).toBeGreaterThan(TUI_FIRST_RUN_WELCOME_WHALE.full.unicode.length)
+    expect(lines.every(line => visibleWidth(line) <= 100)).toBe(true)
+    component.handleInput('\x1b[F')
+    expect(component.render(100).join('\n')).toContain(copy.title)
+  })
+
+  it('renders the bit-equivalent ASCII icon fallback for an explicitly non-Unicode terminal', () => {
+    const fixture = hostFixture(30)
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => {}, () => {}, true)
+    const rendered = component.render(72).join('\n')
+    expect(rendered).toContain(TUI_FIRST_RUN_WELCOME_WHALE.minimal.ascii[0]!.trim())
+    expect(rendered).not.toMatch(/[▀▄█]/u)
+  })
+
+  it.each(['full', 'compact', 'minimal'] as const)('keeps the $tier ASCII raster bit-equivalent', (tier) => {
+    const mapped = TUI_FIRST_RUN_WELCOME_WHALE[tier].unicode.map(line => Array.from(line).map((cell) => {
+      if (cell === '▀') return "'"
+      if (cell === '▄') return '_'
+      if (cell === '█') return '#'
+      return cell
+    }).join(''))
+    expect(mapped).toEqual(TUI_FIRST_RUN_WELCOME_WHALE[tier].ascii)
+  })
+
+  it('ignores Escape and acknowledges only Enter before closing', async () => {
+    const fixture = hostFixture(30)
+    const acknowledge = vi.fn(async () => {})
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, acknowledge, () => {})
+    component.render(72)
+
+    component.handleInput('\x1b')
+    await Promise.resolve()
+    expect(acknowledge).not.toHaveBeenCalled()
+    expect(fixture.closed()).toBe(false)
+
+    component.handleInput('\r')
+    await vi.waitFor(() => { expect(fixture.closed()).toBe(true) })
+    expect(acknowledge).toHaveBeenCalledOnce()
+  })
+
+  it('keeps the notice eligible when Ctrl+C or Ctrl+D requests a normal exit', async () => {
+    const fixture = hostFixture(30)
+    const acknowledge = vi.fn(async () => {})
+    const exit = vi.fn()
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, acknowledge, exit)
+    component.handleInput('\x03')
+    component.handleInput('\x04')
+    expect(exit).toHaveBeenCalledTimes(2)
+    expect(acknowledge).not.toHaveBeenCalled()
+    expect(fixture.closed()).toBe(false)
+  })
+
+  it('does not start a second acknowledgement while the first Enter is pending', async () => {
+    const fixture = hostFixture(30)
+    const pending = Promise.withResolvers<undefined>()
+    const acknowledge = vi.fn(async () => pending.promise)
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, acknowledge, () => {})
+    component.render(72)
+
+    component.handleInput('\r')
+    component.handleInput('\r')
+    component.handleInput('\x1b[B')
+    expect(component.render(72).join('\n')).toContain(copy.saving)
+    expect(acknowledge).toHaveBeenCalledOnce()
+
+    pending.resolve(undefined)
+    await vi.waitFor(() => { expect(fixture.closed()).toBe(true) })
+  })
+
+  it('keeps the overlay open after a persistence failure and lets Enter retry', async () => {
+    const fixture = hostFixture(30)
+    let attempts = 0
+    const component = new TuiFirstRunWelcomeComponent(fixture.host, copy, async () => {
+      attempts += 1
+      if (attempts === 1) throw new Error('disk unavailable')
+    }, () => {})
+    component.render(72)
+
+    component.handleInput('\r')
+    await vi.waitFor(() => {
+      expect(component.render(72).join('\n')).toContain(copy.saveError)
+    })
+    expect(fixture.closed()).toBe(false)
+
+    component.handleInput('\r')
+    await vi.waitFor(() => { expect(fixture.closed()).toBe(true) })
+    expect(attempts).toBe(2)
+    expect(fixture.invalidations()).toBeGreaterThanOrEqual(3)
+  })
+
+  it('opens through the TUI extension and uses the launcher-owned acknowledgement closure', async () => {
+    const home = await temporaryHome('dsh-tui-welcome-apply-')
+    let request: TuiOverlayRequest | undefined
+    let disposePending: (() => Promise<void>) | undefined
+    const ctx = {
+      effect(register: () => () => Promise<void>) {
+        disposePending = register()
+        return () => {}
+      },
+      tui: {
+        openOverlay(value: TuiOverlayRequest) {
+          request = value
+          return {} as never
+        },
+      },
+    } as unknown as Context
+    apply(ctx, { dshHome: home })
+    expect(request?.options).toEqual({
+      width: '100%',
+      maxHeight: '90%',
+      anchor: 'center',
+      margin: 0,
+    })
+
+    const fixture = hostFixture(30)
+    const component = request?.create(fixture.host)
+    expect(component).toBeInstanceOf(TuiFirstRunWelcomeComponent)
+    component?.handleInput?.('\x03')
+    expect(mockDisposeRootAndExit).toHaveBeenCalledWith(ctx, 0)
+    component?.handleInput?.('\r')
+    await disposePending?.()
+    expect(await hasTuiFirstRunWelcomeAcknowledgement(home)).toBe(true)
+
+    apply(ctx, { dshHome: home, asciiArt: true })
+    expect(request?.create(fixture.host).render(72).join('\n'))
+      .toContain(TUI_FIRST_RUN_WELCOME_WHALE.minimal.ascii[0]!.trim())
+  })
+})
@@ -1,6 +1,7 @@
 import { createUserMessage, createMessage } from '@deepseek-ai/dsh-llm'
 import { realpathSync } from 'node:fs'
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
@@ -8,12 +9,30 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS } from '@deepseek-ai/dsh-loader-smoke'
 import { packChunkRuns, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
 import { logPath, toHeaderLine } from '../../../packages/session-persistence/session-persistence-jsonl/src/format.ts'
 import { runTuiPtySmoke, type TuiPtySmokeOptions } from './pty-harness.ts'
+import { HeadlessTerminal } from '../../../packages/ui/tui/tests/headless-terminal.ts'
+import {
+  acknowledgeTuiFirstRunWelcome,
+  hasTuiFirstRunWelcomeAcknowledgement,
+} from '../src/tui-onboarding/tui-first-run-welcome.ts'
+import {
+  TUI_FIRST_RUN_WELCOME_NOTICE_COPY,
+  TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE,
+} from '../src/tui-onboarding/tui-first-run-welcome-copy.ts'
+import { TUI_FIRST_RUN_WELCOME_WHALE } from '../src/tui-onboarding/tui-first-run-welcome-art.ts'

 const dshBinScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
 // `--config` layers an overlay over the shared base, so the default surface
 // needs no config argument at all; these are the overlays under test.
 const scriptedConfigPath = fileURLToPath(new URL('./fixtures/tui-scripted.cordis.yml', import.meta.url))
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const firstRunSnapshots = fileURLToPath(new URL('./tui-first-run-snapshots/', import.meta.url))
+const synchronizedFrameEnd = '\x1b[?2026l'
+// Artifact mode gives the inner PTY driver 60 seconds and its execa owner a
+// five-second backstop. Keep Vitest outside both deadlines so the harness can
+// report its own marker, exit, and cleanup failure instead of being cut off.
+const PTY_SMOKE_TEST_TIMEOUT_MS = process.env.DSH_EXAMPLE_MODE === 'lib'
+  ? 75_000
+  : LOADER_SMOKE_TEST_TIMEOUT_MS

 /**
 * Seed the isolated process workspace: ordinary files land in `cwd`, personal
@@ -125,20 +144,77 @@ async function readLoggedRequestContext(cwd: string): Promise<LoggedRequestConte
 * `tui.cordis.yml`, with no flags) or `configPath` (an overlay layered over that
 * same base through `--config`).
 */
-function smoke(overrides: Partial<TuiPtySmokeOptions> & { label: string }): Promise<string> {
+function smoke(overrides: Partial<TuiPtySmokeOptions> & {
+  label: string
+  showFirstRunWelcome?: boolean
+}): Promise<string> {
+  const { showFirstRunWelcome = false, prepare, ...options } = overrides
  return runTuiPtySmoke({
    tempDirPrefix: 'dsh-tui-smoke-',
    binScript: dshBinScript,
    tsconfigPath,
-    // Telemetry now mounts in the shared base: keep fixture sessions from
-    // POSTing to the production endpoint when run outside CI's workflow env.
-    env: { DEEPSEEK_API_KEY: 'keyless-tui-no-call', DSH_TELEMETRY_DISABLED: '1' },
+    env: {
+      DEEPSEEK_API_KEY: 'keyless-tui-no-call',
+      DSH_TELEMETRY_DISABLED: '1',
+      LANG: 'en_US.UTF-8',
+      LC_ALL: 'en_US.UTF-8',
+      LC_CTYPE: 'en_US.UTF-8',
+      TERM: 'xterm-256color',
+    },
    // Artifact CI builds and smokes concurrently on a contended runner.
    ...(process.env.DSH_EXAMPLE_MODE === 'lib' ? { timeoutMs: 60_000 } : {}),
-    ...overrides,
+    ...options,
+    prepare: async (cwd) => {
+      if (!showFirstRunWelcome) await acknowledgeTuiFirstRunWelcome(join(cwd, '.dsh'))
+      await prepare?.(cwd)
+    },
  })
 }

+const firstRunCopy = TUI_FIRST_RUN_WELCOME_NOTICE_COPY[TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE]
+const firstRunOpeningSentence = `${firstRunCopy.paragraphs[0]!.split('。', 1)[0]}。`
+
+function firstRunArtAnchor(tier: keyof typeof TUI_FIRST_RUN_WELCOME_WHALE): string {
+  return TUI_FIRST_RUN_WELCOME_WHALE[tier].unicode[tier === 'full' ? 2 : 0]!.trim()
+}
+
+/** Keep only the overlay rows, excluding platform-specific scrollback and the underlying TUI. */
+function overlaySnapshot(snapshot: string, columns: number, rows: number): string {
+  const blocks: string[][] = []
+  for (const line of snapshot.split('\n')) {
+    if (/^\d+(?:-\d+)?~?\| /u.test(line)) blocks.push([line])
+    else if (line.startsWith('  style ') && blocks.length > 0) blocks.at(-1)?.push(line)
+  }
+  const first = blocks.findIndex(block => block[0]?.includes('╭') === true)
+  const last = blocks.findIndex((block, index) => index >= first && block[0]?.includes('╰') === true)
+  if (first < 0 || last < first) throw new Error('first-run PTY snapshot has no complete overlay frame')
+  const overlay = blocks.slice(first, last + 1).flatMap((block, index) => [
+    block[0]!.replace(/^\d+(?:-\d+)?(~)?\|/u, `${String(index)}$1|`),
+    ...block.slice(1),
+  ])
+  return [`overlay ${String(columns)}x${String(rows)} rows=${String(last - first + 1)}`, ...overlay, ''].join('\n')
+}
+
+/** Project the first synchronized PTY frame containing `marker` into an overlay-only snapshot. */
+async function firstRunFrameSnapshot(
+  output: string,
+  marker: string,
+  columns: number,
+  rows: number,
+): Promise<string> {
+  const markerIndex = output.indexOf(marker)
+  if (markerIndex < 0) throw new Error(`first-run PTY output has no marker ${JSON.stringify(marker)}`)
+  const frameEnd = output.indexOf(synchronizedFrameEnd, markerIndex)
+  if (frameEnd < 0) throw new Error(`first-run PTY output has no complete frame after ${JSON.stringify(marker)}`)
+  const terminal = new HeadlessTerminal(columns, rows)
+  try {
+    terminal.write(output.slice(0, frameEnd + synchronizedFrameEnd.length))
+    return overlaySnapshot(await terminal.snapshot(), columns, rows)
+  } finally {
+    await terminal.dispose()
+  }
+}
+
 // The scripted conversation switches to the pro model first: the scripted
 // adapter proves routing + prompt variables by rejecting tool-ful calls on any
 // other route (see fixtures/tui-scripted-llm.ts).
@@ -148,6 +224,138 @@ const SELECT_PRO_MODEL = [
 ] as const

 describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => {
+  it.each([
+    { columns: 60, tier: undefined },
+    { columns: 80, tier: 'minimal' },
+    { columns: 120, tier: 'full' },
+    { columns: 160, tier: 'full' },
+  ] as const)('renders and acknowledges the responsive first-run composition at $columns columns', async ({ columns, tier }) => {
+    const output = await smoke({
+      label: `dsh first-run welcome ${String(columns)} columns`,
+      tempDirPrefix: `dsh-tui-welcome-${String(columns)}-`,
+      configPath: scriptedConfigPath,
+      showFirstRunWelcome: true,
+      expectedExitCode: 0,
+      columns,
+      rows: 30,
+      actions: [
+        {
+          waitFor: `Enter  ${firstRunCopy.continueLabel}`,
+          send: '\r\x03',
+        },
+      ],
+      inspect: async (cwd) => {
+        expect(await hasTuiFirstRunWelcomeAcknowledgement(join(cwd, '.dsh'))).toBe(true)
+        const entries = await readdir(join(cwd, '.sessions'), { recursive: true })
+        const logs = entries.filter(name => name.endsWith('.jsonl'))
+        for (const log of logs) {
+          const stored = await readFile(join(cwd, '.sessions', log), 'utf8')
+          expect(stored).not.toContain(firstRunCopy.paragraphs[0])
+        }
+      },
+    })
+    await expect(await firstRunFrameSnapshot(output, firstRunOpeningSentence, columns, 30))
+      .toMatchFileSnapshot(join(firstRunSnapshots, `${String(columns)}-columns.expected.txt`))
+    if (tier === undefined) {
+      expect(output).not.toContain(TUI_FIRST_RUN_WELCOME_WHALE.minimal.unicode[0]!.trim())
+    } else {
+      expect(output).toContain(firstRunArtAnchor(tier))
+    }
+    expect(output).toContain(`Enter  ${firstRunCopy.continueLabel}`)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)
+
+  it('keeps prose and Enter reachable in a low-height real PTY after dropping the whale', async () => {
+    const output = await smoke({
+      label: 'dsh low-height first-run welcome',
+      tempDirPrefix: 'dsh-tui-welcome-low-',
+      configPath: scriptedConfigPath,
+      showFirstRunWelcome: true,
+      expectedExitCode: 0,
+      columns: 60,
+      rows: 12,
+      actions: [
+        { waitFor: firstRunOpeningSentence, send: '\x1b[F' },
+        {
+          waitFor: `Enter  ${firstRunCopy.continueLabel}`,
+          occurrence: 2,
+          send: '\r\x03',
+        },
+      ],
+    })
+    await expect(await firstRunFrameSnapshot(output, firstRunOpeningSentence, 60, 12))
+      .toMatchFileSnapshot(join(firstRunSnapshots, '60-columns-low-height.expected.txt'))
+    expect(output).toContain(firstRunCopy.title)
+    expect(output).toContain(firstRunOpeningSentence)
+    expect(output).toContain('企业微信群')
+    expect(output).toContain(`Enter  ${firstRunCopy.continueLabel}`)
+    expect(output).not.toContain(TUI_FIRST_RUN_WELCOME_WHALE.minimal.unicode[0]!.trim())
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)
+
+  it('shows once and skips the second launch under the same DSH_HOME', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'dsh-tui-welcome-twice-'))
+    try {
+      const first = await smoke({
+        label: 'dsh first welcome launch',
+        tempDirPrefix: 'unused-',
+        cwd,
+        configPath: scriptedConfigPath,
+        showFirstRunWelcome: true,
+        expectedExitCode: 0,
+        actions: [
+          { waitFor: `Enter  ${firstRunCopy.continueLabel}`, send: '\r\x03' },
+        ],
+      })
+      expect(first).toContain(firstRunCopy.title)
+
+      const second = await smoke({
+        label: 'dsh second welcome launch',
+        tempDirPrefix: 'unused-',
+        cwd,
+        configPath: scriptedConfigPath,
+        showFirstRunWelcome: true,
+        expectedExitCode: process.platform === 'win32' ? 0 : -15,
+        actions: [{ waitFor: 'main-session-', signal: 'SIGTERM' }],
+      })
+      expect(second).not.toContain(firstRunOpeningSentence)
+      expect(second).not.toContain(`Enter  ${firstRunCopy.continueLabel}`)
+    } finally {
+      await rm(cwd, { recursive: true, force: true })
+    }
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)
+
+  it.skipIf(process.platform === 'win32')('keeps the notice eligible when the process exits before Enter', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'dsh-tui-welcome-abort-'))
+    try {
+      await smoke({
+        label: 'dsh aborted welcome launch',
+        tempDirPrefix: 'unused-',
+        cwd,
+        configPath: scriptedConfigPath,
+        showFirstRunWelcome: true,
+        expectedExitCode: -15,
+        actions: [{ waitFor: firstRunOpeningSentence, signal: 'SIGTERM' }],
+        inspect: async (workspace) => {
+          expect(await hasTuiFirstRunWelcomeAcknowledgement(join(workspace, '.dsh'))).toBe(false)
+        },
+      })
+
+      const next = await smoke({
+        label: 'dsh welcome after aborted launch',
+        tempDirPrefix: 'unused-',
+        cwd,
+        configPath: scriptedConfigPath,
+        showFirstRunWelcome: true,
+        expectedExitCode: 0,
+        actions: [
+          { waitFor: `Enter  ${firstRunCopy.continueLabel}`, send: '\r\x03' },
+        ],
+      })
+      expect(next).toContain(firstRunOpeningSentence)
+    } finally {
+      await rm(cwd, { recursive: true, force: true })
+    }
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)
+
  it('boots pi-tui, sweeps the borderless banner in, enters plan mode, and restores the terminal', async () => {
    // With no configured welcome the borderless banner sweeps in left-to-right;
    // the detail line's session id (`main-session-<uuid>`) renders only once
@@ -170,7 +378,7 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => {
    expect(output).not.toContain('╭')
    expect(output).not.toContain('╮')
    expect(output).toContain('\u001B[?2004l')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('switches models, streams a response, answers a user-question dialog, and exits cleanly', async () => {
    const output = await smoke({
@@ -223,7 +431,7 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => {
    expect(output).toContain('Registered tools')
    expect(output).toContain('ask_user_question')
    expect(output).toContain('\u001B[?2004l')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('loads a local skill via /skill: and delivers its body to the model as a user turn', async () => {
    // The whole user-only invocation path in one keyless boot: `ctx.get('skills')`
@@ -259,7 +467,7 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => {
    expect(output).not.toContain('[instructions]')
    expect(output).toContain('Scripted skill body received.')
    expect(output).toContain('\u001B[?2004l')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('adds a watched local skill to live /skill: autocomplete without restarting', async () => {
    const skill = [
@@ -289,7 +497,7 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => {
    })
    expect(output).toContain('HOT_ADDED_COMPLETION_MARKER')
    expect(output).toContain('\u001B[?2004l')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it.skipIf(process.env.DSH_EXAMPLE_MODE === 'lib')('fuzzy-completes an @file path without reading or submitting the file', async () => {
    const output = await smoke({
@@ -314,11 +522,51 @@ describe('dsh TUI keyless smoke (real Loader tree in a PTY)', () => {
    expect(output).toContain('File · terminal-special-case.t')
    expect(output).toContain('@src/terminal-special-case.ts')
    expect(output).toContain('\u001B[?2004l')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

 })

 describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
+  it('shows the terminal-local notice over a resumed session without changing its log', async () => {
+    let originalLineCount = 0
+    const output = await smoke({
+      label: 'dsh first-run notice on resume',
+      tempDirPrefix: 'dsh-tui-welcome-resume-',
+      binScript: dshBinScript,
+      configArgs: ['--resume', 'resume-target', '--config', scriptedConfigPath],
+      showFirstRunWelcome: true,
+      expectedExitCode: 0,
+      prepare: async (cwd) => {
+        await seedResumeSession(cwd)
+        const before = await readFile(logPath(
+          join(cwd, '.sessions'),
+          realpathSync.native(cwd),
+          SessionId('resume-target'),
+          'none',
+        ), 'utf8')
+        originalLineCount = before.split('\n').filter(Boolean).length
+      },
+      actions: [
+        { waitFor: `Enter  ${firstRunCopy.continueLabel}`, send: '\r\x03' },
+      ],
+      inspect: async (cwd) => {
+        const after = await readFile(logPath(
+          join(cwd, '.sessions'),
+          realpathSync.native(cwd),
+          SessionId('resume-target'),
+          'none',
+        ), 'utf8')
+        expect(after).not.toContain(firstRunCopy.paragraphs[0])
+        const appended = after.split('\n').filter(Boolean).slice(originalLineCount)
+          .map(line => JSON.parse(line) as SessionEvent)
+        expect(appended).not.toContainEqual(expect.objectContaining({ type: 'user/message' }))
+        expect(appended).not.toContainEqual(expect.objectContaining({ type: 'turn/start' }))
+      },
+    })
+    expect(output).toContain(firstRunOpeningSentence)
+    expect(output).toContain('Resume selector design — DeepSeek Harness')
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)
+
  it('exec-replaces the TUI for /resume and restores the same session state', async () => {
    const output = await smoke({
      label: 'dsh in-place resume',
@@ -338,7 +586,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
    expect(released).toBeGreaterThanOrEqual(0)
    expect(restored).toBeGreaterThan(released)
    expect(output).toContain('Preserve restored state')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('boots the shipped default config with no arguments and no personal overlay', async () => {
    const output = await smoke({
@@ -353,7 +601,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
    expect(output).not.toContain('╭')
    expect(output).not.toContain('╮')
    expect(output).toContain('\u001B[?2004l')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('applies the personal overlay: config.yaml patches an overlay-inserted row, the invoking directory\'s .env feeds its !!js, and the home .env stays out of the environment', async () => {
    // The whole personal-config chain in one boot, plus the environment layer
@@ -390,7 +638,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
    expect(output).toContain('PROJECT OVERLAY READY.')
    expect(output).not.toContain('HOME ENV LEAKED.')
    expect(output).toContain('\u001B[?2004l')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('fails loud instead of booting when the personal config.yaml is invalid', async () => {
    const output = await smoke({
@@ -402,7 +650,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
      expectedExitCode: 1,
    })
    expect(output).toContain('must be a top-level YAML array of loader patch entries')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('routes the --resume flag into the launcher session-identity slot, failing loud on a missing id', async () => {
    // The flag path end to end: apps/cli parses `--resume missing-session`,
@@ -417,7 +665,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
      expectedExitCode: 1,
    })
    expect(output).toContain('ui-tui: session "missing-session" failed to start:')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('prints the launcher-owned resume command on exit, naming the booted config', async () => {
    // The exit line is built by apps/cli from this invocation, so it must carry
@@ -430,7 +678,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
      actions: [{ waitFor: 'scripted TUI ready.', send: '/exit\r' }],
    })
    expect(output).toMatch(/To resume this session: dsh --resume=main-session-[0-9a-f-]{36} --config/)
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('keeps resume working when the personal overlay replaces the whole agent-loop config', async () => {
    // Loader patches replace a targeted `config` key wholesale, so a personal
@@ -465,7 +713,7 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
      actions: [{ waitFor: 'OVERLAY REPLACED THE CONFIG.', send: '/exit\r' }],
    })
    expect(output).toMatch(/To resume this session: dsh --resume=main-session-[0-9a-f-]{36}/)
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

  it('reports a failing bash command exactly once, as the terminal card exit pill', async () => {
    // The model-facing result ends in `[exit code: 3]`, which the terminal card
@@ -488,13 +736,14 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
    expect(output).toContain('SCRIPTED_BASH_FAILED')
    expect(output).toContain('[exit 3]')
    expect(output).not.toContain('[exit code: 3]')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)

-  it('tells the model its source path and offers the bundled maintenance skills', async () => {
+  it('distinguishes its source path from the current workdir and offers the bundled maintenance skills', async () => {
    // The launcher resolves the checkout root three hops up from apps/cli/{src,lib};
    // this test file sits an equal depth under the same root, so the same hop applies.
-    // The source-path line is a system-prompt section; the bundled skills reach the
-    // model through a durable user message, so each assertion targets its own field.
+    // The source-path line explicitly distinguishes that checkout from the current workdir;
+    // bundled skills reach the model through a durable user message, so each assertion
+    // targets its own field.
    const sourceRoot = fileURLToPath(new URL('../../..', import.meta.url))
    let context: LoggedRequestContext = { system: '', skillCatalog: '' }
    await smoke({
@@ -510,9 +759,9 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
      ],
      inspect: async (cwd) => { context = await readLoggedRequestContext(cwd) },
    })
-    expect(context.system).toContain(`Your own source code is the checkout at ${sourceRoot}; you can read it there to learn how dsh works and how to extend it.`)
+    expect(context.system).toContain(`The DeepSeek Harness implementation checkout is at ${sourceRoot}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.`)
    expect(context.skillCatalog).toContain("- `dsh-customize`: Customize or maintain any dsh source checkout — the one powering the current DSH process, the installed `dsh` command, or a sibling dsh/deepseek-harness clone. Use before any requested action that alters such a checkout's files or git state. Read-only questions that only inspect the checkout do not trigger this. Do not edit the personal staging checkout directly.")
    expect(context.skillCatalog).toContain('- `dsh-upgrade`: Upgrades a source-installed, personally customized DSH checkout to upstream master while preserving local changes and an unchanged rollback worktree. Use when the user asks to update or upgrade DSH.')
    expect(context.skillCatalog).toContain('- `dsh-upstream-customization`: Classifies personal DSH customizations for upstream contribution and, after explicit per-feature approval, rebuilds one on upstream master and opens a draft pull request. Use when the user asks to contribute, publish, or upstream a local DSH change, or asks whether one is worth proposing.')
-  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+  }, PTY_SMOKE_TEST_TIMEOUT_MS)
 })
@@ -7,6 +7,7 @@ import { Context } from 'cordis'
 import { scrubRequestHeaders, tokenizeSessionFixtureCwd } from '@deepseek-ai/dsh-acp-snapshot'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import * as AgentCore from '@deepseek-ai/dsh-agent-spine-demo'
+import { addHarnessSourceSection } from '@deepseek-ai/dsh-app-boot'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import WorkerCodeRuntime from '@deepseek-ai/dsh-code-runtime-worker'
@@ -59,6 +60,10 @@ interface Scenario {
  leavePlanModeAfterFirstTurn?: boolean
  recorded: boolean
  seedWorkspace?: boolean
+  /** Add the launcher's model-visible DSH source checkout at this fixed path. */
+  harnessSourceRoot?: string
+  /** Replace the real `pwd` result with a portable fixed-length workspace path. */
+  normalizePwdResult?: boolean
  /**
   * Load the opt-in `todo_write` tool for this scenario. The shipped TUI
   * config omits it, so only the todo-plan scenario (the enabled-path proof)
@@ -115,6 +120,14 @@ const SCENARIOS: Scenario[] = [
    expectedTools: ['bash'],
    recorded: true,
  },
+  {
+    name: 'source-checkout-workdir',
+    composition: 'native',
+    expectedTools: ['bash'],
+    recorded: true,
+    harnessSourceRoot: '/opt/dsh-source',
+    normalizePwdResult: true,
+  },
  {
    name: 'parallel-file-reads',
    composition: 'native',
@@ -251,6 +264,12 @@ function rawSessionLog(session: Session): string {
  ].join('\n')
 }

+async function materializeFixtureCwd(fixtureFile: string, cwd: string, replayRoot: string): Promise<string> {
+  const realized = join(replayRoot, basename(fixtureFile))
+  await writeFile(realized, (await readFile(fixtureFile, 'utf8')).split('{{cwd}}').join(cwd))
+  return realized
+}
+
 function normalizeTerminalSnapshot(snapshot: string, cwd: string, displayCwd: string): string {
  return snapshot
    .split(`/private${cwd}`).join('/workspace/project')
@@ -294,6 +313,7 @@ async function mountScenarioContext(
  displayCwd: string,
  fixtureFile: string,
  childFiles: string[],
+  replayRoot: string | undefined,
 ): Promise<Context> {
  class SnapshotLocalFileSystem extends LocalFileSystem {
    override async resolve(
@@ -313,6 +333,7 @@ async function mountScenarioContext(
    tools: { mode: scenario.composition === 'code' ? 'code' : scenario.composition === 'advanced' ? 'both' : 'native' },
    skills: { local: { agentsHome: join(cwd, '.agents') } },
  })
+  if (scenario.harnessSourceRoot !== undefined) addHarnessSourceSection(ctx, scenario.harnessSourceRoot)
  await ctx.plugin(TokenMeterService)
  if (scenario.manualCompact === true) {
    await ctx.plugin(DeferredSnapshotCompactService, { auto: false })
@@ -349,7 +370,12 @@ async function mountScenarioContext(
  if (MODE === 'record' && scenario.recorded) {
    await ctx.plugin(LlmDeepSeek)
  } else {
-    installLlmReplay(ctx, { file: fixtureFile, childFiles, providers: PROVIDERS })
+    if (replayRoot === undefined) throw new Error('replay mode requires an isolated fixture directory')
+    // Recorded model text may name the generated cwd. Realize the portable token
+    // outside that cwd so tools see only the scenario workspace during replay.
+    const replayFile = await materializeFixtureCwd(fixtureFile, cwd, replayRoot)
+    const replayChildFiles = await Promise.all(childFiles.map(file => materializeFixtureCwd(file, cwd, replayRoot)))
+    installLlmReplay(ctx, { file: replayFile, childFiles: replayChildFiles, providers: PROVIDERS })
  }
  return ctx
 }
@@ -373,15 +399,27 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {

  const cwd = await mkdtemp(join(SNAPSHOT_TMP_ROOT, `dsh-tui-snapshot-${scenario.name}-`))
  const displayCwd = `/tmp/${basename(cwd)}`
+  let replayRoot: string | undefined
  let ctx: Context | undefined
  let controller: ReturnType<typeof createTuiChat> | undefined
  const terminal = new HeadlessTerminal(100, 36)
  try {
+    if (!(MODE === 'record' && scenario.recorded)) {
+      replayRoot = await mkdtemp(join(SNAPSHOT_TMP_ROOT, `dsh-tui-replay-${scenario.name}-`))
+    }
    if (scenario.seedWorkspace === true) {
      const source = join(fixtureDir(scenario), 'workspace')
      await cp(source, cwd, { recursive: true })
    }
-    ctx = await mountScenarioContext(scenario, cwd, displayCwd, fixtureFile, childFiles)
+    ctx = await mountScenarioContext(scenario, cwd, displayCwd, fixtureFile, childFiles, replayRoot)
+    if (scenario.normalizePwdResult === true) {
+      ctx.on('tools/post-execute', async (exec, result, next) => {
+        const args = exec.arguments as { command?: unknown }
+        return exec.name === 'bash' && args.command === 'pwd' && !result.isError
+          ? { kind: 'accept', content: [{ type: 'text', text: '/workspace/project\n' }] }
+          : next()
+      })
+    }
    const disposedSessions: Session[] = []
    ctx.on('session/disposed', (session) => { disposedSessions.push(session) })
    const workflowEvents: string[] = []
@@ -582,6 +620,10 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
    const firstHeader = events.find(event => event.type === 'request/header')
    expect(firstHeader?.type === 'request/header' && firstHeader.data.header.system)
      .toContain(FILE_REFERENCE_PROMPT)
+    if (scenario.harnessSourceRoot !== undefined) {
+      expect(firstHeader?.type === 'request/header' && firstHeader.data.header.system)
+        .toContain(`The DeepSeek Harness implementation checkout is at ${scenario.harnessSourceRoot}. The checkout location and current working directory are separate values and may differ; never infer the working directory from this path. Use pwd to determine the current working directory. Use this checkout only to inspect or extend DSH itself.`)
+    }
    expect(events.filter(event => event.type === 'tool/call').map(event => event.data.name)).toEqual(scenario.expectedTools)
    for (const [type, count] of Object.entries(scenario.expectedEventCounts ?? {})) {
      expect(events.filter(event => event.type === type), `${scenario.name} must emit ${type}`).toHaveLength(count)
@@ -734,6 +776,7 @@ async function runScenario(scenario: Scenario): Promise<ScenarioResult> {
    await ctx?.fiber.dispose()
    await terminal.dispose()
    await rm(cwd, { recursive: true, force: true })
+    if (replayRoot !== undefined) await rm(replayRoot, { recursive: true, force: true })
    clock.mockRestore()
  }
 }
@@ -147,14 +147,21 @@ describe('web e2e: navigation & panes over a rich seeded session', () => {
    await expect.poll(() => page.locator('tr[data-turn-start="true"]').count(), { timeout: 15_000 }).toBe(2)
    await expect.poll(() => page.getByRole('columnheader').count(), { timeout: 10_000 }).toBe(0)
    await page.locator('tr[data-kind="tool"]').first().click()
-    await expect.poll(() => page.getByRole('complementary', { name: 'Event details' }).count(), { timeout: 10_000 }).toBe(1)
+    const details = page.getByRole('complementary', { name: 'Event details' })
+    await expect.poll(() => details.count(), { timeout: 10_000 }).toBe(1)
+    await page.evaluate(() => { document.body.setAttribute('data-ds-dark-theme', '') })
+    const darkSummarySurfaces = await details.getByRole('heading', { name: 'Payload' }).evaluate(heading => ({
+      heading: getComputedStyle(heading).backgroundColor,
+      panel: getComputedStyle(heading.closest('[aria-label="Event details"]')!).backgroundColor,
+    }))
+    expect(darkSummarySurfaces.heading).toBe(darkSummarySurfaces.panel)
+    await page.evaluate(() => { document.body.removeAttribute('data-ds-dark-theme') })
    await page.getByRole('tab', { name: 'Result' }).click()
    await expect.poll(() => page.getByText('NAVIGATION_OK', { exact: false }).count(), { timeout: 10_000 }).toBeGreaterThanOrEqual(1)
    const snapshot = (await captureStableAria(page, '[class*="viewArea"]', scaffold.workspaceCwd))
      .split(SEED_ID).join('{{seededId}}')
    await compareOrRefreshGolden(TRAJECTORY_EXPECTED, snapshot, MODE)
-    await page.getByRole('complementary', { name: 'Event details' })
-      .getByRole('button', { name: 'Close details' }).click()
+    await details.getByRole('button', { name: 'Close details' }).click()
  }, 60_000)

  it.skipIf(MODE === 'record')('focuses the ledger by dragging an overview interval', async () => {
@@ -1,16 +1,16 @@
 // Keyless browser coverage for pending queue actions through the shipped Web
-// composition and real HTTP/SSE wire. A replay override parks the active turn
-// so two ordinary follow-ups remain addressable while the page edits one and
-// removes one. The queue uses an existing recorded model
-// call; this scenario owns only the user-visible mid-turn golden.
+// composition and real HTTP/SSE wire. Replay overrides park consecutive turns
+// so the page can edit and remove exact occurrences, then stop the active turn
+// while proving the preserved Queue advances in FIFO order.
 import { existsSync } from 'node:fs'
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
+import { deriveReplayScript, parseSessionLog, type ReplayEntry } from '@deepseek-ai/dsh-llm-replay'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import {
  assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
@@ -22,6 +22,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/queue-actions', import.m
 const FIXTURE = fileURLToPath(new URL('./snapshots/live-interactions/session.jsonl', import.meta.url))
 const COLLAPSED_EXPECTED = join(SNAPSHOT_DIR, 'collapsed.expected.md')
 const EDITING_EXPECTED = join(SNAPSHOT_DIR, 'editing.expected.md')
+const PRESERVED_EXPECTED = join(SNAPSHOT_DIR, 'preserved.expected.md')
 const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md')
 const MODE = webSnapshotMode()

@@ -29,6 +30,12 @@ const ACTIVE_PROMPT = 'Reply with a one-sentence description of event sourcing,
 const REMOVE = 'Queue item to remove'
 const EDIT = 'Queue item to edit'
 const EDITED = 'Edited queue item'
+const TAIL = 'Queue item preserved after stop'
+
+/** Durable turn-end classifications observed by the scenario. */
+function turnEndReasons(events: readonly SessionEvent[]): string[] {
+  return events.flatMap(event => event.type === 'turn/end' ? [event.data.reason.kind] : [])
+}

 describe('web e2e: queue row actions', () => {
  let scaffold: WebScaffold | undefined
@@ -52,13 +59,19 @@ describe('web e2e: queue row actions', () => {
    if (failures.length > 1) throw new AggregateError(failures, 'queue-actions teardown failed')
  })

-  it.skipIf(MODE === 'record')('edits and removes exact pending occurrences', async () => {
+  it.skipIf(MODE === 'record')('edits and removes exact occurrences and preserves Queue across stop', async () => {
    overrideDir = await mkdtemp(join(tmpdir(), 'dsh-web-queue-actions-'))
    const readyFile = join(overrideDir, '.hang-ready')
+    const nextReadyFile = join(overrideDir, '.next-hang-ready')
    const overridePath = join(overrideDir, 'replay.override.json')
-    await writeFile(overridePath, JSON.stringify({
-      patches: [{ at: 0, entry: { kind: 'hang', readyFile } }],
-    }))
+    const recorded = deriveReplayScript(parseSessionLog(await readFile(FIXTURE, 'utf8')))
+    expect(recorded).toHaveLength(1)
+    const replay: ReplayEntry[] = [
+      { kind: 'hang', readyFile },
+      { kind: 'hang', readyFile: nextReadyFile },
+      recorded[0]!,
+    ]
+    await writeFile(overridePath, JSON.stringify(replay))

    const sessionEvents: SessionEvent[] = []
    scaffold = await launchWebScaffold({ replayFixture: FIXTURE, replayOverride: overridePath })
@@ -135,17 +148,34 @@ describe('web e2e: queue row actions', () => {
    expect(tripwire.pageErrors).toEqual([])
    expect(tripwire.warnings).toEqual([])

-    const editedRow = page.getByText(EDITED, { exact: true }).locator('..')
-    await editedRow.getByRole('button', { name: 'Remove queued message' }).click()
-    await expect.poll(() => page.getByText(EDITED, { exact: true }).count()).toBe(0)
+    await input.fill(TAIL)
+    await input.press('Enter')
+    await expect.poll(
+      () => page.getByRole('button', { name: 'Remove queued message' }).count(),
+      { timeout: 10_000 },
+    ).toBe(2)
+
+    await page.getByRole('button', { name: 'Stop generating' }).click()
+    await expect.poll(() => existsSync(nextReadyFile), { timeout: 15_000 }).toBe(true)
+    await page.getByText(TAIL, { exact: true }).waitFor()
+    await expect.poll(() => page.getByRole('button', { name: 'Remove queued message' }).count())
+      .toBe(1)
+
+    const preservedSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(PRESERVED_EXPECTED, preservedSnapshot, MODE)
+
    await page.getByRole('button', { name: 'Stop generating' }).click()
    await settled
+    expect(turnEndReasons(sessionEvents)).toEqual(['aborted', 'aborted', 'completed'])
+    expect(sessionEvents.filter(event => event.type === 'user/message' && event.data.source.kind === 'user'))
+      .toHaveLength(3)
+    await expect.poll(() => page.locator('[data-queue-dock]').count()).toBe(0)
  }, 120_000)

  it.skipIf(MODE === 'record')('keeps its snapshot inventory closed', async () => {
    await assertFixtureInventory(
      SNAPSHOT_DIR,
-      ['collapsed.expected.md', 'editing.expected.md', 'ui.expected.md'],
+      ['collapsed.expected.md', 'editing.expected.md', 'preserved.expected.md', 'ui.expected.md'],
    )
  })
 })
@@ -496,7 +496,7 @@ export async function seedSession(scaffold: WebScaffold, fixtureText: string, id
 * volatility collapse to stable tokens.
 */
 function normalizeAria(snapshot: string, workspaceCwd: string): string {
-  // The header breadcrumb renders the workspace's basename, not the full
+  // The session heading renders the workspace's basename, not the full
  // path, so both spellings must collapse to the token.
  const base = workspaceCwd.split('/').pop()!
  return snapshot
@@ -357,6 +357,27 @@ describe('web e2e: seeded history renders through cold resume', () => {
    await compareOrRefreshGolden(COMMAND_ROW_EXPECTED, snapshot, MODE)
  }, 60_000)

+  it.skipIf(MODE === 'record')('fits short injected context without a scrollport', async () => {
+    const agent = scaffold.ctx.agents.get(SessionId(SEED_ID))
+    if (agent === undefined) throw new Error('seeded session did not attach an agent')
+    agent.inject(createUserMessage({
+      content: [{ type: 'text', text: 'Short injected context.' }],
+      source: { kind: 'plugin', plugin: 'fixture' },
+    }))
+
+    const disclosures = page.getByRole('button', { name: 'Context injection' })
+    await expect.poll(() => disclosures.count(), { timeout: 10_000 }).toBe(2)
+    const disclosure = disclosures.nth(1)
+    await disclosure.click()
+    await expect.poll(() => disclosure.getAttribute('aria-expanded')).toBe('true')
+
+    const body = page.locator('[data-context-injection-body]')
+    const bodyBox = await body.boundingBox()
+    if (bodyBox === null) throw new Error('short context disclosure geometry is not measurable')
+    expect(bodyBox.height).toBeLessThan(141)
+    expect(await body.evaluate(element => element.scrollHeight > element.clientHeight)).toBe(false)
+  })
+
  it.skipIf(MODE === 'record')('issued zero model calls and stayed clean', async () => {
    // No replay fixture was installed and the llm seam is open — any stray
    // stream would have failed the turn loudly. Cleanliness pins the wire.
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - 'button "Using ONE run_code program: run" [disabled]'
+  - 'heading "Using ONE run_code program: run" [level=1]'
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Use only Cordis tools. First" [disabled]
+  - heading "Use only Cordis tools. First" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Use the bash tool to" [disabled]
+  - heading "Use the bash tool to" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Reply with the single word" [disabled]
+  - heading "Reply with the single word" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Reply with a one-sentence description" [disabled]
+  - heading "Reply with a one-sentence description" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Reply with a one-sentence description" [disabled]
+  - heading "Reply with a one-sentence description" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Reply with a one-sentence description" [disabled]
+  - heading "Reply with a one-sentence description" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Reply with a one-sentence description" [disabled]
+  - heading "Reply with a one-sentence description" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Use the read tool twice" [disabled]
+  - heading "Use the read tool twice" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - 'button "Plan a small change: add" [disabled]'
+  - 'heading "Plan a small change: add" [level=1]'
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Use the ask_user_question tool to" [disabled]
+  - heading "Use the ask_user_question tool to" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Reply with a one-sentence description" [disabled]
+  - heading "Reply with a one-sentence description" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Reply with a one-sentence description" [disabled]
+  - heading "Reply with a one-sentence description" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -0,0 +1,43 @@
+- banner:
+  - heading "Reply with a one-sentence description" [level=1]
+  - tablist:
+    - tab "Chat" [selected]
+    - tab "Trajectory"
+- text: Reply with a one-sentence description of event sourcing, then stop. {{clock}}
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- button "Context injection":
+  - img
+  - img
+  - text: Context injection
+- paragraph: partial
+- text: Stopped
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- text: {{clock}} Edited queue item {{clock}}
+- button "Copy":
+  - img
+- button "Branch into a new conversation":
+  - img
+- paragraph: partial
+- status: Deep diving...
+- list:
+  - listitem:
+    - text: Queue item preserved after stop
+    - button "Edit queued message":
+      - img
+    - button "Remove queued message":
+      - img
+- textbox "Message the agent"
+- button "Commands":
+  - img
+- 'button "Access mode, current: Full access"': Full access
+- button "Select model, current DeepSeek-V4-Flash":
+  - text: DeepSeek-V4-Flash
+  - img
+- button "Stop generating"
+- text: 1 turns · 1 steps Input 0 tok · Output 0 tok
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Reply with a one-sentence description" [disabled]
+  - heading "Reply with a one-sentence description" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Use the read tool twice" [disabled]
+  - heading "Use the read tool twice" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Use the read tool twice" [disabled]
+  - heading "Use the read tool twice" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Use the ask_user_question tool to" [disabled]
+  - heading "Use the ask_user_question tool to" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Use the ask_user_question tool to" [disabled]
+  - heading "Use the ask_user_question tool to" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -21,7 +20,7 @@
  - img
  - img
  - text: Ask question 1/1 answered
- text: "Interjection Interjection: include the word BANANA in your final reply."
+- text: "Interjection: include the word BANANA in your final reply."
 - button "Think The user selected \"Yes\" and wants me to include the word \"BANANA\" in my final reply. Let me acknowledge their answer.":
  - img
  - img
@@ -1,6 +1,5 @@
 - banner:
-  - navigation "Session hierarchy":
-    - button "Use web_search to search exactly" [disabled]
+  - heading "Use web_search to search exactly" [level=1]
  - tablist:
    - tab "Chat" [selected]
    - tab "Trajectory"
@@ -1,16 +1,15 @@
-// Web e2e scenario: mid-turn steering, end to end. The product composer
-// deliberately exposes Queue only, so the steer is POSTed from the page
-// itself over the same same-origin /api transport the client uses.
-// TODO(web-steer-ui): Drive this through a dedicated steering interaction
-// once one exists. Everything downstream is product: the gateway
-// routes mode:'steer' to Agent.steer, the loop drains it at the step
-// boundary into a durable steering/message event, the SSE mux pushes it, and
-// the transcript renders the badged interjection bubble. The question
-// composer supplies the deterministic mid-turn window: while ask_user_question
-// blocks, the turn is provably running, so record and replay perform the
-// identical steer-then-answer sequence with zero timing dependence — and the
-// recorded final reply proves the steer reached the MODEL (it obeys an
-// instruction that only the steering message carries).
+// Web e2e scenario: mid-turn steering over the host wire. The Web UI has no
+// steer entry, so the steer is POSTed from the page over the same
+// same-origin /api transport the client uses. Everything downstream is
+// product: the gateway routes mode:'steer' to Agent.steer, the loop drains
+// it at the step boundary into a durable steering/message event, the SSE mux
+// pushes it, and the transcript shows the text as a plain bubble (no
+// interjection chrome). The question composer supplies the deterministic
+// mid-turn window: while ask_user_question blocks, the turn is provably
+// running, so record and replay perform the identical steer-then-answer
+// sequence with zero timing dependence — and the recorded final reply proves
+// the steer reached the MODEL (it obeys an instruction that only the
+// steering message carries).
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -29,11 +28,11 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/steering', import.meta.u
 const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl')
 // Two goldens for the two distinct states this interaction produces: the
 // mid-turn moment (steer ACCEPTED but deliberately invisible — the loop
-// drains steering at the step boundary, so no interjection bubble exists
-// while the question still blocks the step) and the settled transcript
-// (badged bubble in place, final reply obeying it). The pair pins the
-// timing semantics visually: if the client ever starts rendering pending
-// steers eagerly, the mid-steer golden flips first.
+// drains steering at the step boundary, so no steering text exists while
+// the question still blocks the step) and the settled transcript (plain
+// bubble in place, final reply obeying it). The pair pins the timing
+// semantics visually: if the client ever starts rendering pending steers
+// eagerly, the mid-steer golden flips first.
 const MID_EXPECTED = join(SNAPSHOT_DIR, 'mid-steer.expected.md')
 const SETTLED_EXPECTED = join(SNAPSHOT_DIR, 'settled.expected.md')
 const MODE = webSnapshotMode()
@@ -80,7 +79,7 @@ describe('web e2e: mid-turn steering lands durably and visibly', () => {
    await scaffold?.close()
  })

-  it('steers during the blocked step; the interjection is logged, rendered, and obeyed', async () => {
+  it('steers during the blocked step; the message is logged, rendered, and obeyed', async () => {
    onTestFailed(() => saveFailureShot(page, 'web-e2e-steering'))
    if (MODE !== 'record') {
      // The steer must NOT be a user/message — it lands as steering/message.
@@ -118,10 +117,9 @@ describe('web e2e: mid-turn steering lands durably and visibly', () => {
    if (MODE !== 'record') {
      // Mid-turn golden: the ACCEPTED steer is durable in the inbox but the
      // loop drains steering only at the step boundary, so no steering/message
-      // exists yet and no interjection bubble renders — the composer still
-      // blocks, alone. The DOM is stable here (no further SSE frames can
-      // arrive until the question is answered), making this state capturable.
-      expect(await page.getByText('Interjection', { exact: true }).count()).toBe(0)
+      // exists yet and no steer text renders — the composer still blocks,
+      // alone. The DOM is stable here (no further SSE frames can arrive until
+      // the question is answered), making this state capturable.
      expect(await page.getByText(STEER, { exact: true }).count()).toBe(0)
      expect(await page.getByRole('button', { name: 'Edit queued message' }).count()).toBe(0)
      const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
@@ -155,14 +153,13 @@ describe('web e2e: mid-turn steering lands durably and visibly', () => {
    expect(turnEnds).toHaveLength(1)
    expect((turnEnds[0] as SessionEvent & { data: { reason: { kind: string } } }).data.reason.kind).toBe('completed')

-    // Visible: the badged interjection bubble plus the reply that obeys it
+    // Visible: the plain steering bubble plus the reply that obeys it
    // (steer text + final reply each contain the marker word).
-    await expect.poll(() => page.getByText('Interjection', { exact: true }).count(), { timeout: 15_000 }).toBe(1)
-    await expect.poll(() => page.getByText('Interjection:', { exact: false }).count(), { timeout: 10_000 }).toBe(1)
+    await expect.poll(() => page.getByText(STEER, { exact: true }).count(), { timeout: 15_000 }).toBe(1)
    await expect.poll(() => page.getByText('BANANA', { exact: false }).count(), { timeout: 10_000 }).toBeGreaterThanOrEqual(2)
    expect(await page.locator('[data-question-key]').count()).toBe(0)
-    // Settled golden: badge + interjection between the question round trip
-    // and the obeying reply, composer takeover gone.
+    // Settled golden: steer text between the question round trip and the
+    // obeying reply, composer takeover gone.
    const snapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd)
    await compareOrRefreshGolden(SETTLED_EXPECTED, snapshot, MODE)
    expect(tripwire.pageErrors).toEqual([])
@@ -22,6 +22,7 @@ export default defineConfig({
      { find: /^@deepseek-ai\/dsh-client-web-react$/, replacement: src('../../packages/client/web-react/src/index.ts') },
      { find: /^@deepseek-ai\/dsh-client-ui-slots$/, replacement: src('../../packages/client/ui-slots/src/index.ts') },
      { find: /^@deepseek-ai\/dsh-client-ui-primitives$/, replacement: src('../../packages/client/ui-primitives/src/index.ts') },
+      { find: /^@deepseek-ai\/dsh-client-schema-form$/, replacement: src('../../packages/client/schema-form/src/index.ts') },
      { find: /^@deepseek-ai\/dsh-client-modules\/client$/, replacement: src('../../packages/client/modules/src/client/index.ts') },
    ],
  },
@@ -2010,8 +2010,8 @@ export interface Config extends TuiConfig {
  /**
   * Skill name auto-invoked as this session's first user turn, exactly as if
   * the user typed `/skill:<name>`. Set only by a launcher for a fresh
-   * skill-guided session (`dsh migrate`/`dsh upgrade`); absent leaves the first
-   * turn to the user.
+   * skill-guided session (`dsh migrate`/`dsh upgrade`); absent
+   * leaves the first turn to the user.
   */
  initialSkill?: string
 }
@@ -316,6 +316,7 @@ flowchart TD
  pkg_client_ui_settings --> pkg_client_ui_primitives
  pkg_client_ui_settings --> pkg_client_ui_slots
  pkg_client_ui_settings --> pkg_invariants
+  pkg_client_ui_trajectory --> pkg_client_runtime
  pkg_client_ui_trajectory --> pkg_client_ui_primitives
  pkg_client_ui_trajectory --> pkg_invariants
  pkg_credentials --> pkg_brand
@@ -1082,7 +1083,7 @@ flowchart TD
 | [`client-locale`](../packages/client/locale) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
 | [`client-test-runtime`](../packages/client/test-runtime) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-web-react`](../packages/client/web-react), [`host-apiproxy`](../packages/host/apiproxy), [`invariants`](../packages/support/invariants) |
 | [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants) |
-| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) |
+| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`invariants`](../packages/support/invariants) |
 | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
 | [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
 | [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths) |
@@ -46,7 +46,8 @@ export interface ISession {
   */
  updateQueue(itemId: InboxItemId, action: QueueAction): Promise<RpcResult<{ accepted: true }>>
  /**
-   * Cancel the running turn.
+   * Cancel the running turn. Pending queued work remains and resumes in FIFO
+   * order after the Host reaches cancellation quiescence.
   * @returns acceptance, or the business error.
   */
  cancel(): Promise<RpcResult<{ accepted: true }>>
@@ -388,6 +388,9 @@ export class SessionsService implements ISessions {
   *   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.
+   *   A fractional anchor floors to a real event seq: the frozen nodes of an
+   *   interrupted turn carry flow-ordering seqs between two events, and the
+   *   wire takes integers only.
   * @returns the child session id.
   * @throws {SessionForkError} with the source id.
   * @throws {Error} when a requested child-title rename fails after creation.
@@ -402,7 +405,10 @@ export class SessionsService implements ISessions {
      : undefined
    const result = await this.manager.fork({
      sessionId: opts.sessionId,
-      ...(opts.atSeq === undefined ? {} : { atSeq: opts.atSeq }),
+      // Flooring lands inside the anchor's own turn (every turn opens with a
+      // turn/start), so the host's first-turn/end-at-or-after cut still ends
+      // on that turn — never clipped back to the previous one.
+      ...(opts.atSeq === undefined ? {} : { atSeq: Math.floor(opts.atSeq) }),
    })
    if (!result.ok) throw new SessionForkError(result.error, opts.sessionId)
    this.projectList()
@@ -248,7 +248,8 @@ export class Session implements SessionFace {
  }

  /**
-   * Stop: contract session.cancel 1:1; failures land in promptError (same error-strip display slot).
+   * Stop the active turn while the Host preserves pending inbox work; failures
+   * land in promptError (same error-strip display slot).
   * @returns the cancel result.
   */
  async cancel(): Promise<RpcResult<{ accepted: true }>> {
@@ -455,6 +455,17 @@ describe('fork', () => {
    })
  })

+  it('floors a fractional anchor to the real event seq the wire accepts', async () => {
+    const b = bench()
+    await feedList(b, [{ id: 'source', cwd: '/work' }])
+    b.api.onFork = () => Promise.resolve(ok({ sessionId: sid('child') }))
+
+    // The frozen node of an interrupted turn carries turnEnd.seq - 0.9.
+    await expect(b.svc.fork({ sessionId: sid('source'), atSeq: 41.1 })).resolves.toBe('child')
+
+    expect(b.api.callsOf('session.fork')).toEqual([{ sessionId: 'source', atSeq: 41 }])
+  })
+
  it('does not rename without the title policy or a durable source title', async () => {
    const b = bench()
    await feedList(b, [{ id: 'source', cwd: '/work' }])
@@ -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: 0df6bdf47c39cbb6ea5b939d52e5182fe9b58182
-README.zh.md: 31083683116442df41315fc193f97e18674b6c16
+README.md: b61a70fb079eb6a1bc2a67b682a337ffdf708b79
+README.zh.md: 0bb1740b166cfacc2bc79fe2f49793796f66c365
@@ -6,13 +6,13 @@ Conversation domain: skeleton (header/tabs/composer/empty state), chat view (gro

 Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. The disclosure renders the checkpoint's `compact/summary` provenance; when that event is outside the loaded window, the row remains visible but non-expandable. The framed checkpoint payload is model-facing and never renders.

-The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header occupies the top as ordinary column chrome; beneath it a scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
+The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it a scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.

 The view ring IS a slot: the conversation registration declares the `'conversation.view'` list slot (session scope) in its `children` table, ConversationRoot renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from the ring ledger's registration options (`id`/`order`/`label`). The chat view is this package's own ring entry; other plugins (ui-trajectory) contribute tabs through plain `ctx.slots.register` — the former package-local view registry (`registerView`/`ViewEntry`/`ConversationViewMap` and the chrome attachment table) is retired, with per-view chrome dissolved into the view components themselves.

 Approvals take over the composer through the chain this package declares: `ApprovalPanel` registers as a selector-routed `'conversation.composer'` entry (the ui-question pattern) and occupies the composer in place of the InputBar while an approval wait is pending (amber strip, justification headline, paired command line from the running call's args, one-shot refuse/allow). The `PendingApproval` domain face in `contract/slots.ts` owns the wire encoding — the `ApprovalResponsePayload` value with the audit correlation — over the runtime's `PendingWait` carrier; the broadcast `approval/resolved` frame settles the wait and restores the composer. The sidebar mirrors the blocked state through the manager-tracked `waitingApproval` list bit (lit for uninstantiated sessions too), which outranks the running ring until the question resolves. Pending waits leave the message flow entirely: questions (ui-question) and approvals (ApprovalPanel) both answer through the composer takeover, so no display-only placeholder card remains. The composer's bottom-row Access seat mounts `PermissionSelect`, fed by the host-computed `permissions` projection through the standard-kit `useProjection` (key absence hides the chip); the chip opens a Menu-primitive dropdown whose kebab-case preset names render as title-case labels. Safe preset picks submit `/permission <preset>` immediately through the bar's injected `command` callback, while `danger-full-access` is presented as `Full access` and first opens an in-page Modal risk confirmation. The enabling action stays disabled until the user checks the acknowledgement; cancel, Escape, close, and mask click submit nothing.

-Logged non-user messages render as a default-collapsed `上下文注入` disclosure. It shares the Tool calls header geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded 141px scrollport shows bounded inline JSON for both `content` and `source`, and no tool state, summary, or keyed toolview dispatch is synthesized ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)).
+Logged non-user messages render as a default-collapsed `上下文注入` disclosure. It shares the Tool calls header geometry and interaction with `ToolRow` through the package-internal `DisclosureRow`, while retaining context semantics: the expanded body follows its content height up to a 141px scrolling cap, shows inline JSON for both `content` and `source`, and synthesizes no tool state, summary, or keyed toolview dispatch ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)).

 Generic tool rows classify the built-in bash, read, search, write, edit, and run_code names into dedicated visual variants. The filesystem variants render the edit icon and a path summary; that path is a hover-underline link that opens the file with the host OS default application (`host.openPath`, relative paths resolve against the session cwd). Tool rows are not whole-row click targets and do not open the details panel. The code variant summarizes with the model-authored `description` and expands to the program itself; its logged sub-dispatches render as always-visible nested rows through the SAME keyed toolview hole (custom registrations and the GenericToolCard fallback apply to sub-rows unchanged). Cordis lifecycle tools reuse those generic variants while presenting `Inspect`, `Mount temporary Plugin`, and `Unmount temporary Plugin` with a shared Cordis accent; mount keeps the code variant's expandable source rendering.

@@ -61,4 +61,4 @@ None; this package neither assembles nor sends a provider request.
 - **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.
 - **Queue edit is text-only** — rows containing non-text blocks still show a flattened preview, but their edit control is disabled because the inline editor cannot preserve those blocks. A text row's edit mode replaces delete with save and cancel; Enter saves and Escape cancels. QueueDock exposes no send-now control.
- **Web exposes pending Queue only** — the Host omits pending steering from the Queue snapshot until steering has its own interaction. A consumed `steering/message` still renders in the durable transcript so external steering remains truthful on replay.
+- **Web exposes pending Queue only** — the composer and `conversation.send` never submit `mode:'steer'`. The Host omits pending steering from the Queue snapshot. A consumed `steering/message` still folds into the durable transcript as a plain bubble (no interjection chrome) so external/host steering remains truthful on replay.
@@ -6,11 +6,11 @@

 压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。展开内容来自检查点溯源的 `compact/summary`；该事件位于已加载窗口之外时，标记仍然可见但不可展开。面向模型的带框检查点载荷绝不渲染。

-常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段会话标题栏以普通列 chrome 占据顶部；其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
+常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。

 视图环本身就是 slot：会话注册声明 `'conversation.view'` 列表 slot（Session scope），并将其列在 `children` 表中；ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页从环账本的注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包（package）自身的环配置项；其他插件（ui-trajectory）通过普通的 `ctx.slots.register` 贡献标签页。先前包内的视图注册表（`registerView`／`ViewEntry`／`ConversationViewMap` 及 chrome 附加表）已退役，逐视图 chrome 则被拆入视图组件自身。

-已记录的非用户消息渲染为默认折叠的 `上下文注入` 展开项。它通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 标题栏的几何与交互，同时保留上下文语义：展开后的 141px 滚动区会以内联 JSON 的形式有界展示 `content` 和 `source`，且不会合成工具状态、摘要或键控 toolview 分发（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)）。
+已记录的非用户消息渲染为默认折叠的 `上下文注入` 展开项。它通过包内部的 `DisclosureRow` 与 `ToolRow` 共享 Tool calls 标题栏的几何与交互，同时保留上下文语义：展开内容区的高度会随内容自适应，最大为 141px，超出后滚动，并以内联 JSON 展示 `content` 和 `source`，且不会合成工具状态、摘要或键控 toolview 分发（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-context-injection-disclosure.md)）。

 通用工具行把内置的 bash、read、search、write、edit 和 run_code 名称归入专用视觉变体。文件系统变体会渲染 edit 图标和路径摘要；该路径是悬停下划线链接，点击后通过宿主操作系统的默认应用打开文件（`host.openPath`，相对路径相对会话 cwd 解析）。工具行不再是整行点击目标，也不会打开 details 面板。code 变体以模型撰写的 `description` 作摘要，展开后显示程序本身；其已记录的子调用经由同一个键控 toolview 空位渲染为始终可见的嵌套行（自定义注册和 GenericToolCard fallback 原样适用于子行）。Cordis 生命周期工具复用这些通用变体，同时以统一的 Cordis 强调色呈现 `Inspect`、`Mount temporary Plugin` 和 `Unmount temporary Plugin`；mount 行保留 code 变体的可展开源码渲染。

@@ -61,4 +61,4 @@ todo 两个面就是在该形状上的两个注册项，都是普通注册方插
 - **审批面板的「始终允许此类」暂缓**：持久授权需要授权存储设计；今天只能回答允许一次／拒绝。
 - **TodoPanel 将过长条目截成单行省略号**：figma 条没有换行或展开入口，完整文本无法在行内读完。
 - **Queue 编辑仅支持文本**：包含非文本块的行仍显示扁平化预览，但由于内联编辑器无法保留这些块，其编辑控件会被禁用。文本行进入编辑模式后，删除会替换为保存和取消；Enter 保存，Escape 取消。QueueDock 不提供立即发送控件。
- **Web 仅暴露待处理 Queue**：在 steering（中途引导）拥有专用交互之前，Host 不会把待处理 steering 纳入 Queue 快照。已消费的 `steering/message` 仍会渲染到持久 transcript 中，因此从外部提交的 steering 在回放时仍能如实呈现。
+- **Web 仅暴露待处理 Queue**：composer 与 `conversation.send` 从不提交 `mode:'steer'`。Host 不会把待处理 steering（中途引导）纳入 Queue 快照。已消费的 `steering/message` 仍会折叠进持久 transcript（文本记录），并以无「插话」徽章的普通气泡呈现，因此从外部／Host 提交的 steering 在回放时仍能如实呈现。
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				<svg height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>DeepSeek</title><path d="M23.748 4.482c-.254-.124-.364.113-.512.234-.051.039-.094.09-.137.136-.372.397-.806.657-1.373.626-.829-.046-1.537.214-2.163.848-.133-.782-.575-1.248-1.247-1.548-.352-.156-.708-.311-.955-.65-.172-.241-.219-.51-.305-.774-.055-.16-.11-.323-.293-.35-.2-.031-.278.136-.356.276-.313.572-.434 1.202-.422 1.84.027 1.436.633 2.58 1.838 3.393.137.093.172.187.129.323-.082.28-.18.552-.266.833-.055.179-.137.217-.329.14a5.526 5.526 0 01-1.736-1.18c-.857-.828-1.631-1.742-2.597-2.458a11.365 11.365 0 00-.689-.471c-.985-.957.13-1.743.388-1.836.27-.098.093-.432-.779-.428-.872.004-1.67.295-2.687.684a3.055 3.055 0 01-.465.137 9.597 9.597 0 00-2.883-.102c-1.885.21-3.39 1.102-4.497 2.623C.082 8.606-.231 10.684.152 12.85c.403 2.284 1.569 4.175 3.36 5.653 1.858 1.533 3.997 2.284 6.438 2.14 1.482-.085 3.133-.284 4.994-1.86.47.234.962.327 1.78.397.63.059 1.236-.03 1.705-.128.735-.156.684-.837.419-.961-2.155-1.004-1.682-.595-2.113-.926 1.096-1.296 2.746-2.642 3.392-7.003.05-.347.007-.565 0-.845-.004-.17.035-.237.23-.256a4.173 4.173 0 001.545-.475c1.396-.763 1.96-2.015 2.093-3.517.02-.23-.004-.467-.247-.588zM11.581 18c-2.089-1.642-3.102-2.183-3.52-2.16-.392.024-.321.471-.235.763.09.288.207.486.371.739.114.167.192.416-.113.603-.673.416-1.842-.14-1.897-.167-1.361-.802-2.5-1.86-3.301-3.307-.774-1.393-1.224-2.887-1.298-4.482-.02-.386.093-.522.477-.592a4.696 4.696 0 011.529-.039c2.132.312 3.946 1.265 5.468 2.774.868.86 1.525 1.887 2.202 2.891.72 1.066 1.494 2.082 2.48 2.914.348.292.625.514.891.677-.802.09-2.14.11-3.054-.614zm1-6.44a.306.306 0 01.415-.287.302.302 0 01.2.288.306.306 0 01-.31.307.303.303 0 01-.304-.308zm3.11 1.596c-.2.081-.399.151-.59.16a1.245 1.245 0 01-.798-.254c-.274-.23-.47-.358-.552-.758a1.73 1.73 0 01.016-.588c.07-.327-.008-.537-.239-.727-.187-.156-.426-.199-.688-.199a.559.559 0 01-.254-.078c-.11-.054-.2-.19-.114-.358.028-.054.16-.186.192-.21.356-.202.767-.136 1.146.016.352.144.618.408 1.001.782.391.451.462.576.685.914.176.265.336.537.445.848.067.195-.019.354-.25.452z" fill="#4D6BFE"></path></svg>