Merge remote-tracking branch 'origin/master' into feature/installer-adopt-checkout

.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.md
-2026-07-22-docked-web-goal-bar.md: f014da61d2fa0bf25121c040dae99354ab15de9d
-2026-07-22-docked-web-goal-bar.zh.md: f62c6efbb2d330fb7d5ab74138eb781f1a1bc06c
+2026-07-22-docked-web-goal-bar.md: 30f1d45e80cb2759175948f5683b499720ab50f0
+2026-07-22-docked-web-goal-bar.zh.md: 4c8481e64d9e5177a962f10ab1d043e761d07545

.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.md

@@ -12,7 +12,7 @@ The web UI had no goal surface at all: the goal stack shipped with model tools,
 
 `GoalBar` (`packages/client/ui-goal/src/client/GoalBar.tsx`) is a props-driven, self-contained component registered first in the composer's input-dock list. Its standalone 752px card follows the composer's horizontal geometry, and every visible state shares one fixed 36px height so switching phases never resizes it. Loading (`goal === undefined`), absent (`goal === null`), and `phase === 'complete'` render nothing — a completed goal is history, not chrome.
 
-Visibility drives the label and actions: active shows "Ongoing Goal" with pause/edit/clear; paused shows "Paused Goal" and swaps pause for a resume icon button; blocked shows "Blocked Goal" and carries `blockedReason.message` as the strip's `title` tooltip. Goal creation lives on the `/goal` command, not in the bar. The pencil swaps the strip for an inline edit form prefilled with the current objective: Enter or the check button saves through `GoalBarActions.onEdit(objective)`, Esc cancels, and an all-whitespace objective keeps save disabled. The form closes only when the edit succeeds; a failure preserves the draft and displays the error in the bar. Resume and clear failures are displayed there as well. Clear otherwise calls `onClear` directly with no confirmation — a clear keeps a durable tombstone, so nothing is unrecoverable. An effect keyed on the goal's id drops the edit form when the goal's identity changes, so a surviving draft can never be written over the goal that replaced it.
+Visibility drives the label and actions: active shows "Ongoing Goal" with pause/edit/clear; paused shows "Paused Goal" and swaps pause for a resume icon button; blocked shows "Blocked Goal" and carries `blockedReason.message` as the strip's `title` tooltip. Goal creation lives on the `/goal` command, not in the bar. The pencil swaps the strip for an inline edit form prefilled with the current objective: Enter or the check button saves through `GoalBarActions.onEdit(objective)`, Esc cancels, and an all-whitespace objective keeps save disabled. The form closes only when the edit succeeds; a failure preserves the draft and displays the error in the bar. Resume and clear failures are displayed there as well. Clear otherwise calls `onClear` directly with no confirmation — a clear keeps a durable tombstone, so nothing is unrecoverable. Every mutation first acquires a synchronous component-local single-flight latch because React's pending-state render cannot close the same-frame click window. A successful clear also suppresses that exact goal id immediately while the authoritative null projection catches up, so an acknowledged tombstone cannot leave a stale clear control that submits `GOAL_NOT_FOUND`; a failure releases the latch and remains retryable. An effect keyed on the goal's id resets this transient state and drops the edit form when the goal's identity changes, so neither a cleared marker nor a surviving draft can affect the replacement goal.
 
 `GoalBarActions` lives in ui-goal's slot contract (`packages/client/ui-goal/src/client/slots.ts`) and carries exactly the rendered verbs: `onEdit`/`onPause`/`onResume`/`onClear`. Each callback asynchronously returns an explicit success/failure result so `GoalBar` owns its transitions and error display. `apply.ts` wires them to the runtime session methods; the runtime session resolves the current goal's compare-and-set ref internally, so the UI passes no ref.
 
@@ -22,7 +22,7 @@ The strip's background is `--dsw-alias-interactive-bg-hover` rather than the moc
 
 ## Testing
 
-`packages/client/ui-goal/tests/goalbar.spec.tsx` pins the behavior through props alone: loading/absent/complete render nothing, the active strip renders label/objective and fires clear, the edit form prefills, rejects empty, saves on Enter, cancels on Esc, and resets when the goal's identity changes, the active strip fires pause, the paused strip fires resume, and the blocked strip exposes the reason tooltip. Component failure-path cases prove that a failed edit preserves its draft and that edit/resume/clear errors remain visible in the bar. The skeleton specs mount `ConversationRoot` with and without `goalActions`; the undefined case is seeded with an active goal, so the missing gate — not the missing goal — is what hides the strip. Runtime session specs pin the folded-error results, the live-only in-flight-plus-trailing refetch, and the stale-read guard. A keyless real-browser smoke boots the assembled application through `boot → RPC → runtime → GoalBar` and records an inline snapshot of the rendered label, objective, and actions.
+`packages/client/ui-goal/tests/goalbar.spec.tsx` pins the behavior through props alone: loading/absent/complete render nothing, the active strip renders label/objective and fires clear, rapid same-frame clear clicks dispatch once and a successful clear hides before projection convergence, the edit form prefills, rejects empty, saves on Enter, cancels on Esc, and resets when the goal's identity changes, the active strip fires pause, the paused strip fires resume, and the blocked strip exposes the reason tooltip. Component failure-path cases prove that a failed edit preserves its draft and that edit/resume/clear errors remain visible and retryable in the bar. The skeleton specs mount `ConversationRoot` with and without `goalActions`; the undefined case is seeded with an active goal, so the missing gate — not the missing goal — is what hides the strip. Runtime session specs pin the folded-error results, the live-only in-flight-plus-trailing refetch, and the stale-read guard. A keyless real-browser smoke boots the assembled application through `boot → RPC → runtime → GoalBar` and records an inline snapshot of the rendered label, objective, and actions.
 
 ## Alternatives considered
 
