@crazyhappyone/dsh-tui 0.1.0-alpha.5 → 0.1.0-alpha.51

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+## 0.1.0-alpha.51 — 2026-10-21
+
+Prerelease for DSH `0.2.1-rc.2`; npm channel: `next`.
+
+### Fixed
+
+- Streamed transcript cells now have one physical painter. Ink reserves the slot and paints chrome; sparse incremental frames, pane transitions and resize restore or release that slot without retaining old prose in blank rows. HUD and input-height changes clear the old transcript area and paint the new layout in the same synchronized frame, preventing text from leaking below the transcript during unattended streaming.
+- Mouse wheel and touchpad reports land at their target without row-by-row catch-up. Reports received before a React commit retain their combined movement, and scrolling no longer rerenders the parent loop for every report. Scroll latency is measured through the matching stdout callback.
+- Render-store budgets use incremental row/byte totals and resident LRU order instead of repeatedly scanning all historical lines. Markdown settlement uses a source index to avoid repeatedly searching the full history.
+- `/settings` now browses category → namespace → provider/object → model/array → fields. Search, back navigation and successful edits retain location/selection; nested edits preserve unknown user fields through the official settings service. Narrow layouts reserve space for values and actions.
+- [#14](https://github.com/zhangyang-crazy-one/dsh-tui/issues/14): discard transient text from failed `assistant/attempt` streams, keeping live history consistent with durable replay. Successful retries and officially committed interrupted messages remain visible.
+- [#15](https://github.com/zhangyang-crazy-one/dsh-tui/issues/15): restore SSH port-forward instructions when reopening an in-progress DeepSeek login. Automatic browser opening now checks the actual SSH environment; explicit `o` still opens the link.
+- [#16](https://github.com/zhangyang-crazy-one/dsh-tui/issues/16): resolve file-panel relative paths against the current Session directory after `/cd`, with configured-cwd/filesystem fallback. Absolute paths and the previous root on failure retain their behavior.
+
+### Verification and upgrade
+
+- Passed 2,299 TUI tests across 173 files with two workers, 46 launcher tests, four strict TypeScript projects, five bundle builds/import checks and the npm package-content check.
+- Production rendering in an OS PTY with synthetic services produced 2,928 completed frames. Of these, 2,812 had transcript snapshots for comparison: 77,558 physical rows, zero mismatches and zero transcript leaks into the input/HUD area. Initialization/layout transitions without snapshots were not counted as comparison passes.
+- In the recorded 120×40 PTY fixture, a nine-line wheel burst reached its target in 17.93 ms instead of 168.07 ms. At 60 Hz, React commits fell from 175 to 60 and output from 804,570 to 307,651 bytes. These measurements depend on the fixture and machine; they do not measure physical touchpad or display latency. See the [verification report](docs/performance-audit-2026-10-21/fix-verification.md).
+- Upgrade with `npm install --global @crazyhappyone/dsh-tui@next`, then relaunch. Source-linked installations can use `/reload` after the new bundle is available. The official `deepseek-tui` profile and settings/credential services remain authoritative; no configuration migration is required.
+- Live model authentication and physical-device rendering were not part of this offline/PTY verification. Full TUI tests used two workers after timing-sensitive failures under high concurrency; assertions were not relaxed.
+
+### 中文变更说明
+
+- 修复无操作流式输出的重复正文、空白行残影及终端光标定位；聊天内容统一由物理帧绘制。切换面板、调整尺寸及 HUD/输入区高度变化时，在同步帧中清理旧正文区域，防止正文穿插到下方。
+- 修复滚轮/触控板逐行追赶和同批输入只保留最后一次的问题；滚动直接进入视口，延迟统计到对应 stdout 写入回调为止。
+- 历史渲染缓存改用增量行数/字节统计和驻留 LRU，移除预算检查中的反复全量扫描。
+- 设置改为分类、namespace、Provider/对象、model/数组、字段的逐级浏览；支持搜索、返回和保存后停留。继续使用官方配置接口，保留未知字段，窄屏为值和操作预留空间。
+- 修复失败流式片段残留为普通消息，保证实时历史与持久化回放一致；保留成功重试和官方已提交的中断消息。
+- 修复 SSH 登录页关闭重开后丢失转发命令、错误自动打开远端浏览器；显式按 `o` 仍可打开链接。
+- 修复 `/cd` 后文件面板相对路径仍使用启动目录；改用当前会话目录，保留绝对路径及失败时原目录。
+- 验证：2,299 项 TUI 测试、46 项 launcher 测试、4 个严格类型检查项目及构建/打包通过；2,812 个有快照的 PTY 比较帧覆盖 77,558 行，正文不一致与越界均为 0。完整 TUI 测试限制为 2 个 worker，未放宽断言；不将 PTY 合成数据视为在线认证或真实设备验收。
+- 升级：`npm install --global @crazyhappyone/dsh-tui@next` 后重新启动；源码链接安装可在新 bundle 就绪后 `/reload`。继续使用官方 profile 与配置服务，无需迁移配置。
+
+[Full comparison](https://github.com/zhangyang-crazy-one/dsh-tui/compare/v0.1.0-alpha.50...v0.1.0-alpha.51)
+
+## 0.1.0-alpha.50 — 2026-10-21
+
+Prerelease for DSH `0.2.1-rc.2`; npm channel: `next`. The changes below include the unreleased work since `0.1.0-alpha.49`.
+
+### Fixed
+
+- **Shared official model configuration:** lightweight and source launch modes now both default to `deepseek-tui`. `--profile NAME` / `--profile=NAME` controls both bundle installation and boot; duplicate or missing profile arguments fail before installation. Previously, installing the official `dsh` executable could silently switch lightweight mode to the empty `tui` profile and hide providers configured by Magpie in `deepseek-tui`.
+- `/model` continues to read DSH's `ctx.llm` registry and persists selections through `agentDefaultModel`. No parallel configuration reader, cross-profile copy, or provider credentials are added. Large catalogs now use the actual terminal height, keeping the heading, selected row, filter and navigation visible.
+- Backend-started turns, including Goal continuation and scheduled wakeups, enter the running interaction state. Ctrl+C cancels the active turn. The Goal footer distinguishes durable `active` state from armed/disarmed continuation and explains `/goal resume`.
+- Mouse selection preserves Chinese text, margins and copy order without repainting the entire screen. Repeated coordinates produce no extra output; a clipboard helper closing stdin no longer crashes the TUI with EPIPE.
+- Approval, question and plan-review content uses physical row budgets so decisions stay visible. Custom answers, batch/multiple selections, pasted text, cancellation and chat drafts retain their separate ownership.
+- Credential editors and secret `/key`/`/login` arguments are masked, including caret movement and selection; secret selections cannot be copied.
+- Plugin-market registry selection is preserved through both inspection and installation, and cleared when switching to an official catalog target.
+
+### Added
+
+- `/timeline` event/tool/usage/timing details and full JSON; `/todos` complete task browsing; `/deliveries`, `/attachments` and `/review` for delivered files, typed references and exact per-file diffs.
+- Official time context, `present`, and persistent schedule tools; `/schedules` lists, inspects, opens the owning Session and confirms cancellation. Pending reminders recover on restart; a closed process runs no timers.
+- Subagent live output, continuation (`c`, queue or steer), Stop requests (`s`) and wide-terminal side-by-side viewing (`v`), preserving the main Session and draft.
+- Light/dark themes across truecolor/256/16/plain terminals, grouped settings, `/keys`, conflict-checked composer `/bind` and `/unbind`, grapheme input selection and plain-stream screen-reader mode.
+- File-tree coalesced automatic watching, manual refresh, preserved selection, recoverable errors and watcher disposal.
+- `/preset` with isolated standard/PTC/minimal/cordis compositions, selected before the first turn; `/market` search and approved install preview; `/inspect` official Host contracts; `/focus` rendering.
+- BCP47 locale registration, bounded language-specific lexical code highlighting and read-only Alt+H help during blocking dialogs.
+- macOS image-paste adapter using `pngpaste`, explicit missing-helper errors and cancellation/timeout handling.
+- Official-source runtime initialization, bundle linking, generated-contract preparation and standalone source/test type-check setup.
+
+### Upgrade and boundaries
+
+- Update with `npm install --global @crazyhappyone/dsh-tui@next`. Run `dsh-tui probe` to check the engine and default profile. Source mode also uses the same profile.
+- Existing `tui` and `deepseek-tui` directories are retained. To keep the old lightweight configuration, use `dsh-tui --profile tui`. DSH profiles remain independent; a provider configured only in `web` is not automatically global. Refresh Magpie's DSH connection/catalog after creating a new profile.
+- `/reload` refreshes code in a running source-linked installation while retaining its existing profile; quit and relaunch to change the default profile. Resumed Goals require explicit `/goal resume`.
+- Images and PDF/Office documents use metadata/text or the system opener. IME preedit remains native to the terminal; Ink exposes no composition events. Physical macOS/IME/screen-reader devices, remote market downloads, live model replies and external Stop convergence are not established by offline tests.
+
+### 中文变更说明
+
+- **修复模型配置入口分裂：**轻量模式与源码模式统一默认使用官方 `deepseek-tui` profile；`--profile` 同时决定安装和启动目标。旧版在探测到官方 `dsh` 后会改用缺少配置的 `tui`，导致 Magpie 已写入的模型不出现在列表中。继续使用官方 `ctx.llm` / `agentDefaultModel`，不另建配置加载器、不复制其他 profile；模型列表按实际终端高度显示。
+- **修复运行与输入状态：**后台 Goal/定时回合正确进入生成中，Ctrl+C 取消回合；页脚区分目标 active 和自动续跑是否启用。修复鼠标复制、EPIPE、窄屏决策按钮、自定义/多选问答和秘密输入遮罩。
+- **新增会话与文件能力：**事件轨迹/JSON、完整 TODO、定时提醒、时间上下文、交付物、附件目录、逐文件 diff，以及子代理实时输出、排队/引导续聊、停止请求与宽屏并排。
+- **新增操作与扩展能力：**明暗主题、设置分组、快捷键查看/重绑定、文件树监控、四种隔离 preset、市场预览、Host 自检、focus、语言包注册、有界词法高亮、字素选区、普通流无障碍和阻塞对话只读帮助。
+- **升级：**`npm install --global @crazyhappyone/dsh-tui@next`。旧 profile 均保留；需要旧轻量配置时用 `--profile tui`。`/reload` 保留当前 profile，切换默认 profile 需退出后重新启动；Goal 恢复后执行 `/goal resume`。创建新 profile 后刷新 Magpie 的 DSH 接入/目录。
+- **边界：**关闭进程期间提醒不计时；图片及 PDF/Office 使用文本/元数据或系统程序。未将离线测试等同于联网模型、远程安装、真实外部 Stop 收敛或 macOS/IME/屏幕阅读器实机验证。
+
+[Full comparison](https://github.com/zhangyang-crazy-one/dsh-tui/compare/v0.1.0-alpha.49...v0.1.0-alpha.50)
+
+## Earlier releases
+
+See [GitHub Releases](https://github.com/zhangyang-crazy-one/dsh-tui/releases) for `0.1.0-alpha.49` and earlier release notes.

package/README.i18n.yaml

@@ -1,5 +1,5 @@
 # Bilingual-pair consistency record: both languages carry equal authority.
 # This source-only mirror has no DSH pairing runner. Recompute with:
 #   git hash-object README.md README.zh.md
-README.md: 496d812168deb2af7d4a933f961b58c1cfd814cd
-README.zh.md: 8474c7be4cf16c0d5123222bab95b5231f34e185
+README.md: 85d9293b354853b972f28f7b85d1823395178530
+README.zh.md: 249948d86146a20736141157efd01ce0c2e80768

package/README.md

@@ -1,5 +1,5 @@
 ---
-description: "Installable source-runtime launcher and public source mirror for the DeepSeek Harness terminal interface."
+description: "DeepSeek Harness terminal interface: a dsh plugin bundle plus its launcher."
 kind: "package-group"
 ---
 
@@ -13,10 +13,31 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`@crazyhappyone/dsh-tui` provides the `dsh-tui` command for running and safely updating the DeepSeek Harness terminal interface. The launcher manages a dedicated DSH source checkout, so it never pulls, resets, stashes, or cleans a contributor's development checkout. This public repository also mirrors the `packages/tui/` bundle and renderer sources for review. DSH continues to own agents, sessions, tools, persistence, providers, permissions, and profile assembly.
+`@crazyhappyone/dsh-tui` is a terminal interface for DeepSeek Harness (dsh), shipped as a dsh **plugin bundle** plus a `dsh-tui` launcher. The package declares `dsh.bundle`, so dsh installs it into a profile like any other plugin; the launcher only automates that install and boots the profile. This repository owns the plugin sources (`tui/`, `tui-render/`). DSH continues to own agents, sessions, tools, persistence, providers, permissions, and profile assembly.
+
+## Release 0.1.0-alpha.51
+
+This prerelease targets DSH `0.2.1-rc.2`. It fixes streamed text overlapping the input area, removes wheel scrolling catch-up, reduces history-rendering work, and adds hierarchical settings navigation. It also fixes failed-stream text, SSH login guidance and file paths after `/cd` (#14–#16). See the [changelog](CHANGELOG.md#010-alpha51--2026-10-21) for the full changes and verification boundaries.
+
+```sh
+npm install --global @crazyhappyone/dsh-tui@next
+dsh-tui probe
+dsh-tui
+```
+
+Both lightweight and source modes now default to the official `deepseek-tui` profile under `$DSH_HOME/profiles/` (normally `~/.dsh/profiles/`). `/model` reads `ctx.llm`, and model selection uses DSH's `agentDefaultModel`; this bundle does not read a private model configuration or copy another profile's providers. Magpie writes existing `profiles/*/cordis.patch.yml` files. If Magpie is connected before a new profile is created, refresh its DSH connection/catalog after the profile exists and restart the TUI.
+
+Earlier lightweight versions used `tui`, while source mode used `deepseek-tui`. Neither directory is deleted or migrated automatically. To retain an older lightweight profile, run `dsh-tui --profile tui`. To use another TUI-enabled official profile, pass `--profile NAME`: installation and boot use that exact same target in either mode. Profiles remain independently configured by DSH; a provider configured only in `web` is not automatically global.
+
+For a running source-linked installation, `/reload` loads the rebuilt bundle but preserves that process's selected profile. To change from `tui` to `deepseek-tui`, quit and launch again (or pass the desired profile explicitly). Resumed Goals require `/goal resume` to enable automatic continuation.
+
+`/settings` now opens a hierarchy. Use Enter to open a category, namespace, provider, model or field; ←/Esc returns one level; `/` searches; `i` edits an object's JSON; Space toggles supported values. Successful edits stay in the current location and use DSH's official settings/credential services. In the recorded PTY comparison, a nine-line wheel burst reached its target in 17.93 ms instead of 168.07 ms; 2,812 frames with published transcript snapshots had no text mismatches or input-area leaks. These are synthetic PTY results, not hardware latency guarantees. See the [fix verification](docs/performance-audit-2026-10-21/fix-verification.md) for fixtures and limits.
 
 ## Table of Contents
 
+- [Release and upgrade](#release-010-alpha51)
+- [Changelog](CHANGELOG.md)
+- [Terminal capabilities](#terminal-capabilities)
 - [Screenshots](#screenshots)
 - [Install the launcher](#install-the-launcher)
 - [Run and update](#run-and-update)
@@ -33,9 +54,9 @@ English | [中文](README.zh.md)
 <a id="screenshots"></a>
 ## Screenshots
 
-Idle home:
+Interactive settings pane (`/settings`):
 
-![dsh-tui idle home](assets/screenshots/dsh-tui-home.png)
+![dsh-tui settings pane](assets/screenshots/dsh-tui-settings.png)
 
 After sending `你好`:
 
@@ -51,7 +72,7 @@ The unscoped `dsh-tui` package belongs to another maintainer. This project publi
 `dsh-tui` supports two runtime modes:
 
 ### Mode A: Lightweight Mode (Recommended, Zero-Clone)
-Install the official core engine and the TUI launcher globally (dozens of MB):
+Install the official engine and the TUI launcher globally:
 
 ```text
 npm install --global @deepseek-ai/dsh
@@ -60,7 +81,18 @@ dsh-tui probe
 dsh-tui
 ```
 
-In this mode, the launcher automatically detects the installed `dsh` executable and mounts the bundled prebuilt TUI extension without cloning the 2GB monorepo.
+The first launch runs `dsh plugin --profile deepseek-tui add <package directory>`, which links this package into the `deepseek-tui` profile after `@deepseek-ai/dsh-base`; later launches find it there and run `dsh --profile deepseek-tui` directly. Without the launcher, the same two dsh commands work by hand:
+
+```text
+dsh plugin --profile deepseek-tui add @crazyhappyone/dsh-tui@next
+dsh --profile deepseek-tui
+```
+
+Installing as a bundle matters in dsh 0.2: `/settings` edits are written to the profile's own patch layer, which applies after bundle layers. A `--patch` overlay would apply after the profile layer and dsh refuses settings writes to rows such an overlay owns.
+
+Detection checks an absolute `DSH_BIN` override, PATH, npm and pnpm global packages, then packages resolvable from the working directory and launcher directory. Each probe subprocess has a ten-second timeout, which covers a cold first start. A broken explicit `DSH_BIN` is reported without selecting another installation. Package bin entries run through the launcher's Node executable.
+
+The bundle targets the dsh `0.2` release line (built against `0.2.1-rc.2`, also verified on `0.2.1-alpha.2`). The package declares `@deepseek-ai/dsh` `>=0.2.0-rc.2 <0.3.0` as an optional peer, so dsh's own plugin compatibility check covers manual installs, and the launcher refuses another engine line with the exact install command; `DSH_TUI_SKIP_ENGINE_CHECK=1` bypasses the launcher check.
 
 ### Mode B: Source Mode (Developer / Debugging)
 To debug or hack on TUI or DSH source directly:
@@ -86,7 +118,7 @@ dsh-tui
 
 Run `dsh-tui update` when you want to refresh the dedicated runtime before launching it again.
 
-Ordinary arguments pass to the `deepseek-tui` profile unchanged:
+Ordinary arguments pass unchanged to the selected official profile (`deepseek-tui` by default) in both modes:
 
 ```text
 dsh-tui "review this repository"
@@ -110,13 +142,13 @@ dsh-tui update
 <a id="configure-the-source-runtime"></a>
 ## Configure the source runtime
 
-The defaults track the owner's private `feat/deepseek-tui` branch. Git authorization for that repository is required. Other users can select a compatible accessible repository and ref.
+The defaults use the official public repository at tag `dsh-v0.2.1-rc.2`. Source mode links this bundle into the existing `deepseek-tui` profile and preserves its user patch. Missing Typert runtime artifacts are generated with the upstream generator before boot. The source CLI runs through `pnpm exec node`, avoiding the `predsh` hook that reinstalls the entire workspace on every launch.
 
 | Environment variable | Default | Purpose |
 |---|---|---|
 | `DSH_TUI_RUNTIME_DIR` | `~/.local/share/dsh-tui/runtime` | Dedicated clone used only by the launcher |
-| `DSH_TUI_SOURCE_URL` | `https://github.com/zhangyang-crazy-one/deepseek-harness.git` | Git remote cloned and fetched by `update` |
-| `DSH_TUI_SOURCE_REF` | `feat/deepseek-tui` | Branch or ref fetched by `update` |
+| `DSH_TUI_SOURCE_URL` | `https://github.com/deepseek-ai/deepseek-harness.git` | Git remote cloned and fetched by `update` |
+| `DSH_TUI_SOURCE_REF` | `dsh-v0.2.1-rc.2` | Branch or ref fetched by `update` |
 | `DSH_TUI_PNPM` | `pnpm` | pnpm executable used for install and launch |
 
 Values must be non-empty, and the runtime directory must be absolute. The launcher refuses a symbolic-link runtime path and an existing directory that is not a Git checkout. Child commands receive argument arrays without shell interpolation.
@@ -128,15 +160,69 @@ If dependency refresh fails after a fast-forward, the runtime stays at the repor
 <a id="relationship-to-dsh"></a>
 ## Relationship to DSH
 
-The TUI is a DSH profile layer, not a separate agent runtime:
+The TUI is a dsh plugin bundle, not a fork or a separate agent runtime:
 
 ```text
-@deepseek-ai/dsh-base
-  └─ @deepseek-ai/dsh-tui          profile patch, terminal lifecycle, controller
-       └─ @deepseek-ai/dsh-tui-render   Ink projection and terminal I/O
+@deepseek-ai/dsh-base                  dsh core bundle (agents, sessions, tools)
+  └─ @crazyhappyone/dsh-tui             this bundle: cordis.patch.yml + dist/*
+       ├─ tui-startup  (./startup)      command-line provider (task, --resume, --cwd)
+       ├─ tui          (./settings)     volatile TUI preferences shown in /settings
+       ├─ tui-runtime  (./runtime)      terminal lifecycle and controller
+       ├─ schedule     (./schedule)     official scheduler with shared Session activation
+       └─ zen-proxy    (./zen-proxy)    optional OpenCode Zen header proxy
+```
+
+Rows name plugins through the package's `exports`, so a settings edit records a portable row name in the profile patch. The bundle also inserts the published dsh plugins `session-stats`, `message-feedback`, `tool-ask-user`, `workspace-changes`, `tool-schedule`, `time-context`, `tool-present`, and a loopback `webserver` for the account sign-in callback, and overrides `system-prompt`, `tools`, `session-query-sqlite`, and `session-title-llm`.
+
+### Reminders and user questions
+
+The model can use the official `schedule_create`, `schedule_list`, `schedule_update`, and `schedule_delete` tools. `/schedules` lists reminders across Sessions: ↑↓ or PgUp/PgDn selects, Enter shows the full prompt, a second Enter opens the owning Session, `r` refreshes, and `d` asks for cancellation confirmation (`y` confirms; `n` or Esc keeps it). Delivery resumes the original Session even after navigating elsewhere. Tasks persist across restart; timers run only while this process is open, and overdue tasks are handled on the next launch. A delivery receipt confirms durable inbox admission, not a completed model response. The adapter bundles the official scheduler and Session activation helpers from the pinned DSH build; upstream upgrades require integration checks.
+
+User questions support all questions in a batch, multiple selections, and custom text. Space toggles a multi-select choice; `c` opens the custom editor; Enter saves text and submits choices. Questions without choices open the editor directly. Tab opens the complete question and answer for scrolling; Tab or Esc returns to editing. Esc in the editor discards that edit (or cancels a text-only question), while Esc on the choices cancels the request. Pasted multiline answers retain their original text and do not change the chat draft.
+
+Credential editors and secret arguments in `/key` and `/login` display bullets while keeping credential reference names visible. Masking affects display only: editing and submission retain the original value, and cancelling restores the chat draft.
+
+### Time context, delivered files, and image paste
+
+The official `time-context` plugin supplies the current time and process time zone to the model when preparing a step, refreshing after ten minutes. This model context does not create an extra human transcript message.
+
+The model can explicitly deliver existing files with the official `present` tool (up to eight files per call). `/deliveries` lists this Session's recorded deliveries: ↑↓ selects, Enter previews UTF-8 text, `o` requests opening the selected file in the local system application, and Esc returns. PDF, Office, images, and other binary formats show file details and use the system application. Text reads are limited to 1 MiB by default. Completed turns also show the delivered paths and descriptions; their records survive Session replay, but the files must still exist and remain accessible.
+
+Clipboard image paste uses `pngpaste -` on macOS ([installation: `brew install pngpaste`](https://github.com/jcsalterego/pngpaste)), `wl-paste` on Wayland, or `xclip` on X11. A missing helper gives a visible error. Reads time out after five seconds by default and are cancelled when the TUI closes; existing image limits and validation still apply. The macOS command and subprocess behavior have automated coverage on Linux; macOS hardware validation remains pending.
+
+### DeepSeek account, models, and working directory
+
+- `/login` opens the DeepSeek account page when dsh mounts the `deepseek-account` service: Enter starts browser sign-in, `o` reopens the authorization link, `c` cancels, and the page shows the profile and balance once signed in. The browser returns to the bundle's `webserver` row on `127.0.0.1` with an OS-assigned port. Over SSH the page prints the `ssh -L` forward instead of opening a browser; pin `port` on the `webserver` row so the forward stays stable. Closing and reopening this page retains the active attempt and restores its forwarding instructions; `o` opens the link only when explicitly requested. Without the account service, `/login` and `/key` open the API-key editor.
+- `/logout` signs out after confirmation; stored API keys remain.
+- `/model` lists `deepseek-account` and `deepseek-official` with the step that makes their models available (`/login` or `/key`) while their catalogs are empty, and refuses to select such a row.
+- `/cd [path]` shows or changes the Session working directory on dsh 0.2.1 and later. The header, `@` mentions, and `/files` follow it, including relative paths entered in the file panel, and the model receives the change notice; existing shells keep their own directories.
+- `/plugins` lists official bundles in their own group. An official catalog entry whose files are not installed is marked installable, and Space opens the install preview for its exact target.
+
+### OpenCode Zen free models
+
+The bundled patch mounts `zen-proxy` (vendored from
+[zhangyang-crazy-one/dsh-zen-proxy](https://github.com/zhangyang-crazy-one/dsh-zen-proxy),
+fork of [Yee-h/dsh-zen-proxy](https://github.com/Yee-h/dsh-zen-proxy)): an in-process
+localhost proxy that injects the official OpenCode client headers Zen requires
+(`User-Agent`, `x-opencode-client/session/request/project`). Without it Zen answers
+`400 MissingSessionID` / `429 FreeUsageLimitError` because dsh always sends its
+own attribution `User-Agent`.
+
+To use it, add a provider through the TUI `/settings` provider form (or the
+profile's `cordis.patch.yml`) pointing at the proxy, and keep the key in credentials:
+
+```yaml
+- id: llm-pi-ai
+  config:
+    providers:
+      opencode:
+        api: openai-completions
+        baseURL: http://127.0.0.1:4097/v1
+        apiKeyEnv: OPENCODE_API_KEY
 ```
 
-The integration source lives on the private [`feat/deepseek-tui` DSH branch](https://github.com/zhangyang-crazy-one/deepseek-harness/tree/feat/deepseek-tui/packages/tui). Changes that affect DSH services, profile composition, assembled CLI snapshots, or Agent Notes belong in that monorepo and follow its architecture, testing, and documentation rules.
+The proxy listens on `127.0.0.1:4097` only; add `- id: zen-proxy` with
+`disabled: true` to the profile's `cordis.patch.yml` to turn it off.
 
 -----
 
@@ -145,7 +231,8 @@ The integration source lives on the private [`feat/deepseek-tui` DSH branch](htt
 
 | Package | DSH shape | Responsibility |
 |---|---|---|
-| [`tui/`](tui/README.md) | Profile bundle plus runtime plugin | Composes the terminal layer over `dsh-base`, owns the live terminal session, and maps user actions to DSH services |
+| [`tui/`](tui/README.md) | Runtime, startup, and settings plugins | Composes the terminal layer over `dsh-base`, owns the live terminal session, and maps user actions to DSH services |
+| [`plugins/zen-proxy/`](https://github.com/zhangyang-crazy-one/dsh-zen-proxy) | Vendored plugin (bundled as `dist/zen-proxy.js`) | In-process OpenAI-compatible proxy injecting OpenCode Zen client headers; mounted in `cordis.patch.yml` |
 | [`tui-render/`](tui-render/README.md) | Library | Projects controller state through Ink without owning agents, persistence, or model requests |
 
 -----
@@ -153,9 +240,20 @@ The integration source lives on the private [`feat/deepseek-tui` DSH branch](htt
 <a id="development-workflow"></a>
 ## Development workflow
 
-Implement TUI behavior in the complete DSH checkout, run the checks selected by the changed behavior, and export the confirmed `packages/tui/` tree here. Develop the launcher in this repository with `npm test`; test installation through a packed tarball rather than a workspace link.
+`tui/` and `tui-render/` compile against an upstream dsh checkout at the tag named by `COMPATIBLE_DSH_VERSION` in `src/launcher.js`:
 
-The launcher runtime must remain separate from the development checkout. To test against another source safely, point `DSH_TUI_RUNTIME_DIR` at a temporary absolute directory and configure `DSH_TUI_SOURCE_URL` and `DSH_TUI_SOURCE_REF`.
+```text
+git clone --branch dsh-v0.2.1-rc.2 https://github.com/deepseek-ai/deepseek-harness ../deepseek-harness
+(cd ../deepseek-harness && pnpm install)
+npm run build          # or DSH_SOURCE=/path/to/checkout npm run build
+(cd ../deepseek-harness && pnpm install) # link the mounted plugin's dev dependencies
+npm run dev:setup      # same DSH_SOURCE override; build types and link editor dependencies
+npm run typecheck      # strict checks for sources and tests
+```
+
+`npm run build` copies the plugin packages and `cordis.patch.yml` into the checkout's `packages/tui/` workspace, bundles `dist/index.js`, `dist/startup.js`, `dist/settings.js`, `dist/schedule.js`, and `dist/zen-proxy.js` with esbuild, and import-checks each output. Run the plugin tests from the checkout with `npx vitest run packages/tui`, and the launcher tests here with `npm test`; run `npm run pack:check` before release. Test installation through a packed tarball or `dsh plugin --profile <name> add <this directory>`.
+
+Local `tsconfig.json` files support editors in this standalone repository. The build mounts `tsconfig.workspace.json` as the checkout's package config to preserve upstream project references. `dev:setup` builds dependency declarations and links whole `node_modules` directories, preserving pnpm's relative links. Re-run build and setup after upstream or public type changes; restart the editor's TypeScript project if it still displays old missing-module diagnostics.
 
 -----
 
@@ -178,21 +276,42 @@ The equivalent npm website settings are organization or user `zhangyang-crazy-on
 For each release, bump `package.json`, merge the change after CI passes, then create a GitHub Release whose tag matches the package version:
 
 ```text
-gh release create v0.1.0-alpha.4 --prerelease --generate-notes
+gh release create v0.1.0-alpha.50 --prerelease --notes-file docs/releases/v0.1.0-alpha.50.md
 ```
 
 The `Publish npm` workflow runs tests and packed-package verification again before publishing. Do not rerun an old release tag: npm versions are immutable. Promotion to stable is a new version and a non-prerelease GitHub Release.
 
 -----
 
+## Terminal capabilities
+
+`/timeline` reads individual Session events, actual tool/token/timing data and full JSON; `/attachments` lists typed image/file references and opens local copies; `/review` reads each changed file's official diff. `/files` watches expanded directories with coalesced refresh and retains manual `r` refresh.
+
+`/settings` uses Tab/Shift+Tab section navigation and persists `tui.theme=dark|light`. `/keys` lists context-specific bindings; `/bind ACTION Ctrl+X`, `/bind ACTION default` and `/unbind ACTION` edit composer shortcuts with conflict checks. Shift+arrows/Home/End selects input by grapheme, typing/paste replaces the selection, and Ctrl+Y copies ordinary selections; credential selections cannot be copied. Alt+H opens read-only help during approvals, questions and plan review.
+
+`/agents` supports `c` continuation (Enter queues, Ctrl+Enter steers), `s` request Stop, and `v` side-by-side viewing at 100+ columns. Narrow terminals use the single-pane view. Human controls preserve the catalog's exact direct-parent address; Stop acknowledgement does not claim execution has already stopped.
+
+`/preset` browses standard/PTC/minimal/cordis declarations; `/preset ID` selects an isolated composition before the first turn. Started Sessions remain locked. `/market QUERY` searches configured indexes and routes `i` through plugin-manager inspection and confirmation; `n/p` pages results. `/inspect` browses official Host providers; `/inspect host PROVIDER METHOD JSON` reads an exact contract. `/focus` hides intermediate tool cards without changing model tools or the Session log. External language packs can call `registerTuiLocale`; fenced code uses bounded language-specific lexical highlighting.
+
+The Goal footer distinguishes armed automatic continuation from a stopped continuation requiring `/goal resume`. Backend-started turns update the running state and Ctrl+C cancellation path. After updating a running source installation, use `/reload`; a resumed Goal requires explicit `/goal resume` to rearm.
+
+Verification and platform boundaries: [P1/P2 evidence](docs/p1-p2-verification-2026-10-20.md).
+
+-----
+
 <a id="known-limitations"></a>
 ## Known limitations
 
-- **Private default source** — npm installation is public, but the default DSH runtime remote requires repository authorization; anonymous users must configure an accessible compatible source.
+- **Third-party plugins must match the engine** — dsh 0.2 rejects older authentication plugins that only declare dsh 0.1.x support; the launcher never grants version exemptions automatically.
 - **Source toolchain required** — runtime initialization requires Git, pnpm, and a DSH-supported Node version.
 - **No automatic conflict resolution** — dirty or non-fast-forward runtime history requires explicit human action or a new runtime directory.
 - **Runtime update is not launcher update** — `dsh-tui update` refreshes DSH source and dependencies; npm updates the launcher package.
 - **Integration owns release readiness** — launcher success does not replace the DSH branch's behavior, snapshot, build, or hygiene checks.
+- **Source mode also uses this plugin** — the configured checkout must be compatible with this bundle's dsh version. Replace a historical profile's `@deepseek-ai/dsh-tui` bundle with `@crazyhappyone/dsh-tui`; back up the profile and preserve user settings during migration.
+- **Reminders need a running process** — `/schedules` uses the official service and persistent origin Sessions. Restart can recover pending reminders; a closed process runs no timers.
+- **Terminal capability limits** — images and PDF/Office files use metadata/text or the system opener. Ink exposes no IME composition events; native terminal preedit remains authoritative. `INK_SCREEN_READER=true` enables plain-stream rendering, without mouse capture, alternate screen or animation; physical IME/screen-reader devices and macOS clipboard have not been verified.
+- **Account sign-in needs a reachable Platform** — sign-in reports `no-response` when the host cannot reach `platform.deepseek.com`; use `/key` in that case.
+- **No physical session deletion on dsh 0.2** — 0.2 session persistence archives instead of deleting, and the TUI composition mounts no workspace archive service, so the session list reports deletion as unavailable.
 
 <a id="dev-note"></a>
 ## Dev Note