dsh-oc-tui 0.1.4 → 0.1.5

package/README.md

@@ -1,5 +1,11 @@
 # dsh-oc-tui
 
+**As the custom TUI engine cannot support advanced visual effects or full Markdown and Mermaid integration**, future versions will incorporate dependencies such as `chafa`, `mmdc`, and `mdcat` to enhance the visual experience. This update is tentatively scheduled for version `0.2.0` ; please note that this may result in incompatibility between the `0.1.x` and `0.2.x` series. We plan to release pre-release versions first to gather feedback. If you have suggestions for specific visual features, please share them in this issue thread or open a new issue with a title containing `Visual Experience Suggestion`
+
+**_Thank you for your support of the `dsh-oc-tui` plugin!_**
+
+---
+
 **A terminal UI for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)** — an opencode-inspired chat client that boots inside the `dsh` process as a profile app plugin.
 
 [![npm latest](https://img.shields.io/npm/v/dsh-oc-tui?label=npm&color=BF392B)](https://www.npmjs.com/package/dsh-oc-tui)
@@ -67,7 +73,16 @@ dsh --version
 pnpm --version
 ```
 
-**Compatibility.** Verified against dsh `0.1.2-rc.1` (and `0.1.1-rc.2`). DSH renamed parts of the session API in 0.1.2 — `Session.events` became `snapshotEvents()` — and this plugin reads whichever accessor the host provides, so one build serves both lines.
+**Compatibility.** Verified against dsh `0.2.0-rc.2` and `0.1.2-rc.1` (`0.1.1-rc.2` before that). DSH renamed parts of the session API in 0.1.2 — `Session.events` became `snapshotEvents()` — and this plugin reads whichever accessor the host provides, so one build serves both lines.
+
+**dsh (the harness) 0.2.0 is a breaking update — upgrade this plugin first.** From dsh `0.2.0-rc.1` the agent-preset packages were split: the roster provider `@deepseek-ai/dsh-agent-presets` (which shipped its own presets) became `@deepseek-ai/dsh-agent-preset-registry`, and a new `@deepseek-ai/dsh-agent-preset` package is only a *declarative* preset row that injects the service the registry provides. A TUI older than `0.1.5` names the old provider, and dsh reports it at every boot:
+
+```
+dsh: disabling profile plugin row "agent-presets": Plugin @deepseek-ai/dsh-agent-presets@0.1.1-rc.2 is
+incompatible with dsh 0.2.0-rc.2: peerDependencies {…}. Running it may cause crashes or data loss.
+```
+
+The TUI still starts, but Settings → Default preset loses its roster (the row is hidden once no provider mounts it). Updating `dsh-oc-tui` to `0.1.5` or later removes the report: this bundle mounts no roster row at all, because no single package name works on both lines — the old one warns on dsh 0.2.0, the singular never activates, and the registry activates empty unless a host declares presets. A dsh 0.2.0 profile that wants a roster mounts the registry plus its own preset declarations, exactly as `dsh-web-app` does. Nothing about your sessions changes in either direction; `cordis.patch.yml` documents the same decision next to the rows.
 
 ## Install
 
@@ -140,7 +155,7 @@ Verify without booting:
 dsh --profile tui --dump-config
 ```
 
-The dump shows a `# == dsh-oc-tui` layer containing `tui-startup`, `tui-app`, the `agent-presets` roster row, and the `tool-ask-user` row.
+The dump shows a `# == dsh-oc-tui` layer containing `tui-startup`, `tui-app`, and the `tool-ask-user` row — three rows, no agent-preset one (see the compatibility note above).
 
 ## Quick start
 
@@ -271,11 +286,11 @@ Figures come from the same sources as the Web UI, projection-first with the plug
 
 `Ctrl+P` opens a settings menu over the same host settings namespaces as the Web UI, persisted through `ctx.settings` to `$DSH_HOME/settings.yaml`. A left menu splits it into three tabs (`Tab` or click to switch):
 
-- **Main** — General (busy-Enter behaviour, default agent preset, permission preset), Sessions (new session, manage sessions), System (provider API hints, update-manager shortcut, settings file path).
+- **Main** — General (busy-Enter behaviour, permission preset), Sessions (new session, manage sessions), System (provider API hints, update-manager shortcut, settings file path).
 - **Model** — the default provider/model/reasoning choice, then one group per provider holding its URL, API key, and model list. Pressing `Enter` on **Models** fetches the provider's advertised catalog (`ctx.llm.discoverModels`) and opens a checkbox window; pressing `Enter` on a listed model makes it the default route.
 - **Update** — see [In-app updates](#in-app-updates).
 
-Only providers you actually added (present in your user settings layer) are listed; a provider that was never added stays hidden. The default agent preset comes from the roster the profile mounts (the shipped presets plus any you authored under `$DSH_HOME/.agent-presets`) — note that a TUI session composes process-wide from the base, so the stored default applies where a session is created from a preset. Web-UI-only options (`ui-theme` appearance, `locale`) are not shown because they have no effect in the TUI.
+Only providers you actually added (present in your user settings layer) are listed; a provider that was never added stays hidden. **Default preset** is shown only when the profile mounts an agent-preset roster, because the choice list is that roster — and this plugin deliberately mounts none (see the compatibility note above), so on a stock `tui` profile the row is absent rather than empty. Where a roster *is* mounted, note that a TUI session composes process-wide from the base, so the stored default applies where a session is created from a preset. Web-UI-only options (`ui-theme` appearance, `locale`) are not shown because they have no effect in the TUI.
 
 ### In-app updates
 
@@ -286,18 +301,20 @@ Only providers you actually added (present in your user settings layer) are list
 - `No stable release — pick from Versions` — the registry has no stable release yet; pick one manually.
 - `Install damaged — reinstall below` — the global dsh tree is in a mixed old/new state; reinstall it.
 
-`Enter` on a package's **Versions** row opens the full registry list (newest first, `[latest]`/`[next]`/other tags and `(installed)` colour-coded) where you can pick any version — including pre-releases — for a y/n-confirmed install through `npm`/`dsh plugin`. `Check now` re-reads the registry; `Startup check` toggles the silent boot-time stable-release check. Installs run in the background, never block the UI, and need a restart to apply.
+`Enter` on a package's **Versions** row opens the full registry list (newest first, `[latest]`/`[next]`/other tags and `(installed)` colour-coded) where you can pick any version — including pre-releases. A picked version is **downloaded first**: the tarball streams into `$DSH_HOME/updates` with live byte progress, `Esc` cancels mid-flight, and the sha512 registry hash is checked before the file is kept. Applying it is a **restart**: after the y/n confirm the TUI spawns a detached applier, exits, and that child installs from the staged tarball, verifies the on-disk version, and relaunches dsh in the same terminal with the same arguments (`--profile tui --resume …` included) and working directory.
+
+Version rows are tagged `[cached]` when that tarball is already on disk — a version you downloaded before (or rolled back from) needs no new download — and `[staged]` for the version waiting to be applied. A staged install also shows up on the Update tab as **Restart to apply x.y.z** (one `Enter`) and **Discard downloaded x.y.z**, and its state survives a crash: the row is only offered while the staged tarball actually exists. `Check now` re-reads the registry; `Startup check` toggles the silent boot-time stable-release check.
 
 <details>
-<summary><strong>Windows: why dsh installs are deferred to exit</strong></summary>
+<summary><strong>Why an update never installs while the TUI runs</strong></summary>
 
-On Windows, updating dsh while any dsh process runs can *silently corrupt* the global install: npm replaces the directory while the running process holds memory-mapped native DLLs, still exits 0, and the resulting old/new hybrid tree fails to boot. The updater guards this in three layers:
+Updating a package that a live `dsh` process has loaded can *silently corrupt* it: on Windows the process holds memory-mapped native DLLs, npm's directory replace fails, and the result is an old/new hybrid tree — while npm still exits 0. The crash of 2026-09-04 happened exactly that way. Migrating the whole flow to "download, then restart to apply" removed the window instead of narrowing it, on every platform:
 
-1. **dsh installs are deferred to TUI exit** — a detached helper waits for the TUI to close, runs the install, and records the outcome in `$DSH_HOME/tui-dsh-install.json`, which the Update page verifies on the next visit.
-2. **The on-disk version is compared** against the requested target after every direct install, so a silent corruption surfaces as an `install corrupt` toast with repair instructions.
-3. **An already-damaged install is flagged** in the Status row rather than reported as a bogus success.
+1. **Nothing is installed until this process is gone.** The download is only a file; the applier polls this pid, and the TUI refuses to start the restart while any *other* dsh process is alive.
+2. **The on-disk version decides success**, not npm's exit code. A mismatch is reported as `Install damaged — reinstall below` with repair instructions, never as a bogus success.
+3. **The staged tarball is kept**, so a rollback to any downloaded version is a verified cache hit through the same code path as an update.
 
-macOS/Linux have no DLL lock, but an install is refused while other dsh processes are running.
+The applier writes the outcome to `$DSH_HOME/tui-dsh-install.json`, which the Update page reads and drains on the next visit — so the result of an interrupted install is still reported.
 </details>
 
 ## How it works
@@ -397,7 +414,7 @@ More detail, in Chinese: [docs/用户手册.md](docs/用户手册.md).
 - Harness slash commands need a live session; on the title screen the TUI tells you to start one first.
 - Deferring a question with `Esc` does not cancel the tool call — it delegates, and with no other answerer the tool call fails. Per-question skip (as the Web UI composer offers) is not implemented.
 - `--resume`, Settings → Manage sessions, the context meter, and the stats strip depend on services mounted by `@deepseek-ai/dsh-base` (`sessionQuery`, `sessionProjections`); a hand-built profile must provide them. The `sessionStats` projection is a web-app-layer row, so the TUI folds those figures from the session log itself when no profile mounts it.
-- The deferred dsh install on Windows waits for the TUI that scheduled it, not for every dsh process on the machine — close other TUI windows (and `dsh web`) before it runs.
+- An update restart only waits for the TUI that scheduled it: the "no other dsh process" check runs *before* you confirm, so a `dsh web` window opened afterwards can still overlap the install. Close other dsh windows first.
 - Two `@dsh-std` presentation surfaces have no caller today, because the runtime protocol support is gated off (see [@dsh-std interop](#dsh-std-interop)). A standard `secret-input` request would open a masked prompt with `minLength`/`maxLength` bounds, and a standard `ApprovalRequest` is the only thing that populates the approval box's `Origin` / `Risk` / `Details` rows. Both paths are written and integration-tested; neither can be reached from a normal `dsh --profile tui` session, which is why the harness-shaped approval box shows only the action and the summary.
 
 ## Layout
@@ -410,17 +427,18 @@ lib/ui.js            responsive view model + renderer (includes the question mod
 lib/metrics.js       whole-session stats + token usage fold (web stats strip / tokenUsage port)
 lib/interrupt.js     Ctrl+C lifecycle state
 lib/web-settings.js  shared WebUI settings projection
-lib/updates.js       in-app update manager (npm registry + installs)
+lib/updates.js       in-app update manager (npm registry, download + staging, install verification)
 lib/markdown.js      markdown -> styled lines
 lib/util.js          text/display helpers
 lib/bridge.js        live-TUI registry the @dsh-std facet forwards through
 lib/facet.js         @dsh-std facet entry (interop shell; never starts the TUI)
 lib/std/             @dsh-std protocol adapters (adapt, presentation, commands, command-list)
 bin/dsh-oc-tui.js    convenience launcher for `dsh --profile tui`
+bin/apply-update.cjs detached applier: waits for the TUI to exit, installs the staged tarball, relaunches dsh
 install.sh           one-command installer (Linux/macOS)
 install.ps1          one-command installer (Windows)
 dsh-plugin.json      @dsh-std component manifest (discovery + preflight only)
-cordis.patch.yml     bundle patch layer (TUI rows, agent-presets roster, ask-user tool)
+cordis.patch.yml     bundle patch layer (TUI rows, ask-user tool; no agent-preset row, with the reason in a comment)
 docs/用户手册.md       Chinese user manual
 docs/dsh-std-接入说明.md  @dsh-std interop scope and constraints (Chinese)
 tests/smoke.test.mjs standalone smoke tests

package/bin/apply-update.cjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// Detached applier for a TUI-driven update. Spawned by the running TUI
+// immediately before it exits: `node bin/apply-update.cjs <plan.json>`.
+//
+// The plan is a JSON file (written by the TUI into $DSH_HOME/updates) naming
+// one package (dsh or dsh-oc-tui), the staged tarball to install from, how to
+// verify the result, and how to relaunch. The child waits for the TUI to die
+// *first* — that is the whole point of the restart handoff: a global npm
+// install (or a profile reinstall) while a dsh process is alive can leave a
+// hybrid old/new tree behind, and npm still exits 0.
+//
+// Deliberately self-contained: it outlives the plugin that spawned it,
+// including when that plugin is the package being replaced, so it imports
+// nothing from the plugin and stays plain CJS.
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const cp = require('node:child_process')
+const { createRequire } = require('node:module')
+
+const PARENT_WAIT_MS = 600_000
+
+function log(line) {
+  try { process.stdout.write('[dsh-oc-tui] ' + line + '\n') } catch { /* terminal already gone */ }
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true } catch { return false }
+}
+
+function installedVersion(manifestPath) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+    return typeof manifest.version === 'string' ? manifest.version : null
+  } catch {
+    return null
+  }
+}
+
+// Re-resolve the dsh bin entry through the shim *after* the install, so a
+// layout change inside a new dsh version cannot break the relaunch.
+function entryFromShim(shim) {
+  if (typeof shim !== 'string' || shim === '') return null
+  try {
+    const manifestPath = createRequire(path.resolve(shim)).resolve('@deepseek-ai/dsh/package.json')
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+    const entry = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin && manifest.bin.dsh
+    return typeof entry === 'string' && entry !== '' ? path.resolve(path.dirname(manifestPath), entry) : null
+  } catch {
+    return null
+  }
+}
+
+function relaunchTarget(plan) {
+  const entry = entryFromShim(plan.dshShim)
+  if (entry) return { command: process.execPath, args: [entry, ...(plan.dshArgs ?? [])] }
+  const fallback = plan.relaunch
+  if (fallback && Array.isArray(fallback.args) && fallback.args.length > 0) return { command: fallback.command ?? process.execPath, args: fallback.args }
+  return null
+}
+
+function writeMarker(plan, code) {
+  try {
+    fs.mkdirSync(path.dirname(plan.marker), { recursive: true })
+    fs.writeFileSync(plan.marker, JSON.stringify({
+      requested: plan.version,
+      pkg: plan.pkg === 'tui' ? 'tui' : 'dsh',
+      code,
+      finishedAt: Date.now(),
+    }))
+  } catch {
+    // Unwritable home: the next boot simply has nothing to verify.
+  }
+}
+
+// The tarball itself stays in the cache — a rollback to the same version then
+// costs no download. Only the "waiting to be applied" record goes.
+function dropStaged(plan) {
+  try { fs.unlinkSync(path.join(path.dirname(plan.tarball), 'staged.json')) } catch { /* nothing staged */ }
+}
+
+function runInstall(plan) {
+  if (plan.pkg === 'dsh') {
+    if (!plan.npm) {
+      log('npm could not be located — install manually: npm install -g @deepseek-ai/dsh@' + plan.version)
+      return { code: 1 }
+    }
+    const result = cp.spawnSync(plan.npm.command, [...plan.npm.args, 'install', '-g', plan.tarball], {
+      stdio: 'inherit',
+      windowsHide: false,
+    })
+    return { code: result.status === null ? 1 : result.status }
+  }
+  if (!plan.dsh) {
+    log('the dsh CLI could not be located — reinstall the plugin with: dsh plugin --profile ' + plan.profile + ' add -w ' + plan.tarball)
+    return { code: 1 }
+  }
+  // Reinstalling the same version does not reliably replace the installed
+  // copy, so detach the dependency first — the documented dev-loop order.
+  const detach = cp.spawnSync(plan.dsh.command, [
+    ...plan.dsh.args, 'plugin', '--profile', plan.profile, 'remove', '-w', plan.packageName,
+  ], { stdio: 'inherit', windowsHide: false })
+  if (detach.status !== 0) log('detaching the previous copy exited ' + detach.status + ' — continuing anyway')
+  const add = cp.spawnSync(plan.dsh.command, [
+    ...plan.dsh.args, 'plugin', '--profile', plan.profile, 'add', '-w', plan.tarball,
+  ], { stdio: 'inherit', windowsHide: false })
+  return { code: add.status === null ? 1 : add.status }
+}
+
+function apply(plan) {
+  log('installing ' + plan.packageName + '@' + plan.version + ' from ' + plan.tarball)
+  const result = runInstall(plan)
+  const found = plan.verifyPath ? installedVersion(plan.verifyPath) : null
+  if (result.code === 0) {
+    if (found === plan.version) {
+      log('verified ' + plan.packageName + '@' + plan.version)
+    } else {
+      // npm exit 0 is not proof — the on-disk manifest decides. The marker
+      // (code 0, mismatched version) is what the next boot reads back as a
+      // damaged install.
+      log('WARNING: the install reported success but ' + (plan.verifyPath ?? 'the manifest') +
+        ' reports ' + (found ?? 'nothing') + ' (expected ' + plan.version + ')')
+    }
+  } else {
+    log('install failed (exit ' + result.code + ')')
+  }
+  writeMarker(plan, result.code)
+  dropStaged(plan)
+  relaunch(plan)
+}
+
+function relaunch(plan) {
+  const target = relaunchTarget(plan)
+  if (!target) {
+    log('could not locate the dsh entry — start dsh again yourself')
+    process.exit(0)
+  }
+  log('restarting dsh…')
+  try {
+    const child = cp.spawn(target.command, target.args, {
+      cwd: plan.cwd || undefined,
+      detached: true,
+      stdio: 'inherit',
+      windowsHide: false,
+    })
+    child.unref()
+  } catch (error) {
+    log('relaunch failed: ' + (error?.message ?? String(error)) + ' — start dsh again yourself')
+  }
+  process.exit(0)
+}
+
+const planFile = process.argv[2] ?? ''
+let plan = null
+if (planFile !== '') {
+  try {
+    plan = JSON.parse(fs.readFileSync(planFile, 'utf8'))
+  } catch {
+    plan = null
+  }
+}
+if (!plan || typeof plan.tarball !== 'string' || plan.tarball === '' || typeof plan.version !== 'string' || plan.version === '') {
+  log('no usable plan at ' + (planFile || '(no path given)') + ' — nothing to do')
+  process.exit(1)
+}
+if (!plan.marker) {
+  log('plan carries no marker path — nothing to do')
+  process.exit(1)
+}
+
+;(function waitForParent() {
+  const deadline = Date.now() + PARENT_WAIT_MS
+  if (alive(plan.parentPid) && Date.now() < deadline) {
+    // Still inside the window: keep polling. The TUI paints its own screen
+    // until it is gone, so nothing is logged before this point.
+    setTimeout(waitForParent, 250)
+    return
+  }
+  if (alive(plan.parentPid)) {
+    // Never went away (or the pid was reused): never install over a live tree.
+    writeMarker(plan, 1)
+    log('timed out waiting for the TUI to exit — nothing was installed')
+    process.exit(0)
+  }
+  apply(plan)
+})()

package/cordis.patch.yml

@@ -1,32 +1,46 @@
-# dsh-oc-tui bundle patch: the terminal UI over the dsh-base layer.
-# Rows reference this package by name, so the package must be resolvable from
-# the profile — the official path is `dsh plugin --profile tui add
-# dsh-oc-tui`, which installs it into the profile's node_modules and
-# appends this bundle. The zero-install development bootstrap may instead
-# restate these rows in the profile's own patch with absolute module paths.
-
-- insert:
-    - id: tui-startup
-      name: 'dsh-oc-tui/startup'
-
-    - id: tui-app
-      name: 'dsh-oc-tui'
-      config:
-        sidebar: true
-        showReasoning: true
-
-    # The preset roster behind the Settings -> Default preset list.
-    # Sessions keep composing process-wide from the base (single-session TUI);
-    # this row only makes the roster and its settings namespace available.
-    - id: agent-presets
-      name: '@deepseek-ai/dsh-agent-presets'
-      config:
-        default: standard
-
-    # The model-facing `ask_user_question` tool. dsh-base mounts the
-    # `user-questions` service but NOT this tool — the agent presets mount it,
-    # and a TUI session composes process-wide from the base rather than from a
-    # preset, so the row must be declared here or the tool is simply absent.
-    # lib/index.js answers the `user-questions/request` waterfall with a modal.
-    - id: tool-ask-user
-      name: '@deepseek-ai/dsh-tool-ask-user'
+# dsh-oc-tui bundle patch: the terminal UI over the dsh-base layer.
+# Rows reference this package by name, so the package must be resolvable from
+# the profile — the official path is `dsh plugin --profile tui add
+# dsh-oc-tui`, which installs it into the profile's node_modules and
+# appends this bundle. The zero-install development bootstrap may instead
+# restate these rows in the profile's own patch with absolute module paths.
+
+- insert:
+    - id: tui-startup
+      name: 'dsh-oc-tui/startup'
+
+    - id: tui-app
+      name: 'dsh-oc-tui'
+      config:
+        sidebar: true
+        showReasoning: true
+
+    # The model-facing `ask_user_question` tool. dsh-base mounts the
+    # `user-questions` service but NOT this tool, so the row must be declared
+    # here or the tool is simply absent. lib/index.js answers the
+    # `user-questions/request` waterfall with a modal.
+    - id: tool-ask-user
+      name: '@deepseek-ai/dsh-tool-ask-user'
+
+# There is deliberately no agent-preset row. The Settings -> Default preset list
+# reads the roster the profile mounts, and no single package name serves both dsh
+# lines:
+#
+#   * dsh 0.1.x: `@deepseek-ai/dsh-agent-presets` (plural) *is* the roster
+#     provider and ships its own presets. Naming it here is what 0.1.0-0.1.4 did.
+#   * dsh 0.2.0-rc.1 renamed the pieces: `@deepseek-ai/dsh-agent-presets` peers
+#     on the 0.1.x packages, so dsh *disables* the row at every boot with a
+#     wall-of-text incompatibility report ("may cause crashes or data loss"),
+#     while `@deepseek-ai/dsh-agent-preset` (singular) is only a declarative
+#     preset row that injects the service and never activates on its own, and
+#     `@deepseek-ai/dsh-agent-preset-registry` mounts an empty roster unless a
+#     host declares the presets.
+#
+# A row naming a package this dsh cannot resolve is skipped silently rather than
+# loaded, so the honest options were "always warn on the new line" (plural),
+# "never activate" (singular) or "activate empty" (registry). None of them
+# restores a roster a host-owned composition owns, so the bundle mounts none:
+# the TUI boots clean on both lines and Settings simply omits the Default preset
+# row (lib/web-settings.js hides a row whose namespace has no provider). A dsh
+# 0.2.0 profile that wants a roster mounts the registry plus its own preset
+# declarations, exactly as dsh-web-app does.

package/docs//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -134,7 +134,7 @@ profile 目录把自己声明为 pnpm workspace 根（`pnpm-workspace.yaml` →
 dsh --profile tui --dump-config
 ```
 
-输出中应出现 `# == dsh-oc-tui` 这一层，包含 `tui-startup`、`tui-app`、`agent-presets`（预设名册）与 `tool-ask-user`（提问工具）四行。
+输出中应出现 `# == dsh-oc-tui` 这一层，包含 `tui-startup`、`tui-app` 与 `tool-ask-user`（提问工具）三行——本 bundle 刻意不挂载 agent 预设名册（原因见 5.7 的破坏性更新说明），因此这一层没有预设行。
 
 ## 4. 启动
 
@@ -268,7 +268,7 @@ dsh 的人类命令（`/compact`、`/goal`、`/plan` 等）会转发给 `ctx.com
 
 按 `Ctrl+P` 打开。菜单覆盖与 WebUI 相同的 Host 设置命名空间，修改通过 `ctx.settings` 持久化到 `$DSH_HOME/settings.yaml`。左侧菜单栏用 `Tab`（或鼠标点击）在三个标签间切换，`↑/↓` 移动、`Enter` 打开选项列表、`Esc` 返回，分区标题行不可选中：
 
-- **Main**：General（Busy Enter 行为、默认 agent 预设、权限预设）、Sessions（新建会话、管理会话）、System（Provider API 配置提示、更新管理器快捷入口、设置文件路径）
+- **Main**：General（Busy Enter 行为、权限预设）、Sessions（新建会话、管理会话）、System（Provider API 配置提示、更新管理器快捷入口、设置文件路径）
 - **Model**：默认 provider / model / 思考强度；随后是你添加过的每个 provider 一组，组内为 Provider URL、Provider API key、Models
 - **Update**：见 [5.7](#57-程序内更新)
 
@@ -276,7 +276,7 @@ dsh 的人类命令（`/compact`、`/goal`、`/plan` 等）会转发给 `ctx.com
 
 **Models 自动获取**：在某个 provider 的 **Models** 行按 `Enter`，TUI 调用 `ctx.llm.discoverModels` 获取该 provider 的完整模型目录（内置路由直接取内置目录，自定义路由则请求其端点），弹出勾选窗口用 `[x]`/`[ ]` 选择（`Enter` 切换、`Esc` 返回）。选中的模型保存到该 provider 的 `models` 配置；在列出的模型上按 `Enter` 可把它设为默认模型。
 
-默认 agent 预设来自 profile 挂载的 `agent-presets` 名册（内置预设 + 你在 `$DSH_HOME/.agent-presets` 下自建的预设）。注意 TUI 会话始终从进程级 base 组合生成，因此该默认值只在按预设创建会话时生效。
+**默认 agent 预设** 只有在 profile 挂载了预设名册时才会出现——选项列表就是那份名册，而本插件刻意不挂载（见 5.7），所以默认的 `tui` profile 里这一行是「没有」而不是「空白」。若某一套 profile 确实挂载了名册，请注意 TUI 会话始终从进程级 base 组合生成，该默认值只在按预设创建会话时生效。
 
 WebUI 专属选项（`ui-theme` 外观、`locale` 语言）不在 TUI 中显示，因为它们在终端里没有效果。
 
@@ -293,15 +293,22 @@ WebUI 专属选项（`ui-theme` 外观、`locale` 语言）不在 TUI 中显示
 
 `Enter` 打开某个包的 **Versions** 完整版本列表（新→旧），`[latest]`（绿）、`[next]`（青）、`(installed)`（浅蓝）等标识区分频道与当前版本；选中任意版本（含 rc/alpha）后按 `Enter` 出现 y/n 确认（文案含目标版本号）。`Check now` 重新拉取 registry；`Startup check` 开关启动后 2 秒的静默稳定版检查。
 
-安装过程后台进行、不阻塞界面、不会自动重启；完成后 toast `... installed — restart to apply`，重启后生效。
+**更新分两步：先下载，再重启生效。** 确认后 TUI 自己把 tarball 下载到 `$DSH_HOME/updates`，界面上有实时字节进度条（`Esc` 随时取消），落盘前按 registry 上的 sha512 校验完整性；下载完成后再问一次「重启即应用」，确认后 TUI 先派生一个独立安装进程、自己退出，该子进程等本进程消失才执行安装（dsh 走 `npm install -g <tarball>`，TUI 走 `dsh plugin … add -w <tarball>`），校验磁盘实际版本，然后带着原来的参数和工作目录把 dsh 重新拉起来。因此：
 
-**Windows 上的 dsh 更新（重要）**：Windows 会锁定运行中程序加载的原生 DLL，而 `npm install -g` 需要替换整个 dsh 目录——若更新时有任何 dsh 进程在运行，npm 可能**静默留下新旧混杂的损坏安装**并仍报成功。因此更新器有三层保护：
+- 版本列表会打 `[cached]`（该版本 tarball 已在磁盘上，回退/重试都不需要重新下载）和 `[staged]`（等待重启应用的那个版本）标记；
+- Update 页面对下载未应用的版本会多出 **Restart to apply x.y.z**（直接 `Enter` 重启应用）与 **Discard downloaded x.y.z**（丢弃）两行，且只有 tarball 确实还在磁盘上时才会出现——上次下载后崩溃也不会留下一个假入口；
+- 安装结果写入 `$DSH_HOME/tui-dsh-install.json`，下次打开 Update 页自动读取并清除；已损坏的安装会被标出（Status 行 `Install damaged — reinstall below`），而不是报一个虚假的成功。
 
-1. **dsh 安装在 Windows 上延迟到 TUI 退出后执行**：确认后 toast 提示 `will install when this TUI exits`，关闭 TUI 时一个独立小进程等待本进程退出、执行 `npm install`，并把结果写入 `$DSH_HOME/tui-dsh-install.json`，下次打开 Update 页自动核对。
-2. **每次直接安装后校验磁盘实际版本**与目标是否一致，不一致（静默损坏）时 toast 报 `install corrupt` 并给出修复指引。
-3. **已损坏的安装会被标出**（Status 行 `Install damaged — reinstall below`），而不是报一个虚假的成功。
+**为什么更新绝不在 TUI 运行期间安装**：给一个正在被 `dsh` 进程加载的包做全局安装，可能**静默**留下新旧混杂的损坏安装——Windows 上运行中的进程锁着内存映射的原生 DLL，npm 替换目录失败却仍以 0 退出（2026-09-04 就是这样把 dsh 弄坏的）。改成「下载 → 重启应用」之后，这台戏在任何平台都不再有窗口期：应用进程会等本进程消失才动手，且 TUI 在确认重启前会检查是否有别的 dsh 进程在跑（有就拒绝）。残留窗口只有一个：该检查发生在确认**之前**，之后又开起来的 `dsh web` 仍可能撞上安装。
 
-macOS/Linux 没有 DLL 锁，但检测到其它 dsh 进程运行时也会拒绝安装。
+**dsh 0.2.0 是破坏性更新——先升 TUI，再升 dsh。** 从 `0.2.0-rc.1` 起，预设相关包被拆开：原来的名册提供方 `@deepseek-ai/dsh-agent-presets`（自带预设）改名为 `@deepseek-ai/dsh-agent-preset-registry`，而新的 `@deepseek-ai/dsh-agent-preset` 只是**声明式**的预设行——它注入注册表提供的服务，自己不会激活。`0.1.5` 以下的 TUI 引用的还是旧名，于是 dsh 每次启动都会打印一段墙一样的不兼容报告：
+
+```
+dsh: disabling profile plugin row "agent-presets": Plugin @deepseek-ai/dsh-agent-presets@0.1.1-rc.2 is
+incompatible with dsh 0.2.0-rc.2: peerDependencies {…}. Running it may cause crashes or data loss.
+```
+
+TUI 仍然能启动，但 Settings → Default preset 不再有名册可选（没有人提供名册时该行直接隐藏）。把 TUI 更到 `0.1.5` 或更高，这段报告就消失：本 bundle **根本不挂载名册行**——因为没有任何一个包名能在两条 dsh 线上同时成立：旧名在 0.2.0 上会触发上面的报告，单数名永远不会激活，注册表名册在没有主机声明预设时激活出来也是空的。需要名册的 dsh 0.2.0 profile 应当自己挂载注册表并声明预设（`dsh-web-app` 正是这么做的）。两个方向都不影响会话数据。
 
 ## 6. 工作原理
 
@@ -413,7 +420,7 @@ bin/dsh-oc-tui.js   便捷启动器
 install.sh          一键安装脚本（Linux/macOS）
 install.ps1         一键安装脚本（Windows）
 dsh-plugin.json     @dsh-std 组件清单（仅用于发现与预检）
-cordis.patch.yml    bundle 补丁层（TUI 行、预设名册、提问工具）
+cordis.patch.yml    bundle 补丁层（TUI 行、提问工具；刻意不含预设名册行，注释里写了原因）
 docs/用户手册.md     本手册
 docs/dsh-std-接入说明.md  @dsh-std 接入范围与约束
 tests/smoke.test.mjs 独立冒烟测试

package/dsh-plugin.json

@@ -1,65 +1,65 @@
-{
-  "$schema": "https://raw.githubusercontent.com/Yan-Zero/dsh-std/main/packages/manifest/schema/dsh-plugin-0.15.schema.json",
-  "manifestVersion": "0.15",
-  "id": "io.github.rayafriandion.dsh-oc-tui",
-  "name": "dsh-oc-tui",
-  "version": "0.1.4",
-  "license": "LGPL-3.0-or-later",
-  "source": { "repository": "https://github.com/rayafriandion/dsh-oc-tui" },
-  "facets": { "host": { "entry": "lib/facet.js", "apiVersion": "v1alpha1" } },
-  "requires": {
-    "contracts": [
-      { "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "optional": true }
-    ]
-  },
-  "permissions": [
-    { "name": "storage.local.read", "scope": "io.github.rayafriandion.dsh-oc-tui",
-      "reason": "Read TUI settings from the host settings store." },
-    { "name": "storage.local.write", "scope": "io.github.rayafriandion.dsh-oc-tui",
-      "reason": "Persist TUI settings chosen in the Settings pages." }
-  ],
-  "contributes": {
-    "x-dev.dsh-std.extensions": [
-      { "id": "io.github.rayafriandion.dsh-oc-tui.settings",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "settings",
-        "spec": { "title": "Open the TUI settings pages",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.help",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "help",
-        "spec": { "title": "Show the TUI key and command reference",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.stats",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "stats",
-        "spec": { "title": "Show session token and cache statistics",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.new",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "new",
-        "spec": { "title": "Start a new session",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.resume",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "resume",
-        "spec": { "title": "Resume a persisted session",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.clear",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "clear",
-        "spec": { "title": "Clear the transcript",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.cancel",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "cancel",
-        "spec": { "title": "Cancel the running turn",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.rewind",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "rewind",
-        "spec": { "title": "Rewind the session to an earlier point",
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
-      { "id": "io.github.rayafriandion.dsh-oc-tui.quit",
-        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "quit",
-        "spec": { "title": "Leave the TUI", "aliases": ["exit"],
-                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } }
-    ]
-  },
-  "overrides": [
-    { "target": "@deepseek-ai/dsh-base", "kind": "patch",
-      "description": "cordis.patch.yml inserts the tui-startup, tui-app, agent-presets and tool-ask-user rows." }
-  ]
-}
+{
+  "$schema": "https://raw.githubusercontent.com/Yan-Zero/dsh-std/main/packages/manifest/schema/dsh-plugin-0.15.schema.json",
+  "manifestVersion": "0.15",
+  "id": "io.github.rayafriandion.dsh-oc-tui",
+  "name": "dsh-oc-tui",
+  "version": "0.1.5",
+  "license": "LGPL-3.0-or-later",
+  "source": { "repository": "https://github.com/rayafriandion/dsh-oc-tui" },
+  "facets": { "host": { "entry": "lib/facet.js", "apiVersion": "v1alpha1" } },
+  "requires": {
+    "contracts": [
+      { "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "optional": true }
+    ]
+  },
+  "permissions": [
+    { "name": "storage.local.read", "scope": "io.github.rayafriandion.dsh-oc-tui",
+      "reason": "Read TUI settings from the host settings store." },
+    { "name": "storage.local.write", "scope": "io.github.rayafriandion.dsh-oc-tui",
+      "reason": "Persist TUI settings chosen in the Settings pages." }
+  ],
+  "contributes": {
+    "x-dev.dsh-std.extensions": [
+      { "id": "io.github.rayafriandion.dsh-oc-tui.settings",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "settings",
+        "spec": { "title": "Open the TUI settings pages",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.help",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "help",
+        "spec": { "title": "Show the TUI key and command reference",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.stats",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "stats",
+        "spec": { "title": "Show session token and cache statistics",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.new",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "new",
+        "spec": { "title": "Start a new session",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.resume",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "resume",
+        "spec": { "title": "Resume a persisted session",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.clear",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "clear",
+        "spec": { "title": "Clear the transcript",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.cancel",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "cancel",
+        "spec": { "title": "Cancel the running turn",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.rewind",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "rewind",
+        "spec": { "title": "Rewind the session to an earlier point",
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } },
+      { "id": "io.github.rayafriandion.dsh-oc-tui.quit",
+        "apiVersion": "commands.dsh/v1alpha1", "kind": "Command", "name": "quit",
+        "spec": { "title": "Leave the TUI", "aliases": ["exit"],
+                  "placements": [{ "apiVersion": "tui.dsh/v1alpha1", "kind": "CommandLine" }] } }
+    ]
+  },
+  "overrides": [
+    { "target": "@deepseek-ai/dsh-base", "kind": "patch",
+      "description": "cordis.patch.yml inserts the tui-startup, tui-app, agent-presets and tool-ask-user rows." }
+  ]
+}