@@ -34,6 +34,7 @@ The strip's background is `--dsw-alias-interactive-bg-hover` rather than the moc
 ## Consequences
 
 - Goal presence in the web UI is a standalone composer-context strip: sparkle, phase label, truncated objective, and pause/edit/clear (resume replacing pause when paused) — the browser client's first goal surface.
+- Goal mutations are single-flight within the component; a successful clear hides its exact goal immediately while projection delivery converges, preventing duplicate CAS errors without making transient UI state authoritative.
 - The runtime session exposes the goal verbs over RPC with folded transport errors, and refreshes the snapshot's goal on open and on live goal-change meta (coalesced, guarded against stale reads).
 - Objective editing is reachable from the UI for the first time, through `goal.edit` with the runtime-owned ref; complete remains available to other surfaces (`/goal`, model tools).
 - `goal === null` renders nothing; the composer carries no persistent create affordance — creation is the `/goal` command's job.

.agents/notes/implemented/feature/2026-07-22-docked-web-goal-bar.zh.md

@@ -12,7 +12,7 @@ Web UI 此前没有任何目标相关的界面：目标栈已随模型工具、T
 
 `GoalBar`（`packages/client/ui-goal/src/client/GoalBar.tsx`）是一个由 props 驱动的自包含组件，在 composer 的 input-dock 列表中注册为第一个条目。它采用独立的 752px 卡片，遵循 composer 的水平几何；所有可见状态均使用固定的 36px 高度，切换阶段不会改变尺寸。加载中（`goal === undefined`）、无目标（`goal === null`）和 `phase === 'complete'` 时不渲染任何内容：已完成的目标是历史记录，不是常驻界面元素。
 
-可见性决定标签和操作：active 状态显示 "Ongoing Goal" 并提供暂停／编辑／清除；paused 状态显示 "Paused Goal"，把暂停换成一个恢复图标按钮；blocked 状态显示 "Blocked Goal"，并把 `blockedReason.message` 作为横条的 `title` 悬浮提示。创建目标的入口在 `/goal` 命令上，不在横条里。铅笔图标把横条切换为内联编辑表单，预填当前目标内容：Enter 或勾选按钮通过 `GoalBarActions.onEdit(objective)` 保存，Esc 取消，目标内容全为空白字符时保存按钮保持禁用。编辑成功后表单才会关闭；编辑失败时保留草稿，并在横条中显示错误。恢复和清除失败也显示在横条中。除此之外，清除直接调用 `onClear`，不做确认——清除会保留 durable 墓碑，没有不可恢复的损失。一个以目标 id 为键的 effect 会在目标身份变化时丢弃编辑表单，因此存留的草稿绝不可能覆盖掉替换它的新目标。
+可见性决定标签和操作：active 状态显示 "Ongoing Goal" 并提供暂停／编辑／清除；paused 状态显示 "Paused Goal"，把暂停换成一个恢复图标按钮；blocked 状态显示 "Blocked Goal"，并把 `blockedReason.message` 作为横条的 `title` 悬浮提示。创建目标的入口在 `/goal` 命令上，不在横条里。铅笔图标把横条切换为内联编辑表单，预填当前目标内容：Enter 或勾选按钮通过 `GoalBarActions.onEdit(objective)` 保存，Esc 取消，目标内容全为空白字符时保存按钮保持禁用。编辑成功后表单才会关闭；编辑失败时保留草稿，并在横条中显示错误。恢复和清除失败也显示在横条中。除此之外，清除直接调用 `onClear`，不做确认——清除会保留 durable 墓碑，没有不可恢复的损失。每次变更都会先取得一个同步的组件内 single-flight 锁，因为 React 的 pending 状态渲染无法关闭同一帧内的点击窗口。清除成功后还会立即抑制该 goal id，直到权威的 null 投影追上，因此已确认的墓碑不会留下陈旧的清除控件并再次提交 `GOAL_NOT_FOUND`；失败则释放锁，并且仍可重试。一个以目标 id 为键的 effect 会在目标身份变化时重置瞬态状态并丢弃编辑表单，因此无论已清除标记还是存留草稿，都不会影响替换目标。
 
 `GoalBarActions` 位于 ui-goal 的槽位契约（`packages/client/ui-goal/src/client/slots.ts`），只携带实际渲染的动词：`onEdit`/`onPause`/`onResume`/`onClear`。每个回调都会异步返回显式成功／失败结果，因此 `GoalBar` 自行负责界面转换和错误显示。`apply.ts` 把它们接到运行时会话方法上；运行时会话在内部解析当前目标的 compare-and-set ref，因此 UI 不传 ref。
 
@@ -22,7 +22,7 @@ Web UI 此前没有任何目标相关的界面：目标栈已随模型工具、T
 
 ## 测试
 
-`packages/client/ui-goal/tests/goalbar.spec.tsx` 仅通过 props 固定这些行为：加载中／无目标／已完成时不渲染；active 横条渲染标签和目标内容并触发清除；编辑表单预填内容、拒绝空值、按 Enter 保存、按 Esc 取消，并在目标身份变化时重置；active 横条触发暂停；paused 横条触发恢复；blocked 横条暴露原因悬浮提示。组件失败路径用例证明编辑失败时保留草稿，并且编辑／恢复／清除错误持续显示在横条中。skeleton 规格测试分别挂载带与不带 `goalActions` 的 `ConversationRoot`；未定义的情形预置了一个 active 目标，因此隐藏横条的是缺失的挂载门，而不是缺失的目标。运行时会话规格测试固定了折叠错误结果、仅 live 的执行中读取加尾随读取，以及陈旧读取守卫。一个无密钥真实浏览器冒烟测试通过 `boot → RPC → runtime → GoalBar` 启动组装后的应用，并以内联快照记录渲染出的标签、目标内容和操作。
+`packages/client/ui-goal/tests/goalbar.spec.tsx` 仅通过 props 固定这些行为：加载中／无目标／已完成时不渲染；active 横条渲染标签和目标内容并触发清除；同一帧内快速连续点击清除只会分发一次，清除成功后横条会在投影收敛前隐藏；编辑表单预填内容、拒绝空值、按 Enter 保存、按 Esc 取消，并在目标身份变化时重置；active 横条触发暂停；paused 横条触发恢复；blocked 横条暴露原因悬浮提示。组件失败路径用例证明编辑失败时保留草稿，并且编辑／恢复／清除错误持续显示在横条中且可重试。skeleton 规格测试分别挂载带与不带 `goalActions` 的 `ConversationRoot`；未定义的情形预置了一个 active 目标，因此隐藏横条的是缺失的挂载门，而不是缺失的目标。运行时会话规格测试固定了折叠错误结果、仅 live 的执行中读取加尾随读取，以及陈旧读取守卫。一个无密钥真实浏览器冒烟测试通过 `boot → RPC → runtime → GoalBar` 启动组装后的应用，并以内联快照记录渲染出的标签、目标内容和操作。
 
 ## 考虑过的替代方案
 
@@ -34,6 +34,7 @@ Web UI 此前没有任何目标相关的界面：目标栈已随模型工具、T
 ## 后果
 
 - Web UI 中目标的存在形式是独立的 composer 上下文横条：闪光图标、阶段标签、截断的目标内容，以及暂停／编辑／清除（暂停时恢复取代暂停）——这是浏览器客户端的第一个目标界面。
+- 目标变更在组件内走 single-flight；清除成功后会在投影投递收敛期间立即隐藏与其 id 完全匹配的目标，既防止重复 CAS 错误，又不会把瞬态 UI 状态视为权威。
 - 运行时会话通过 RPC 暴露目标动词并折叠传输层错误，且在打开时和 live 目标变更元数据到达时刷新快照中的目标（合并拉取，带陈旧读取守卫）。
 - 目标内容首次可以从 UI 编辑，经由 `goal.edit`，ref 由运行时持有；完成对其他界面（`/goal`、模型工具）照常可用。
 - `goal === null` 时不渲染任何内容；输入框不提供常驻的创建入口，创建是 `/goal` 命令的职责。

README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write README.md
-README.md: fb956dce51838438fb508db7ea9ebdf9e0b3a50b
-README.zh.md: aa80b744465d7d253a54fffeead7262a1fdf69eb
+README.md: 8ecd0928ee630eeca1cb8ce8b9c59d19f6984969
+README.zh.md: 9ffb3b3086415550df4a0f776c7b91c94122dd97

README.md

@@ -24,7 +24,7 @@ cd deepseek-harness
 scripts/install.sh
 ```
 
-The installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, and prompts for a DeepSeek API key.
+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.
 
 The installer keeps every checkout under `~/.dsh/source`: the master clone at `~/.dsh/source/master` and each install's staging checkout as a git worktree `~/.dsh/source/staging-<timestamp>`. The stable symlink `~/.dsh/source/current` points at the active staging worktree, and `dsh` in `~/.local/bin` links to `current/bin/dsh`, so an upgrade repoints one symlink and the `dsh` on PATH never moves. Re-running the command adds a fresh staging worktree from an updated master and repoints `current` at it. See [`scripts/install.sh`](scripts/install.sh) for alternate install locations and other options.
 
@@ -32,14 +32,14 @@ The installer keeps every checkout under `~/.dsh/source`: the master clone at `~
 
 ### Web UI
 
-For the recommended local interface, build the active checkout after installation and after each update, then start the Web UI:
+For the recommended local interface, choose Web UI when the installer finishes. To start it later, or after updating the active checkout, build the repository and run:
 
 ```sh
 (cd ~/.dsh/source/current && pnpm run build)
 dsh web
 ```
 
-The full build produces the library and client bundles plus the frontend dist. The path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.
+The path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.
 
 ### TUI
 

README.zh.md

@@ -24,7 +24,7 @@ cd deepseek-harness
 scripts/install.sh
 ```
 
-安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥。
+安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，随后让你选择启动 Web UI 或 TUI。选择 Web UI 时，安装器会先构建所需的仓库产物。
 
 安装器会把所有检出都放在 `~/.dsh/source` 下：master 克隆位于 `~/.dsh/source/master`，每次安装的 staging 检出是一个 git worktree `~/.dsh/source/staging-<时间戳>`。稳定符号链接 `~/.dsh/source/current` 指向当前生效的 staging worktree，`~/.local/bin` 中的 `dsh` 链接到 `current/bin/dsh`，因此升级只需重指一个符号链接，PATH 上的 `dsh` 从不移动。再次运行该命令会基于更新后的 master 新增一个 staging worktree，并把 `current` 重指到它。其他安装位置和选项见 [`scripts/install.sh`](scripts/install.sh)。
 
@@ -32,14 +32,14 @@ scripts/install.sh
 
 ### Web UI
 
-推荐在本地使用 Web UI。安装完成后以及每次更新后，请先构建当前生效的检出，再启动 Web UI：
+推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：
 
 ```sh
 (cd ~/.dsh/source/current && pnpm run build)
 dsh web
 ```
 
-完整构建会生成库与客户端 bundle，以及前端 dist。上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。
+上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。
 
 ### TUI
 

apps/cli/src/app-cli-entry.ts

@@ -324,7 +324,7 @@ export class AppCLIEntry {
     try {
       return require.resolve('@deepseek-ai/dsh-frontend/dist/index.html')
     } catch {
-      throw new Error('dsh: frontend dist not built; run pnpm --filter @deepseek-ai/dsh-frontend build first')
+      throw new Error('dsh: frontend dist not built; run pnpm run build from the repository root first')
     }
   }
 }

apps/cli/tests/install-script.spec.ts

@@ -0,0 +1,155 @@
+import { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execa } from 'execa'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const installer = fileURLToPath(new URL('../../../scripts/install.sh', import.meta.url))
+const fixtures: string[] = []
+
+const PTY_DRIVER = String.raw`
+import errno, json, os, pty, select, signal, sys, time
+script, cwd, env_json, actions_json = sys.argv[1:]
+env = os.environ.copy()
+env.update(json.loads(env_json))
+actions = json.loads(actions_json)
+pid, fd = pty.fork()
+if pid == 0:
+    os.chdir(cwd)
+    os.execvpe("sh", ["sh", script], env)
+
+output = bytearray()
+action_index = 0
+deadline = time.monotonic() + 15
+status = None
+while time.monotonic() < deadline:
+    ready, _, _ = select.select([fd], [], [], 0.05)
+    if ready:
+        try:
+            chunk = os.read(fd, 65536)
+        except OSError as error:
+            if error.errno != errno.EIO:
+                raise
+            chunk = b""
+        output.extend(chunk)
+    while action_index < len(actions) and actions[action_index]["waitFor"].encode() in output:
+        os.write(fd, actions[action_index]["send"].encode())
+        action_index += 1
+    waited, candidate = os.waitpid(pid, os.WNOHANG)
+    if waited == pid:
+        status = candidate
+        break
+
+if status is None:
+    os.kill(pid, signal.SIGKILL)
+    _, status = os.waitpid(pid, 0)
+sys.stdout.buffer.write(output)
+if action_index != len(actions):
+    sys.stderr.write(f"completed {action_index}/{len(actions)} PTY actions\n")
+    sys.exit(124)
+sys.exit(os.waitstatus_to_exitcode(status))
+`
+
+interface Action {
+  readonly waitFor: string
+  readonly send: string
+}
+
+interface Fixture {
+  readonly binDirectory: string
+  readonly launchLog: string
+  readonly pnpmLog: string
+  readonly root: string
+  readonly script: string
+}
+
+afterEach(async () => {
+  await Promise.all(fixtures.splice(0).map(async (fixture) => { await rm(fixture, { force: true, recursive: true }) }))
+})
+
+function executable(path: string, content: string): void {
+  writeFileSync(path, content)
+  chmodSync(path, 0o755)
+}
+
+async function createFixture(): Promise<Fixture> {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-install-'))
+  fixtures.push(root)
+  const checkoutDirectory = join(root, 'checkout')
+  const scriptsDirectory = join(checkoutDirectory, 'scripts')
+  const sourceBinDirectory = join(checkoutDirectory, 'bin')
+  const fakeBinDirectory = join(root, 'fake-bin')
+  const binDirectory = join(root, 'path-bin')
+  for (const directory of [scriptsDirectory, sourceBinDirectory, fakeBinDirectory, binDirectory, join(root, 'home/.dsh')]) {
+    mkdirSync(directory, { recursive: true })
+  }
+  const script = join(scriptsDirectory, 'install.sh')
+  copyFileSync(installer, script)
+  const launchLog = join(root, 'launch.log')
+  const pnpmLog = join(root, 'pnpm.log')
+  executable(join(sourceBinDirectory, 'dsh'), '#!/bin/sh\nprintf \'%s\\n\' "$*" >"$DSH_TEST_LAUNCH_LOG"\n')
+  executable(join(fakeBinDirectory, 'pnpm'), `#!/bin/sh
+if [ "\${1:-}" = --version ]; then printf '11.7.0\\n'; exit 0; fi
+printf '%s\\n' "$*" >>"$DSH_TEST_PNPM_LOG"
+`)
+  await execa('git', ['init', '-q'], { cwd: checkoutDirectory })
+  await execa('git', ['add', 'bin/dsh', 'scripts/install.sh'], { cwd: checkoutDirectory })
+  await execa('git', [
+    '-c', 'user.name=dsh-test',
+    '-c', 'user.email=dsh-test@example.invalid',
+    'commit', '-qm', 'fixture',
+  ], { cwd: checkoutDirectory })
+  writeFileSync(join(root, 'home/.dsh/.env'), 'DEEPSEEK_API_KEY=test\n')
+  return { binDirectory, launchLog, pnpmLog, root, script }
+}
+
+async function runInstaller(fixture: Fixture, actions: readonly Action[]): Promise<string> {
+  const result = await execa('python3', [
+    '-c',
+    PTY_DRIVER,
+    fixture.script,
+    fixture.root,
+    JSON.stringify({
+      DSH_BIN_DIR: fixture.binDirectory,
+      DSH_HOME: join(fixture.root, 'home/.dsh'),
+      DSH_TEST_LAUNCH_LOG: fixture.launchLog,
+      DSH_TEST_PNPM_LOG: fixture.pnpmLog,
+      HOME: join(fixture.root, 'home'),
+      PATH: `${join(fixture.root, 'fake-bin')}:${fixture.binDirectory}:${process.env.PATH ?? ''}`,
+    }),
+    JSON.stringify(actions),
+  ], { reject: false, stripFinalNewline: false, timeout: 20_000 })
+  expect(result.exitCode, result.stderr).toBe(0)
+  return result.stdout
+}
+
+describe.runIf(process.platform !== 'win32')('one-line installer interface choice', { timeout: 25_000 }, () => {
+  it('builds and launches the Web UI when the default choice is accepted', async () => {
+    const fixture = await createFixture()
+
+    const output = await runInstaller(fixture, [
+      { waitFor: 'Replace it?', send: '\n' },
+      { waitFor: 'Choose an interface [1/2]:', send: '\n' },
+    ])
+
+    expect(output).toContain('launching Web UI')
+    expect(readFileSync(fixture.pnpmLog, 'utf8')).toBe('install\nrun build\n')
+    expect(readFileSync(fixture.launchLog, 'utf8')).toBe('web\n')
+  })
+
+  it('rejects an unknown choice, then launches the TUI without building', async () => {
+    const fixture = await createFixture()
+
+    const output = await runInstaller(fixture, [
+      { waitFor: 'Replace it?', send: '\n' },
+      { waitFor: 'Choose an interface [1/2]:', send: 'terminal\n' },
+      { waitFor: 'choose 1 for Web UI or 2 for TUI', send: '2\n' },
+    ])
+
+    expect(output).toContain('launching TUI')
+    expect(readFileSync(fixture.pnpmLog, 'utf8')).toBe('install\n')
+    expect(readFileSync(fixture.launchLog, 'utf8')).toBe('\n')
+  })
+})

apps/web/tests/goal-bar.e2e.ts

@@ -0,0 +1,71 @@
+// Keyless assembled-browser coverage for the goal bar over the shipped Web
+// bundles and FixtureApiClient wire. The command creates a real projected
+// goal in the fixture session; the golden pins the active strip, while the
+// clear gesture proves the acknowledged tombstone leaves neither stale chrome
+// nor a duplicate-mutation error.
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import {
+  assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/goal-bar', import.meta.url))
+const ACTIVE_EXPECTED = join(SNAPSHOT_DIR, 'active.expected.md')
+const OVERLAY = fileURLToPath(new URL('./goal-bar.overlay.yml', import.meta.url))
+const MODE = webSnapshotMode()
+
+describe('web e2e: goal bar clear convergence', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({ extraOverlayPath: OVERLAY, welcomeNoticePending: true })
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(`${scaffold.baseUrl}?fixture`, { waitUntil: 'load' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
+  }, 120_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  it('renders one active goal and clears it without exposing a stale error', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-goal-bar-clear'))
+    // Startup reuses the fixture workspace's blank session, keeping this
+    // command independent of alpha's running replay and pending question.
+    const input = page.getByPlaceholder('Describe what you want to build')
+    await input.waitFor({ timeout: 10_000 })
+    await input.fill('/goal guard rapid clear clicks')
+    await input.press('Enter')
+
+    const bar = page.locator('[data-goal-bar]')
+    await bar.waitFor({ timeout: 10_000 })
+    const snapshot = await captureStableAria(page, '[data-goal-bar]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(ACTIVE_EXPECTED, snapshot, MODE)
+
+    const clear = bar.getByRole('button', { name: 'Clear goal' })
+    await clear.evaluate((button) => {
+      const control = button as HTMLButtonElement
+      control.click()
+      control.click()
+    })
+    await expect.poll(() => page.locator('[data-goal-bar]').count(), { timeout: 10_000 }).toBe(0)
+    expect(await page.getByText(/no current goal/iu).count()).toBe(0)
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  }, 60_000)
+
+  it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
+    await assertFixtureInventory(SNAPSHOT_DIR, ['active.expected.md'])
+  })
+})

apps/web/tests/goal-bar.overlay.yml

@@ -0,0 +1,5 @@
+# The client-side FixtureApiClient intentionally rejects settings writes, so
+# this goal-only scenario omits the durable welcome step that would otherwise
+# cover the page. Onboarding owns separate assembled-browser coverage.
+- id: ui-settings-general
+  disabled: true

apps/web/tests/snapshots/goal-bar/active.expected.md

@@ -0,0 +1,8 @@
+- img
+- text: Ongoing Goal guard rapid clear clicks
+- button "Pause goal":
+  - img
+- button "Edit goal":
+  - img
+- button "Clear goal":
+  - img

apps/web/tests/support.ts

@@ -35,7 +35,7 @@ export async function newEnglishPage(browser: Browser, height = 1000): Promise<P
 /** Fail loud on a stale checkout instead of testing yesterday's bundle. */
 export function requireDist(): void {
   if (!existsSync(DIST_INDEX)) {
-    throw new Error('web app dist not built — run `pnpm --filter @deepseek-ai/dsh-frontend build` (pnpm run test:web does this first)')
+    throw new Error('web app dist not built — run `pnpm run build` from the repository root (`pnpm run test:web` does this first)')
   }
 }
 

apps/web/tsconfig.json

@@ -50,6 +50,7 @@
     "tests/permission-policy-context.e2e.ts",
     "tests/access-confirmation.e2e.ts",
     "tests/shipped-composition.e2e.ts",
+    "tests/goal-bar.e2e.ts",
     "tests/startup-auto-selection.e2e.ts"
   ],
   "references": [

packages/client/ui-goal/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-goal/README.md
-README.md: 2c109ab1fbe0b566b8749a6af44ec5e0055fe3b2
-README.zh.md: b81113c67566fd834b3ddb10931d4ecc630aa2f9
+README.md: cfb54fd28044ed80e6ec05de0be057f5d4cfaf46
+README.zh.md: fd999cf1c4c9695d15cfaab3e83afdf475f40448

packages/client/ui-goal/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Goal surface plugin, browser half: the `GoalBar` strip is the first standalone card in the `conversation.input.dock` composer-context stack (order 0, before Todo and Queue). The live goal arrives through `useProjection('goal')` — the host-computed whole value seeded by the history tail page and updated by `session/projection` frames — so the plugin owns no store, no refresh chain, and no event listener. The slot inject face carries only the four mutation verbs (edit / pause / resume / clear over the `goal.*` wire domain — an active goal offers the pause action, a paused one resume); each reads the CAS ref from the session's current projected value at call time and surfaces the settled RPC error inline (the RPC's compare-and-set is the staleness guard — there is no client fence). Goal creation stays on the `/goal` host command; loading, absent, and completed goals render nothing.
+Goal surface plugin, browser half: the `GoalBar` strip is the first standalone card in the `conversation.input.dock` composer-context stack (order 0, before Todo and Queue). The live goal arrives through `useProjection('goal')` — the host-computed whole value seeded by the history tail page and updated by `session/projection` frames — so the plugin owns no domain store, refresh chain, or event listener. The slot inject face carries only the four mutation verbs (edit / pause / resume / clear over the `goal.*` wire domain — an active goal offers the pause action, a paused one resume); each reads the CAS ref from the session's current projected value at call time and surfaces the settled RPC error inline. The strip single-flights mutations synchronously because React's pending render cannot fence same-frame clicks; after a successful clear it immediately suppresses that exact goal id while the authoritative null projection catches up. Goal creation stays on the `/goal` host command; loading, absent, completed, and successfully cleared goals render nothing.
 
 The `/client` export surface is the plugin body (`apply`/`inject`), the `GoalBar`/`GoalDock` components, and the injected verb face types.
 
@@ -17,4 +17,3 @@ None beyond the goal mutation's own context event, which appends to the log tail
 ## Known Limitations and Deferred Work
 
 - **Durable phase only** — the projection value deliberately omits process-local activation (armed/disarmed), so the strip cannot distinguish an active-but-disarmed goal from an armed one; resume re-arms through the RPC side. A host-live-value channel is deferred until a real consumer needs it.
-- **No keyless snapshot yet** — the assembled-application transcript (boot → projection → GoalBar) is deferred to the post-review cleanup pass recorded on the landing PR.

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

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Goal 表面插件（浏览器半件）：`GoalBar` 条带是 `conversation.input.dock` composer 上下文堆栈中的第一张独立卡片（order 0，位于 Todo 和 Queue 之前）。活值经 `useProjection('goal')` 到达——host 计算的全量值由历史尾页播种、由 `session/projection` 帧更新——因此本插件不持有 store、不设刷新链、不挂事件监听。slot 注入面只携带四个变更动词（edit / pause / resume / clear，走 `goal.*` 协议域——active 的 goal 提供暂停动作，paused 的提供恢复）；每个动词在调用时从会话当前投影值读取 CAS ref，并把结算后的 RPC 错误内联呈现（RPC 的 compare-and-set 即陈旧性防护——客户端没有任何栅栏）。goal 的创建仍归 `/goal` host 命令；加载中、无 goal、已完成三种状态一律不渲染。
+Goal 表面插件（浏览器半件）：`GoalBar` 条带是 `conversation.input.dock` composer 上下文堆栈中的第一张独立卡片（order 0，位于 Todo 和 Queue 之前）。活值经 `useProjection('goal')` 到达——host 计算的全量值由历史尾页播种、由 `session/projection` 帧更新——因此本插件不持有领域 store、不设刷新链、不挂事件监听。slot 注入面只携带四个变更动词（edit / pause / resume / clear，走 `goal.*` 协议域——active 的 goal 提供暂停动作，paused 的提供恢复）；每个动词在调用时从会话当前投影值读取 CAS ref，并把结算后的 RPC 错误内联呈现。由于 React 的 pending 渲染无法拦住同一帧内的点击，横条会同步为变更建立 single-flight 防护；清除成功后，会立即抑制该 goal id 对应的目标显示，直到权威的 null 投影追上。goal 的创建仍归 `/goal` host 命令；加载中、无 goal、已完成和已成功清除的 goal 一律不渲染。
 
 `/client` 出口面为插件本体（`apply`/`inject`）、`GoalBar`/`GoalDock` 组件与注入动词面类型。
 
@@ -17,4 +17,3 @@ Goal 表面插件（浏览器半件）：`GoalBar` 条带是 `conversation.input
 ## Known Limitations and Deferred Work
 
 - **只反映持久 phase** —— 投影值有意省略进程本地的 activation（armed/disarmed），条带无法区分 active-but-disarmed 与 armed 状态；resume 经 RPC 侧重新武装。host 活值通道待出现真实消费方后再议。
-- **暂缺 keyless 快照** —— 组装应用级 transcript（boot → 投影 → GoalBar）推迟到落地 PR 记录的评审后收口批次。

packages/client/ui-goal/src/client/GoalBar.tsx

@@ -8,7 +8,7 @@
  * the injected face.
  */
 
-import { useCallback, useEffect, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import type { GoalSnapshot } from '@deepseek-ai/dsh-goal/client'
 import {
   IconCheckOutline16, IconCloseOutline16, IconEditOutline16, IconPauseOutline16, IconPlayOutline16, IconSparkle16, IconTrashOutline16,
@@ -35,6 +35,8 @@ export function GoalBar({ goal, onEdit, onPause, onResume, onClear, t }: GoalBar
   const [draft, setDraft] = useState('')
   const [pending, setPending] = useState(false)
   const [actionError, setActionError] = useState<string | null>(null)
+  const [clearedGoalId, setClearedGoalId] = useState<GoalSnapshot['id'] | null>(null)
+  const pendingRef = useRef(false)
 
   // A new goal identity (cleared/completed/replaced externally) invalidates the local edit
   // state: without the reset a surviving draft's Enter would write over the NEW goal.
@@ -42,32 +44,37 @@ export function GoalBar({ goal, onEdit, onPause, onResume, onClear, t }: GoalBar
   useEffect(() => {
     setEditing(false)
     setActionError(null)
+    setClearedGoalId(null)
   }, [goalId])
 
-  const handleEdit = useCallback(async () => {
-    const trimmed = draft.trim()
-    if (trimmed === '') return
-    setPending(true)
-    setActionError(null)
-    const result = await onEdit(trimmed)
-    setPending(false)
-    if (result.ok) {
-      setEditing(false)
-    } else {
-      setActionError(`${result.error.message} (${result.error.code})`)
-    }
-  }, [draft, onEdit])
-
-  const runAction = useCallback(async (action: () => Promise<GoalActionResult>) => {
+  // React state disables the controls on the next render; the ref closes the
+  // same-render window so rapid clicks cannot submit the same CAS twice.
+  const runAction = useCallback(async (action: () => Promise<GoalActionResult>): Promise<GoalActionResult | undefined> => {
+    if (pendingRef.current) return undefined
+    pendingRef.current = true
     setPending(true)
     setActionError(null)
     const result = await action()
+    pendingRef.current = false
     setPending(false)
     if (!result.ok) setActionError(`${result.error.message} (${result.error.code})`)
+    return result
   }, [])
 
+  const handleEdit = useCallback(async () => {
+    const trimmed = draft.trim()
+    if (trimmed === '') return
+    const result = await runAction(() => onEdit(trimmed))
+    if (result?.ok) setEditing(false)
+  }, [draft, onEdit, runAction])
+
+  const handleClear = useCallback(async (clearedId: GoalSnapshot['id']) => {
+    const result = await runAction(onClear)
+    if (result?.ok) setClearedGoalId(clearedId)
+  }, [onClear, runAction])
+
   // Loading, absent, and complete goals have no strip at all.
-  if (goal === undefined || goal === null || goal.phase === 'complete') return null
+  if (goal === undefined || goal === null || goal.phase === 'complete' || goal.id === clearedGoalId) return null
 
   if (editing) {
     return (
@@ -142,7 +149,7 @@ export function GoalBar({ goal, onEdit, onPause, onResume, onClear, t }: GoalBar
           >
             <IconEditOutline16 />
           </button>
-          <button type="button" className={css.iconBtn} disabled={pending} onClick={() => { void runAction(onClear) }} title={t('action.clear')} aria-label={t('action.clear')}>
+          <button type="button" className={css.iconBtn} disabled={pending} onClick={() => { void handleClear(goal.id) }} title={t('action.clear')} aria-label={t('action.clear')}>
             <IconTrashOutline16 />
           </button>
         </div>

packages/client/ui-goal/tests/goalbar.spec.tsx

@@ -3,13 +3,13 @@
 // inline edit form, and resume/clear icon actions — driven purely through
 // props, no wire. Loading, absent, and complete goals render nothing.
 
-import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { GoalSnapshot } from '@deepseek-ai/dsh-goal/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
 import { GoalBar } from '../src/client/GoalBar.tsx'
-import type { GoalBarActions } from '../src/client/slots.ts'
+import type { GoalActionResult, GoalBarActions } from '../src/client/slots.ts'
 import { zh } from '../src/client/locales.ts'
 
 // The framework-injected t seat, stubbed over the zh dictionaries (the default locale).
@@ -61,6 +61,27 @@ describe('GoalBar', () => {
     expect(actions.onClear).toHaveBeenCalledTimes(1)
   })
 
+  it('single-flights rapid clear clicks and hides the committed goal before its projection catches up', async () => {
+    const actions = makeActions()
+    let resolveClear!: (result: GoalActionResult) => void
+    actions.onClear.mockImplementation(() => new Promise((resolve) => { resolveClear = resolve }))
+    const { container, rerender } = render(<GoalBar goal={makeGoal()} {...actions} t={t} />)
+    const clear = screen.getByRole<HTMLButtonElement>('button', { name: '清除目标' })
+
+    act(() => {
+      clear.click()
+      clear.click()
+    })
+    expect(actions.onClear).toHaveBeenCalledTimes(1)
+    expect(clear.disabled).toBe(true)
+
+    await act(async () => { resolveClear({ ok: true }) })
+    expect(container.firstChild).toBeNull()
+
+    rerender(<GoalBar goal={makeGoal({ id: 'g2' as GoalSnapshot['id'], objective: 'Next goal' })} {...actions} t={t} />)
+    expect(screen.getByText('Next goal')).toBeTruthy()
+  })
+
   it('edit swaps the strip for a prefilled form; Enter saves, empty stays disabled', async () => {
     const actions = makeActions()
     render(<GoalBar goal={makeGoal()} {...actions} t={t} />)
@@ -180,5 +201,7 @@ describe('GoalBar', () => {
     fireEvent.click(screen.getByRole('button', { name: '清除目标' }))
     expect((await screen.findByRole('alert')).textContent).toBe('clear failed (agent-busy)')
     expect(screen.getByText('Ship the redesign')).toBeTruthy()
+    fireEvent.click(screen.getByRole('button', { name: '清除目标' }))
+    await waitFor(() => { expect(actions.onClear).toHaveBeenCalledTimes(2) })
   })
 })

scripts/install.sh

@@ -7,15 +7,16 @@
 # ~/.dsh/source/master), adds a per-install staging worktree at
 # ~/.dsh/source/staging-<timestamp> on branch dsh-staging/<timestamp>, checks
 # host dependencies (git, Node, pnpm) and offers to install a missing pnpm, runs
-# `pnpm install` (no build — the `bin/dsh` launcher runs the TypeScript source
-# through the repo's own tsx), points the stable `~/.dsh/source/current` symlink
+# `pnpm install`, points the stable `~/.dsh/source/current` symlink
 # at that staging worktree and symlinks `dsh` onto PATH at `current/bin/dsh`,
 # records your API credentials in the Harness home (`~/.dsh`) dsh reads at boot,
-# and drops you into `dsh`. Keeping every checkout under ~/.dsh/source keeps
-# successive upgrades in one place instead of scattered sibling clones, and lets
-# staging worktrees share the master clone's object store. The PATH symlink
-# resolves through `current`, so an upgrade repoints one stable symlink instead
-# of relinking PATH: the `dsh` on PATH never moves and can never dangle.
+# and lets you launch the Web UI or TUI. The Web choice builds the repository
+# artifacts first; the TUI runs directly from TypeScript source through the
+# repo's own tsx. Keeping every checkout under ~/.dsh/source keeps successive
+# upgrades in one place instead of scattered sibling clones, and lets staging
+# worktrees share the master clone's object store. The PATH symlink resolves through
+# `current`, so an upgrade repoints one stable symlink instead of relinking PATH:
+# the `dsh` on PATH never moves and can never dangle.
 #
 # When run from inside an existing checkout (e.g. `sh scripts/install.sh` rather
 # than `curl ... | sh`) it never clones and never touches that working tree;
@@ -413,12 +414,33 @@ if [ "${SKIP_CREDS:-0}" != 1 ]; then
   fi
 fi
 
-# --- 6. launch -----------------------------------------------------------------
+# --- 6. choose and launch an interface -----------------------------------------
 step "Done"
 if [ "$HAS_TTY" = 1 ]; then
-  info "launching dsh — run 'dsh' anytime to start again"
-  exec "$DSH_BIN_DIR/dsh" </dev/tty
+  printf '    1) Web UI (recommended)\n'
+  printf '    2) TUI\n'
+  while :; do
+    LAUNCH_INTERFACE=$(ask "Choose an interface [1/2]:" 1)
+    case "$LAUNCH_INTERFACE" in
+      1|web|Web|WEB)
+        step "Building DeepSeek Harness for Web UI"
+        ( cd "$DSH_STAGING" && pnpm run build )
+        info "launching Web UI — run 'dsh web' anytime to start again"
+        exec "$DSH_BIN_DIR/dsh" web </dev/tty
+        ;;
+      2|tui|Tui|TUI)
+        info "launching TUI — run 'dsh' anytime to start again"
+        exec "$DSH_BIN_DIR/dsh" </dev/tty
+        ;;
+      *)
+        warn "choose 1 for Web UI or 2 for TUI"
+        ;;
+    esac
+  done
 else
-  info "install complete. Start it with:"
+  info "install complete. Build and start the Web UI with:"
+  printf '    (cd %s && pnpm run build)\n' "$DSH_STAGING"
+  printf '    %s web\n' "$DSH_BIN_DIR/dsh"
+  info "or start the TUI with:"
   printf '    %s\n' "$DSH_BIN_DIR/dsh"
 fi

tsconfig.host.json

@@ -37,6 +37,7 @@
     "apps/web/tests/permission-policy-context.e2e.ts",
     "apps/web/tests/access-confirmation.e2e.ts",
     "apps/web/tests/shipped-composition.e2e.ts",
+    "apps/web/tests/goal-bar.e2e.ts",
     "apps/web/tests/startup-auto-selection.e2e.ts",
     "apps/cli/tests/**/*.ts",
     "examples/*/src/**/*.ts",